PyPI workbook run (Track D)

From inside your Track D workbook folder (created by pystatsv1 workbook init --track d --dest ...), run:

pystatsv1 workbook run |trackd_run|

Outputs are written under outputs/track_d/ by default. If you’re unsure what a file is for, start with Track D Outputs Guide.

To see the full chapter-by-chapter run map (D00–D23), see Track D chapter index (PyPI).

Optional: write to a custom output folder:

pystatsv1 workbook run |trackd_run| --outdir outputs/track_d_custom

Interpretation prompts (quick self-check):

  • What is the accounting or business measurement goal in this chapter?

  • Which invariant/check would catch a “numbers look fine but are wrong” mistake here?

Track D — Chapter 16

Seasonality and Seasonal Baselines (NSO running case)

Chapter 15 showed how to produce a defensible baseline forecast using simple methods and a 12-month backtest.

Chapter 16 adds one major realism upgrade: seasonality.

In accounting-shaped business data, it’s common for revenue (and sometimes COGS) to follow calendar patterns:

  • holiday spikes,

  • summer slowdowns,

  • predictable quarter-end effects,

  • predictable “busy months” and “quiet months.”

If a series has seasonality, a non-seasonal baseline (like naive_last) can produce a forecast that is systematically wrong in the same direction every year.

What you will build

1) A month-of-year seasonality profile

You will compute a simple seasonal profile from history:

  • month-of-year mean revenue (1..12)

  • seasonal index = (month mean) / (overall mean)

This is not “fancy” time series decomposition. It is intentionally explainable and audit-friendly.

2) Seasonal baselines + backtest metrics

You will compare five baseline methods on a 12-month holdout window:

Non-seasonal baselines (from Chapter 15)

  • naive_last — next month equals the last observed month

  • moving_avg_3 — next month equals the average of the last 3 months

  • linear_trend — fit a straight line and extrapolate

Seasonal baselines (new)

  • seasonal_naive_12 — reuse last year’s value for the same calendar month

  • seasonal_mean — forecast each month as the mean of that calendar month in history

Selection rule (same as Chapter 15)

Pick the method with lowest MAPE on the 12-month holdout (tie-break on MAE).

Data source

This chapter uses the NSO income statement monthly table:

  • data/synthetic/nso_v1/statements_is_monthly.csv

The script pivots the income statement into a clean monthly wide table and forecasts revenue (the Sales Revenue line).

How to run Chapter 16

Prerequisite: generate the NSO dataset (once)

If you already ran Chapter 14/15, you already have NSO v1 in:

data/synthetic/nso_v1

If not:

make business-nso-sim
make business-validate

Run the Chapter 16 analysis

make business-ch16

By default this runs:

python -m scripts.business_ch16_seasonality_baselines \
  --datadir data/synthetic/nso_v1 \
  --outdir outputs/track_d \
  --seed 123

Outputs

All artifacts are written under:

outputs/track_d/track_d

Core tables (CSV)

  • ch16_series_monthly.csv Clean monthly series used in this chapter (revenue + key income statement lines + month keys).

  • ch16_seasonal_profile.csv Month-of-year mean revenue and seasonal index (mean / overall mean).

  • ch16_backtest_predictions.csv Month-by-month predictions for each method on the holdout year.

  • ch16_backtest_metrics.csv MAE/MAPE by method (this is the best file to open first).

  • ch16_forecast_next12.csv Selected method forecast for the next 12 months, including a simple range.

Design + narrative (JSON/MD)

  • ch16_design.json Machine-readable cover sheet: methods, windows, selection rule, chosen method.

  • ch16_memo.md Short memo: seasonal profile highlights + backtest results + next-12 forecast table.

Figures (PNG) + manifest

Figures are written under:

outputs/track_d/track_d/figures

and listed in:

  • ch16_figures_manifest.csv

Figures include:

  • seasonal index by month-of-year

  • backtest overlay for the selected method

  • next-12 forecast overlay

Troubleshooting

“Chapter 16 requires 24 months…”

Chapter 16 runs a 12/12 backtest. You need at least 24 months of monthly data.

“Expected statements_is_monthly.csv … but not found.”

Confirm you ran the simulator and that --datadir points to the NSO folder:

  • Correct: --datadir data/synthetic/nso_v1

What’s next (Chapter 17+)

  • Chapter 17: rolling forecasts + scenario planning

  • Chapter 18: forecasting with drivers (combine operational drivers + time series)

End-of-chapter exercises

  1. Run Chapter 16 but forecast COGS (instead of revenue). Do seasonal methods help?

  2. Change the selection rule to “min MAE” and compare which method wins.

  3. Identify one month that looks like an outlier. Explain how it could bias seasonal means.