Skip to content

Commit ec1e420

Browse files
nicholaskarlsonnicholaskarlson
authored
Docs: Track D BYOD hub + GnuCash tutorial + demo downloads (#321)
1 parent d60a7fc commit ec1e420

9 files changed

Lines changed: 385 additions & 2 deletions

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
date,revenue_proxy,expenses_proxy
2+
2026-01-03,250.0,0.0
3+
2026-01-05,300.0,20.0
4+
2026-01-07,180.0,0.0
5+
2026-01-09,100.0,0.0
6+
2026-01-02,0.0,120.0
7+
2026-01-04,0.0,800.0
8+
2026-01-06,0.0,50.0

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Date,Transaction ID,Number,Description,Full Account Name,Account Name,Amount (Num.)
2+
2026-01-01,TXN-0001,,Owner investment,Assets:Current Assets:Checking,Checking,5000.00
3+
2026-01-01,TXN-0001,,Owner investment,Equity:Owner Capital,Owner Capital,5000.00
4+
2026-01-02,TXN-0002,,Buy shipping supplies,Expenses:Supplies,Supplies,120.00
5+
2026-01-02,TXN-0002,,Buy shipping supplies,Assets:Current Assets:Checking,Checking,-120.00
6+
2026-01-03,TXN-0003,,Online sale (order #1001),Assets:Current Assets:Checking,Checking,250.00
7+
2026-01-03,TXN-0003,,Online sale (order #1001),Income:Sales,Sales,250.00
8+
2026-01-04,TXN-0004,,Rent payment,Expenses:Rent,Rent,800.00
9+
2026-01-04,TXN-0004,,Rent payment,Assets:Current Assets:Checking,Checking,-800.00
10+
2026-01-05,TXN-0005,,Online sale (order #1002),Assets:Current Assets:Checking,Checking,300.00
11+
2026-01-05,TXN-0005,,Online sale (order #1002),Income:Sales,Sales,300.00
12+
2026-01-05,TXN-0006,,Ship order #1001,Expenses:Shipping,Shipping,20.00
13+
2026-01-05,TXN-0006,,Ship order #1001,Assets:Current Assets:Checking,Checking,-20.00
14+
2026-01-06,TXN-0007,,Instagram ads,Expenses:Advertising,Advertising,50.00
15+
2026-01-06,TXN-0007,,Instagram ads,Assets:Current Assets:Checking,Checking,-50.00
16+
2026-01-07,TXN-0008,,Online sale (order #1003),Assets:Current Assets:Checking,Checking,180.00
17+
2026-01-07,TXN-0008,,Online sale (order #1003),Income:Sales,Sales,180.00
18+
2026-01-09,TXN-0009,,Online sale (order #1004) + sales tax,Assets:Current Assets:Checking,Checking,105.00
19+
2026-01-09,TXN-0009,,Online sale (order #1004) + sales tax,Income:Sales,Sales,100.00
20+
2026-01-09,TXN-0009,,Online sale (order #1004) + sales tax,Liabilities:Sales Tax Payable,Sales Tax Payable,5.00
21+
2026-01-10,TXN-0010,,Buy label printer (card),Assets:Equipment,Equipment,600.00
22+
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‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
step,date,where_to_enter,description,transfer_to,amount,notes
2+
1,2026-01-01,Checking register,Owner investment,Equity:Owner Capital,+5000.00,Deposit into checking; transfer to Owner Capital.
3+
2,2026-01-02,Checking register,Buy shipping supplies,Expenses:Supplies,-120.00,Withdrawal from checking; expense increases.
4+
3,2026-01-03,Checking register,Online sale (order #1001),Income:Sales,+250.00,Deposit; transfer to Sales income.
5+
4,2026-01-04,Checking register,Rent payment,Expenses:Rent,-800.00,Withdrawal; rent expense.
6+
5,2026-01-05,Checking register,Online sale (order #1002),Income:Sales,+300.00,Deposit; transfer to Sales income.
7+
6,2026-01-05,Checking register,Ship order #1001,Expenses:Shipping,-20.00,Withdrawal; shipping expense.
8+
7,2026-01-06,Checking register,Instagram ads,Expenses:Advertising,-50.00,Withdrawal; advertising expense.
9+
8,2026-01-07,Checking register,Online sale (order #1003),Income:Sales,+180.00,Deposit; transfer to Sales income.
10+
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.
11+
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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,8 @@ PyStatsV1 Workbook
1919
track_d_dataset_map
2020
track_d_outputs_guide
2121
track_d_my_own_data
22+
track_d_byod
23+
track_d_byod_gnucash
24+
track_d_byod_gnucash_demo_analysis
2225
track_d_assignments
2326
track_d_lab_ta_notes

‎docs/source/workbook/track_d_byod.rst‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
.. _track_d_byod:
2+
3+
=================================
4+
Track D BYOD: Bring Your Own Data
5+
=================================
6+
7+
Track D is built around a realistic accounting case study (NSO), but the *skills* are meant to transfer.
8+
9+
This BYOD (Bring Your Own Data) pipeline lets you take **real exports** (from a bookkeeping/accounting system)
10+
and convert them into the same **Track D dataset contract** used in the workbook.
11+
12+
What “BYOD” means in Track D
13+
----------------------------
14+
15+
Think of BYOD as a boring, reliable 3-step pipeline:
16+
17+
1. **Export** data from a real system (or a CSV you already have).
18+
2. **Normalize** it into Track D’s canonical tables (``normalized/``).
19+
3. **Validate + analyze** the normalized tables using the Track D workflow.
20+
21+
The core idea is: *separate the messy export from the clean analysis tables*.
22+
23+
Quick start (template)
24+
----------------------
25+
26+
Create a BYOD project folder (this writes header-only templates under ``tables/``):
27+
28+
.. code-block:: console
29+
30+
pystatsv1 trackd byod init --dest byod/my_project --profile core_gl
31+
32+
Edit ``byod/my_project/config.toml`` to choose an adapter (examples):
33+
34+
- ``adapter = "passthrough"`` — your ``tables/`` files are already in Track D’s canonical format
35+
- ``adapter = "core_gl"`` — generic GL export adapter (varies by source)
36+
- ``adapter = "gnucash_gl"`` — **GnuCash** “Export Transactions to CSV” (complex layout)
37+
38+
Then normalize:
39+
40+
.. code-block:: console
41+
42+
pystatsv1 trackd byod normalize --project byod/my_project
43+
44+
You should now have:
45+
46+
- ``byod/my_project/normalized/chart_of_accounts.csv``
47+
- ``byod/my_project/normalized/gl_journal.csv``
48+
49+
Validate the normalized tables:
50+
51+
.. code-block:: console
52+
53+
pystatsv1 trackd validate --datadir byod/my_project/normalized --profile core_gl
54+
55+
Next: choose a tutorial
56+
-----------------------
57+
58+
.. toctree::
59+
:maxdepth: 1
60+
61+
track_d_byod_gnucash
62+
track_d_byod_gnucash_demo_analysis
63+
64+
Where this fits in the workbook
65+
-------------------------------
66+
67+
- If you’re new to Track D, start with :doc:`track_d_student_edition`.
68+
- If you’re ready to apply the workflow to your own data, see :doc:`track_d_my_own_data`.
69+
- 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‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
.. _track_d_byod_gnucash:
2+
3+
===========================================
4+
Track D BYOD with GnuCash (core_gl profile)
5+
===========================================
6+
7+
GnuCash is a **free, open-source** double-entry accounting system.
8+
In Track D, we use it as a “real but accessible” source system:
9+
10+
- it produces realistic **multi-line split** exports (not toy spreadsheets)
11+
- it teaches a *cleaning + normalization* lesson that matches real analytics work
12+
- it requires **no trials** and works offline
13+
14+
What you’ll do
15+
--------------
16+
17+
1. Create a tiny mock business in GnuCash (guided transaction list).
18+
2. Export your transactions using **Export Transactions to CSV** with **Simple Layout OFF**.
19+
3. Run the Track D BYOD normalization pipeline to produce:
20+
21+
- ``normalized/chart_of_accounts.csv``
22+
- ``normalized/gl_journal.csv``
23+
24+
Downloads (demo pack)
25+
---------------------
26+
27+
If you want to follow along quickly, download:
28+
29+
- :download:`Transaction list to enter in GnuCash <_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv>`
30+
- :download:`Demo export (complex/multi-line) <_downloads/gnucash_demo/gnucash_demo_export_complex.csv>`
31+
32+
The export file above is **adapter-ready** (it matches what the ``gnucash_gl`` adapter expects).
33+
34+
Step 1 — Create a tiny GnuCash book
35+
-----------------------------------
36+
37+
In GnuCash, create a new file (a “book”).
38+
39+
You can either:
40+
41+
- use a default “Small Business” chart of accounts, *or*
42+
- create only the accounts you need (minimum below)
43+
44+
Minimum accounts used in the demo:
45+
46+
- ``Assets:Current Assets:Checking``
47+
- ``Assets:Equipment``
48+
- ``Liabilities:Credit Card``
49+
- ``Liabilities:Sales Tax Payable``
50+
- ``Equity:Owner Capital``
51+
- ``Income:Sales``
52+
- ``Expenses:Supplies``
53+
- ``Expenses:Rent``
54+
- ``Expenses:Shipping``
55+
- ``Expenses:Advertising``
56+
57+
Step 2 — Enter the demo transactions
58+
------------------------------------
59+
60+
Use the downloaded transaction list as your guide:
61+
62+
:download:`gnucash_demo_transactions_to_enter.csv <_downloads/gnucash_demo/gnucash_demo_transactions_to_enter.csv>`
63+
64+
Tips:
65+
66+
- Most entries can be done in the **Checking** register.
67+
- For the “sales tax” example, use a **split** transaction.
68+
- For the credit-card equipment purchase, enter it in the **Credit Card** register.
69+
70+
Step 3 — Export from GnuCash (complex layout)
71+
---------------------------------------------
72+
73+
Use:
74+
75+
``File → Export → Export Transactions to CSV``
76+
77+
Critical setting:
78+
79+
- **Uncheck** “Simple Layout” (this creates the multi-line export)
80+
81+
Export a CSV that includes your accounts and the date range that covers your demo transactions.
82+
83+
Step 4 — Initialize a Track D BYOD project
84+
------------------------------------------
85+
86+
From your PyStatsV1 repo root (or any folder you like):
87+
88+
.. code-block:: console
89+
90+
pystatsv1 trackd byod init --dest byod/gnucash_demo --profile core_gl
91+
92+
This creates:
93+
94+
- ``tables/`` (where you place exports)
95+
- ``normalized/`` (generated outputs)
96+
- ``config.toml`` (tiny config: profile, tables_dir, adapter)
97+
98+
Step 5 — Point the project at the GnuCash adapter
99+
-------------------------------------------------
100+
101+
Open:
102+
103+
``byod/gnucash_demo/config.toml``
104+
105+
Change:
106+
107+
.. code-block:: toml
108+
109+
[trackd]
110+
adapter = "gnucash_gl"
111+
112+
(Leave ``profile = "core_gl"`` as-is.)
113+
114+
Step 6 — Place your export in the expected location
115+
---------------------------------------------------
116+
117+
Copy your GnuCash export CSV to:
118+
119+
``byod/gnucash_demo/tables/gl_journal.csv``
120+
121+
Yes, the file is called ``gl_journal.csv`` even though it is still “raw export.”
122+
The adapter reads this file and writes the canonical tables to ``normalized/``.
123+
124+
If you want to test without GnuCash, copy the demo export instead:
125+
126+
.. code-block:: console
127+
128+
# (Windows PowerShell)
129+
copy docs\source\workbook\_downloads\gnucash_demo\gnucash_demo_export_complex.csv byod\gnucash_demo\tables\gl_journal.csv
130+
131+
# (macOS/Linux)
132+
cp docs/source/workbook/_downloads/gnucash_demo/gnucash_demo_export_complex.csv byod/gnucash_demo/tables/gl_journal.csv
133+
134+
Step 7 — Normalize
135+
------------------
136+
137+
Run:
138+
139+
.. code-block:: console
140+
141+
pystatsv1 trackd byod normalize --project byod/gnucash_demo
142+
143+
You should now have:
144+
145+
- ``byod/gnucash_demo/normalized/chart_of_accounts.csv``
146+
- ``byod/gnucash_demo/normalized/gl_journal.csv``
147+
148+
Step 8 — Validate the normalized tables
149+
---------------------------------------
150+
151+
.. code-block:: console
152+
153+
pystatsv1 trackd validate --datadir byod/gnucash_demo/normalized --profile core_gl
154+
155+
Step 9 — Do a first analysis
156+
----------------------------
157+
158+
Go to:
159+
160+
- :doc:`track_d_byod_gnucash_demo_analysis` (daily totals + basic plots), or
161+
- :doc:`track_d_my_own_data` (the general “apply Track D to your data” bridge)
162+
163+
Troubleshooting
164+
---------------
165+
166+
- If normalization complains about missing columns, re-export and confirm **Simple Layout is OFF**.
167+
- 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‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
.. _track_d_byod_gnucash_demo_analysis:
2+
3+
===========================================
4+
GnuCash demo: daily totals + first analysis
5+
===========================================
6+
7+
Once you have a normalized BYOD project (see :doc:`track_d_byod_gnucash`), you can turn accounting tables into
8+
a simple “business time series” for basic statistics and forecasting.
9+
10+
What we’ll build
11+
----------------
12+
13+
A small daily table:
14+
15+
- ``date``
16+
- ``revenue_proxy`` (credits to Income accounts)
17+
- ``expenses_proxy`` (debits to Expense accounts)
18+
19+
Download (prebuilt)
20+
-------------------
21+
22+
If you want to jump straight to analysis without running the normalization step first:
23+
24+
- :download:`gnucash_demo_daily_totals.csv <_downloads/gnucash_demo/gnucash_demo_daily_totals.csv>`
25+
26+
Option A — Build daily totals from your normalized tables
27+
---------------------------------------------------------
28+
29+
Assume your BYOD project is at ``byod/gnucash_demo`` and you have:
30+
31+
- ``byod/gnucash_demo/normalized/gl_journal.csv``
32+
- ``byod/gnucash_demo/normalized/chart_of_accounts.csv``
33+
34+
Create a tiny script (for example ``scripts/gnucash_daily_totals.py``) with:
35+
36+
.. code-block:: python
37+
38+
from pathlib import Path
39+
import pandas as pd
40+
41+
root = Path("byod/gnucash_demo")
42+
43+
gl = pd.read_csv(root / "normalized" / "gl_journal.csv")
44+
coa = pd.read_csv(root / "normalized" / "chart_of_accounts.csv")
45+
46+
gl["date"] = pd.to_datetime(gl["date"], errors="coerce")
47+
48+
gl["debit"] = pd.to_numeric(gl["debit"], errors="coerce").fillna(0.0)
49+
gl["credit"] = pd.to_numeric(gl["credit"], errors="coerce").fillna(0.0)
50+
51+
gl = gl.merge(coa[["account_id", "account_type"]], on="account_id", how="left")
52+
53+
revenue = (
54+
gl.query("account_type == 'Income'")
55+
.groupby(gl["date"].dt.date)["credit"]
56+
.sum()
57+
.rename("revenue_proxy")
58+
)
59+
60+
expenses = (
61+
gl.query("account_type == 'Expenses'")
62+
.groupby(gl["date"].dt.date)["debit"]
63+
.sum()
64+
.rename("expenses_proxy")
65+
)
66+
67+
daily = (
68+
pd.concat([revenue, expenses], axis=1)
69+
.fillna(0.0)
70+
.reset_index()
71+
.rename(columns={"index": "date"})
72+
)
73+
74+
out = root / "normalized" / "daily_totals.csv"
75+
daily.to_csv(out, index=False)
76+
print("Wrote:", out)
77+
print(daily)
78+
79+
Option B — Run the existing “My Own Data” explore scaffold
80+
----------------------------------------------------------
81+
82+
PyStatsV1 includes a beginner-friendly scaffold script:
83+
84+
``scripts/my_data_01_explore.py``
85+
86+
Run it against the daily totals CSV (either the prebuilt download, or the file you generated above):
87+
88+
.. code-block:: console
89+
90+
python scripts/my_data_01_explore.py --csv byod/gnucash_demo/normalized/daily_totals.csv --outdir outputs/gnucash_demo
91+
92+
This will write a few simple outputs under ``outputs/gnucash_demo/`` (tables + quick plots).

‎docs/source/workbook/track_d_my_own_data.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,13 @@ and your own accounting / bookkeeping / finance data.
1414
- run **checks** (duplicates, missingness, reconciliations)
1515
- produce **reproducible outputs** (tables + charts + short memo)
1616

17+
.. tip::
18+
19+
If your starting point is a **real export** (GnuCash / QuickBooks / bank / invoices),
20+
begin with :doc:`track_d_byod` to normalize it into Track D’s canonical tables.
21+
Then come back to this page for the analysis checklist.
22+
23+
1724
If you haven’t yet, skim these pages first:
1825

1926
- :doc:`track_d_student_edition` (entry point)

0 commit comments

Comments
 (0)