1 · Problem Statement

An Intermodal Operations Hub (IO Hub) moves containers and trailers across the country using rail for the long haul and trucks for first/last mile. Every day, thousands of containers, chassis, and railcars flow through dozens of terminals — gating in, sitting in the yard, mounting onto trains, traveling, and gating out again.

The operation is reactive. Teams find out a yard is full after it is full, learn a gate is congested while trucks are already queued, and discover a chassis shortage when a driver is already waiting. There is rich event data, but it is not yet turned into foresight.

The core problem: we cannot reliably answer simple forward-looking questions such as —

• “How full will Terminal X's yard be in 6 hours? Will it breach capacity?”
• “How many trucks will hit the gate in the next 1–3 hours?”
• “Which containers are sitting too long (dwell), and which equipment is idle or bad-ordered?”
• “Will we have enough empties / chassis / railcars where and when they're needed?”

2 · What We're Trying to Achieve

Turn the existing equipmentActivityReported event stream into predictive, actionable insight — moving the operation from reactive to proactive.

3 · The Business — Intermodal 101

Intermodal transportation moves freight using more than one mode — primarily rail (long-haul) and truck (first/last mile) — without handling the freight itself when switching modes, because it stays inside the same container.

Core assets

End-to-end flow of a container

Container states

Business tension: too many mounted empties = wasted cost; too few = service delay. Grounded = storage; Mounted = readiness.

4 · Terminal Operations

A terminal's day revolves around three things: the gate (entry/exit), the yard (storage), and the train (load/unload). These are exactly the flows our data captures.

Gate operations — the inventory valve

Yard, chassis & train

• Yard: arrival → storage → assignment to a booking → mount/lift → load or gate-out.
• Chassis: bare → mounted → used → returned → reused. Availability directly limits pickups.
• Load to train: reservations set demand; units staged & lifted; track Units Loaded vs Left-to-Load.
• Train unload: arrivals removed into yard/chassis → feeds the next demand cycle.
• Enroute: loads & empties already moving between terminals.

Operational challenges called out in the source: over-/under-usage of chassis, bad-order equipment reducing usable capacity, and yard overflow.

5 · The 8 Predictive Use-Case Groups

The IO Hub vision defines 8 groups of predictive & analytics use cases. They are the menu of value we want to unlock from the data.

6 · The Source Data — equipmentActivityReported

Everything above is powered by one real dataset: an export of equipment-activity events from the container-history system (IPRO_CONTAINER_HISTORY).

What one record looks like

It is MongoDB extended JSON — one big array of event objects. Each event is a snapshot of a single piece of equipment at a moment in time. A trimmed real example:

{
  "equipmentId": "UNKN324740",
  "equipmentTypeCode": "H",                // H = chassis
  "loadEmptyStatus": "E",                  // Empty
  "currentStatus": "On Ramp",
  "trainMoveCategory": "Storage",
  "eventDescription": "Created",
  "eventDateTime": "2026-05-29T20:54:21Z", // the heartbeat
  "terminal": { "code": "WOR", "name": "WORCESTER", "region": "North" },
  "shipperName": "JB HUNT TRANSPORT SERVICES INC",
  "flatcarId": "BNSF211633",
  "holdFlag": 0, "damageFlag": -1,
  "header": { "uuid": "36395582-…", "messageTypeId": "imod_equipment_activity_reported" }
}

The full proto definition lists every field; the Container Inventory — Important Fields doc highlights the ones that matter for reporting and prediction, catalogued next.

7 · Field Catalog — what each column tells us

The 119 raw fields group into seven meaningful families. Below are the key fields for tracking, reporting, and (later) prediction.

8 · Data Reality & Caveats

Being honest about the source is part of the complete picture.

9 · POC Scope & the Next Step

Of the 8 use-case groups, three are directly supported by the data we already have — no extra source systems required. These are the natural POC focus:

Document synthesized from: Container Inventory — Important Fields, Intermodal Business & Terminal Operations, IO Hub Predictive & Analytics Use Cases, and the live equipmentActivityReported source. Generated May 31, 2026.

Start here — the one big idea

We have a giant diary of what every container did over the last ~2.5 months. We use that history to teach a computer to guess the near future — how full a yard will get, how many trucks will arrive, how long things will sit.

That's it. Everything below is just the detail behind those four steps.

10 · Every number on the card, explained

Here's a real Yard card and what each line is telling you:

Yard inventory (+24h)
  winning model:   Ridge  · 1739 train pts
  Last actual      52,348
  Forecast (next)  52,422.5
  MAE (error)      64.56
  Accuracy (MAPE)  0.1%      # = 99.9% accurate
  Congestion threshold 45,566
  Forecast vs threshold OVER # congestion predicted

11 · The “model race” (the leaderboard)

For each thing we predict, we don't pick one method and hope. We enter six different algorithms into a race, give them all the same data, and let the most accurate one win.

Your Yard leaderboard, read as a race result (lower = better):

Why did the powerful tree models lose on yard? Because yard inventory is a smooth, slowly-drifting line — a straight-line method (Ridge) fits it better than complex trees, which overcomplicate it. Different problems, different winners.

12 · What each algorithm actually does

The six racers, in plain words — and what kind of problem each is good at.

13 · What data (tables) we have

It all starts from one source: 845,277 equipment-activity events (119 fields each, 32 terminals, ~2.5 months). From that raw stream we build four clean tables the models read:

14 · How we train and pick a winner

1. Shape the data: turn events into an hourly/daily time-series per terminal.
2. Add clues (features): hour-of-day, day-of-week, and recent past values (“lags”).
3. Split fairly: train on older data, test on a recent slice the model never saw.
4. Race the six: each predicts the hidden slice; we score the error.
5. Crown the winner: lowest error wins and is saved as a .joblib file.
6. Forecast: the winner predicts the next 24h (yard) or next period (gate).

We did this for every terminal × every metric — 127 models in ~15 minutes on a laptop CPU. The “Load & run the real .joblib” button proves each one is a genuine saved model, not a hardcoded number.

15 · Why Gate accuracy looks “low” (and what's really going on)

Two honest reasons Gate is weaker:

• Far less data: 67 points vs 1,739. Hard to learn a pattern from so few.
• Much longer horizon: guessing 14 days ahead is far harder than 24 hours ahead.

16 · What MORE data would help (and how much)

More data is the single biggest lever — especially for gate & flows.

17 · Other algorithms we could add to the race

The current six cover the main families. With more data, these are worth entering:

18 · If I add 1 year of data — is it production-ready?

19 · How to read the screen, quickly

• Find the 🏆 on the leaderboard — that's the chosen model. Lower number = better.
• Compare MAE and MAPE. Both small → trust it. Small MAE but big MAPE → it's a low-volume series, not a broken model.
• Read “Forecast vs threshold.” OVER = act now (prepare yard space / staffing).
• Click “Load & run the real .joblib.” Confirms it's a genuine saved model, live.

Merged from the explained.html companion. Same warm reading theme, no dark mode. Generated May 31, 2026.