From aa2ef610178f41b4c09b09ad602e641aa680fbc1 Mon Sep 17 00:00:00 2001 From: Nicholas Karlson Date: Wed, 21 Jan 2026 02:27:46 -0800 Subject: [PATCH] Docs: Track D BYOD hub + GnuCash tutorial + demo downloads --- .../gnucash_demo_daily_totals.csv | 8 + .../gnucash_demo_export_complex.csv | 22 +++ .../gnucash_demo_transactions_to_enter.csv | 11 ++ docs/source/workbook/index.rst | 3 + docs/source/workbook/track_d_byod.rst | 69 ++++++++ docs/source/workbook/track_d_byod_gnucash.rst | 167 ++++++++++++++++++ .../track_d_byod_gnucash_demo_analysis.rst | 92 ++++++++++ docs/source/workbook/track_d_my_own_data.rst | 7 + .../workbook/track_d_student_edition.rst | 8 +- 9 files changed, 385 insertions(+), 2 deletions(-) create mode 100644 docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_daily_totals.csv create mode 100644 docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv create mode 100644 docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv create mode 100644 docs/source/workbook/track_d_byod.rst create mode 100644 docs/source/workbook/track_d_byod_gnucash.rst create mode 100644 docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst diff --git a/docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_daily_totals.csv b/docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_daily_totals.csv new file mode 100644 index 0000000..f747370 --- /dev/null +++ b/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 diff --git a/docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv b/docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv new file mode 100644 index 0000000..874307d --- /dev/null +++ b/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 diff --git a/docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv b/docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv new file mode 100644 index 0000000..8075222 --- /dev/null +++ b/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). diff --git a/docs/source/workbook/index.rst b/docs/source/workbook/index.rst index d6ae282..9ce2786 100644 --- a/docs/source/workbook/index.rst +++ b/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 diff --git a/docs/source/workbook/track_d_byod.rst b/docs/source/workbook/track_d_byod.rst new file mode 100644 index 0000000..b97e197 --- /dev/null +++ b/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. diff --git a/docs/source/workbook/track_d_byod_gnucash.rst b/docs/source/workbook/track_d_byod_gnucash.rst new file mode 100644 index 0000000..222f7eb --- /dev/null +++ b/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. diff --git a/docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst b/docs/source/workbook/track_d_byod_gnucash_demo_analysis.rst new file mode 100644 index 0000000..1e729d0 --- /dev/null +++ b/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). diff --git a/docs/source/workbook/track_d_my_own_data.rst b/docs/source/workbook/track_d_my_own_data.rst index 8e1cdcd..ae4b436 100644 --- a/docs/source/workbook/track_d_my_own_data.rst +++ b/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) diff --git a/docs/source/workbook/track_d_student_edition.rst b/docs/source/workbook/track_d_student_edition.rst index 19217a1..73e28e2 100644 --- a/docs/source/workbook/track_d_student_edition.rst +++ b/docs/source/workbook/track_d_student_edition.rst @@ -173,13 +173,17 @@ By the end of Track D you should be able to: - Produce a simple forecast and scenario analysis with clear assumptions. - Write a short memo that a manager could actually use. + How to apply Track D to your own data ------------------------------------- For a general starting point, see :doc:`my_own_data`. -Track D will also include a Track D-specific “Bring Your Own Data” playbook that shows how to map real -exports (QuickBooks / bank / invoices) to the same **dataset contract** used in the NSO synthetic case. +For Track D specifically: + +- Start with :doc:`track_d_my_own_data` (what to analyze + what to check). +- Use :doc:`track_d_byod` to turn a **real export** into Track D’s canonical tables (the BYOD pipeline). + Next page