Container shipping demand/supply model

A reproducible pipeline that projects, lane by lane (Transpacific, Asia-Europe, Transatlantic), the demand-to-supply capacity ratio over an 18 to 36 month horizon under three scenarios. The ratio is a proxy for freight-rate pressure. Free public sources only, with every limitation naming the paid reference that would lift it.

Headline result (as of 3 July 2026): the ratio falls on all three lanes in all three scenarios. The orderbook stands at 33.4% of the active fleet, i.e. roughly 8% annual capacity growth in 2026 and 2027 against 2 to 3% demand growth. The swing variable is the return via Suez (about 16 ratio points on Asia-Europe), not GDP.

Live dashboard

streamlit run app.py

A self-contained interactive version (no server needed, opens in any browser) is committed at reports/dashboard.html.

Deliverables

Deliverable	Path
Interactive dashboard (Streamlit app)	app.py
Self-contained interactive dashboard (HTML)	reports/dashboard.html
Ratio trajectories by lane and scenario	data/final/ratio_trajectories.csv
Decision log (five method decisions)	docs/decision_log.md
Data-source map, free versus paid	references/data_sources.md

Layout

data/raw/        raw data as downloaded, never modified, one MANIFEST.md per source
data/interim/    cleaned data, regenerable from raw (not tracked)
data/final/      data deliverables
notebooks/       01 exploration, 02 demand model, 03 supply model, 04 balance and scenarios
src/data/        traced acquisition (SHA-256 journal in data/raw/downloads.log)
src/features/    raw to interim transforms, replayable
src/visualization/ shared chart style (validated palette, colour by entity)
reports/         read-out deliverables and figures
docs/            decision log
references/      data-source map

Reproduce

python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt

# 1. Acquisition (archives raw files and journals URL, size, SHA-256)
.venv/Scripts/python.exe src/data/download_sources.py all
.venv/Scripts/python.exe src/data/download_sources.py vintages

# 2. Raw to interim preparation
.venv/Scripts/python.exe src/features/prepare_cpb.py
.venv/Scripts/python.exe src/features/prepare_port_la.py
.venv/Scripts/python.exe src/features/prepare_supply.py

# 3. Notebooks, in order
.venv/Scripts/python.exe -m jupyter nbconvert --to notebook --execute --inplace notebooks/01_exploration.ipynb
.venv/Scripts/python.exe -m jupyter nbconvert --to notebook --execute --inplace notebooks/02_demand_model.ipynb
.venv/Scripts/python.exe -m jupyter nbconvert --to notebook --execute --inplace notebooks/03_supply_model.ipynb
.venv/Scripts/python.exe -m jupyter nbconvert --to notebook --execute --inplace notebooks/04_balance_scenarios.ipynb

Reference environment: Python 3.11.9, versions frozen in requirements.txt, seeds fixed to 42, no manual transformation. Note that some raw files (CPB workbook, Port of LA pages, Alphaliner snapshot) are not committed to keep the public repository free of publisher content; the acquisition scripts regenerate them. Live sources (Alphaliner, PortWatch, CPB) evolve, so a fresh acquisition produces a more recent snapshot than the one analysed; the committed archived data from 2 and 3 July 2026 remains the reference for the published results.

Method

A two-block protocol (reflection validated before any code, then tools), with five decisions made explicitly and recorded in docs/decision_log.md. Permanent verification gates: look-ahead control (34 WEO vintages archived via DBnomics, a backtest uses only the vintage known at the simulated date), no data leakage, freight is never a demand regressor, reliability distinguished from validity.

Modelling: demand by transparent structural regression (trade-to-GDP pass-through 0.88 excluding COVID, decision 4: exclusion of 2020 to 2023), supply by an accounting model (fleet plus phased orderbook minus scrapping, corrected for the Red Sea absorption measured from PortWatch transits), balance as an index at 100 in 2025. Planned extensions: a backtest on vintages, a VECM robustness annex in R (urca), snapshot historisation.

Disclaimer

This is a personal method-demonstration project built from free public data. It is not investment advice. Figures are illustrative and carry the limitations stated in the notebooks and the dashboard.

Licence

MIT, see LICENSE. The code is MIT-licensed; third-party data remain under their own providers' terms (see the per-source manifests in data/raw/*/MANIFEST.md).