Docs: Track D workbook (PyPI-only quickstart + dataset map)

docs/source/business_intro.rst

@@ -1,7 +1,7 @@
 .. _business-track:
 
 Track D – Business Statistics & Forecasting for Accountants
-==========================================================
+===========================================================
 
 Track D teaches **business statistics and forecasting** to learners who work with
 accounting-shaped data (bookkeeping, AP/AR, payroll, staff accounting, finance ops).
@@ -15,6 +15,34 @@ We treat statistical analysis like **production software**:
 * automated checks (tests) so you can trust what you share,
 * “audit-friendly” artifacts (tables, figures, memos) that support decisions.
 
+Run Track D as a Workbook (PyPI-only)
+-------------------------------------
+
+If you're a student following Track D, the easiest path is the **Track D Workbook**.
+It installs from PyPI and generates a self-contained folder (scripts + tests + data).
+
+.. code-block:: bash
+
+   python -m venv .venv
+   # Windows (Git Bash)
+   source .venv/Scripts/activate
+   python -m pip install --upgrade pip
+   python -m pip install "pystatsv1[workbook]"
+
+   pystatsv1 workbook init --track d ./track_d_workbook
+   cd ./track_d_workbook
+
+   # Start here
+   pystatsv1 workbook run d00_peek_data
+   pystatsv1 workbook run d01
+
+   # Optional: run the included smoke test
+   pystatsv1 workbook check business_smoke
+
+The workbook ships canonical datasets (seed=123) under ``data/synthetic/`` and writes
+chapter outputs to ``outputs/track_d/``. See :doc:`workbook/track_d` for the dataset map,
+output conventions, and tips.
+
 The running case and data
 -------------------------
 
@@ -39,7 +67,7 @@ Reproducibility quick start
 Inputs and outputs follow two conventions:
 
 * **Inputs live in** ``data/synthetic/...`` (generated datasets)
-* **Outputs live in** ``outputs/track_d/track_d`` (chapter artifacts)
+* **Outputs live in** ``outputs/track_d/`` (chapter artifacts)
 
 To (re)generate the NSO v1 dataset:
 

docs/source/workbook/index.rst

@@ -13,3 +13,4 @@ PyStatsV1 Workbook
    my_own_data
    troubleshooting
    track_c
+   track_d

docs/source/workbook/quickstart.rst

@@ -77,6 +77,16 @@ Pick a folder you want to work in, then run:
 
    pystatsv1 workbook init ./my_workbook
 
+.. tip::
+
+   Want the Track D accounting case workbook? Use:
+
+   .. code-block:: bash
+
+      pystatsv1 workbook init --track d ./track_d_workbook
+
+   Then see :doc:`track_d` for the Track D workflow and dataset map.
+
 This creates a ready-to-run Workbook folder (scripts + tests + data).
 
 

docs/source/workbook/track_d.rst

@@ -0,0 +1,175 @@
+Track D Workbook: Business Statistics for Accounting Data
+=========================================================
+
+Track D is a **Business Statistics & Forecasting** track built around a realistic
+accounting running case (North Shore Outfitters, “NSO”).
+
+The Track D Workbook is a **PyPI-first** student experience. You can install
+PyStatsV1, create a Track D workbook folder, and run **Track D only** (no repo
+clone required).
+
+If you haven't seen the Track D overview yet, start here:
+
+* `Track D overview (main docs) <https://pystatsv1.readthedocs.io/en/latest/business_intro.html>`_
+
+What you get
+------------
+
+When you run ``pystatsv1 workbook init --track d``, PyStatsV1 creates a local
+folder containing:
+
+* convenience runner scripts (``d01`` … ``d23``) that map to Track D chapters
+* a reproducible, pre-installed dataset under ``data/synthetic/`` (seed=123)
+* an ``outputs/track_d/`` folder where results are written
+* a small smoke test so you can quickly confirm everything is working
+
+Quickstart (PyPI-only)
+----------------------
+
+1) Create a virtual environment and install the workbook extras.
+
+.. code-block:: bash
+
+   python -m venv .venv
+   # Windows (Git Bash):
+   source .venv/Scripts/activate
+
+   python -m pip install -U pip
+   pip install "pystatsv1[workbook]"
+
+2) Create a Track D workbook folder.
+
+.. code-block:: bash
+
+   pystatsv1 workbook init --track d --dest track_d_workbook
+   cd track_d_workbook
+
+3) See what you can run.
+
+.. code-block:: bash
+
+   pystatsv1 workbook list --track d
+
+4) **Peek the data** (recommended first step).
+
+.. code-block:: bash
+
+   pystatsv1 workbook run d00_peek_data
+
+This prints the row counts and column names for the key CSV files and writes a
+short markdown summary into ``outputs/track_d/``.
+
+5) Run the first chapter.
+
+.. code-block:: bash
+
+   pystatsv1 workbook run d01
+
+6) Run a quick self-check.
+
+.. code-block:: bash
+
+   pystatsv1 workbook check business_smoke
+
+.. tip::
+
+   You can re-run any chapter as many times as you want. The scripts overwrite
+   outputs deterministically as long as you keep the dataset unchanged.
+
+What data you are working with
+------------------------------
+
+Track D ships **two canonical datasets**. They are **synthetic but realistic**,
+and are the same every time (seed=123).
+
+1) **LedgerLab (Ch01)** — a small “starter ledger”
+
+* purpose: introduce the accounting equation, debits/credits, and how a general
+  ledger becomes an analysis-ready table
+* location: ``data/synthetic/ledgerlab_ch01/``
+* key files:
+
+  * ``chart_of_accounts.csv``
+  * ``gl_journal.csv``
+  * monthly outputs like ``trial_balance_monthly.csv`` and ``statements_*_monthly.csv``
+
+2) **NSO v1 running case** — a richer business dataset
+
+* purpose: practice the *real* analyst workflow: reconcile, validate, reshape,
+  summarize, model, and forecast
+* location: ``data/synthetic/nso_v1/``
+* key files include event logs (AR/AP/payroll/inventory), a bank statement feed,
+  a generated general ledger, and monthly statements and trial balances
+
+If you want to see the full data dictionary for NSO v1:
+
+* `NSO v1 data dictionary cheat sheet (main docs) <https://pystatsv1.readthedocs.io/en/latest/business_appendix_ch14b_nso_v1_data_dictionary.html>`_
+
+Resetting (or regenerating) the datasets
+----------------------------------------
+
+Datasets are installed automatically during workbook init.
+
+If you edit anything under ``data/synthetic/`` and want to return to the
+canonical seed=123 version:
+
+.. code-block:: bash
+
+   pystatsv1 workbook run d00_setup_data --force
+
+This restores the canonical dataset files and re-runs a few lightweight checks.
+
+Where your results go
+---------------------
+
+By default, Track D scripts write artifacts to:
+
+* ``outputs/track_d/`` — tables, memos, and small machine-readable summaries
+* ``outputs/track_d/figures/`` — charts created by chapters that plot results
+
+A typical chapter produces:
+
+* one or more ``.csv`` artifacts (tables you can open in Excel)
+* a short ``.md`` memo describing what the script did and what to look for
+* a “manifest” CSV listing outputs (useful for grading or reproducible reports)
+
+How Track D helps you become a better accounting-data analyst
+-------------------------------------------------------------
+
+Track D is not “statistics in isolation.” The goal is to practice the full loop:
+
+* **Measurement + integrity**: understand what the numbers *mean* and what can go wrong
+* **Quality control**: detect issues early (duplicates, broken keys, imbalances)
+* **Summarization**: build monthly statements and diagnostic KPIs from transactions
+* **Explanation**: connect changes in performance to drivers (mix, price, volume)
+* **Forecasting**: build baselines, add drivers, run scenarios, and communicate uncertainty
+
+Most chapters are designed to leave you with a concrete artifact you can show:
+
+* an analysis table (CSV)
+* a chart
+* a short memo with the “story” and the assumptions
+
+Suggested workflow by week
+--------------------------
+
+A simple way to work through Track D:
+
+* Start each week with ``d00_peek_data`` to remind yourself what tables exist.
+* Run the chapter wrapper (``dNN``).
+* Open ``outputs/track_d/`` and read the newest memo first.
+* Use the artifacts for your write-up.
+
+To connect the workbook runs to the textbook pages, use the Track D chapter docs
+as your “book”:
+
+* `Track D chapter docs (main site) <https://pystatsv1.readthedocs.io/en/latest/business_intro.html>`_
+
+Troubleshooting
+---------------
+
+* If a chapter fails, try running ``pystatsv1 workbook check business_smoke``
+  to confirm your environment is healthy.
+* If you modified data and things look “weird,” reset with
+  ``pystatsv1 workbook run d00_setup_data --force``.
+* For general workbook workflow tips, see :doc:`workflow`.

docs/source/workbook/workflow.rst

@@ -28,6 +28,11 @@ Run a chapter script:
 
    pystatsv1 workbook run ch18
 
+.. note::
+
+   Track D uses the same loop, but the chapter wrappers are named ``d01``..``d23``
+   and outputs default to ``outputs/track_d/``. See :doc:`track_d`.
+
 Or run a script by path:
 
 .. code-block:: bash