data-analyst-mcp 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +262 -262
- package/dist/report/method_audit.js +7 -1
- package/dist/report/method_audit.js.map +1 -1
- package/dist/report/scan_secrets.d.ts +4 -1
- package/dist/report/scan_secrets.js +36 -5
- package/dist/report/scan_secrets.js.map +1 -1
- package/dist/server.d.ts +1 -1
- package/dist/server.js +3 -2
- package/dist/server.js.map +1 -1
- package/guide/WORKFLOW.md +134 -134
- package/guide/assets/disclaimer.txt +1 -1
- package/guide/assets/download_data.ps1 +162 -162
- package/guide/assets/report_template.html +597 -597
- package/guide/references/routing.md +171 -171
- package/guide/references/style_guide.md +398 -398
- package/package.json +56 -56
- package/packs/acf/endpoints.json +114 -114
- package/packs/acf/policy.json +104 -104
- package/packs/actuaries/endpoints.json +82 -82
- package/packs/actuaries/policy.json +109 -109
- package/packs/bea/assets/download_bea.ps1 +182 -182
- package/packs/bea/docs/bea_api.md +461 -461
- package/packs/bea/docs/datasets.md +157 -157
- package/packs/bea/docs/report_patterns.md +112 -112
- package/packs/bea/policy.json +170 -170
- package/packs/bea/source.md +152 -152
- package/packs/bls/assets/download_bls.ps1 +152 -152
- package/packs/bls/docs/analysis_patterns.md +108 -108
- package/packs/bls/docs/bls_api.md +73 -73
- package/packs/bls/docs/series_ids.md +149 -149
- package/packs/bls/policy.json +238 -238
- package/packs/bts/endpoints.json +346 -346
- package/packs/bts/policy.json +94 -94
- package/packs/cdc/endpoints.json +197 -197
- package/packs/cdc/policy.json +83 -83
- package/packs/census/endpoints.json +99 -99
- package/packs/cfpb/endpoints.json +326 -326
- package/packs/cfpb/policy.json +119 -119
- package/packs/clinical-trials/endpoints.json +166 -166
- package/packs/clinical-trials/policy.json +84 -84
- package/packs/cms/endpoints.json +69 -69
- package/packs/cms/policy.json +96 -96
- package/packs/college-scorecard/endpoints.json +252 -252
- package/packs/college-scorecard/policy.json +106 -106
- package/packs/congress/endpoints.json +1701 -1701
- package/packs/congress/policy.json +117 -117
- package/packs/dhs-ohss/endpoints.json +66 -66
- package/packs/dhs-ohss/policy.json +107 -107
- package/packs/doj-news/endpoints.json +59 -59
- package/packs/doj-news/policy.json +96 -96
- package/packs/dol/endpoints.json +817 -817
- package/packs/dol/policy.json +135 -135
- package/packs/eia/endpoints.json +717 -717
- package/packs/eia/policy.json +112 -112
- package/packs/epa/endpoints.json +291 -291
- package/packs/epa/policy.json +99 -99
- package/packs/epa-aqs/endpoints.json +173 -173
- package/packs/epa-aqs/policy.json +96 -96
- package/packs/fbi/endpoints.json +1841 -1841
- package/packs/fbi/policy.json +118 -118
- package/packs/fda/endpoints.json +237 -237
- package/packs/fda/policy.json +121 -121
- package/packs/fdic/endpoints.json +416 -416
- package/packs/fdic/policy.json +83 -83
- package/packs/fec/endpoints.json +707 -707
- package/packs/fec/policy.json +93 -93
- package/packs/fed-board/endpoints.json +89 -89
- package/packs/fed-board/policy.json +136 -136
- package/packs/federal-register/endpoints.json +143 -143
- package/packs/federal-register/policy.json +86 -86
- package/packs/fema/endpoints.json +645 -645
- package/packs/fema/policy.json +103 -103
- package/packs/fhfa/endpoints.json +105 -105
- package/packs/fhfa/policy.json +109 -109
- package/packs/fred/assets/download_fred.ps1 +122 -122
- package/packs/fred/docs/analysis_patterns.md +124 -124
- package/packs/fred/docs/fred_api.md +94 -94
- package/packs/fred/docs/series.md +188 -188
- package/packs/fred/policy.json +253 -253
- package/packs/fsa/endpoints.json +150 -150
- package/packs/fsa/policy.json +99 -99
- package/packs/govinfo/endpoints.json +519 -519
- package/packs/gsa-calc/endpoints.json +93 -93
- package/packs/gsa-calc/policy.json +97 -97
- package/packs/hud/endpoints.json +146 -146
- package/packs/hud/policy.json +84 -84
- package/packs/ipums/docs/report_patterns.md +117 -117
- package/packs/irs-soi/endpoints.json +114 -114
- package/packs/irs-soi/policy.json +107 -107
- package/packs/medicaid/endpoints.json +412 -412
- package/packs/medicaid/policy.json +108 -108
- package/packs/naep/endpoints.json +217 -217
- package/packs/naep/policy.json +100 -100
- package/packs/nhtsa/endpoints.json +132 -132
- package/packs/nhtsa/policy.json +93 -93
- package/packs/nih/endpoints.json +452 -452
- package/packs/nih/policy.json +86 -86
- package/packs/noaa/endpoints.json +431 -431
- package/packs/noaa/policy.json +95 -95
- package/packs/nrel/endpoints.json +327 -327
- package/packs/nrel/policy.json +96 -96
- package/packs/nws/endpoints.json +271 -271
- package/packs/nws/policy.json +82 -82
- package/packs/nyfed/endpoints.json +80 -80
- package/packs/nyfed/policy.json +92 -92
- package/packs/omb/endpoints.json +460 -460
- package/packs/omb/policy.json +106 -106
- package/packs/open-payments/endpoints.json +297 -297
- package/packs/open-payments/policy.json +101 -101
- package/packs/opm/assets/download_opm.ps1 +125 -125
- package/packs/opm/docs/fields.md +184 -184
- package/packs/opm/docs/opm_api.md +71 -71
- package/packs/opm/docs/report_patterns.md +83 -83
- package/packs/opm/lib/data_dictionary.csv +73 -73
- package/packs/pbgc/endpoints.json +483 -483
- package/packs/pbgc/policy.json +94 -94
- package/packs/philfed/endpoints.json +85 -85
- package/packs/philfed/policy.json +94 -94
- package/packs/regulations/endpoints.json +287 -287
- package/packs/regulations/policy.json +86 -86
- package/packs/sec/endpoints.json +236 -236
- package/packs/sec/policy.json +86 -86
- package/packs/senate-lobbying/endpoints.json +553 -553
- package/packs/senate-lobbying/policy.json +99 -99
- package/packs/snapqc/endpoints.json +1426 -1426
- package/packs/snapqc/policy.json +92 -92
- package/packs/treasury/catalog.json +2267 -2267
- package/packs/treasury/docs/api_guide.md +245 -245
- package/packs/treasury/docs/datasets.md +56 -56
- package/packs/treasury/docs/report_patterns.md +126 -126
- package/packs/treasury/policy.json +159 -159
- package/packs/treasury/source.md +170 -165
- package/packs/treasury-yields/endpoints.json +226 -226
- package/packs/treasury-yields/policy.json +86 -86
- package/packs/usaspending/endpoints.json +1315 -1315
- package/packs/usaspending/policy.json +109 -109
- package/packs/usda-fna/policy.json +133 -133
- package/packs/usda-fooddata/endpoints.json +180 -180
- package/packs/usda-fooddata/policy.json +94 -94
- package/packs/usda-nass/endpoints.json +323 -323
- package/packs/usda-nass/policy.json +95 -95
- package/packs/usda-outlook/endpoints.json +86 -86
- package/packs/usda-outlook/policy.json +109 -109
- package/packs/usgs/endpoints.json +313 -313
- package/packs/usgs/policy.json +95 -95
- package/packs/usitc/endpoints.json +74 -74
- package/packs/usitc/policy.json +111 -111
- package/packs/uspto/endpoints.json +141 -141
- package/packs/uspto/policy.json +95 -95
- package/packs/va/endpoints.json +414 -414
- package/packs/va/policy.json +101 -101
- package/packs/world-bank/endpoints.json +122 -122
- package/packs/world-bank/policy.json +101 -101
|
@@ -1,56 +1,56 @@
|
|
|
1
|
-
# Which dataset answers which question
|
|
2
|
-
|
|
3
|
-
Start here to pick endpoints. Each row says whether the measure is a **stock** (a level at a date:
|
|
4
|
-
take the end-of-period value or an average) or a **flow** (an amount over a period: sum months, or
|
|
5
|
-
read a fiscal-year-to-date row). Confirm paths and field names live with `request_schema` (`search: "<words>"`, then
|
|
6
|
-
`search: "<endpoint>"` for its fields); details and pitfalls are in `api_guide.md` (section numbers in brackets).
|
|
7
|
-
|
|
8
|
-
Units: **$** = dollars and cents; **$M** = millions of dollars; **%** = already in percent.
|
|
9
|
-
|
|
10
|
-
"Rows to use" always names the column with the value (`data_type_cd` = T, not "the T row"): the same
|
|
11
|
-
letter can be a value in two columns. Check live with `request_schema` and `search: "<endpoint> <filter JSON> values"`;
|
|
12
|
-
each download's `data/treasury/README.md` also lists the values found in every code and description column.
|
|
13
|
-
|
|
14
|
-
## Question → endpoint
|
|
15
|
-
|
|
16
|
-
| Question | Endpoint | Rows to use | Stock/flow | Units | Pitfalls |
|
|
17
|
-
|---|---|---|---|---|---|
|
|
18
|
-
| Total federal debt, debt held by the public, intragovernmental holdings (daily, since 1993) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ | DHP and intragov are null before 2005-03-31; the latest day lags one business day |
|
|
19
|
-
| Debt at each fiscal year end, back to 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ | early years dated Jan 1, recent years Sep 30; definitions change over two centuries |
|
|
20
|
-
| Debt by security type (bills, notes, bonds, TIPS, FRNs; marketable vs nonmarketable), monthly | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total ..." rows when summing | stock | $M | totals differ from Debt to the Penny by rounding and FFB debt [4.14] |
|
|
21
|
-
| Debt subject to the statutory limit | `v1/debt/mspd/mspd_table_2` (monthly) or `v1/accounting/dts/debt_subject_to_limit` (daily) | `debt_catg_desc` | stock | $M | |
|
|
22
|
-
| Monthly receipts, outlays, deficit (long series since FY1981) | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` = Receipts / Outlays / Deficit/Surplus (-) | flow | $M | deficit is **positive** in this table [4.3] |
|
|
23
|
-
| Monthly receipts, outlays, deficit (since FY2015, more detail) | `v1/accounting/mts/mts_table_1` | months: the **latest** `record_date` only, `record_type_cd` = MTH; full fiscal year: September `record_date`, `classification_desc` = "Year-to-Date" (`record_type_cd` = SL, `data_type_cd` = T) | flow | $ | each release holds **two fiscal-year blocks**: `sequence_number_cd` 1.x = prior FY (as revised), 2.x = current FY, so "Year-to-Date" appears twice per release [4.8]; releases repeat prior months and revise them: never stack releases [4.5, 4.6]; deficit positive [4.3] |
|
|
24
|
-
| Receipts by source (individual, corporate, payroll, excise, customs ...) and outlays by function (defense, Social Security, Medicare, net interest ...) | `v1/accounting/mts/mts_table_9` | September `record_date` for a full FY; `data_type_cd` = D for components, `data_type_cd` = T with `classification_desc` = "Total" for totals; `record_type_cd` = RSG for receipts, F for functions | flow (`current_fytd_*` is cumulative) | $ | Social Insurance is an S header with 3 D children; never sum all rows [4.9] |
|
|
25
|
-
| Outlays by function and subfunction | `v1/accounting/mts/mts_table_9_outlays_functions_subfunctions` | D rows at the wanted `sequence_level_nbr` | flow | $ | |
|
|
26
|
-
| Receipts detail (gross, refunds, net) | `v1/accounting/mts/mts_table_4` | totals: the rows with `classification_desc` starting "Total -- " (`data_type_cd` = T or `record_type_cd` = SL) | flow | $ | **D rows do not sum to the total** in Table 4 [4.9]; prefer Table 9 for receipts by source |
|
|
27
|
-
| Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A = agency totals; D rows sum to "Total Outlays" | flow | $ | Table 5's "Total Surplus (+) or Deficit (-)" is **negative** for a deficit [4.3]; never add T rows to D rows |
|
|
28
|
-
| Interest expense on the public debt (gross, by security type) | `v2/accounting/od/interest_expense` | `expense_catg_desc`, `expense_group_desc`, `expense_type_desc`; `month_expense_amt` per month or September `fytd_expense_amt` | flow | $ | detail rows only (no total rows): the sum of **all** rows is the total interest expense (FY2024: $1,133.0 billion). From FY2025 it includes a GAS line "Restoration of Interest" ($4.4 billion in FY2025, $0.4 billion in FY2026) that MTS Table 5 "Interest on Treasury Debt Securities (Gross)" leaves out: drop it to match MTS. Marketable TIPS interest is the sum of the TIPS lines, inflation compensation included ("Int. Expense Inflation Compensation (TIPS)"); the GAS "Inflation Compensation" line is not TIPS, so never select TIPS with a substring such as "Inflation". Marketable = the Treasury Bills, Notes, Bonds, TIPS (both TIPS lines) and FRN lines; the other public-issue lines are nonmarketable held by the public (Savings Bonds, State & Local Government (SLGS), Domestic, Foreign and REA Series) or miscellaneous (Matured Debt, Limited Payability, Recertified Agency Payments), about $8 billion in FY2026: public issues are not all marketable. Check the lines with `--values`. Two categories: INTEREST EXPENSE ON PUBLIC ISSUES (debt held by the public) and ON GOVT ACCOUNT SERIES (trust funds; intragovernmental). The GAS groups "ACCRUAL BASIS GAS EXPENSE" (zero-coupon amortized discount only) and "CASH BASIS GAS PAYMENTS" are different line items, not two versions of the same amount: keep both. Some lines are negative (premiums, collected discounts). Total = gross interest; MTS "Net Interest" (Table 9) is the budget's **net** measure (nets out trust-fund interest and other receipts): say which one is used |
|
|
29
|
-
| Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` = "Total Interest-bearing Debt", "Total Marketable", "Treasury Bills" ... | stock (a rate at month end) | % | rows for totals and components sit side by side; "Total Marketable" leaves out TIPS and FRNs (see source.md) |
|
|
30
|
-
| Treasury cash balance (TGA) | `v1/accounting/dts/operating_cash_balance` | before 2022-04-18: TGA / Federal Reserve Account row, `close_today_bal`; from 2022-04-18: "Treasury General Account (TGA) Closing Balance" row, `open_today_bal` | stock | $M | **format change on 2022-04-18** [4.11] |
|
|
31
|
-
| Daily deposits and withdrawals by category (tax receipts, Social Security, Medicare, interest ...) | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg`; drop the "Total ..." account rows when summing details | flow (`transaction_today_amt`; `_mtd`, `_fytd` are cumulative) | $M | gross public debt cash issues and redemptions are in here: exclude for operating flows; category names change over time [4.12] |
|
|
32
|
-
| Gross borrowing: debt issued and redeemed | `v1/accounting/dts/public_debt_transactions` | `transaction_type` Issues / Redemptions, `security_type` | flow | $M | |
|
|
33
|
-
| Auction results (yields, bid-to-cover, who bought) | `v1/accounting/od/auctions_query` | completed auctions only (`auction_date` <= today, non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security: No` for nominal securities (TIPS are `security_type` Note too) | event | mixed | future auctions have null results [4.16] |
|
|
34
|
-
| Exchange rates used for federal reporting | `v1/accounting/od/rates_of_exchange` | `country_currency_desc`; latest `effective_date` per quarter | stock | foreign units per USD | amendments create duplicate quarter rows [4.15] |
|
|
35
|
-
| Revenue collections by channel and tax category | `v2/revenue/rcm` | `tax_category_desc`, `channel_type_desc` | flow | $ | collections, not budget receipts |
|
|
36
|
-
| Receivables and delinquent debt owed to agencies | `v2/debt/tror` | per agency × receivable type | stock | $ | ~230 columns: select by name |
|
|
37
|
-
| Treasury Offset Program collections | `v1/debt/treasury_offset_program` | filter by date and agency | flow | $ | 3.5 million rows: always filter |
|
|
38
|
-
| Gifts to reduce the debt | `v2/accounting/od/gift_contributions` | one row per month | flow | $ | |
|
|
39
|
-
| Savings bonds, I bond rates | `v2/accounting/od/sb_value`, `v1/accounting/od/i_bonds_interest_rates` | | | | **no record_date**: set `date_field` [3] |
|
|
40
|
-
| Buybacks | `v1/accounting/od/buybacks_operations` | | event | $ | date column is `operation_date` |
|
|
41
|
-
| Federal government balance sheet, net cost (Financial Report) | `v2/accounting/od/balance_sheets`, `v2/accounting/od/statement_net_cost` | | annual | $ | lags months |
|
|
42
|
-
|
|
43
|
-
Anything else: `request_schema` for treasury with a search (`"<words>"`) lists every matching endpoint with
|
|
44
|
-
frequency, earliest and latest date, row count and the dataset page.
|
|
45
|
-
|
|
46
|
-
## Not in Fiscal Data: say so and offer the right source
|
|
47
|
-
- **GDP, CPI, inflation**: BEA and BLS, through the treasury spec's `context` field (CPI-U from FRED or BLS; GDP from
|
|
48
|
-
FRED, with an annual World Bank fallback).
|
|
49
|
-
- **Budget projections, baselines, scoring**: CBO (https://www.cbo.gov/data/budget-economic-data).
|
|
50
|
-
- **Historical budget tables, % of GDP back to 1930, the President's budget**: OMB Historical Tables
|
|
51
|
-
(https://www.whitehouse.gov/omb/budget/historical-tables/).
|
|
52
|
-
- **Who holds Treasury debt (foreign holders by country)**: Treasury International Capital (TIC), not
|
|
53
|
-
Fiscal Data; the Treasury Bulletin OFS-2 table (`v1/accounting/tb/ofs2_...`) gives ownership by sector.
|
|
54
|
-
- **Market yields (daily Treasury par yield curve)**: the treasury-yields pack (home.treasury.gov interest-rate statistics), not this API;
|
|
55
|
-
Fiscal Data has auction results and average rates on outstanding debt.
|
|
56
|
-
- **State and local finances**: Census Bureau Annual Survey of State and Local Government Finances.
|
|
1
|
+
# Which dataset answers which question
|
|
2
|
+
|
|
3
|
+
Start here to pick endpoints. Each row says whether the measure is a **stock** (a level at a date:
|
|
4
|
+
take the end-of-period value or an average) or a **flow** (an amount over a period: sum months, or
|
|
5
|
+
read a fiscal-year-to-date row). Confirm paths and field names live with `request_schema` (`search: "<words>"`, then
|
|
6
|
+
`search: "<endpoint>"` for its fields); details and pitfalls are in `api_guide.md` (section numbers in brackets).
|
|
7
|
+
|
|
8
|
+
Units: **$** = dollars and cents; **$M** = millions of dollars; **%** = already in percent.
|
|
9
|
+
|
|
10
|
+
"Rows to use" always names the column with the value (`data_type_cd` = T, not "the T row"): the same
|
|
11
|
+
letter can be a value in two columns. Check live with `request_schema` and `search: "<endpoint> <filter JSON> values"`;
|
|
12
|
+
each download's `data/treasury/README.md` also lists the values found in every code and description column.
|
|
13
|
+
|
|
14
|
+
## Question → endpoint
|
|
15
|
+
|
|
16
|
+
| Question | Endpoint | Rows to use | Stock/flow | Units | Pitfalls |
|
|
17
|
+
|---|---|---|---|---|---|
|
|
18
|
+
| Total federal debt, debt held by the public, intragovernmental holdings (daily, since 1993) | `v2/accounting/od/debt_to_penny` | one row per business day | stock | $ | DHP and intragov are null before 2005-03-31; the latest day lags one business day |
|
|
19
|
+
| Debt at each fiscal year end, back to 1790 | `v2/accounting/od/debt_outstanding` | one row per year | stock | $ | early years dated Jan 1, recent years Sep 30; definitions change over two centuries |
|
|
20
|
+
| Debt by security type (bills, notes, bonds, TIPS, FRNs; marketable vs nonmarketable), monthly | `v1/debt/mspd/mspd_table_1` | `security_type_desc`, `security_class_desc`; skip "Total ..." rows when summing | stock | $M | totals differ from Debt to the Penny by rounding and FFB debt [4.14] |
|
|
21
|
+
| Debt subject to the statutory limit | `v1/debt/mspd/mspd_table_2` (monthly) or `v1/accounting/dts/debt_subject_to_limit` (daily) | `debt_catg_desc` | stock | $M | |
|
|
22
|
+
| Monthly receipts, outlays, deficit (long series since FY1981) | `v1/accounting/mts/mts_receipts_outlays_deficit_surplus` | `amt_category` = Receipts / Outlays / Deficit/Surplus (-) | flow | $M | deficit is **positive** in this table [4.3] |
|
|
23
|
+
| Monthly receipts, outlays, deficit (since FY2015, more detail) | `v1/accounting/mts/mts_table_1` | months: the **latest** `record_date` only, `record_type_cd` = MTH; full fiscal year: September `record_date`, `classification_desc` = "Year-to-Date" (`record_type_cd` = SL, `data_type_cd` = T) | flow | $ | each release holds **two fiscal-year blocks**: `sequence_number_cd` 1.x = prior FY (as revised), 2.x = current FY, so "Year-to-Date" appears twice per release [4.8]; releases repeat prior months and revise them: never stack releases [4.5, 4.6]; deficit positive [4.3] |
|
|
24
|
+
| Receipts by source (individual, corporate, payroll, excise, customs ...) and outlays by function (defense, Social Security, Medicare, net interest ...) | `v1/accounting/mts/mts_table_9` | September `record_date` for a full FY; `data_type_cd` = D for components, `data_type_cd` = T with `classification_desc` = "Total" for totals; `record_type_cd` = RSG for receipts, F for functions | flow (`current_fytd_*` is cumulative) | $ | Social Insurance is an S header with 3 D children; never sum all rows [4.9] |
|
|
25
|
+
| Outlays by function and subfunction | `v1/accounting/mts/mts_table_9_outlays_functions_subfunctions` | D rows at the wanted `sequence_level_nbr` | flow | $ | |
|
|
26
|
+
| Receipts detail (gross, refunds, net) | `v1/accounting/mts/mts_table_4` | totals: the rows with `classification_desc` starting "Total -- " (`data_type_cd` = T or `record_type_cd` = SL) | flow | $ | **D rows do not sum to the total** in Table 4 [4.9]; prefer Table 9 for receipts by source |
|
|
27
|
+
| Outlays by agency, bureau, program | `v1/accounting/mts/mts_table_5` | `record_type_cd` A = agency totals; D rows sum to "Total Outlays" | flow | $ | Table 5's "Total Surplus (+) or Deficit (-)" is **negative** for a deficit [4.3]; never add T rows to D rows |
|
|
28
|
+
| Interest expense on the public debt (gross, by security type) | `v2/accounting/od/interest_expense` | `expense_catg_desc`, `expense_group_desc`, `expense_type_desc`; `month_expense_amt` per month or September `fytd_expense_amt` | flow | $ | detail rows only (no total rows): the sum of **all** rows is the total interest expense (FY2024: $1,133.0 billion). From FY2025 it includes a GAS line "Restoration of Interest" ($4.4 billion in FY2025, $0.4 billion in FY2026) that MTS Table 5 "Interest on Treasury Debt Securities (Gross)" leaves out: drop it to match MTS. Marketable TIPS interest is the sum of the TIPS lines, inflation compensation included ("Int. Expense Inflation Compensation (TIPS)"); the GAS "Inflation Compensation" line is not TIPS, so never select TIPS with a substring such as "Inflation". Marketable = the Treasury Bills, Notes, Bonds, TIPS (both TIPS lines) and FRN lines; the other public-issue lines are nonmarketable held by the public (Savings Bonds, State & Local Government (SLGS), Domestic, Foreign and REA Series) or miscellaneous (Matured Debt, Limited Payability, Recertified Agency Payments), about $8 billion in FY2026: public issues are not all marketable. Check the lines with `--values`. Two categories: INTEREST EXPENSE ON PUBLIC ISSUES (debt held by the public) and ON GOVT ACCOUNT SERIES (trust funds; intragovernmental). The GAS groups "ACCRUAL BASIS GAS EXPENSE" (zero-coupon amortized discount only) and "CASH BASIS GAS PAYMENTS" are different line items, not two versions of the same amount: keep both. Some lines are negative (premiums, collected discounts). Total = gross interest; MTS "Net Interest" (Table 9) is the budget's **net** measure (nets out trust-fund interest and other receipts): say which one is used |
|
|
29
|
+
| Average interest rate on the debt | `v2/accounting/od/avg_interest_rates` | `security_desc` = "Total Interest-bearing Debt", "Total Marketable", "Treasury Bills" ... | stock (a rate at month end) | % | rows for totals and components sit side by side; "Total Marketable" leaves out TIPS and FRNs (see source.md) |
|
|
30
|
+
| Treasury cash balance (TGA) | `v1/accounting/dts/operating_cash_balance` | before 2022-04-18: TGA / Federal Reserve Account row, `close_today_bal`; from 2022-04-18: "Treasury General Account (TGA) Closing Balance" row, `open_today_bal` | stock | $M | **format change on 2022-04-18** [4.11] |
|
|
31
|
+
| Daily deposits and withdrawals by category (tax receipts, Social Security, Medicare, interest ...) | `v1/accounting/dts/deposits_withdrawals_operating_cash` | `transaction_type`, `transaction_catg`; drop the "Total ..." account rows when summing details | flow (`transaction_today_amt`; `_mtd`, `_fytd` are cumulative) | $M | gross public debt cash issues and redemptions are in here: exclude for operating flows; category names change over time [4.12] |
|
|
32
|
+
| Gross borrowing: debt issued and redeemed | `v1/accounting/dts/public_debt_transactions` | `transaction_type` Issues / Redemptions, `security_type` | flow | $M | |
|
|
33
|
+
| Auction results (yields, bid-to-cover, who bought) | `v1/accounting/od/auctions_query` | completed auctions only (`auction_date` <= today, non-null `high_yield`); `original_security_term` to include reopenings; `inflation_index_security: No` for nominal securities (TIPS are `security_type` Note too) | event | mixed | future auctions have null results [4.16] |
|
|
34
|
+
| Exchange rates used for federal reporting | `v1/accounting/od/rates_of_exchange` | `country_currency_desc`; latest `effective_date` per quarter | stock | foreign units per USD | amendments create duplicate quarter rows [4.15] |
|
|
35
|
+
| Revenue collections by channel and tax category | `v2/revenue/rcm` | `tax_category_desc`, `channel_type_desc` | flow | $ | collections, not budget receipts |
|
|
36
|
+
| Receivables and delinquent debt owed to agencies | `v2/debt/tror` | per agency × receivable type | stock | $ | ~230 columns: select by name |
|
|
37
|
+
| Treasury Offset Program collections | `v1/debt/treasury_offset_program` | filter by date and agency | flow | $ | 3.5 million rows: always filter |
|
|
38
|
+
| Gifts to reduce the debt | `v2/accounting/od/gift_contributions` | one row per month | flow | $ | |
|
|
39
|
+
| Savings bonds, I bond rates | `v2/accounting/od/sb_value`, `v1/accounting/od/i_bonds_interest_rates` | | | | **no record_date**: set `date_field` [3] |
|
|
40
|
+
| Buybacks | `v1/accounting/od/buybacks_operations` | | event | $ | date column is `operation_date` |
|
|
41
|
+
| Federal government balance sheet, net cost (Financial Report) | `v2/accounting/od/balance_sheets`, `v2/accounting/od/statement_net_cost` | | annual | $ | lags months |
|
|
42
|
+
|
|
43
|
+
Anything else: `request_schema` for treasury with a search (`"<words>"`) lists every matching endpoint with
|
|
44
|
+
frequency, earliest and latest date, row count and the dataset page.
|
|
45
|
+
|
|
46
|
+
## Not in Fiscal Data: say so and offer the right source
|
|
47
|
+
- **GDP, CPI, inflation**: BEA and BLS, through the treasury spec's `context` field (CPI-U from FRED or BLS; GDP from
|
|
48
|
+
FRED, with an annual World Bank fallback).
|
|
49
|
+
- **Budget projections, baselines, scoring**: CBO (https://www.cbo.gov/data/budget-economic-data).
|
|
50
|
+
- **Historical budget tables, % of GDP back to 1930, the President's budget**: OMB Historical Tables
|
|
51
|
+
(https://www.whitehouse.gov/omb/budget/historical-tables/).
|
|
52
|
+
- **Who holds Treasury debt (foreign holders by country)**: Treasury International Capital (TIC), not
|
|
53
|
+
Fiscal Data; the Treasury Bulletin OFS-2 table (`v1/accounting/tb/ofs2_...`) gives ownership by sector.
|
|
54
|
+
- **Market yields (daily Treasury par yield curve)**: the treasury-yields pack (home.treasury.gov interest-rate statistics), not this API;
|
|
55
|
+
Fiscal Data has auction results and average rates on outstanding debt.
|
|
56
|
+
- **State and local finances**: Census Bureau Annual Survey of State and Local Government Finances.
|
|
@@ -1,126 +1,126 @@
|
|
|
1
|
-
# Analysis and report patterns for federal fiscal data
|
|
2
|
-
|
|
3
|
-
Use this file to frame the analysis, choose the critical questions, and shape the product. The aim is
|
|
4
|
-
work a careful budget analyst would recognize: the right measure (stock or flow, gross or net), the
|
|
5
|
-
right period (fiscal or calendar year, complete or partial), stated units and dollar basis, numbers that
|
|
6
|
-
tie to the published statement, and limitations stated plainly.
|
|
7
|
-
|
|
8
|
-
## Typical questions and how they are framed
|
|
9
|
-
|
|
10
|
-
- **Debt level and growth:** "How much has the debt grown since 2015?" Measures: total public debt
|
|
11
|
-
outstanding and debt held by the public (Debt to the Penny) at fiscal-year ends; growth in dollars, in
|
|
12
|
-
percent and per year (CAGR). Benchmark: the September Monthly Statement of the Public Debt.
|
|
13
|
-
- **Deficits:** "What was the deficit in FY2025, and how does it compare?" Measures: receipts, outlays and
|
|
14
|
-
the deficit for the fiscal year (MTS Table 1 Year-to-Date, or Table 9 totals), and against the prior
|
|
15
|
-
year. Often as a share of GDP. Benchmark: Treasury's final MTS for September, and CBO's Monthly Budget Review.
|
|
16
|
-
- **Fiscal year to date:** "How is FY2026 going so far?" Compare the same months of the prior year (October
|
|
17
|
-
through the latest month), never a partial year with a full year.
|
|
18
|
-
- **Composition:** "Where does the money come from and go?" Receipts by source and outlays by function (MTS
|
|
19
|
-
Table 9): levels, shares of the total and changes.
|
|
20
|
-
- **Interest costs:** "How fast is interest on the debt rising?" Measures: net interest outlays (MTS Table 9,
|
|
21
|
-
the budget measure) or gross interest expense (`interest_expense`), the average interest rate on
|
|
22
|
-
interest-bearing debt, and interest as a share of outlays or receipts. Decompose growth into the debt-level
|
|
23
|
-
effect and the rate effect when asked why.
|
|
24
|
-
- **Cash and the debt limit:** "How much cash does Treasury have?" The TGA closing balance (DTS) and debt
|
|
25
|
-
subject to limit; mind the 2022 DTS format change.
|
|
26
|
-
- **Borrowing and auctions:** gross issuance and redemptions (DTS), auction sizes, yields and bid-to-cover by
|
|
27
|
-
security type and term.
|
|
28
|
-
- **Exchange rates:** the Treasury reporting rate for a currency over time (not market rates).
|
|
29
|
-
|
|
30
|
-
## Critical questions bank
|
|
31
|
-
|
|
32
|
-
Ask only the ones that would change a headline number for this request, at most four, in one round,
|
|
33
|
-
with "Don't know — decide for me" on each and the recommended option first. Skip what the request
|
|
34
|
-
already settles.
|
|
35
|
-
|
|
36
|
-
| Choice | Ask when | Options (recommended first, typical) | How to decide empirically when the user doesn't know |
|
|
37
|
-
|---|---|---|---|
|
|
38
|
-
| **Period basis** | annual figures for budget flows or year-end stocks | Federal fiscal year (Oct–Sep) · Calendar year | Fiscal year for budget measures (precedent: MTS, CBO, OMB); calendar year only to match a calendar-year comparison (GDP from the World Bank, a calendar-year report) |
|
|
39
|
-
| **Time span** | the request names no years | last 10 complete fiscal years · since 2015 (MTS API start) · longest available | 10 complete years; include the current partial year only as "year to date" against the same months a year earlier. For **change** over "the past decade / N years", compare endpoints N years apart (latest complete FY vs. latest − N, so N + 1 years shown); for lists or totals, use the N latest complete years. Name the years either way |
|
|
40
|
-
| **Debt measure** | any debt question | Debt held by the public · Total public debt outstanding · Debt subject to limit | Held by the public for economic analysis (CBO precedent); total for "the national debt" in plain usage; report both when unsure and say how they differ |
|
|
41
|
-
| **Dollar basis** | comparisons across more than about 3 years, or "real" growth | Nominal · Real (CPI-U, latest full fiscal year dollars) · Share of GDP | Nominal for levels people quote; add real or % of GDP when growth over a decade or more is the point; run both and say whether the conclusion changes |
|
|
42
|
-
| **Stock: end of period or average** | yearly or monthly debt, cash, rates | End of period · Period average | End of fiscal year (matches published year-end figures); show the average as a sensitivity when the series is volatile (TGA cash) |
|
|
43
|
-
| **Interest measure** | interest questions | Net interest (MTS, budget) · Gross interest expense (`interest_expense`) · Interest on debt held by the public only | Net interest for budget questions; gross for "what Treasury pays"; public-issues expense for market-facing costs; state the choice in notes |
|
|
44
|
-
| **Gross or net** | receipts or outlays | Net (budget convention) · Gross | Net: it is what the MTS totals and CBO report |
|
|
45
|
-
| **Partial latest period** | the latest fiscal year is incomplete | Fiscal year to date vs. same months last year · Exclude it · Trailing 12 months | FYTD against the same months; trailing-12-month totals for trend charts |
|
|
46
|
-
| **Product** | the user did not ask for a report | Short answer + data (default) · Full HTML report · Data files only | The default; offer the report in one line |
|
|
47
|
-
| **Audience and organization** | a report is wanted | Neutral analyst product · Named organization | Neutral unless the user names one |
|
|
48
|
-
|
|
49
|
-
Questions that are **not** critical (decide and record them): CSV vs JSON, field selection, chart type,
|
|
50
|
-
rounding, the exact endpoint when two give identical published totals.
|
|
51
|
-
|
|
52
|
-
## Conventions to follow
|
|
53
|
-
|
|
54
|
-
**Periods and timing**
|
|
55
|
-
- The federal fiscal year runs October 1 to September 30 and is named for the year it ends. Write
|
|
56
|
-
"fiscal year 2025" in prose (style guide), "FY2025" only in tables and charts.
|
|
57
|
-
- `record_date` is the reporting date (month end for the MTS, business day for the DTS and Debt to the
|
|
58
|
-
Penny). The MTS for September is the final, full-year statement; it is published in mid-October.
|
|
59
|
-
- Say how current the data are: "data through September 30, 2025, retrieved October 19, 2026".
|
|
60
|
-
- Fix the cut-off in the spec (`as_of`) so reruns return the same rows.
|
|
61
|
-
|
|
62
|
-
**Stocks and flows**
|
|
63
|
-
- Stocks (debt, cash, rates): take the end-of-period value (`period_end`) or the average (`period_mean`).
|
|
64
|
-
Never sum them.
|
|
65
|
-
- Flows (receipts, outlays, deficit, interest): sum monthly values (`period_sum`, check `complete`), or read
|
|
66
|
-
the September fiscal-year-to-date value. Never sum fiscal-year-to-date values across months.
|
|
67
|
-
|
|
68
|
-
**Tying to published totals**
|
|
69
|
-
- Every component breakdown must add to its published total (`check_total`), and every headline should
|
|
70
|
-
match the official statement for the same date (the MTS, MSPD or DTS PDF, or Treasury's press summary).
|
|
71
|
-
State the benchmark in Data and Methods. A difference above rounding means a filter or hierarchy mistake.
|
|
72
|
-
When the downloaded table is itself the statement's total, check the internal identities instead, plus
|
|
73
|
-
one independent publication (press release, CBO Monthly Budget Review).
|
|
74
|
-
- MTS tables repeat history and revise it. Use the latest release for a monthly series; use the September
|
|
75
|
-
release for a full fiscal year.
|
|
76
|
-
|
|
77
|
-
**Units and signs**
|
|
78
|
-
- MTS tables 1-9, Debt to the Penny and interest expense are in dollars; DTS, MSPD and the long MTS series
|
|
79
|
-
(`mts_receipts_outlays_deficit_surplus`, field `mil_amt`) are in millions. Convert once,
|
|
80
|
-
name the unit in every exhibit subtitle ("Billions of dollars").
|
|
81
|
-
- Deficits: MTS Table 1 and the long MTS series show a deficit as positive; MTS Table 5 shows it as negative.
|
|
82
|
-
Pick one convention for the product ("the deficit was $1.8 trillion") and state it.
|
|
83
|
-
|
|
84
|
-
**Real dollars and GDP**
|
|
85
|
-
- Deflate with the CPI-U averaged over the same fiscal year (`compute` `to_fiscal` with `how` "mean", then
|
|
86
|
-
`deflate`), into the dollars of the latest complete fiscal year; name the index and base year in notes.
|
|
87
|
-
- Fiscal-year GDP is the average of the four quarterly seasonally adjusted annual rates from October to
|
|
88
|
-
September (`to_fiscal` with `freq` "Q", `how` "mean"). Calendar-year GDP (World Bank fallback) does not match fiscal-year budget totals;
|
|
89
|
-
if only that is available, say so or use calendar-year flows.
|
|
90
|
-
- An incomplete period (the `complete` flag is False; `to_fiscal` notes it) is provisional: say so
|
|
91
|
-
in the text and the exhibit notes, with its coverage ("GDP for three of four quarters"). In October the
|
|
92
|
-
latest fiscal year usually lacks GDP's July–September quarter, so its share of GDP is provisional.
|
|
93
|
-
|
|
94
|
-
**Revisions and provenance**
|
|
95
|
-
- Treasury revises some values in later releases. Record the retrieval date (it is in `data/treasury/README.md`)
|
|
96
|
-
and note revisions when a comparison spans releases.
|
|
97
|
-
|
|
98
|
-
## Publication structure (mirrored in `build_report`, `"mode": "report"`)
|
|
99
|
-
|
|
100
|
-
The default layout, the **exhibit chartbook**, runs in this order:
|
|
101
|
-
1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart.
|
|
102
|
-
2. **At a Glance** (one page of about 300–420 words): one framing paragraph (what was examined, the measures,
|
|
103
|
-
the period), then 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by
|
|
104
|
-
2–4 sentences with the key numbers.
|
|
105
|
-
3. **Contents** and **List of Exhibits** (built automatically).
|
|
106
|
-
4. **Notes About This Report:** fiscal years; rounding; nominal or real dollars (index and base year); the
|
|
107
|
-
data source and retrieval date; sign conventions; partial-year coverage; a pointer to Appendix A.
|
|
108
|
-
5. **Introduction:** a lead paragraph with the headline numbers; question-style subheadings, one per section
|
|
109
|
-
("How Did Interest Costs Change?"); then "What Data Were Used?" and, when updating earlier work,
|
|
110
|
-
"How Do These Estimates Compare With Published Figures?".
|
|
111
|
-
6. **Thematic sections** (2–5): each opens with 1–3 summary paragraphs, then one exhibit per page with 2–4
|
|
112
|
-
narrative paragraphs beside the chart (level, change, comparison; "see Exhibit 3").
|
|
113
|
-
7. **Appendix A: Data and Methods:** endpoints and rows used, filters, the cut-off date, stock/flow treatment,
|
|
114
|
-
period basis, deflator, benchmark comparison with the published statement, revisions, limitations.
|
|
115
|
-
8. **About This Document** (optional).
|
|
116
|
-
|
|
117
|
-
Use `"mode": "paper"` for a prose-led product with the exhibits in the running text.
|
|
118
|
-
|
|
119
|
-
## Chart forms
|
|
120
|
-
- Trends over fiscal years: line charts (debt, interest, rates) or columns (annual deficits), at most 4–5
|
|
121
|
-
series. Trailing-12-month lines suit monthly flows, which are very seasonal (April tax receipts).
|
|
122
|
-
- Composition (receipts by source, outlays by function): horizontal bars for one year, sorted; stacked
|
|
123
|
-
columns for change over time with at most about 6 groups plus "Other".
|
|
124
|
-
- Deficits: columns with the sign convention stated; surpluses below zero if shown as negative deficits.
|
|
125
|
-
- No dual axes, no pie charts, no 3-D. Scale amounts to billions or trillions in the exhibit CSV and name
|
|
126
|
-
the unit in the subtitle.
|
|
1
|
+
# Analysis and report patterns for federal fiscal data
|
|
2
|
+
|
|
3
|
+
Use this file to frame the analysis, choose the critical questions, and shape the product. The aim is
|
|
4
|
+
work a careful budget analyst would recognize: the right measure (stock or flow, gross or net), the
|
|
5
|
+
right period (fiscal or calendar year, complete or partial), stated units and dollar basis, numbers that
|
|
6
|
+
tie to the published statement, and limitations stated plainly.
|
|
7
|
+
|
|
8
|
+
## Typical questions and how they are framed
|
|
9
|
+
|
|
10
|
+
- **Debt level and growth:** "How much has the debt grown since 2015?" Measures: total public debt
|
|
11
|
+
outstanding and debt held by the public (Debt to the Penny) at fiscal-year ends; growth in dollars, in
|
|
12
|
+
percent and per year (CAGR). Benchmark: the September Monthly Statement of the Public Debt.
|
|
13
|
+
- **Deficits:** "What was the deficit in FY2025, and how does it compare?" Measures: receipts, outlays and
|
|
14
|
+
the deficit for the fiscal year (MTS Table 1 Year-to-Date, or Table 9 totals), and against the prior
|
|
15
|
+
year. Often as a share of GDP. Benchmark: Treasury's final MTS for September, and CBO's Monthly Budget Review.
|
|
16
|
+
- **Fiscal year to date:** "How is FY2026 going so far?" Compare the same months of the prior year (October
|
|
17
|
+
through the latest month), never a partial year with a full year.
|
|
18
|
+
- **Composition:** "Where does the money come from and go?" Receipts by source and outlays by function (MTS
|
|
19
|
+
Table 9): levels, shares of the total and changes.
|
|
20
|
+
- **Interest costs:** "How fast is interest on the debt rising?" Measures: net interest outlays (MTS Table 9,
|
|
21
|
+
the budget measure) or gross interest expense (`interest_expense`), the average interest rate on
|
|
22
|
+
interest-bearing debt, and interest as a share of outlays or receipts. Decompose growth into the debt-level
|
|
23
|
+
effect and the rate effect when asked why.
|
|
24
|
+
- **Cash and the debt limit:** "How much cash does Treasury have?" The TGA closing balance (DTS) and debt
|
|
25
|
+
subject to limit; mind the 2022 DTS format change.
|
|
26
|
+
- **Borrowing and auctions:** gross issuance and redemptions (DTS), auction sizes, yields and bid-to-cover by
|
|
27
|
+
security type and term.
|
|
28
|
+
- **Exchange rates:** the Treasury reporting rate for a currency over time (not market rates).
|
|
29
|
+
|
|
30
|
+
## Critical questions bank
|
|
31
|
+
|
|
32
|
+
Ask only the ones that would change a headline number for this request, at most four, in one round,
|
|
33
|
+
with "Don't know — decide for me" on each and the recommended option first. Skip what the request
|
|
34
|
+
already settles.
|
|
35
|
+
|
|
36
|
+
| Choice | Ask when | Options (recommended first, typical) | How to decide empirically when the user doesn't know |
|
|
37
|
+
|---|---|---|---|
|
|
38
|
+
| **Period basis** | annual figures for budget flows or year-end stocks | Federal fiscal year (Oct–Sep) · Calendar year | Fiscal year for budget measures (precedent: MTS, CBO, OMB); calendar year only to match a calendar-year comparison (GDP from the World Bank, a calendar-year report) |
|
|
39
|
+
| **Time span** | the request names no years | last 10 complete fiscal years · since 2015 (MTS API start) · longest available | 10 complete years; include the current partial year only as "year to date" against the same months a year earlier. For **change** over "the past decade / N years", compare endpoints N years apart (latest complete FY vs. latest − N, so N + 1 years shown); for lists or totals, use the N latest complete years. Name the years either way |
|
|
40
|
+
| **Debt measure** | any debt question | Debt held by the public · Total public debt outstanding · Debt subject to limit | Held by the public for economic analysis (CBO precedent); total for "the national debt" in plain usage; report both when unsure and say how they differ |
|
|
41
|
+
| **Dollar basis** | comparisons across more than about 3 years, or "real" growth | Nominal · Real (CPI-U, latest full fiscal year dollars) · Share of GDP | Nominal for levels people quote; add real or % of GDP when growth over a decade or more is the point; run both and say whether the conclusion changes |
|
|
42
|
+
| **Stock: end of period or average** | yearly or monthly debt, cash, rates | End of period · Period average | End of fiscal year (matches published year-end figures); show the average as a sensitivity when the series is volatile (TGA cash) |
|
|
43
|
+
| **Interest measure** | interest questions | Net interest (MTS, budget) · Gross interest expense (`interest_expense`) · Interest on debt held by the public only | Net interest for budget questions; gross for "what Treasury pays"; public-issues expense for market-facing costs; state the choice in notes |
|
|
44
|
+
| **Gross or net** | receipts or outlays | Net (budget convention) · Gross | Net: it is what the MTS totals and CBO report |
|
|
45
|
+
| **Partial latest period** | the latest fiscal year is incomplete | Fiscal year to date vs. same months last year · Exclude it · Trailing 12 months | FYTD against the same months; trailing-12-month totals for trend charts |
|
|
46
|
+
| **Product** | the user did not ask for a report | Short answer + data (default) · Full HTML report · Data files only | The default; offer the report in one line |
|
|
47
|
+
| **Audience and organization** | a report is wanted | Neutral analyst product · Named organization | Neutral unless the user names one |
|
|
48
|
+
|
|
49
|
+
Questions that are **not** critical (decide and record them): CSV vs JSON, field selection, chart type,
|
|
50
|
+
rounding, the exact endpoint when two give identical published totals.
|
|
51
|
+
|
|
52
|
+
## Conventions to follow
|
|
53
|
+
|
|
54
|
+
**Periods and timing**
|
|
55
|
+
- The federal fiscal year runs October 1 to September 30 and is named for the year it ends. Write
|
|
56
|
+
"fiscal year 2025" in prose (style guide), "FY2025" only in tables and charts.
|
|
57
|
+
- `record_date` is the reporting date (month end for the MTS, business day for the DTS and Debt to the
|
|
58
|
+
Penny). The MTS for September is the final, full-year statement; it is published in mid-October.
|
|
59
|
+
- Say how current the data are: "data through September 30, 2025, retrieved October 19, 2026".
|
|
60
|
+
- Fix the cut-off in the spec (`as_of`) so reruns return the same rows.
|
|
61
|
+
|
|
62
|
+
**Stocks and flows**
|
|
63
|
+
- Stocks (debt, cash, rates): take the end-of-period value (`period_end`) or the average (`period_mean`).
|
|
64
|
+
Never sum them.
|
|
65
|
+
- Flows (receipts, outlays, deficit, interest): sum monthly values (`period_sum`, check `complete`), or read
|
|
66
|
+
the September fiscal-year-to-date value. Never sum fiscal-year-to-date values across months.
|
|
67
|
+
|
|
68
|
+
**Tying to published totals**
|
|
69
|
+
- Every component breakdown must add to its published total (`check_total`), and every headline should
|
|
70
|
+
match the official statement for the same date (the MTS, MSPD or DTS PDF, or Treasury's press summary).
|
|
71
|
+
State the benchmark in Data and Methods. A difference above rounding means a filter or hierarchy mistake.
|
|
72
|
+
When the downloaded table is itself the statement's total, check the internal identities instead, plus
|
|
73
|
+
one independent publication (press release, CBO Monthly Budget Review).
|
|
74
|
+
- MTS tables repeat history and revise it. Use the latest release for a monthly series; use the September
|
|
75
|
+
release for a full fiscal year.
|
|
76
|
+
|
|
77
|
+
**Units and signs**
|
|
78
|
+
- MTS tables 1-9, Debt to the Penny and interest expense are in dollars; DTS, MSPD and the long MTS series
|
|
79
|
+
(`mts_receipts_outlays_deficit_surplus`, field `mil_amt`) are in millions. Convert once,
|
|
80
|
+
name the unit in every exhibit subtitle ("Billions of dollars").
|
|
81
|
+
- Deficits: MTS Table 1 and the long MTS series show a deficit as positive; MTS Table 5 shows it as negative.
|
|
82
|
+
Pick one convention for the product ("the deficit was $1.8 trillion") and state it.
|
|
83
|
+
|
|
84
|
+
**Real dollars and GDP**
|
|
85
|
+
- Deflate with the CPI-U averaged over the same fiscal year (`compute` `to_fiscal` with `how` "mean", then
|
|
86
|
+
`deflate`), into the dollars of the latest complete fiscal year; name the index and base year in notes.
|
|
87
|
+
- Fiscal-year GDP is the average of the four quarterly seasonally adjusted annual rates from October to
|
|
88
|
+
September (`to_fiscal` with `freq` "Q", `how` "mean"). Calendar-year GDP (World Bank fallback) does not match fiscal-year budget totals;
|
|
89
|
+
if only that is available, say so or use calendar-year flows.
|
|
90
|
+
- An incomplete period (the `complete` flag is False; `to_fiscal` notes it) is provisional: say so
|
|
91
|
+
in the text and the exhibit notes, with its coverage ("GDP for three of four quarters"). In October the
|
|
92
|
+
latest fiscal year usually lacks GDP's July–September quarter, so its share of GDP is provisional.
|
|
93
|
+
|
|
94
|
+
**Revisions and provenance**
|
|
95
|
+
- Treasury revises some values in later releases. Record the retrieval date (it is in `data/treasury/README.md`)
|
|
96
|
+
and note revisions when a comparison spans releases.
|
|
97
|
+
|
|
98
|
+
## Publication structure (mirrored in `build_report`, `"mode": "report"`)
|
|
99
|
+
|
|
100
|
+
The default layout, the **exhibit chartbook**, runs in this order:
|
|
101
|
+
1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart.
|
|
102
|
+
2. **At a Glance** (one page of about 300–420 words): one framing paragraph (what was examined, the measures,
|
|
103
|
+
the period), then 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by
|
|
104
|
+
2–4 sentences with the key numbers.
|
|
105
|
+
3. **Contents** and **List of Exhibits** (built automatically).
|
|
106
|
+
4. **Notes About This Report:** fiscal years; rounding; nominal or real dollars (index and base year); the
|
|
107
|
+
data source and retrieval date; sign conventions; partial-year coverage; a pointer to Appendix A.
|
|
108
|
+
5. **Introduction:** a lead paragraph with the headline numbers; question-style subheadings, one per section
|
|
109
|
+
("How Did Interest Costs Change?"); then "What Data Were Used?" and, when updating earlier work,
|
|
110
|
+
"How Do These Estimates Compare With Published Figures?".
|
|
111
|
+
6. **Thematic sections** (2–5): each opens with 1–3 summary paragraphs, then one exhibit per page with 2–4
|
|
112
|
+
narrative paragraphs beside the chart (level, change, comparison; "see Exhibit 3").
|
|
113
|
+
7. **Appendix A: Data and Methods:** endpoints and rows used, filters, the cut-off date, stock/flow treatment,
|
|
114
|
+
period basis, deflator, benchmark comparison with the published statement, revisions, limitations.
|
|
115
|
+
8. **About This Document** (optional).
|
|
116
|
+
|
|
117
|
+
Use `"mode": "paper"` for a prose-led product with the exhibits in the running text.
|
|
118
|
+
|
|
119
|
+
## Chart forms
|
|
120
|
+
- Trends over fiscal years: line charts (debt, interest, rates) or columns (annual deficits), at most 4–5
|
|
121
|
+
series. Trailing-12-month lines suit monthly flows, which are very seasonal (April tax receipts).
|
|
122
|
+
- Composition (receipts by source, outlays by function): horizontal bars for one year, sorted; stacked
|
|
123
|
+
columns for change over time with at most about 6 groups plus "Other".
|
|
124
|
+
- Deficits: columns with the sign convention stated; surpluses below zero if shown as negative deficits.
|
|
125
|
+
- No dual axes, no pie charts, no 3-D. Scale amounts to billions or trillions in the exhibit CSV and name
|
|
126
|
+
the unit in the subtitle.
|