data-analyst-mcp 0.3.0 → 0.4.0

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.
Files changed (292) hide show
  1. package/README.md +286 -262
  2. package/dist/adapters/bjs.d.ts +13 -0
  3. package/dist/adapters/bjs.js +28 -0
  4. package/dist/adapters/bjs.js.map +1 -0
  5. package/dist/adapters/cbp.d.ts +5 -0
  6. package/dist/adapters/cbp.js +64 -0
  7. package/dist/adapters/cbp.js.map +1 -0
  8. package/dist/adapters/cdc-wonder.d.ts +5 -0
  9. package/dist/adapters/cdc-wonder.js +68 -0
  10. package/dist/adapters/cdc-wonder.js.map +1 -0
  11. package/dist/adapters/cpsc.d.ts +4 -0
  12. package/dist/adapters/cpsc.js +125 -0
  13. package/dist/adapters/cpsc.js.map +1 -0
  14. package/dist/adapters/fhwa.d.ts +9 -0
  15. package/dist/adapters/fhwa.js +16 -0
  16. package/dist/adapters/fhwa.js.map +1 -0
  17. package/dist/adapters/foreign-assistance.d.ts +9 -0
  18. package/dist/adapters/foreign-assistance.js +42 -0
  19. package/dist/adapters/foreign-assistance.js.map +1 -0
  20. package/dist/adapters/hud-ahar.d.ts +3 -0
  21. package/dist/adapters/hud-ahar.js +80 -0
  22. package/dist/adapters/hud-ahar.js.map +1 -0
  23. package/dist/adapters/nces.d.ts +10 -0
  24. package/dist/adapters/nces.js +32 -0
  25. package/dist/adapters/nces.js.map +1 -0
  26. package/dist/adapters/nsf.d.ts +11 -0
  27. package/dist/adapters/nsf.js +25 -0
  28. package/dist/adapters/nsf.js.map +1 -0
  29. package/dist/adapters/onrr.d.ts +9 -0
  30. package/dist/adapters/onrr.js +35 -0
  31. package/dist/adapters/onrr.js.map +1 -0
  32. package/dist/adapters/sba.d.ts +10 -0
  33. package/dist/adapters/sba.js +134 -0
  34. package/dist/adapters/sba.js.map +1 -0
  35. package/dist/adapters/treasury-tic.d.ts +30 -0
  36. package/dist/adapters/treasury-tic.js +149 -0
  37. package/dist/adapters/treasury-tic.js.map +1 -0
  38. package/dist/adapters/uscourts.d.ts +8 -0
  39. package/dist/adapters/uscourts.js +8 -0
  40. package/dist/adapters/uscourts.js.map +1 -0
  41. package/dist/analysis/cite.d.ts +9 -1
  42. package/dist/analysis/cite.js +9 -2
  43. package/dist/analysis/cite.js.map +1 -1
  44. package/dist/bin/cli.d.ts +2 -0
  45. package/dist/bin/cli.js +17 -0
  46. package/dist/bin/cli.js.map +1 -1
  47. package/dist/core/generic-rest.js +42 -17
  48. package/dist/core/generic-rest.js.map +1 -1
  49. package/dist/core/guard.d.ts +32 -0
  50. package/dist/core/guard.js +176 -0
  51. package/dist/core/guard.js.map +1 -0
  52. package/dist/core/http.d.ts +10 -0
  53. package/dist/core/http.js +36 -7
  54. package/dist/core/http.js.map +1 -1
  55. package/dist/core/keys.d.ts +13 -3
  56. package/dist/core/keys.js +67 -7
  57. package/dist/core/keys.js.map +1 -1
  58. package/dist/core/package.d.ts +12 -3
  59. package/dist/core/package.js +56 -12
  60. package/dist/core/package.js.map +1 -1
  61. package/dist/core/secret_patterns.d.ts +6 -0
  62. package/dist/core/secret_patterns.js +20 -0
  63. package/dist/core/secret_patterns.js.map +1 -0
  64. package/dist/core/tabular.d.ts +43 -1
  65. package/dist/core/tabular.js +149 -6
  66. package/dist/core/tabular.js.map +1 -1
  67. package/dist/envelope.js +3 -1
  68. package/dist/envelope.js.map +1 -1
  69. package/dist/index.d.ts +29 -22
  70. package/dist/index.js +45 -46
  71. package/dist/index.js.map +1 -1
  72. package/dist/remote/app.js +87 -31
  73. package/dist/remote/app.js.map +1 -1
  74. package/dist/remote/oauth.js +8 -1
  75. package/dist/remote/oauth.js.map +1 -1
  76. package/dist/remote/pages.d.ts +3 -7
  77. package/dist/remote/pages.js +49 -19
  78. package/dist/remote/pages.js.map +1 -1
  79. package/dist/remote/sign.d.ts +7 -1
  80. package/dist/remote/sign.js +33 -7
  81. package/dist/remote/sign.js.map +1 -1
  82. package/dist/remote/store.js +14 -5
  83. package/dist/remote/store.js.map +1 -1
  84. package/dist/report/audit_report.js +29 -7
  85. package/dist/report/audit_report.js.map +1 -1
  86. package/dist/report/build_report.js +34 -4
  87. package/dist/report/build_report.js.map +1 -1
  88. package/dist/report/method_audit.js +10 -1
  89. package/dist/report/method_audit.js.map +1 -1
  90. package/dist/report/scan_secrets.d.ts +4 -1
  91. package/dist/report/scan_secrets.js +38 -18
  92. package/dist/report/scan_secrets.js.map +1 -1
  93. package/dist/server.d.ts +3 -1
  94. package/dist/server.js +46 -13
  95. package/dist/server.js.map +1 -1
  96. package/dist/tools.js +27 -6
  97. package/dist/tools.js.map +1 -1
  98. package/guide/WORKFLOW.md +134 -134
  99. package/guide/assets/disclaimer.txt +1 -1
  100. package/guide/assets/download_data.ps1 +164 -162
  101. package/guide/assets/download_data.sh +8 -2
  102. package/guide/assets/report_template.html +597 -597
  103. package/guide/references/routing.md +198 -171
  104. package/guide/references/style_guide.md +398 -398
  105. package/package.json +56 -56
  106. package/packs/acf/endpoints.json +114 -114
  107. package/packs/acf/policy.json +104 -104
  108. package/packs/actuaries/endpoints.json +82 -82
  109. package/packs/actuaries/policy.json +109 -109
  110. package/packs/bea/assets/download_bea.ps1 +182 -182
  111. package/packs/bea/docs/bea_api.md +461 -461
  112. package/packs/bea/docs/datasets.md +157 -157
  113. package/packs/bea/docs/report_patterns.md +112 -112
  114. package/packs/bea/policy.json +170 -170
  115. package/packs/bea/source.md +152 -152
  116. package/packs/bjs/endpoints.json +150 -0
  117. package/packs/bjs/policy.json +114 -0
  118. package/packs/bjs/source.md +98 -0
  119. package/packs/bls/assets/download_bls.ps1 +152 -152
  120. package/packs/bls/docs/analysis_patterns.md +108 -108
  121. package/packs/bls/docs/bls_api.md +73 -73
  122. package/packs/bls/docs/series_ids.md +149 -149
  123. package/packs/bls/policy.json +238 -238
  124. package/packs/bts/endpoints.json +346 -346
  125. package/packs/bts/policy.json +94 -94
  126. package/packs/cbp/endpoints.json +31 -0
  127. package/packs/cbp/policy.json +85 -0
  128. package/packs/cbp/source.md +57 -0
  129. package/packs/cdc/endpoints.json +197 -197
  130. package/packs/cdc/policy.json +83 -83
  131. package/packs/cdc/source.md +1 -1
  132. package/packs/cdc-wonder/endpoints.json +26 -0
  133. package/packs/cdc-wonder/policy.json +84 -0
  134. package/packs/cdc-wonder/source.md +53 -0
  135. package/packs/census/endpoints.json +99 -99
  136. package/packs/cfpb/endpoints.json +326 -326
  137. package/packs/cfpb/policy.json +119 -119
  138. package/packs/clinical-trials/endpoints.json +166 -166
  139. package/packs/clinical-trials/policy.json +84 -84
  140. package/packs/cms/endpoints.json +69 -69
  141. package/packs/cms/policy.json +96 -96
  142. package/packs/college-scorecard/endpoints.json +252 -252
  143. package/packs/college-scorecard/policy.json +106 -106
  144. package/packs/college-scorecard/source.md +1 -1
  145. package/packs/congress/endpoints.json +1701 -1701
  146. package/packs/congress/policy.json +117 -117
  147. package/packs/cpsc/endpoints.json +91 -0
  148. package/packs/cpsc/policy.json +91 -0
  149. package/packs/cpsc/source.md +76 -0
  150. package/packs/dhs-ohss/endpoints.json +66 -66
  151. package/packs/dhs-ohss/policy.json +107 -107
  152. package/packs/dhs-ohss/source.md +1 -1
  153. package/packs/doj-news/endpoints.json +59 -59
  154. package/packs/doj-news/policy.json +96 -96
  155. package/packs/doj-news/source.md +1 -1
  156. package/packs/dol/endpoints.json +817 -817
  157. package/packs/dol/policy.json +135 -135
  158. package/packs/eia/endpoints.json +717 -717
  159. package/packs/eia/policy.json +112 -112
  160. package/packs/epa/endpoints.json +291 -291
  161. package/packs/epa/policy.json +99 -99
  162. package/packs/epa-aqs/endpoints.json +173 -173
  163. package/packs/epa-aqs/policy.json +96 -96
  164. package/packs/fbi/endpoints.json +1841 -1841
  165. package/packs/fbi/policy.json +118 -118
  166. package/packs/fbi/source.md +3 -3
  167. package/packs/fda/endpoints.json +237 -237
  168. package/packs/fda/policy.json +121 -121
  169. package/packs/fdic/endpoints.json +416 -416
  170. package/packs/fdic/policy.json +83 -83
  171. package/packs/fec/endpoints.json +707 -707
  172. package/packs/fec/policy.json +93 -93
  173. package/packs/fed-board/endpoints.json +89 -89
  174. package/packs/fed-board/policy.json +136 -136
  175. package/packs/federal-register/endpoints.json +143 -143
  176. package/packs/federal-register/policy.json +86 -86
  177. package/packs/fema/endpoints.json +645 -645
  178. package/packs/fema/policy.json +103 -103
  179. package/packs/fhfa/endpoints.json +105 -105
  180. package/packs/fhfa/policy.json +109 -109
  181. package/packs/fhwa/endpoints.json +48 -0
  182. package/packs/fhwa/policy.json +91 -0
  183. package/packs/fhwa/source.md +59 -0
  184. package/packs/foreign-assistance/endpoints.json +166 -0
  185. package/packs/foreign-assistance/policy.json +80 -0
  186. package/packs/foreign-assistance/source.md +76 -0
  187. package/packs/fred/assets/download_fred.ps1 +122 -122
  188. package/packs/fred/docs/analysis_patterns.md +124 -124
  189. package/packs/fred/docs/fred_api.md +94 -94
  190. package/packs/fred/docs/series.md +188 -188
  191. package/packs/fred/policy.json +253 -253
  192. package/packs/fsa/endpoints.json +150 -150
  193. package/packs/fsa/policy.json +99 -99
  194. package/packs/fsa/source.md +1 -1
  195. package/packs/govinfo/endpoints.json +519 -519
  196. package/packs/gsa-calc/endpoints.json +93 -93
  197. package/packs/gsa-calc/policy.json +97 -97
  198. package/packs/hud/endpoints.json +146 -146
  199. package/packs/hud/policy.json +84 -84
  200. package/packs/hud/source.md +1 -1
  201. package/packs/hud-ahar/endpoints.json +92 -0
  202. package/packs/hud-ahar/policy.json +88 -0
  203. package/packs/hud-ahar/source.md +72 -0
  204. package/packs/ipums/docs/report_patterns.md +117 -117
  205. package/packs/irs-soi/endpoints.json +114 -114
  206. package/packs/irs-soi/policy.json +107 -107
  207. package/packs/medicaid/endpoints.json +412 -412
  208. package/packs/medicaid/policy.json +108 -108
  209. package/packs/naep/endpoints.json +217 -217
  210. package/packs/naep/policy.json +100 -100
  211. package/packs/naep/source.md +1 -1
  212. package/packs/nces/endpoints.json +101 -0
  213. package/packs/nces/policy.json +99 -0
  214. package/packs/nces/source.md +75 -0
  215. package/packs/nhtsa/endpoints.json +132 -132
  216. package/packs/nhtsa/policy.json +93 -93
  217. package/packs/nhtsa/source.md +1 -1
  218. package/packs/nih/endpoints.json +452 -452
  219. package/packs/nih/policy.json +86 -86
  220. package/packs/noaa/endpoints.json +431 -431
  221. package/packs/noaa/policy.json +95 -95
  222. package/packs/nrel/endpoints.json +327 -327
  223. package/packs/nrel/policy.json +96 -96
  224. package/packs/nsf/endpoints.json +33 -0
  225. package/packs/nsf/policy.json +83 -0
  226. package/packs/nsf/source.md +59 -0
  227. package/packs/nws/endpoints.json +271 -271
  228. package/packs/nws/policy.json +82 -82
  229. package/packs/nyfed/endpoints.json +80 -80
  230. package/packs/nyfed/policy.json +92 -92
  231. package/packs/omb/endpoints.json +460 -460
  232. package/packs/omb/policy.json +106 -106
  233. package/packs/onrr/endpoints.json +198 -0
  234. package/packs/onrr/policy.json +91 -0
  235. package/packs/onrr/source.md +55 -0
  236. package/packs/open-payments/endpoints.json +297 -297
  237. package/packs/open-payments/policy.json +101 -101
  238. package/packs/opm/assets/download_opm.ps1 +125 -125
  239. package/packs/opm/docs/fields.md +184 -184
  240. package/packs/opm/docs/opm_api.md +71 -71
  241. package/packs/opm/docs/report_patterns.md +83 -83
  242. package/packs/opm/lib/data_dictionary.csv +73 -73
  243. package/packs/pbgc/endpoints.json +483 -483
  244. package/packs/pbgc/policy.json +94 -94
  245. package/packs/philfed/endpoints.json +85 -85
  246. package/packs/philfed/policy.json +94 -94
  247. package/packs/port.json +65 -0
  248. package/packs/regulations/endpoints.json +287 -287
  249. package/packs/regulations/policy.json +86 -86
  250. package/packs/sba/endpoints.json +34 -0
  251. package/packs/sba/policy.json +86 -0
  252. package/packs/sba/source.md +60 -0
  253. package/packs/sec/endpoints.json +236 -236
  254. package/packs/sec/policy.json +86 -86
  255. package/packs/senate-lobbying/endpoints.json +553 -553
  256. package/packs/senate-lobbying/policy.json +99 -99
  257. package/packs/snapqc/endpoints.json +1426 -1426
  258. package/packs/snapqc/policy.json +92 -92
  259. package/packs/treasury/catalog.json +2267 -2267
  260. package/packs/treasury/docs/api_guide.md +245 -245
  261. package/packs/treasury/docs/datasets.md +56 -56
  262. package/packs/treasury/docs/report_patterns.md +126 -126
  263. package/packs/treasury/policy.json +159 -159
  264. package/packs/treasury/source.md +170 -165
  265. package/packs/treasury-tic/endpoints.json +77 -0
  266. package/packs/treasury-tic/policy.json +89 -0
  267. package/packs/treasury-tic/source.md +80 -0
  268. package/packs/treasury-yields/endpoints.json +226 -226
  269. package/packs/treasury-yields/policy.json +86 -86
  270. package/packs/usaspending/endpoints.json +1315 -1315
  271. package/packs/usaspending/policy.json +109 -109
  272. package/packs/uscourts/endpoints.json +22 -0
  273. package/packs/uscourts/policy.json +87 -0
  274. package/packs/uscourts/source.md +56 -0
  275. package/packs/usda-fna/policy.json +133 -133
  276. package/packs/usda-fooddata/endpoints.json +180 -180
  277. package/packs/usda-fooddata/policy.json +94 -94
  278. package/packs/usda-nass/endpoints.json +323 -323
  279. package/packs/usda-nass/policy.json +95 -95
  280. package/packs/usda-outlook/endpoints.json +86 -86
  281. package/packs/usda-outlook/policy.json +109 -109
  282. package/packs/usgs/endpoints.json +313 -313
  283. package/packs/usgs/policy.json +95 -95
  284. package/packs/usitc/endpoints.json +74 -74
  285. package/packs/usitc/policy.json +111 -111
  286. package/packs/uspto/endpoints.json +141 -141
  287. package/packs/uspto/policy.json +95 -95
  288. package/packs/uspto/source.md +1 -1
  289. package/packs/va/endpoints.json +414 -414
  290. package/packs/va/policy.json +101 -101
  291. package/packs/world-bank/endpoints.json +122 -122
  292. package/packs/world-bank/policy.json +101 -101
@@ -1,157 +1,157 @@
1
- # Choosing BEA data: datasets, tables, lines and concepts
2
-
3
- Read §1 to pick the dataset, §2 for verified tables and lines, §3 for the concepts that decide whether a
4
- number is right. Confirm names before you download with `request_schema`: `search: "<words>"` (NIPA titles, no key),
5
- `search: "lines <NIPA table>"` (line numbers and series codes, no key), and with a key
6
- `search: "values Regional TableName"` or `search: "Regional <words>"`. Line numbers can change at
7
- comprehensive updates, so select NIPA series by table + line *and* check the description or series code.
8
-
9
- ## Contents
10
- 1. Which dataset answers which question
11
- 2. Verified tables and lines
12
- 3. Concepts that change the answer
13
- 4. Geography notes (states, counties, metro areas)
14
- 5. Benchmarks: BEA's own numbers to check against
15
-
16
- ## 1. Which dataset answers which question
17
-
18
- | Question | Dataset (spec `dataset`) | Typical tables | Bulk (no key)? |
19
- |---|---|---|---|
20
- | GDP growth, components, contributions, prices (national) | `NIPA` | T10101, T10102, T10104-T10106, T10111, T11706 | yes |
21
- | Personal income, saving rate, PCE, PCE inflation | `NIPA` | T20100 (A/Q), T20600 (M), T20804/T20805/T20806/T20807 (M) | yes |
22
- | GDP and income per capita | `NIPA` | T70100: line 1 GDP per capita (current dollars), line 10 real GDP per capita (chained 2017 dollars), line 3 personal income; descriptions repeat ("Gross domestic product" on lines 1 and 10; "Current dollars"/"Chained (2017) dollars" under disposable personal income on lines 4 and 12): select by line or series code (RC current, RX real). Annual values are annual GDP over annual population, not the mean of the quarterly ratios | yes |
23
- | Shares of GDP (consumption, investment, government purchases, net exports) | `NIPA` | T10110 (percent of GDP, as BEA publishes it); T10105 lines 22-26 for government consumption and gross investment levels | yes |
24
- | Government receipts, spending, deficits (NIPA basis) | `NIPA` | T30100 (total), T30200 (federal), T30300 (state and local); total spending includes transfers, so "government's share of GDP" as purchases is T10110 / T10105 lines 22-26, not Table 3.1 | yes |
25
- | Corporate profits, saving and investment, trade in the NIPAs | `NIPA` | T61600D, T50100, T40100 | yes |
26
- | Detailed PCE, inventories, auto sales (lower quality) | `NIUnderlyingDetail` | U20305, U20405, U70205S | no: API (the flat files hold only the U-table lines shared with published tables) |
27
- | State GDP, by industry, real and nominal | `Regional` | SAGDP2 (current $), SAGDP9 (real), SAGDP11 (contributions), SQGDP9 (quarterly real) | yes |
28
- | State personal income, per capita income, population | `Regional` | SAINC1 (summary), SAINC4 (components), SQINC1 (quarterly), SAINC5N (earnings by industry) | yes |
29
- | State PCE, price levels (RPPs), real personal income | `Regional` | SAPCE1-SAPCE4, SARPP, SARPI | yes |
30
- | County income and GDP | `Regional` | CAINC1, CAINC4, CAINC5N, CAINC30, CAGDP2, CAGDP9 | yes |
31
- | Metro-area price parities | `Regional` | MARPP | yes |
32
- | Value added, gross output by industry (national) | `GDPbyIndustry` with workbook codes (`"table": "TVA105"`) | TVA105 value added, TVA106 real value added, TVA101 real growth, TVA102 contributions to real GDP growth, TVA110 shares of GDP; TGO1xx gross output; A and Q | yes (public workbooks) |
33
- | Same, detail the workbooks lack (Industry filters, UnderlyingGDPbyIndustry) | `GDPbyIndustry` / `UnderlyingGDPbyIndustry` (`params`: TableID, Frequency, Year, Industry) | list with the search `values GDPbyIndustry TableID` | no: API |
34
- | Trade balance, current account, by country | `ITA` (`params`: Indicator, AreaOrCountry, Frequency, Year) | Indicator BalGds (goods balance); list others with the search `values ITA Indicator` | no: API (keyless: the current account balance is NIPA T4030B line 50 "Balance on current account, ITAs" in the bulk files, or FRED `IEABC` (quarterly); T4030B can keep an older ITA vintage for some years (2010-2012 differ by a few hundred million): check against IEABC; trade balances: the FRED pack's monthly series BOPGSTB, BOPGTB, BOPSTB, EXPCH/IMPCH; see fred `docs/series.md`) |
35
- | Services trade by type and country | `IntlServTrade` | TypeOfService, TradeDirection, AreaOrCountry | no: API |
36
- | Net international investment position | `IIP` | TypeOfInvestment, Component | no: API (keyless: the FRED pack's `IIPUSNETIQ` quarterly / `IIPUSNETIA` annual net position) |
37
- | Foreign direct investment, multinationals | `MNE` | DirectionOfInvestment, Classification | no: API |
38
- | Capital stock, depreciation | `FixedAssets` | FAAt201 (see the search `values FixedAssets TableName`) | no: API |
39
- | Input-output use and make tables | `InputOutput` | TableID 56 (see the search `values InputOutput TableID`) | no: API |
40
-
41
- Things BEA does not publish, so say so rather than improvise: GDP forecasts (BEA publishes history only; CBO, the
42
- Federal Reserve and private forecasters project), monthly GDP, unemployment and jobs (BLS), CPI (BLS; BEA's measure is
43
- the PCE price index), federal budget data on a fiscal-year basis (Treasury, OMB, CBO).
44
-
45
- ## 2. Verified tables and lines
46
-
47
- NIPA lines below were checked against SeriesRegister.txt (September 2026 release). "SAAR" = seasonally adjusted at
48
- annual rates.
49
-
50
- | Table | Line | Series | What it is | Unit |
51
- |---|---|---|---|---|
52
- | T10101 | 1 | A191RL | Real GDP, percent change from preceding period | percent, annual rate (Q is annualized) |
53
- | T10101 | 2 | DPCERL | Real PCE, percent change | percent, annual rate |
54
- | T10102 | 1+ | — | Contributions to percent change in real GDP | percentage points |
55
- | T10104 | 1 | — | GDP price index | index, 2017 = 100 |
56
- | T10105 | 1 / 2 / 7 / 15 / 22 | A191RC / DPCERC / A006RC / A019RC / A822RC | GDP / PCE / investment / net exports / government, current dollars | millions of dollars (unit_mult 6), SAAR for Q |
57
- | T10106 | 1 | A191RX | Real GDP | millions of chained 2017 dollars, SAAR for Q |
58
- | T10111 | 1 | A191RO | Real GDP, percent change from the same quarter a year ago | percent |
59
- | T11706 | 1 / 2 / 3 | A191RX / A261RX / LB000009 | Real GDP / real GDI / average of GDP and GDI | chained 2017 dollars |
60
- | T20100 | 1 / 27 / 37 / 35 / 40 | A065RC / A067RC / A067RX / A072RC / B230RC | Personal income / disposable personal income / real DPI / saving rate / population (thousands) | millions; percent; thousands |
61
- | T20600 | 1 / 35 | A065RC / A072RC | Monthly personal income / saving rate | SAAR millions; percent |
62
- | T20600 | 37 / 43 | A067RX / A067RM | Monthly real disposable personal income / its percent change from the preceding month (not annualized) | chained-dollar SAAR millions; percent |
63
- | T20804 | 1 / 25 | DPCERG / DPCCRG | PCE price index / core PCE price index (excluding food and energy), monthly | index, 2017 = 100 |
64
- | T20807 | 1 / 25 | DPCERGM / DPCCRGM | PCE / core PCE prices, percent change from the preceding month | percent, **not annualized** |
65
- | T20811 | 32 / 37 | BPCERO / BPCCRO | PCE / core PCE prices, percent change from the month one year ago (the 12-month inflation rate; the table's title says "Real PCE", lines 1-31 are quantities) | percent |
66
- | T70100 | 1 / 3 | A939RC / A792RC | GDP per capita / personal income per capita, current dollars | dollars |
67
-
68
- GDP-by-industry workbook tables (checked in ValueAdded.xlsx, September 2026): line 1 = gross domestic product,
69
- line 2 = private industries, then NAICS sectors and subsectors (indentation kept in `dims`). TVA105 is in millions of
70
- dollars; TVA106 in millions of chained 2017 dollars and has an extra "Not allocated by industry" line, so line numbers
71
- differ between tables: match industries by description and order. Duplicate names (for example "General
72
- government" under federal and under state and local) are told apart by line number within a table.
73
-
74
- Regional lines (checked in the bulk files' `definition.xml` or the API guide):
75
-
76
- | Table | Line | What it is | Unit |
77
- |---|---|---|---|
78
- | SAGDP2 / SQGDP2 | 1 = all-industry total, 2 = private industries, then NAICS sectors | GDP, current dollars | millions of current dollars |
79
- | SAGDP9 / SQGDP9 | same lines as SAGDP2 | Real GDP | millions of chained 2017 dollars |
80
- | SAINC1 / SQINC1 / CAINC1 | 1 = personal income, 2 = population, 3 = per capita personal income | income (millions for states, thousands for counties); people; dollars |
81
- | SAINC4 / CAINC4 | 10 = personal income, 20 = population, 30 = per capita personal income; other lines are components | as above |
82
- | SARPP / MARPP | 1 = all items RPP | index, U.S. = 100; published about a year after state income (in October 2026 the latest RPPs and SARPI are for 2024): for the latest income year, say which RPP year you used |
83
-
84
- API table names sometimes carry an `N` suffix (`SAGDP9N`, `SAGDP2N`); the bulk files drop it. `fetch` accepts either.
85
-
86
- ## 3. Concepts that change the answer
87
-
88
- - **Nominal vs. real.** Current-dollar series include price changes; chained-dollar (real) series remove them. Growth
89
- "of the economy" means real GDP unless the user says otherwise. Real values are in chained 2017 dollars (the reference
90
- year since the 2023 comprehensive update; check `unit` in the data).
91
- - **Chained dollars do not add.** Real components do not sum to real GDP, and real state GDP does not sum to real U.S.
92
- GDP. Compute shares from current-dollar values, and use BEA's published contributions (T10102, SAGDP11) for what
93
- drove growth, never differences of chained-dollar components.
94
- - **Annual rates.** Quarterly and monthly dollar levels are SAAR: a quarter's value is what the year would total at
95
- that pace. Average the quarters for an annual figure; do not add them.
96
- - **Growth measures differ.** BEA's headline quarterly growth is the change from the preceding quarter at a compound
97
- annual rate (T10101). Alternatives: year-over-year (T10111), fourth quarter over fourth quarter, and annual average
98
- over annual average (the annual line of T10101). They can differ by more than a percentage point in turning years,
99
- so name the measure in every exhibit and sentence. For multi-year spans ("since 2019"), report the cumulative
100
- change and the average annual rate; the two order areas identically, so the choice to test as a sensitivity is
101
- the start and end period, above all a base year inside a recession or other shock.
102
- - **Price measures.** The PCE price index (T20804) is the Federal Reserve's inflation target measure; the GDP price
103
- index (T10104) covers all domestic production. Core PCE excludes food and energy.
104
- - **Per capita.** Use BEA's per capita lines when they exist (T70100, SAINC1 line 3); otherwise divide by population
105
- in the same table (T20100 line 40 is in thousands). State per capita income in real terms needs RPPs (SARPI).
106
- BEA publishes no real GDP per capita by state: divide SAGDP9 line 1 (millions of chained 2017 dollars) by
107
- SAINC1 line 2 (resident population, same vintage). The U.S. row computed this way sits a little above
108
- T70100 line 10, whose population includes the armed forces overseas: say so when comparing.
109
- - **Vintage.** BEA serves only its latest estimates. GDP has advance, second and third estimates each quarter,
110
- annual updates every September (revising several years) and comprehensive updates about every five years. Record
111
- the release in Data and Methods ("estimates as released on September 30, 2026"), and do not compare a number from an
112
- old publication with today's estimate without saying that revisions may explain the difference. Old vintages:
113
- https://apps.bea.gov/histdata/ (not through the API). Next releases: https://www.bea.gov/news/schedule.
114
- - **Suppressed cells.** Regional and industry tables use `(D)` (suppressed to avoid disclosure), `(NA)`, `(NM)`,
115
- `(L)` and others. They are not zeros. A ranking or total that needs a suppressed cell must say so or drop the area.
116
- - **Calendar years.** All BEA annual data are calendar years, including federal government spending in the NIPAs
117
- (unlike budget data, which use fiscal years). NIPA government spending also differs from budget outlays in concept.
118
- - **Industry classification.** Regional and GDP-by-industry data use NAICS. Long state series by industry begin in
119
- 1997 (SIC-based data before that are not comparable).
120
-
121
- ## 4. Geography notes
122
-
123
- - `geo_fips`: `00000` = United States; `SS000` = states (`06000` California); `91000`-`98000` = BEA regions;
124
- five-digit county FIPS (`06037` Los Angeles County).
125
- - Independent cities are their own county-level areas: "Baltimore (Independent City), MD" is 24510, "Baltimore,
126
- MD" is Baltimore County (24005); Virginia's independent cities are often combined with a county
127
- ("Albemarle + Charlottesville"). Match by FIPS, not by name.
128
- - County tables (CAINC*) and state tables (SAINC*) come out on different schedules: from late September to
129
- early December the state table carries the newer annual revision, so a county's state row in CAINC1 and the
130
- same state in SAINC1 can differ. Compare a county with its state from the same table.
131
- - `geo_fips: "STATE"` returns the 50 states, the District of Columbia and the U.S. total. Say whether D.C. is
132
- included in rankings ("the 50 states and the District of Columbia").
133
- - In the state GDP tables (SAGDP*), the U.S. row is national GDP (it matched NIPA T10106 line 1 to rounding in the
134
- September 2026 vintage); the *sum of the states* is what differs, because it leaves out federal military and
135
- civilian activity overseas and uses different source data (BEA footnote 1, in `notes.csv`). For other tables, read
136
- the table's footnotes in `notes.csv` before comparing a state total with a NIPA figure. Compare states with the U.S.
137
- figure from the same table.
138
- - **Metro areas:** since February 2026 BEA no longer produces GDP or personal income for metropolitan statistical
139
- areas, micropolitan areas, metropolitan divisions, combined areas or metro/nonmetro portions. For a metro estimate,
140
- sum the component counties' current-dollar values (county-to-MSA delineations:
141
- https://apps.bea.gov/regional/geography.htm; BEA's tool: https://github.com/us-bea/bea_geo_aggregator), say that
142
- it is an aggregation of county data, and do not sum chained-dollar values. Older metro estimates are in
143
- https://apps.bea.gov/histdata/. MSA price parities (MARPP) are still published.
144
-
145
- ## 5. Benchmarks
146
-
147
- Compute what you can from levels and check it against BEA's own published numbers (fetch the
148
- published table too and compare); any mismatch beyond rounding means a selection or method error:
149
- - real GDP growth from T10106 levels vs. T10101 line 1 (quarterly, annualized) or the annual line;
150
- - year-over-year growth vs. T10111;
151
- - monthly PCE inflation from T20804 (plain monthly change) vs. T20807, and 12-month inflation
152
- vs. T20811 lines 32 / 37;
153
- - the U.S. row of SAGDP9 / SAGDP2 vs. NIPA T10106 / T10105 line 1 levels (they match within a few million dollars; a free
154
- check that the state table, line and units were read right);
155
- - shares of GDP from T10105 current dollars vs. the "percent of GDP" figures in BEA releases.
156
- Also compare the headline number with the latest BEA news release (https://www.bea.gov/news) and say in Data and
157
- Methods whether it matches.
1
+ # Choosing BEA data: datasets, tables, lines and concepts
2
+
3
+ Read §1 to pick the dataset, §2 for verified tables and lines, §3 for the concepts that decide whether a
4
+ number is right. Confirm names before you download with `request_schema`: `search: "<words>"` (NIPA titles, no key),
5
+ `search: "lines <NIPA table>"` (line numbers and series codes, no key), and with a key
6
+ `search: "values Regional TableName"` or `search: "Regional <words>"`. Line numbers can change at
7
+ comprehensive updates, so select NIPA series by table + line *and* check the description or series code.
8
+
9
+ ## Contents
10
+ 1. Which dataset answers which question
11
+ 2. Verified tables and lines
12
+ 3. Concepts that change the answer
13
+ 4. Geography notes (states, counties, metro areas)
14
+ 5. Benchmarks: BEA's own numbers to check against
15
+
16
+ ## 1. Which dataset answers which question
17
+
18
+ | Question | Dataset (spec `dataset`) | Typical tables | Bulk (no key)? |
19
+ |---|---|---|---|
20
+ | GDP growth, components, contributions, prices (national) | `NIPA` | T10101, T10102, T10104-T10106, T10111, T11706 | yes |
21
+ | Personal income, saving rate, PCE, PCE inflation | `NIPA` | T20100 (A/Q), T20600 (M), T20804/T20805/T20806/T20807 (M) | yes |
22
+ | GDP and income per capita | `NIPA` | T70100: line 1 GDP per capita (current dollars), line 10 real GDP per capita (chained 2017 dollars), line 3 personal income; descriptions repeat ("Gross domestic product" on lines 1 and 10; "Current dollars"/"Chained (2017) dollars" under disposable personal income on lines 4 and 12): select by line or series code (RC current, RX real). Annual values are annual GDP over annual population, not the mean of the quarterly ratios | yes |
23
+ | Shares of GDP (consumption, investment, government purchases, net exports) | `NIPA` | T10110 (percent of GDP, as BEA publishes it); T10105 lines 22-26 for government consumption and gross investment levels | yes |
24
+ | Government receipts, spending, deficits (NIPA basis) | `NIPA` | T30100 (total), T30200 (federal), T30300 (state and local); total spending includes transfers, so "government's share of GDP" as purchases is T10110 / T10105 lines 22-26, not Table 3.1 | yes |
25
+ | Corporate profits, saving and investment, trade in the NIPAs | `NIPA` | T61600D, T50100, T40100 | yes |
26
+ | Detailed PCE, inventories, auto sales (lower quality) | `NIUnderlyingDetail` | U20305, U20405, U70205S | no: API (the flat files hold only the U-table lines shared with published tables) |
27
+ | State GDP, by industry, real and nominal | `Regional` | SAGDP2 (current $), SAGDP9 (real), SAGDP11 (contributions), SQGDP9 (quarterly real) | yes |
28
+ | State personal income, per capita income, population | `Regional` | SAINC1 (summary), SAINC4 (components), SQINC1 (quarterly), SAINC5N (earnings by industry) | yes |
29
+ | State PCE, price levels (RPPs), real personal income | `Regional` | SAPCE1-SAPCE4, SARPP, SARPI | yes |
30
+ | County income and GDP | `Regional` | CAINC1, CAINC4, CAINC5N, CAINC30, CAGDP2, CAGDP9 | yes |
31
+ | Metro-area price parities | `Regional` | MARPP | yes |
32
+ | Value added, gross output by industry (national) | `GDPbyIndustry` with workbook codes (`"table": "TVA105"`) | TVA105 value added, TVA106 real value added, TVA101 real growth, TVA102 contributions to real GDP growth, TVA110 shares of GDP; TGO1xx gross output; A and Q | yes (public workbooks) |
33
+ | Same, detail the workbooks lack (Industry filters, UnderlyingGDPbyIndustry) | `GDPbyIndustry` / `UnderlyingGDPbyIndustry` (`params`: TableID, Frequency, Year, Industry) | list with the search `values GDPbyIndustry TableID` | no: API |
34
+ | Trade balance, current account, by country | `ITA` (`params`: Indicator, AreaOrCountry, Frequency, Year) | Indicator BalGds (goods balance); list others with the search `values ITA Indicator` | no: API (keyless: the current account balance is NIPA T4030B line 50 "Balance on current account, ITAs" in the bulk files, or FRED `IEABC` (quarterly); T4030B can keep an older ITA vintage for some years (2010-2012 differ by a few hundred million): check against IEABC; trade balances: the FRED pack's monthly series BOPGSTB, BOPGTB, BOPSTB, EXPCH/IMPCH; see fred `docs/series.md`) |
35
+ | Services trade by type and country | `IntlServTrade` | TypeOfService, TradeDirection, AreaOrCountry | no: API |
36
+ | Net international investment position | `IIP` | TypeOfInvestment, Component | no: API (keyless: the FRED pack's `IIPUSNETIQ` quarterly / `IIPUSNETIA` annual net position) |
37
+ | Foreign direct investment, multinationals | `MNE` | DirectionOfInvestment, Classification | no: API |
38
+ | Capital stock, depreciation | `FixedAssets` | FAAt201 (see the search `values FixedAssets TableName`) | no: API |
39
+ | Input-output use and make tables | `InputOutput` | TableID 56 (see the search `values InputOutput TableID`) | no: API |
40
+
41
+ Things BEA does not publish, so say so rather than improvise: GDP forecasts (BEA publishes history only; CBO, the
42
+ Federal Reserve and private forecasters project), monthly GDP, unemployment and jobs (BLS), CPI (BLS; BEA's measure is
43
+ the PCE price index), federal budget data on a fiscal-year basis (Treasury, OMB, CBO).
44
+
45
+ ## 2. Verified tables and lines
46
+
47
+ NIPA lines below were checked against SeriesRegister.txt (September 2026 release). "SAAR" = seasonally adjusted at
48
+ annual rates.
49
+
50
+ | Table | Line | Series | What it is | Unit |
51
+ |---|---|---|---|---|
52
+ | T10101 | 1 | A191RL | Real GDP, percent change from preceding period | percent, annual rate (Q is annualized) |
53
+ | T10101 | 2 | DPCERL | Real PCE, percent change | percent, annual rate |
54
+ | T10102 | 1+ | — | Contributions to percent change in real GDP | percentage points |
55
+ | T10104 | 1 | — | GDP price index | index, 2017 = 100 |
56
+ | T10105 | 1 / 2 / 7 / 15 / 22 | A191RC / DPCERC / A006RC / A019RC / A822RC | GDP / PCE / investment / net exports / government, current dollars | millions of dollars (unit_mult 6), SAAR for Q |
57
+ | T10106 | 1 | A191RX | Real GDP | millions of chained 2017 dollars, SAAR for Q |
58
+ | T10111 | 1 | A191RO | Real GDP, percent change from the same quarter a year ago | percent |
59
+ | T11706 | 1 / 2 / 3 | A191RX / A261RX / LB000009 | Real GDP / real GDI / average of GDP and GDI | chained 2017 dollars |
60
+ | T20100 | 1 / 27 / 37 / 35 / 40 | A065RC / A067RC / A067RX / A072RC / B230RC | Personal income / disposable personal income / real DPI / saving rate / population (thousands) | millions; percent; thousands |
61
+ | T20600 | 1 / 35 | A065RC / A072RC | Monthly personal income / saving rate | SAAR millions; percent |
62
+ | T20600 | 37 / 43 | A067RX / A067RM | Monthly real disposable personal income / its percent change from the preceding month (not annualized) | chained-dollar SAAR millions; percent |
63
+ | T20804 | 1 / 25 | DPCERG / DPCCRG | PCE price index / core PCE price index (excluding food and energy), monthly | index, 2017 = 100 |
64
+ | T20807 | 1 / 25 | DPCERGM / DPCCRGM | PCE / core PCE prices, percent change from the preceding month | percent, **not annualized** |
65
+ | T20811 | 32 / 37 | BPCERO / BPCCRO | PCE / core PCE prices, percent change from the month one year ago (the 12-month inflation rate; the table's title says "Real PCE", lines 1-31 are quantities) | percent |
66
+ | T70100 | 1 / 3 | A939RC / A792RC | GDP per capita / personal income per capita, current dollars | dollars |
67
+
68
+ GDP-by-industry workbook tables (checked in ValueAdded.xlsx, September 2026): line 1 = gross domestic product,
69
+ line 2 = private industries, then NAICS sectors and subsectors (indentation kept in `dims`). TVA105 is in millions of
70
+ dollars; TVA106 in millions of chained 2017 dollars and has an extra "Not allocated by industry" line, so line numbers
71
+ differ between tables: match industries by description and order. Duplicate names (for example "General
72
+ government" under federal and under state and local) are told apart by line number within a table.
73
+
74
+ Regional lines (checked in the bulk files' `definition.xml` or the API guide):
75
+
76
+ | Table | Line | What it is | Unit |
77
+ |---|---|---|---|
78
+ | SAGDP2 / SQGDP2 | 1 = all-industry total, 2 = private industries, then NAICS sectors | GDP, current dollars | millions of current dollars |
79
+ | SAGDP9 / SQGDP9 | same lines as SAGDP2 | Real GDP | millions of chained 2017 dollars |
80
+ | SAINC1 / SQINC1 / CAINC1 | 1 = personal income, 2 = population, 3 = per capita personal income | income (millions for states, thousands for counties); people; dollars |
81
+ | SAINC4 / CAINC4 | 10 = personal income, 20 = population, 30 = per capita personal income; other lines are components | as above |
82
+ | SARPP / MARPP | 1 = all items RPP | index, U.S. = 100; published about a year after state income (in October 2026 the latest RPPs and SARPI are for 2024): for the latest income year, say which RPP year you used |
83
+
84
+ API table names sometimes carry an `N` suffix (`SAGDP9N`, `SAGDP2N`); the bulk files drop it. `fetch` accepts either.
85
+
86
+ ## 3. Concepts that change the answer
87
+
88
+ - **Nominal vs. real.** Current-dollar series include price changes; chained-dollar (real) series remove them. Growth
89
+ "of the economy" means real GDP unless the user says otherwise. Real values are in chained 2017 dollars (the reference
90
+ year since the 2023 comprehensive update; check `unit` in the data).
91
+ - **Chained dollars do not add.** Real components do not sum to real GDP, and real state GDP does not sum to real U.S.
92
+ GDP. Compute shares from current-dollar values, and use BEA's published contributions (T10102, SAGDP11) for what
93
+ drove growth, never differences of chained-dollar components.
94
+ - **Annual rates.** Quarterly and monthly dollar levels are SAAR: a quarter's value is what the year would total at
95
+ that pace. Average the quarters for an annual figure; do not add them.
96
+ - **Growth measures differ.** BEA's headline quarterly growth is the change from the preceding quarter at a compound
97
+ annual rate (T10101). Alternatives: year-over-year (T10111), fourth quarter over fourth quarter, and annual average
98
+ over annual average (the annual line of T10101). They can differ by more than a percentage point in turning years,
99
+ so name the measure in every exhibit and sentence. For multi-year spans ("since 2019"), report the cumulative
100
+ change and the average annual rate; the two order areas identically, so the choice to test as a sensitivity is
101
+ the start and end period, above all a base year inside a recession or other shock.
102
+ - **Price measures.** The PCE price index (T20804) is the Federal Reserve's inflation target measure; the GDP price
103
+ index (T10104) covers all domestic production. Core PCE excludes food and energy.
104
+ - **Per capita.** Use BEA's per capita lines when they exist (T70100, SAINC1 line 3); otherwise divide by population
105
+ in the same table (T20100 line 40 is in thousands). State per capita income in real terms needs RPPs (SARPI).
106
+ BEA publishes no real GDP per capita by state: divide SAGDP9 line 1 (millions of chained 2017 dollars) by
107
+ SAINC1 line 2 (resident population, same vintage). The U.S. row computed this way sits a little above
108
+ T70100 line 10, whose population includes the armed forces overseas: say so when comparing.
109
+ - **Vintage.** BEA serves only its latest estimates. GDP has advance, second and third estimates each quarter,
110
+ annual updates every September (revising several years) and comprehensive updates about every five years. Record
111
+ the release in Data and Methods ("estimates as released on September 30, 2026"), and do not compare a number from an
112
+ old publication with today's estimate without saying that revisions may explain the difference. Old vintages:
113
+ https://apps.bea.gov/histdata/ (not through the API). Next releases: https://www.bea.gov/news/schedule.
114
+ - **Suppressed cells.** Regional and industry tables use `(D)` (suppressed to avoid disclosure), `(NA)`, `(NM)`,
115
+ `(L)` and others. They are not zeros. A ranking or total that needs a suppressed cell must say so or drop the area.
116
+ - **Calendar years.** All BEA annual data are calendar years, including federal government spending in the NIPAs
117
+ (unlike budget data, which use fiscal years). NIPA government spending also differs from budget outlays in concept.
118
+ - **Industry classification.** Regional and GDP-by-industry data use NAICS. Long state series by industry begin in
119
+ 1997 (SIC-based data before that are not comparable).
120
+
121
+ ## 4. Geography notes
122
+
123
+ - `geo_fips`: `00000` = United States; `SS000` = states (`06000` California); `91000`-`98000` = BEA regions;
124
+ five-digit county FIPS (`06037` Los Angeles County).
125
+ - Independent cities are their own county-level areas: "Baltimore (Independent City), MD" is 24510, "Baltimore,
126
+ MD" is Baltimore County (24005); Virginia's independent cities are often combined with a county
127
+ ("Albemarle + Charlottesville"). Match by FIPS, not by name.
128
+ - County tables (CAINC*) and state tables (SAINC*) come out on different schedules: from late September to
129
+ early December the state table carries the newer annual revision, so a county's state row in CAINC1 and the
130
+ same state in SAINC1 can differ. Compare a county with its state from the same table.
131
+ - `geo_fips: "STATE"` returns the 50 states, the District of Columbia and the U.S. total. Say whether D.C. is
132
+ included in rankings ("the 50 states and the District of Columbia").
133
+ - In the state GDP tables (SAGDP*), the U.S. row is national GDP (it matched NIPA T10106 line 1 to rounding in the
134
+ September 2026 vintage); the *sum of the states* is what differs, because it leaves out federal military and
135
+ civilian activity overseas and uses different source data (BEA footnote 1, in `notes.csv`). For other tables, read
136
+ the table's footnotes in `notes.csv` before comparing a state total with a NIPA figure. Compare states with the U.S.
137
+ figure from the same table.
138
+ - **Metro areas:** since February 2026 BEA no longer produces GDP or personal income for metropolitan statistical
139
+ areas, micropolitan areas, metropolitan divisions, combined areas or metro/nonmetro portions. For a metro estimate,
140
+ sum the component counties' current-dollar values (county-to-MSA delineations:
141
+ https://apps.bea.gov/regional/geography.htm; BEA's tool: https://github.com/us-bea/bea_geo_aggregator), say that
142
+ it is an aggregation of county data, and do not sum chained-dollar values. Older metro estimates are in
143
+ https://apps.bea.gov/histdata/. MSA price parities (MARPP) are still published.
144
+
145
+ ## 5. Benchmarks
146
+
147
+ Compute what you can from levels and check it against BEA's own published numbers (fetch the
148
+ published table too and compare); any mismatch beyond rounding means a selection or method error:
149
+ - real GDP growth from T10106 levels vs. T10101 line 1 (quarterly, annualized) or the annual line;
150
+ - year-over-year growth vs. T10111;
151
+ - monthly PCE inflation from T20804 (plain monthly change) vs. T20807, and 12-month inflation
152
+ vs. T20811 lines 32 / 37;
153
+ - the U.S. row of SAGDP9 / SAGDP2 vs. NIPA T10106 / T10105 line 1 levels (they match within a few million dollars; a free
154
+ check that the state table, line and units were read right);
155
+ - shares of GDP from T10105 current dollars vs. the "percent of GDP" figures in BEA releases.
156
+ Also compare the headline number with the latest BEA news release (https://www.bea.gov/news) and say in Data and
157
+ Methods whether it matches.
@@ -1,112 +1,112 @@
1
- # Report patterns for BEA data products
2
-
3
- Use this file to shape both the analysis and the product. The aim is something a careful reviewer would
4
- recognize: precise measures (real or nominal, which growth rate, which release), a lead summary with
5
- numbers, numbered exhibits that each carry notes and a source line, data shipped alongside, and
6
- limitations stated plainly.
7
-
8
- ## Typical questions and how they are framed
9
-
10
- These recur in work by statistical and policy agencies (BEA itself, CBO, the Federal Reserve, CRS, GAO,
11
- state budget offices, research institutes), so there is usually a precedent to follow and benchmark against.
12
-
13
- - **How fast is the economy growing?** (NIPA T10101, T10106, T10102). Measures: real GDP growth, quarterly
14
- at an annual rate and annual; contributions of consumer spending, investment, government and net exports
15
- (from T10102, not computed). Headline style: "Real GDP increased at an annual rate of 2.2 percent in the
16
- second quarter of 2026, according to BEA's third estimate." Name the estimate (advance, second, third) and
17
- compare with the previous quarter and the prior-year average.
18
- - **Inflation by BEA's measure** (T20804, T20807; T10104 for GDP prices). PCE and core PCE price indexes,
19
- 12-month changes for monthly data; compare with the Federal Reserve's 2 percent objective only as a fact,
20
- not advice.
21
- - **Household income and saving** (T20100, T20600, T70100). Personal income, disposable personal income in
22
- real terms, the saving rate, per capita amounts. Distinguish personal income (includes transfers and
23
- employer contributions) from household money income in Census surveys.
24
- - **Which states (or counties) are growing fastest?** (SAGDP9, SQGDP9, SAINC1, CAINC1). Real GDP growth or
25
- per capita income by state, ranked; regional patterns (BEA regions); industry drivers (SAGDP11
26
- contributions, SAGDP2 shares). Report the U.S. figure from the same table, say whether D.C. is included,
27
- and note (D) suppressions.
28
- - **Industry structure** (GDPbyIndustry; SAGDP2 by state). Value added shares of GDP in current dollars;
29
- real growth by industry; long series start in 1997 (NAICS).
30
- - **Trade and international position** (ITA, IntlServTrade, IIP). Goods and services balances by country,
31
- current account as a share of GDP (use T10105 for GDP).
32
- - **Government in the economy** (T30100-T30300). Receipts, expenditures, net saving on a NIPA, calendar-year
33
- basis; explain how it differs from budget (fiscal-year) data when the reader may compare them.
34
- - **Cost of living across places** (SARPP, MARPP, SARPI). Regional price parities (U.S. = 100) and real
35
- personal income; say that RPPs compare price levels across places in one year, not changes over time.
36
-
37
- ## Conventions to follow
38
-
39
- **Measures and definitions**
40
- - Real values in chained (2017) dollars; current-dollar values in nominal terms; say which in every exhibit
41
- subtitle ("Billions of chained 2017 dollars", "Percent change at an annual rate").
42
- - Growth rates: name the measure (quarter at an annual rate, year over year, Q4 over Q4, annual average).
43
- - Shares of GDP or of the U.S. total: current dollars only.
44
- - Per capita: BEA's published per capita lines first; otherwise the population line of the same table.
45
- - Rankings: say how many areas are ranked and what happens with suppressed values or ties.
46
-
47
- **Accuracy**
48
- - Every computed growth rate or share that BEA also publishes is checked against BEA's number
49
- (fetched alongside), and the check is reported in Data and Methods.
50
- - The vintage: the release date and estimate (for example "the third estimate for the second quarter of 2026,
51
- released September 25, 2026", or "state GDP as released on September 30, 2026") is in the notes page and
52
- in Data and Methods; the products say estimates are subject to revision.
53
- - No sampling error is attached to BEA estimates, so there are no standard errors and no "statistically
54
- different". Describe differences by size; for small differences, note that revisions are often of that size
55
- (find and cite BEA's latest revision study, published in the *Survey of Current Business*, for the typical
56
- size of revisions to the measure at hand), and say so instead of overinterpreting.
57
- - Do not attribute causes beyond what the accounts show. "Growth was led by consumer spending" is a
58
- contribution fact; "because of tariffs" is not something BEA data establish.
59
-
60
- **Publication structure (mirrored in `build_report`, `"mode": "report"`)**
61
-
62
- The default layout, the **exhibit chartbook**, runs in this order:
63
- 1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart that has its own title and unit label.
64
- 2. **At a Glance** (one page of about 300–420 words):
65
- - one framing paragraph saying what was examined, the population, the period and the dimensions;
66
- - 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by 2–4 sentences with the key numbers.
67
- 3. **Contents:** the Introduction subsections, each section with an "Exhibits a–b" sub-line, the appendixes, and About This Document when there is one.
68
- 4. **List of Exhibits:** grouped under section headings, each entry "N. Title, years".
69
- 5. **Notes About This Report** (also titled "Notes" or "Notes and Definitions"). Short unnumbered paragraphs covering:
70
- - calendar years;
71
- - "Numbers in the text and exhibits may not add up to totals because of rounding.";
72
- - real vs. nominal, the chained-dollar reference year, seasonal adjustment at annual rates;
73
- - the data source, tables and vintage (release date), and that BEA revises its estimates;
74
- - key definitions (the growth measure, per capita, the areas covered);
75
- - recession shading, if any;
76
- - where the data are posted.
77
- 6. **Introduction** (or "Summary and Introduction"):
78
- - a lead paragraph with the headline numbers;
79
- - question-style subheadings, one per section ("Which States Grew Fastest?");
80
- - closing subsections such as "How Are Growth Rates Measured?", "What Data Were Used?" and, when updating earlier work, "What Is New in This Report?".
81
- 7. **Thematic sections** (2–5, unnumbered):
82
- - Each opens on a full-width page with 1–3 summary paragraphs.
83
- - Then comes **one exhibit per page**: "Exhibit N." with a title-case title ending in ", 1998 to 2018", a unit label above the chart, and 2–4 narrative paragraphs beside it (levels, changes, comparisons, "(see Exhibit 5)").
84
- - Below the chart: the data source line ("Data source: `<organization>`, using data from …", or "Data source: Analyst calculations using data from …" when no organization is named), then the notes, then lettered notes ("a.").
85
- 8. **Appendix A: Data and Methods** (or "Appendix: Estimating …"): data and vintage, tables and lines, definitions, computations, checks against BEA's published figures, revisions and limitations. Sometimes followed by **Appendix B: Definitions**, an alphabetical glossary.
86
- 9. **About This Document** (optional), in this order:
87
- - who requested it, or what question prompted it;
88
- - who prepared it, with what data and tools;
89
- - the reviewers, if any;
90
- - the date.
91
- 10. **Footnotes** are numbered in each part (restarting in each section), and cite publications as: Organization, *Title* (Month Year), URL.
92
-
93
- Other variants, not built by `build_report`:
94
- - **Long-form**:
95
- - a Summary with Figure S-1 / Table S-1;
96
- - "Chapter N:" sections in two-column prose with embedded "Figure 1-1." / "Table 2-3.";
97
- - Boxes;
98
- - a List of Tables and Figures at the back.
99
- - **Hybrid**: full-width pages each with a heading, a paragraph and unnumbered charts; sources pooled in an appendix.
100
- - Use `"mode": "paper"` when a prose-led product is wanted.
101
-
102
-
103
- **Reading PDFs from sites that block scripts:** some publishers refuse scripts and the in-app browser (HTTP 403, bot-check slider). Fetch `https://web.archive.org/web/<year>/<full pdf url>` and extract the text with pypdf. If the plain year URL returns HTML, use a CDX timestamp with `id_` (for example `https://web.archive.org/web/20240430034127id_/<url>`). Cite the original URL.
104
-
105
- **Data files:** `data/bea_data.csv`, `data/notes.csv`, `data/request.json` and each exhibit's CSV ship with the report, so every number can be traced. BEA data are public domain, so the replication package includes the data.
106
-
107
- **Chart forms**
108
- - Trends over time: line charts with at most 4–5 series; quarterly growth rates as columns (positive and negative bars read better than a line).
109
- - Levels and growth together: two exhibits, not a dual axis.
110
- - Group comparisons at a point in time (states, industries): horizontal bars sorted by value; for all 50 states plus D.C., a sorted bar chart or a table, with the U.S. value marked in the notes or as its own bar.
111
- - Composition (contributions to growth, shares of GDP): stacked columns, with the total shown as its own series or in the text.
112
- - No dual axes, no pie charts, no 3-D. Maps need a library the builder does not have; use sorted bars.
1
+ # Report patterns for BEA data products
2
+
3
+ Use this file to shape both the analysis and the product. The aim is something a careful reviewer would
4
+ recognize: precise measures (real or nominal, which growth rate, which release), a lead summary with
5
+ numbers, numbered exhibits that each carry notes and a source line, data shipped alongside, and
6
+ limitations stated plainly.
7
+
8
+ ## Typical questions and how they are framed
9
+
10
+ These recur in work by statistical and policy agencies (BEA itself, CBO, the Federal Reserve, CRS, GAO,
11
+ state budget offices, research institutes), so there is usually a precedent to follow and benchmark against.
12
+
13
+ - **How fast is the economy growing?** (NIPA T10101, T10106, T10102). Measures: real GDP growth, quarterly
14
+ at an annual rate and annual; contributions of consumer spending, investment, government and net exports
15
+ (from T10102, not computed). Headline style: "Real GDP increased at an annual rate of 2.2 percent in the
16
+ second quarter of 2026, according to BEA's third estimate." Name the estimate (advance, second, third) and
17
+ compare with the previous quarter and the prior-year average.
18
+ - **Inflation by BEA's measure** (T20804, T20807; T10104 for GDP prices). PCE and core PCE price indexes,
19
+ 12-month changes for monthly data; compare with the Federal Reserve's 2 percent objective only as a fact,
20
+ not advice.
21
+ - **Household income and saving** (T20100, T20600, T70100). Personal income, disposable personal income in
22
+ real terms, the saving rate, per capita amounts. Distinguish personal income (includes transfers and
23
+ employer contributions) from household money income in Census surveys.
24
+ - **Which states (or counties) are growing fastest?** (SAGDP9, SQGDP9, SAINC1, CAINC1). Real GDP growth or
25
+ per capita income by state, ranked; regional patterns (BEA regions); industry drivers (SAGDP11
26
+ contributions, SAGDP2 shares). Report the U.S. figure from the same table, say whether D.C. is included,
27
+ and note (D) suppressions.
28
+ - **Industry structure** (GDPbyIndustry; SAGDP2 by state). Value added shares of GDP in current dollars;
29
+ real growth by industry; long series start in 1997 (NAICS).
30
+ - **Trade and international position** (ITA, IntlServTrade, IIP). Goods and services balances by country,
31
+ current account as a share of GDP (use T10105 for GDP).
32
+ - **Government in the economy** (T30100-T30300). Receipts, expenditures, net saving on a NIPA, calendar-year
33
+ basis; explain how it differs from budget (fiscal-year) data when the reader may compare them.
34
+ - **Cost of living across places** (SARPP, MARPP, SARPI). Regional price parities (U.S. = 100) and real
35
+ personal income; say that RPPs compare price levels across places in one year, not changes over time.
36
+
37
+ ## Conventions to follow
38
+
39
+ **Measures and definitions**
40
+ - Real values in chained (2017) dollars; current-dollar values in nominal terms; say which in every exhibit
41
+ subtitle ("Billions of chained 2017 dollars", "Percent change at an annual rate").
42
+ - Growth rates: name the measure (quarter at an annual rate, year over year, Q4 over Q4, annual average).
43
+ - Shares of GDP or of the U.S. total: current dollars only.
44
+ - Per capita: BEA's published per capita lines first; otherwise the population line of the same table.
45
+ - Rankings: say how many areas are ranked and what happens with suppressed values or ties.
46
+
47
+ **Accuracy**
48
+ - Every computed growth rate or share that BEA also publishes is checked against BEA's number
49
+ (fetched alongside), and the check is reported in Data and Methods.
50
+ - The vintage: the release date and estimate (for example "the third estimate for the second quarter of 2026,
51
+ released September 25, 2026", or "state GDP as released on September 30, 2026") is in the notes page and
52
+ in Data and Methods; the products say estimates are subject to revision.
53
+ - No sampling error is attached to BEA estimates, so there are no standard errors and no "statistically
54
+ different". Describe differences by size; for small differences, note that revisions are often of that size
55
+ (find and cite BEA's latest revision study, published in the *Survey of Current Business*, for the typical
56
+ size of revisions to the measure at hand), and say so instead of overinterpreting.
57
+ - Do not attribute causes beyond what the accounts show. "Growth was led by consumer spending" is a
58
+ contribution fact; "because of tariffs" is not something BEA data establish.
59
+
60
+ **Publication structure (mirrored in `build_report`, `"mode": "report"`)**
61
+
62
+ The default layout, the **exhibit chartbook**, runs in this order:
63
+ 1. **Cover:** "Month Year", the title (with the period for trend reports), and a hero chart that has its own title and unit label.
64
+ 2. **At a Glance** (one page of about 300–420 words):
65
+ - one framing paragraph saying what was examined, the population, the period and the dimensions;
66
+ - 3–5 bullets, each opening with a **bold lead phrase.** that names a section, followed by 2–4 sentences with the key numbers.
67
+ 3. **Contents:** the Introduction subsections, each section with an "Exhibits a–b" sub-line, the appendixes, and About This Document when there is one.
68
+ 4. **List of Exhibits:** grouped under section headings, each entry "N. Title, years".
69
+ 5. **Notes About This Report** (also titled "Notes" or "Notes and Definitions"). Short unnumbered paragraphs covering:
70
+ - calendar years;
71
+ - "Numbers in the text and exhibits may not add up to totals because of rounding.";
72
+ - real vs. nominal, the chained-dollar reference year, seasonal adjustment at annual rates;
73
+ - the data source, tables and vintage (release date), and that BEA revises its estimates;
74
+ - key definitions (the growth measure, per capita, the areas covered);
75
+ - recession shading, if any;
76
+ - where the data are posted.
77
+ 6. **Introduction** (or "Summary and Introduction"):
78
+ - a lead paragraph with the headline numbers;
79
+ - question-style subheadings, one per section ("Which States Grew Fastest?");
80
+ - closing subsections such as "How Are Growth Rates Measured?", "What Data Were Used?" and, when updating earlier work, "What Is New in This Report?".
81
+ 7. **Thematic sections** (2–5, unnumbered):
82
+ - Each opens on a full-width page with 1–3 summary paragraphs.
83
+ - Then comes **one exhibit per page**: "Exhibit N." with a title-case title ending in ", 1998 to 2018", a unit label above the chart, and 2–4 narrative paragraphs beside it (levels, changes, comparisons, "(see Exhibit 5)").
84
+ - Below the chart: the data source line ("Data source: `<organization>`, using data from …", or "Data source: Analyst calculations using data from …" when no organization is named), then the notes, then lettered notes ("a.").
85
+ 8. **Appendix A: Data and Methods** (or "Appendix: Estimating …"): data and vintage, tables and lines, definitions, computations, checks against BEA's published figures, revisions and limitations. Sometimes followed by **Appendix B: Definitions**, an alphabetical glossary.
86
+ 9. **About This Document** (optional), in this order:
87
+ - who requested it, or what question prompted it;
88
+ - who prepared it, with what data and tools;
89
+ - the reviewers, if any;
90
+ - the date.
91
+ 10. **Footnotes** are numbered in each part (restarting in each section), and cite publications as: Organization, *Title* (Month Year), URL.
92
+
93
+ Other variants, not built by `build_report`:
94
+ - **Long-form**:
95
+ - a Summary with Figure S-1 / Table S-1;
96
+ - "Chapter N:" sections in two-column prose with embedded "Figure 1-1." / "Table 2-3.";
97
+ - Boxes;
98
+ - a List of Tables and Figures at the back.
99
+ - **Hybrid**: full-width pages each with a heading, a paragraph and unnumbered charts; sources pooled in an appendix.
100
+ - Use `"mode": "paper"` when a prose-led product is wanted.
101
+
102
+
103
+ **Reading PDFs from sites that block scripts:** some publishers refuse scripts and the in-app browser (HTTP 403, bot-check slider). Fetch `https://web.archive.org/web/<year>/<full pdf url>` and extract the text with pypdf. If the plain year URL returns HTML, use a CDX timestamp with `id_` (for example `https://web.archive.org/web/20240430034127id_/<url>`). Cite the original URL.
104
+
105
+ **Data files:** `data/bea_data.csv`, `data/notes.csv`, `data/request.json` and each exhibit's CSV ship with the report, so every number can be traced. BEA data are public domain, so the replication package includes the data.
106
+
107
+ **Chart forms**
108
+ - Trends over time: line charts with at most 4–5 series; quarterly growth rates as columns (positive and negative bars read better than a line).
109
+ - Levels and growth together: two exhibits, not a dual axis.
110
+ - Group comparisons at a point in time (states, industries): horizontal bars sorted by value; for all 50 states plus D.C., a sorted bar chart or a table, with the U.S. value marked in the notes or as its own bar.
111
+ - Composition (contributions to growth, shares of GDP): stacked columns, with the total shown as its own series or in the text.
112
+ - No dual axes, no pie charts, no 3-D. Maps need a library the builder does not have; use sorted bars.