Docs: Track D BYOD GnuCash tutorial pack

docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_daily_totals.csv

@@ -0,0 +1,8 @@
+date,revenue_proxy,expenses_proxy
+2026-01-03,250.0,0.0
+2026-01-05,300.0,20.0
+2026-01-07,180.0,0.0
+2026-01-09,100.0,0.0
+2026-01-02,0.0,120.0
+2026-01-04,0.0,800.0
+2026-01-06,0.0,50.0

docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv

@@ -0,0 +1,22 @@
+Date,Transaction ID,Number,Description,Full Account Name,Account Name,Amount (Num.)
+2026-01-01,TXN-0001,,Owner investment,Assets:Current Assets:Checking,Checking,5000.00
+2026-01-01,TXN-0001,,Owner investment,Equity:Owner Capital,Owner Capital,5000.00
+2026-01-02,TXN-0002,,Buy shipping supplies,Expenses:Supplies,Supplies,120.00
+2026-01-02,TXN-0002,,Buy shipping supplies,Assets:Current Assets:Checking,Checking,-120.00
+2026-01-03,TXN-0003,,Online sale (order #1001),Assets:Current Assets:Checking,Checking,250.00
+2026-01-03,TXN-0003,,Online sale (order #1001),Income:Sales,Sales,250.00
+2026-01-04,TXN-0004,,Rent payment,Expenses:Rent,Rent,800.00
+2026-01-04,TXN-0004,,Rent payment,Assets:Current Assets:Checking,Checking,-800.00
+2026-01-05,TXN-0005,,Online sale (order #1002),Assets:Current Assets:Checking,Checking,300.00
+2026-01-05,TXN-0005,,Online sale (order #1002),Income:Sales,Sales,300.00
+2026-01-05,TXN-0006,,Ship order #1001,Expenses:Shipping,Shipping,20.00
+2026-01-05,TXN-0006,,Ship order #1001,Assets:Current Assets:Checking,Checking,-20.00
+2026-01-06,TXN-0007,,Instagram ads,Expenses:Advertising,Advertising,50.00
+2026-01-06,TXN-0007,,Instagram ads,Assets:Current Assets:Checking,Checking,-50.00
+2026-01-07,TXN-0008,,Online sale (order #1003),Assets:Current Assets:Checking,Checking,180.00
+2026-01-07,TXN-0008,,Online sale (order #1003),Income:Sales,Sales,180.00
+2026-01-09,TXN-0009,,Online sale (order #1004) + sales tax,Assets:Current Assets:Checking,Checking,105.00
+2026-01-09,TXN-0009,,Online sale (order #1004) + sales tax,Income:Sales,Sales,100.00
+2026-01-09,TXN-0009,,Online sale (order #1004) + sales tax,Liabilities:Sales Tax Payable,Sales Tax Payable,5.00
+2026-01-10,TXN-0010,,Buy label printer (card),Assets:Equipment,Equipment,600.00
+2026-01-10,TXN-0010,,Buy label printer (card),Liabilities:Credit Card,Credit Card,600.00

docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv

@@ -0,0 +1,11 @@
+step,date,where_to_enter,description,transfer_to,amount,notes
+1,2026-01-01,Checking register,Owner investment,Equity:Owner Capital,+5000.00,Deposit into checking; transfer to Owner Capital.
+2,2026-01-02,Checking register,Buy shipping supplies,Expenses:Supplies,-120.00,Withdrawal from checking; expense increases.
+3,2026-01-03,Checking register,Online sale (order #1001),Income:Sales,+250.00,Deposit; transfer to Sales income.
+4,2026-01-04,Checking register,Rent payment,Expenses:Rent,-800.00,Withdrawal; rent expense.
+5,2026-01-05,Checking register,Online sale (order #1002),Income:Sales,+300.00,Deposit; transfer to Sales income.
+6,2026-01-05,Checking register,Ship order #1001,Expenses:Shipping,-20.00,Withdrawal; shipping expense.
+7,2026-01-06,Checking register,Instagram ads,Expenses:Advertising,-50.00,Withdrawal; advertising expense.
+8,2026-01-07,Checking register,Online sale (order #1003),Income:Sales,+180.00,Deposit; transfer to Sales income.
+9,2026-01-09,Checking register (split),Online sale (order #1004) + sales tax,Split: Income:Sales (100) AND Liabilities:Sales Tax Payable (5),+105.00,Use a split transaction so the deposit equals 105.
+10,2026-01-10,Credit Card register,Buy label printer (card),Assets:Equipment,+600.00,Charge on card; transfer to Equipment asset (shows as an increase).

docs/source/workbook/index.rst

@@ -19,5 +19,8 @@ PyStatsV1 Workbook
    track_d_dataset_map
    track_d_outputs_guide
    track_d_my_own_data
+   track_d_byod
+   track_d_byod_gnucash
+   track_d_byod_gnucash_demo_analysis
    track_d_assignments
    track_d_lab_ta_notes

docs/source/workbook/track_d_byod.rst

@@ -0,0 +1,69 @@
+.. _track_d_byod:
+
+=================================
+Track D BYOD: Bring Your Own Data
+=================================
+
+Track D is built around a realistic accounting case study (NSO), but the *skills* are meant to transfer.
+
+This BYOD (Bring Your Own Data) pipeline lets you take **real exports** (from a bookkeeping/accounting system)
+and convert them into the same **Track D dataset contract** used in the workbook.
+
+What “BYOD” means in Track D
+----------------------------
+
+Think of BYOD as a boring, reliable 3-step pipeline:
+
+1. **Export** data from a real system (or a CSV you already have).
+2. **Normalize** it into Track D’s canonical tables (``normalized/``).
+3. **Validate + analyze** the normalized tables using the Track D workflow.
+
+The core idea is: *separate the messy export from the clean analysis tables*.
+
+Quick start (template)
+----------------------
+
+Create a BYOD project folder (this writes header-only templates under ``tables/``):
+
+.. code-block:: console
+
+   pystatsv1 trackd byod init --dest byod/my_project --profile core_gl
+
+Edit ``byod/my_project/config.toml`` to choose an adapter (examples):
+
+- ``adapter = "passthrough"`` — your ``tables/`` files are already in Track D’s canonical format
+- ``adapter = "core_gl"`` — generic GL export adapter (varies by source)
+- ``adapter = "gnucash_gl"`` — **GnuCash** “Export Transactions to CSV” (complex layout)
+
+Then normalize:
+
+.. code-block:: console
+
+   pystatsv1 trackd byod normalize --project byod/my_project
+
+You should now have:
+
+- ``byod/my_project/normalized/chart_of_accounts.csv``
+- ``byod/my_project/normalized/gl_journal.csv``
+
+Validate the normalized tables:
+
+.. code-block:: console
+
+   pystatsv1 trackd validate --datadir byod/my_project/normalized --profile core_gl
+
+Next: choose a tutorial
+-----------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   track_d_byod_gnucash
+   track_d_byod_gnucash_demo_analysis
+
+Where this fits in the workbook
+-------------------------------
+
+- If you’re new to Track D, start with :doc:`track_d_student_edition`.
+- If you’re ready to apply the workflow to your own data, see :doc:`track_d_my_own_data`.
+- This BYOD hub is the “how do I get from *my export* to *Track D tables*?” bridge.

docs/source/workbook/track_d_byod_gnucash.rst

@@ -0,0 +1,167 @@
+.. _track_d_byod_gnucash:
+
+===========================================
+Track D BYOD with GnuCash (core_gl profile)
+===========================================
+
+GnuCash is a **free, open-source** double-entry accounting system.
+In Track D, we use it as a “real but accessible” source system:
+
+- it produces realistic **multi-line split** exports (not toy spreadsheets)
+- it teaches a *cleaning + normalization* lesson that matches real analytics work
+- it requires **no trials** and works offline
+
+What you’ll do
+--------------
+
+1. Create a tiny mock business in GnuCash (guided transaction list).
+2. Export your transactions using **Export Transactions to CSV** with **Simple Layout OFF**.
+3. Run the Track D BYOD normalization pipeline to produce:
+
+   - ``normalized/chart_of_accounts.csv``
+   - ``normalized/gl_journal.csv``
+
+Downloads (demo pack)
+---------------------
+
+If you want to follow along quickly, download:
+
+- :download:`Transaction list to enter in GnuCash <_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv>`
+- :download:`Demo export (complex/multi-line) <_downloads/gnucash_demo/gnucash_demo_export_complex.csv>`
+
+The export file above is **adapter-ready** (it matches what the ``gnucash_gl`` adapter expects).
+
+Step 1 — Create a tiny GnuCash book
+-----------------------------------
+
+In GnuCash, create a new file (a “book”).
+
+You can either:
+
+- use a default “Small Business” chart of accounts, *or*
+- create only the accounts you need (minimum below)
+
+Minimum accounts used in the demo:
+
+- ``Assets:Current Assets:Checking``
+- ``Assets:Equipment``
+- ``Liabilities:Credit Card``
+- ``Liabilities:Sales Tax Payable``
+- ``Equity:Owner Capital``
+- ``Income:Sales``
+- ``Expenses:Supplies``
+- ``Expenses:Rent``
+- ``Expenses:Shipping``
+- ``Expenses:Advertising``
+
+Step 2 — Enter the demo transactions
+------------------------------------
+
+Use the downloaded transaction list as your guide:
+
+:download:`gnucash_demo_transactions_to_enter.csv <_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv>`
+
+Tips:
+
+- Most entries can be done in the **Checking** register.
+- For the “sales tax” example, use a **split** transaction.
+- For the credit-card equipment purchase, enter it in the **Credit Card** register.
+
+Step 3 — Export from GnuCash (complex layout)
+---------------------------------------------
+
+Use:
+
+``File → Export → Export Transactions to CSV``
+
+Critical setting:
+
+- **Uncheck** “Simple Layout” (this creates the multi-line export)
+
+Export a CSV that includes your accounts and the date range that covers your demo transactions.
+
+Step 4 — Initialize a Track D BYOD project
+------------------------------------------
+
+From your PyStatsV1 repo root (or any folder you like):
+
+.. code-block:: console
+
+   pystatsv1 trackd byod init --dest byod/gnucash_demo --profile core_gl
+
+This creates:
+
+- ``tables/`` (where you place exports)
+- ``normalized/`` (generated outputs)
+- ``config.toml`` (tiny config: profile, tables_dir, adapter)
+
+Step 5 — Point the project at the GnuCash adapter
+-------------------------------------------------
+
+Open:
+
+``byod/gnucash_demo/config.toml``
+
+Change:
+
+.. code-block:: toml
+
+   [trackd]
+   adapter = "gnucash_gl"
+
+(Leave ``profile = "core_gl"`` as-is.)
+
+Step 6 — Place your export in the expected location
+---------------------------------------------------
+
+Copy your GnuCash export CSV to:
+
+``byod/gnucash_demo/tables/gl_journal.csv``
+
+Yes, the file is called ``gl_journal.csv`` even though it is still “raw export.”
+The adapter reads this file and writes the canonical tables to ``normalized/``.
+
+If you want to test without GnuCash, copy the demo export instead:
+
+.. code-block:: console
+
+   # (Windows PowerShell)
+   copy docs\source\workbook\_downloads\gnucash_demo\gnucash_demo_export_complex.csv byod\gnucash_demo\tables\gl_journal.csv
+
+   # (macOS/Linux)
+   cp docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv byod/gnucash_demo/tables/gl_journal.csv
+
+Step 7 — Normalize
+------------------
+
+Run:
+
+.. code-block:: console
+
+   pystatsv1 trackd byod normalize --project byod/gnucash_demo
+
+You should now have:
+
+- ``byod/gnucash_demo/normalized/chart_of_accounts.csv``
+- ``byod/gnucash_demo/normalized/gl_journal.csv``
+
+Step 8 — Validate the normalized tables
+---------------------------------------
+
+.. code-block:: console
+
+   pystatsv1 trackd validate --datadir byod/gnucash_demo/normalized --profile core_gl
+
+Step 9 — Do a first analysis
+----------------------------
+
+Go to:
+
+- :doc:`track_d_byod_gnucash_demo_analysis` (daily totals + basic plots), or
+- :doc:`track_d_my_own_data` (the general “apply Track D to your data” bridge)
+
+Troubleshooting
+---------------
+
+- If normalization complains about missing columns, re-export and confirm **Simple Layout is OFF**.
+- If numbers import incorrectly (decimal commas, etc.), adjust your export settings so amounts use a ``.`` decimal.

docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst

@@ -0,0 +1,92 @@
+.. _track_d_byod_gnucash_demo_analysis:
+
+===========================================
+GnuCash demo: daily totals + first analysis
+===========================================
+
+Once you have a normalized BYOD project (see :doc:`track_d_byod_gnucash`), you can turn accounting tables into
+a simple “business time series” for basic statistics and forecasting.
+
+What we’ll build
+----------------
+
+A small daily table:
+
+- ``date``
+- ``revenue_proxy`` (credits to Income accounts)
+- ``expenses_proxy`` (debits to Expense accounts)
+
+Download (prebuilt)
+-------------------
+
+If you want to jump straight to analysis without running the normalization step first:
+
+- :download:`gnucash_demo_daily_totals.csv <_downloads/gnucash_demo/gnucash_demo_daily_totals.csv>`
+
+Option A — Build daily totals from your normalized tables
+---------------------------------------------------------
+
+Assume your BYOD project is at ``byod/gnucash_demo`` and you have:
+
+- ``byod/gnucash_demo/normalized/gl_journal.csv``
+- ``byod/gnucash_demo/normalized/chart_of_accounts.csv``
+
+Create a tiny script (for example ``scripts/gnucash_daily_totals.py``) with:
+
+.. code-block:: python
+
+   from pathlib import Path
+   import pandas as pd
+
+   root = Path("byod/gnucash_demo")
+
+   gl = pd.read_csv(root / "normalized" / "gl_journal.csv")
+   coa = pd.read_csv(root / "normalized" / "chart_of_accounts.csv")
+
+   gl["date"] = pd.to_datetime(gl["date"], errors="coerce")
+
+   gl["debit"] = pd.to_numeric(gl["debit"], errors="coerce").fillna(0.0)
+   gl["credit"] = pd.to_numeric(gl["credit"], errors="coerce").fillna(0.0)
+
+   gl = gl.merge(coa[["account_id", "account_type"]], on="account_id", how="left")
+
+   revenue = (
+       gl.query("account_type == 'Income'")
+         .groupby(gl["date"].dt.date)["credit"]
+         .sum()
+         .rename("revenue_proxy")
+   )
+
+   expenses = (
+       gl.query("account_type == 'Expenses'")
+         .groupby(gl["date"].dt.date)["debit"]
+         .sum()
+         .rename("expenses_proxy")
+   )
+
+   daily = (
+       pd.concat([revenue, expenses], axis=1)
+         .fillna(0.0)
+         .reset_index()
+         .rename(columns={"index": "date"})
+   )
+
+   out = root / "normalized" / "daily_totals.csv"
+   daily.to_csv(out, index=False)
+   print("Wrote:", out)
+   print(daily)
+
+Option B — Run the existing “My Own Data” explore scaffold
+----------------------------------------------------------
+
+PyStatsV1 includes a beginner-friendly scaffold script:
+
+``scripts/my_data_01_explore.py``
+
+Run it against the daily totals CSV (either the prebuilt download, or the file you generated above):
+
+.. code-block:: console
+
+   python scripts/my_data_01_explore.py --csv byod/gnucash_demo/normalized/daily_totals.csv --outdir outputs/gnucash_demo
+
+This will write a few simple outputs under ``outputs/gnucash_demo/`` (tables + quick plots).

docs/source/workbook/track_d_my_own_data.rst

@@ -14,6 +14,13 @@ and your own accounting / bookkeeping / finance data.
 - run **checks** (duplicates, missingness, reconciliations)
 - produce **reproducible outputs** (tables + charts + short memo)
 
+.. tip::
+
+   If your starting point is a **real export** (GnuCash / QuickBooks / bank / invoices),
+   begin with :doc:`track_d_byod` to normalize it into Track D’s canonical tables.
+   Then come back to this page for the analysis checklist.
+
+
 If you haven’t yet, skim these pages first:
 
 - :doc:`track_d_student_edition` (entry point)