docs: fix stale fixture description and Direct/Total vignette figures (M1, M2, M5)

M5: README.md described the bundled fixture as a "3.6 MB two-year slice
(2019 + 2020)"; it's now a 15 MB four-year slice (2011, 2012, 2019,
2020), matching the regenerated fixture and the vignette's own
description.

M2: total-spending.Rmd cited County 1.8% / City 0.8% intergovernmental-
to-Direct and County 91.6% L/M, all roughly 2x off against the bundled
fixture. Measured directly against the fixture (all 50 states, each of
its four years): County IG/Direct 3.4%-5.1%, City IG/Direct 2.6%-3.1%,
County L/M 43%-51% (all varying by year). State 17.2%, AL 7.6%,
national 11.6%, and City L/M 188.3% were re-checked and left as-is.

M1: the "Why Total = Direct + M + L" paragraph described money a local
government *receives* and the state "redistributing as M" -- backwards.
M and L are both the *queried* government's own payments *out*: M to
other local governments, L up to its state. Rewrote the explanation;
the conclusion and non-M2-flagged figures are unchanged.
This commit is contained in:
2026-07-27 12:06:37 -04:00
parent a4eb80d823
commit e7d3a7a310
2 changed files with 24 additions and 17 deletions
+4 -3
View File
@@ -47,9 +47,10 @@ explanation with worked examples.
### Testing ### Testing
The package ships a bundled fixture corpus at `inst/extdata/fixture_corpus/` — The package ships a bundled fixture corpus at `inst/extdata/fixture_corpus/` —
a 3.6 MB two-year slice (2019 + 2020) of the full corpus covering all 50 a 15 MB four-year slice (2011, 2012, 2019, 2020) of the full corpus covering
states. `tests/testthat/setup.R` automatically points `USCOGDATA_URL` at this all 50 states. `tests/testthat/setup.R` automatically points `USCOGDATA_URL`
fixture, so the full test suite runs offline with no network dependency: at this fixture, so the full test suite runs offline with no network
dependency:
```r ```r
devtools::test() # uses bundled fixture, no credentials required devtools::test() # uses bundled fixture, no credentials required
+20 -14
View File
@@ -155,14 +155,15 @@ silently overstating every multi-layer figure it produces.
# How big is the risk in practice # How big is the risk in practice
Intergovernmental transfers aren't evenly distributed by government type. Intergovernmental transfers aren't evenly distributed by government type.
Measured on the full published corpus, intergovernmental spending as a Measured against the bundled fixture corpus (all 50 states, each of its
four years -- 2011, 2012, 2019, 2020), intergovernmental spending as a
share of a government's own Direct spending is: share of a government's own Direct spending is:
| Government type | Intergovernmental / Direct | | Government type | Intergovernmental / Direct |
|---|---| |---|---|
| State | 17.2% | | State | 17.2% |
| County | 1.8% | | County | 3.4%-5.1% (varies by year) |
| City | 0.8% | | City | 2.6%-3.1% (varies by year) |
So the Direct/Total choice matters overwhelmingly for **state** governments So the Direct/Total choice matters overwhelmingly for **state** governments
-- a state's Total genuinely differs from its Direct by a meaningful margin, -- a state's Total genuinely differs from its Direct by a meaningful margin,
@@ -174,17 +175,22 @@ for Alabama in FY2019, and 11.6% nationally.
# Why Total = Direct + M + L, not Direct + M # Why Total = Direct + M + L, not Direct + M
It's tempting to assume `total` only needs to add `M` (payments to local It's tempting to assume `total` only needs to add `M`. But `M` and `L` are
governments). But not all of the money a county or city receives arrives both money the queried government itself pays **out** -- they're not two
directly from its state as an `M` payment -- some flows through as `L` different accounts of a receiving government's revenue. `M` is what it
(payments *to* the state government), which the state government then pays to other **local** governments (e.g. a county paying a city for a
redistributes as `M`. On the published corpus, `L` is 0 for state shared paving contract); `L` is what it pays **up** to its **state**
governments (a state has no "payments to the state government" leg of its government (e.g. a county's contribution to a state-administered program).
own) but is 91.6% the size of `M` for counties and 188.3% the size of `M` A local government's Total genuinely includes both legs, because both are
for cities -- so a `total` that omitted `L` would silently undercount Total its own spending, just routed to a different kind of recipient. On the
specifically for local governments. `cog_spending(expenditure_concept = bundled fixture corpus (all 50 states, 2011/2012/2019/2020), `L` is 0 for
"total")` includes both legs (excluding the `L--` family-total rollup row, state governments (a state has no "payments to the state government" leg of
which would double-count its own components). its own) but is 43%-51% the size of `M` for counties (varies by year) and
188.3% the size of `M` for cities -- so a `total` that omitted `L` would
silently undercount Total specifically for local governments.
`cog_spending(expenditure_concept = "total")` includes both legs (excluding
the `L--` family-total rollup row, which would double-count its own
components).
# Composition rules # Composition rules