# Fictional depot jobs data

## Provenance and generation

The dataset was generated entirely for this course with NumPy's default_rng seed 20261014. It represents 1,500 invented jobs, six arrivals per day across 250 days beginning 2025-01-01 UTC. No records describe real people, customers, depots or company performance. The reference dates describe a simulated historical process, not a live business.

Each job arrives at 08:00, 10:00, 12:00, 14:00, 16:00 or 18:00 UTC. Twelve fictional depots recur over time. Distance is uniform from 2 to 80 km. Queue length is Poisson with mean 6 before day 190 and 8 thereafter. Item count is an integer 1–10. Priority and zone are sampled categorically. A seeded depot effect, distance, queue, item count, a nonlinear queue-congestion term, west-zone effect, express adjustment, gradual post-day 180 mechanism shift, and Gaussian noise determine duration. The code clips duration to [0.5,23.5] hours and rounds to three decimals. Read `courseml/data.py` for the exact formula.

Distance is then hidden with 5% probability and queue length with 3% probability, independently of the outcome. The mechanism uses their latent original values. These are designed missingness assumptions, not conclusions about real systems. They make train-fitted imputation meaningful while leaving irreducible uncertainty. The course does not claim that its model ranking or numerical performance transfers to actual operations.

## Row unit and fields

One row is one job, predicted once at intake. All permitted inputs are available at that moment in the simulation. Real systems must prove this with timestamps and historical as-of data, not rely on column names.

| Field | Meaning | Predictor? |
|---|---|---|
| job_id | Unique synthetic job identifier | No; audit only |
| day | Integer day 0–249 | No; split only |
| intake_at | UTC prediction timestamp | No directly; audit/split |
| distance_km | Planned route distance; some values missing | Yes |
| queued_jobs | Jobs already in queue at intake; some values missing | Yes |
| item_count | Known number of items 1–10 | Yes |
| weekday | Intake day-of-week, Monday 0 through Sunday 6 | Yes |
| priority | standard or express, known at intake | Yes |
| zone | central, east or west | Yes |
| depot_id | Fictional depot D00–D11 | Yes for known-depot future question |
| promised_hours | Promise known at intake:10 standard,6 express | Yes |
| duration_hours | Observed completion duration | Regression target; never input |
| late |1 when duration_hours>promised_hours; equality is on time | Classification target; never input |
| label_available_at | Completion timestamp; outcome becomes known then | No; leakage trap and maturity audit |
| final_delay_reason | late_confirmed/on_time_confirmed after completion | No; direct target leakage |
| close_cost | Cost calculated from actual duration after closure | No; outcome proxy leakage |

Priority and promised_hours are deterministically related here. They are included to teach why correlated predictors complicate interpretation; a coefficient or permutation score is not a causal effect. Unknown depots can transform through one-hot encoding but this does not establish performance for new depots.

## Partition contract

- train.csv: days 0–148, 894 jobs; only source for estimator fitting and CV tuning
- validation.csv: days 150–198, 294 jobs; calibration days 150–173 (144), omit day 174 (6) internally, threshold/error analysis days 175–198 (144)
- embargo.csv: days 149 and 199, 12 rows; unused in fitting and scoring
- test.csv: days 200–249, 300 jobs; future final evaluation only after freeze

All labels from the earlier role must be available before the earliest intake in the next role. One omitted day is enough at outer boundaries for this less-than 24-hour horizon. Training CV uses four expanding TimeSeriesSplit folds and a 12-row gap, conservatively two arrival days. Validation folds have equal row counts, but their boundaries can cut across days. The source has six jobs each day, with unequal overnight and within-day spacing, so these scores are job-weighted evaluations rather than exact equal-duration averages from an evenly spaced time series. For a different arrival process or label delay, use timestamps and derive an appropriate embargo.

The group holdout demonstration uses training data only and holds out entire depots. It asks about unseen depots within a historical period. It does not estimate future new-depot performance; that would require both group and time constraints and sufficient independent depots.

## Storage and safety

CSV values are plain text. Datetimes are parsed with explicit mixed-format UTC handling because fractional seconds differ. The archive contains source code and data, no pickled model or executable binary. Regeneration is deterministic for the tested dependencies; hashes and numerical tests document what was actually reproduced. Dataset regeneration overwrites course fixture CSVs, so keep learner edits separately.