Method & sensitivity analysis
The full pipeline — parse, calibrate, price, accrue, prove, control — with this run's actual numbers inline. Then a sensitivity lab: drag the assumptions and the same deterministic engine re-runs the entire close in your browser, so you can see what moves the number and what doesn't.
How the accrual is calculated — visual flow
How the April manifest flows through the engine to the booked number: each carrier is priced from its calibrated rates against the actual shipments, then summed net of the credit reserve. Live figures from this run.
1 · Parse & normalize
Messy operational CSVs → typed records. All normalization tables live in config, not code.
- Carrier names normalize via an alias map (“PEAK LOG”, “Peak Logistics Inc” →
peak); unknown carriers raise anUNKNOWN_CARRIERerror flag. - 161 shipment rows → 160 unique (duplicate ids dropped and flagged, never double-counted). 811 invoice lines across six months feed calibration.
- Special-handling free text maps to canonical accessorial codes; residential is a flag, not a guess. Missing weights: imputed from units × the carrier's median lb/unit only where weight affects price (Heartland prices a flat zone rate — no imputation needed, flagged info-level).
2 · Calibrate: the monthly rate index
The one mechanism the whole method hangs on — discovered from the invoices, not assumed.
Each carrier bills the printed (structural) card times a global monthly multiplier — identical across that carrier's destinations, zones, and regions within a month. The engine recovers it per carrier-month as the median ratio of billed base to structural base. That single number is why reconstruction ties every historical invoice to ±$0.32.
billed_base = structural_rate(card) × monthIndex[carrier][month] × (volume discount, HF only)| Carrier | Index range (6 mo) | Mean | Applied to April | vs printed card |
|---|---|---|---|---|
| Peak Logistics | 0.6113 – 1.0705 | 0.8074 | 0.80625 | printed runs 24.0% high — flagged |
| Heartland Freight | 1.0046 – 1.2265 | 1.0893 | 1.12148 | printed runs 10.8% low — flagged |
| Coastal Express | 0.7854 – 1.1907 | 1.0518 | 1.16962 | printed runs 14.5% low — flagged |
The index moves both directions (Peak's card prices high lately; Heartland/Coastal price low), which is why “just use the printed card” misprices in both directions and why the per-carrier rateSource override exists with a divergence flag. April uses the recent-3-month average; the back-test reproduces each month at its own index.
3 · Price every shipment
Three carrier modules, one contract: priced result + human-readable calc trace + flags.
base = max(miles(dest) × rate/mi(weight tier), min) × index
+ fuel 14.0% × base
+ accessorials (face value)Mileage fallback chain: invoice-calibrated → printed table → geo estimate (haversine × circuity), each non-calibrated rung flagged. Fuel % is calibrated from invoices, not assumed.
base = zoneRate(ZIP prefix) × index
× (1 − QTD volume discount)
+ accessorials (never discounted)Fuel is included in the zone rate. The volume tier is cumulative quarter-to-date shipment count — resets Jan/Apr/Jul/Oct (the reset is the single most predictable swing in the data), carries in for mid-quarter closes.
base = max(lb × $/lb(region), min) × index
+ fuel 9.5% × base
+ residential tier (by weight) + accessorialsRegions by destination ZIP range; the minimum charge scales with the index (verified in invoices: $28 min × 1.191 = $33.34). Residential tier fees calibrated from residential-only invoice lines.
4 · Assemble the accrual + one accrued-liability entry
Everything ties — asserted in code, shown on every page.
- Carrier subtotal = Σ its shipment estimates; total = Σ carriers ($93,817 subtotal).
- Credit reserve -$287.03: historical net adjustments run ~−0.3% of invoiced, so the gross estimate would sit systematically high without it. Booked as a contra line, flagged info-level.
- JE: Dr Freight Expense (one line per carrier, ties to shipment backup) / Cr Accrued Freight Liability $93,530 — reverses on invoice receipt. 8 tie-outs asserted (all pass): JE balances, JE == accrual, Σ shipments == carrier == total, reconstruction ties.
5 · Prove it: back-test design
No circularity, no cherry-picking — and honest about where the engine loses.
- Expanding-window forecast (the headline): month M's index is calibrated only from months < M, then applied to M's actual activity. First month is cold-start and excluded — for both methods.
- Reconstruction (the mechanics proof): every line repriced at its own month's index ties to ±$0.32. In-sample by design — labeled as proof of pricing mechanics, not forecast accuracy.
- The monthly index is near-unpredictable (±30%); monthly spend is stabilized because rate and volume move opposite ways. So per-month percentage error is inherently noisy — the engine's case is near-zero bias (-0.2%), the structurally-knowable Heartland reset, and shipment-level auditability. The head-to-head vs the prior manual estimate is on the Denise Comparison tab.
6 · Controls: every assumption raises a flag
No silent defaults — automation without controls just automates errors faster.
23 flags this run (0 error · 11 warn · 12 info): pricing fallbacks, imputed weights, duplicate rows, calibrated-vs-printed divergence past 10.0%, per-carrier cost outliers past 3σ, back-test MAPE past 5.0%, the credit-reserve note, and the service-level pricing assumption. Thresholds are config, not code — and you can stress them in the lab below.
Methodology & math — sources, assumptions, limitations
The judgment behind the estimate, stated plainly. Counts are live from this run.
| Source | Records | How it's used |
|---|---|---|
| Shipments (current period) | 161 rows → 160 unique | Priced this period; deduped + carrier-name normalized on ingest. |
| Carrier invoices (history) | 811 lines through March 2026 | Calibrate effective rates + the honest back-test; the actual register for closed months. |
| Rate cards (Peak / Heartland / Coastal) | 3 contracted cards | Structural rates + fallback; calibrated against billed invoices (cards run stale). |
| Denise baseline | 18 carrier-months | Prior manual estimate — comparison only, quarantined to the vs. Denise tab. |
- Heartland's volume-tier discount is quarter-to-date cumulative and resets on the quarter start (Apr 1) — priced from the shipment sequence, not a trailing blend.
- Printed rate cards are stale; effective rates are calibrated from the trailing invoice history (recent-window median), with a printed-card / scenario override for announced forward changes.
- Fuel surcharge is calibrated from invoice history (Peak ≈14%, Coastal ≈9.5%); a scenario override applies an announced change and flags the divergence.
- Missing weight (5 this period) is imputed from units × the carrier's median lb/unit and flagged — never silently dropped; off-table / non-Denver mileage is recovered per-origin (Denver vs SLC) and flagged.
- Where invoice history doesn't separate origin, Denver is assumed and flagged (ORIGIN_ASSUMPTION); service level is assumed not to affect price (no card prices by service).
- Off-table Peak destinations fall back to geo-estimated mileage (1 fallback this period, flagged); long-haul lanes are the noisiest and carry the widest band.
- Historical shipments (Oct 2025–Mar 2026) are reconstructed from invoice line items (origin assumed Denver; residential inferred from accessorial detail) and are badged "Reconstructed" — the back-test's absolute error carries that noise.
- The confidence band is ±1σ of each carrier's monthly rate-index volatility, combined in quadrature assuming independence — a first-order estimate, not a full distribution.
- One-off accessorial surges and credit adjustments aren't predicted shipment-by-shipment; a small historical credit reserve absorbs the run-rate, the rest shows as variance at true-up.
- Out-of-sample, a trailing average is hard to beat on per-month MAPE; Freight Close's edge is transparency, adaptability, controls, repeatability, and a near-unbiased estimate — shown honestly on the Accuracy and vs. Denise tabs.
Sensitivity lab — drag the assumptions
The full engine (calibration → pricing → back-test → exceptions) re-runs in your browser on every change. Analysis only: the booked accrual always uses the committed config — sliders never change the books.
Base rates stay calibrated — only the fuel % moves, so the impact is cleanly the fuel delta. Any change raises RATE_DIVERGENCE (an announced rate change a trailing average can't see). This is the May Peak-spike adaptability demo, inline.
What to notice: the accrual moves only modestly across windows 2–6 (the index averages out), the band widens as you demand more confidence, and tighter thresholds trade alert fatigue for sensitivity. The committed settings are marked under each slider.
Where the figures on this page come from
Nothing on this page is typed in — every number is read from the deterministic run output.
The engine is ~4,200 lines of unit-tested TypeScript with no database and no network calls. It runs at build time (this site) and in your browser (Run a close, and the lab above). Same inputs + same config ⇒ byte-identical output — that determinism is what makes the ±$0.32 reconstruction and the “Re-run & verify” proof on the Run a close tab possible. Current April indices: Peak 0.80625, Heartland 1.12148, Coastal 1.16962.