From 6a64b7102d5d1cd1110cfbb26b19d0c2f850f749 Mon Sep 17 00:00:00 2001 From: Nicholas Karlson Date: Sun, 18 Jan 2026 14:06:11 -0800 Subject: [PATCH] Docs: add Track D outputs guide (workbook) --- docs/source/workbook/index.rst | 1 + docs/source/workbook/track_d.rst | 3 + docs/source/workbook/track_d_lab_ta_notes.rst | 1 + .../source/workbook/track_d_outputs_guide.rst | 221 ++++++++++++++++++ .../workbook/track_d_student_edition.rst | 1 + 5 files changed, 227 insertions(+) create mode 100644 docs/source/workbook/track_d_outputs_guide.rst diff --git a/docs/source/workbook/index.rst b/docs/source/workbook/index.rst index 2ad8e18..9ab6452 100644 --- a/docs/source/workbook/index.rst +++ b/docs/source/workbook/index.rst @@ -15,4 +15,5 @@ PyStatsV1 Workbook track_c track_d_student_edition track_d + track_d_outputs_guide track_d_lab_ta_notes \ No newline at end of file diff --git a/docs/source/workbook/track_d.rst b/docs/source/workbook/track_d.rst index ff32a35..3f92b4c 100644 --- a/docs/source/workbook/track_d.rst +++ b/docs/source/workbook/track_d.rst @@ -137,6 +137,9 @@ 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 +For a practical walkthrough of the most common output files (CSV/JSON/PNG) and how to use them in a +write-up, see :doc:`track_d_outputs_guide`. + A typical chapter produces: * one or more ``.csv`` artifacts (tables you can open in Excel) diff --git a/docs/source/workbook/track_d_lab_ta_notes.rst b/docs/source/workbook/track_d_lab_ta_notes.rst index e969f92..cddd409 100644 --- a/docs/source/workbook/track_d_lab_ta_notes.rst +++ b/docs/source/workbook/track_d_lab_ta_notes.rst @@ -228,6 +228,7 @@ TA line: “Trial balance is the structured ledger; statements are the story.” pystatsv1 workbook run d01 It prints **Checks** and **Key metrics**, then writes artifacts under ``outputs/track_d``. +If students ask "what is this file?", point them to :doc:`track_d_outputs_guide`. 7.1 Checks (what they mean) --------------------------- diff --git a/docs/source/workbook/track_d_outputs_guide.rst b/docs/source/workbook/track_d_outputs_guide.rst new file mode 100644 index 0000000..38d7448 --- /dev/null +++ b/docs/source/workbook/track_d_outputs_guide.rst @@ -0,0 +1,221 @@ +Track D Outputs Guide +===================== + +This page explains what Track D writes to disk when you run workbook scripts, where those files go, and +how to use them in a lab, assignment, or your own analysis. + +Why outputs matter +------------------ + +Track D is designed so you practice two real-world skills at once: + +1. **Accounting-data discipline**: checks that the data behave like a coherent accounting system + (balanced postings, accounting equation consistency, etc.). +2. **Analytics discipline**: metrics, tables, and plots that turn accounting data into decisions. + +The **files written to** ``outputs/`` are the evidence trail for both. + +Where outputs go +---------------- + +By default, Track D scripts write into a folder under your workbook directory: + +.. code-block:: text + + / + outputs/ + track_d/ + +Example (Windows): + +.. code-block:: text + + C:\Users\nicho\Videos\Python\Test6PyStatsV1\track_d_workbook\outputs\track_d + +All Track D scripts use the same convention so you always know where to look. + +Tip: if you run a script and nothing appears to change in ``outputs/track_d``, you may not be in the +workbook folder. Run ``pwd`` (Git Bash) to confirm you are inside your ``track_d_workbook`` directory. + +What kinds of files you get +--------------------------- + +Track D outputs are intentionally simple and "Excel-friendly": + +**1) Summary JSON (machine-readable)** + +Many chapters write a compact ``*.json`` summary you can: + +* read in a text editor +* load in Python for grading or reporting +* compare across runs (did your results change?) + +**2) Tables as CSV (spreadsheet-friendly)** + +Common derived tables are written as ``*.csv`` so you can open them in: + +* Excel / Google Sheets +* pandas + +These are often the best starting point for "what is the data doing?" + +**3) Plots as PNG (report-friendly)** + +Chapters that produce visuals write ``*.png`` files so you can paste them into: + +* a lab write-up +* a slide deck +* a memo + +**4) Human-readable Markdown summaries (quick scan)** + +Some utilities (like ``d00_peek_data``) write a ``*.md`` file that you can read immediately. + +The Track D output folder layout +-------------------------------- + +After you run a few scripts, ``outputs/track_d`` will look something like this: + +.. code-block:: text + + outputs/track_d/ + d00_peek_data_summary.md + business_ch01_summary.json + business_ch01_cash_flow_bridge.png + business_ch01_trial_balance.png + ... + +The exact filenames vary by chapter. + +**The most important rule:** each chapter script declares its expected outputs at the top of the file. +Open the script (in your workbook folder under ``scripts/``) and look at the docstring. + +Example from Chapter 1: + +.. code-block:: text + + scripts/business_ch01_accounting_measurement.py + Outputs -> outputs/track_d/ + - business_ch01_summary.json + - business_ch01_trial_balance.png + - business_ch01_cash_flow_bridge.png + +Interpreting the console output +------------------------------- + +Most Track D scripts print two blocks to your terminal: + +**Checks** + These are pass/fail guards. They answer: *"Is the dataset coherent?"* and *"Did we violate an + accounting invariant?"* + +**Key metrics** + These are the results. They answer: *"What happened in the business?"* and *"What should we do next?"* + +Example (abridged): + +.. code-block:: console + + $ pystatsv1 workbook run d01 + + Checks: + - transactions_balanced: True + - accounting_equation_balances: True + + Key metrics: + - sales_total: 4079.3879 + - gross_margin_pct: 0.4500 + - net_income: -2155.5873 + - ending_cash: 2974.2179 + +How to explain that to students: + +* **Checks** tell you whether it's safe to trust the results. +* **Metrics** are the business story. + +For example, a negative net income does *not* mean the analysis "failed". It might mean: + +* the business spent heavily in a startup month (rent, equipment, payroll), +* revenue hasn't ramped up yet, +* or costs were higher than expected. + +The job of the analyst is to connect those numbers back to the underlying transaction patterns. + +Fast workflow: from outputs to a write-up +----------------------------------------- + +This is a reliable "lab rhythm" that works for almost any Track D chapter: + +1. Run the script. + + .. code-block:: console + + pystatsv1 workbook run d01 + +2. Read the console output (Checks + Key metrics). + +3. Open the files in ``outputs/track_d``. + + * open ``*.png`` plots first to get intuition + * open ``*.csv`` tables next to find the rows driving the story + * use the ``*.json`` summary as your "official" numbers + +4. Write 4-6 sentences: + + * What checks matter here and did we pass them? + * What are the two most important metrics? + * What is your hypothesis for why those numbers look that way? + * What would you check next (a drill-down or follow-up plot)? + +Optional: changing the output location +-------------------------------------- + +Most Track D scripts support an ``--outdir`` argument. + +This is useful if you want one folder per lab group, or you want to keep a "clean" outputs folder. + +.. code-block:: console + + pystatsv1 workbook run d01 --outdir outputs/track_d_groupA + +If you are new to command-line tools, ignore this at first and use the default. + +Common gotchas +-------------- + +**"My outputs aren't showing up"** + Make sure you are in the workbook folder (the one that contains ``data/``, ``scripts/``, and + ``outputs/``). In Git Bash: ``pwd``. + +**"I edited the data and now results look weird"** + Track D ships canonical seed=123 datasets so everyone starts from the same baseline. + If you want to reset, run: + + .. code-block:: console + + pystatsv1 workbook run d00_setup_data --force + +**"Why are there so many files?"** + This is intentional. In real analytics work, outputs are what let you: + + * reproduce results + * audit calculations + * review someone else's analysis + * grade consistently + +Appendix: reading a JSON summary in Python +------------------------------------------ + +If you want to pull "official" metrics into a notebook, start with the JSON summary. + +.. code-block:: python + + import json + from pathlib import Path + + summary_path = Path("outputs/track_d/business_ch01_summary.json") + summary = json.loads(summary_path.read_text(encoding="utf-8")) + + summary["key_metrics"]["net_income"], summary["key_metrics"]["gross_margin_pct"] + +You can then build your own tables/plots on top of those saved artifacts. diff --git a/docs/source/workbook/track_d_student_edition.rst b/docs/source/workbook/track_d_student_edition.rst index c72d5d3..aa270f6 100644 --- a/docs/source/workbook/track_d_student_edition.rst +++ b/docs/source/workbook/track_d_student_edition.rst @@ -129,6 +129,7 @@ A good weekly rhythm: 1) Run the chapter script (``pystatsv1 workbook run dXX``). 2) Open what it writes in ``outputs/track_d/`` (tables + summaries). + If you are not sure what a file is for, use :doc:`track_d_outputs_guide`. 3) Answer the chapter questions *in words* (what changed, why, what action follows). 4) Run the smoke checks (``pystatsv1 workbook check business_smoke``).