diff --git a/docs/source/business_intro.rst b/docs/source/business_intro.rst index e77dede..f266191 100644 --- a/docs/source/business_intro.rst +++ b/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: diff --git a/docs/source/workbook/index.rst b/docs/source/workbook/index.rst index 51f4407..658a4c1 100644 --- a/docs/source/workbook/index.rst +++ b/docs/source/workbook/index.rst @@ -13,3 +13,4 @@ PyStatsV1 Workbook my_own_data troubleshooting track_c + track_d diff --git a/docs/source/workbook/quickstart.rst b/docs/source/workbook/quickstart.rst index 7f03a7b..59f8770 100644 --- a/docs/source/workbook/quickstart.rst +++ b/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). diff --git a/docs/source/workbook/track_d.rst b/docs/source/workbook/track_d.rst new file mode 100644 index 0000000..84feedd --- /dev/null +++ b/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) `_ + +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) `_ + +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) `_ + +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`. diff --git a/docs/source/workbook/workflow.rst b/docs/source/workbook/workflow.rst index 867b99e..d07db1d 100644 --- a/docs/source/workbook/workflow.rst +++ b/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