jared
c7260cb20c
C1: spending_long/spending_long_harmonized filter NOT is_aggregate but
ig_long deliberately doesn't (legacy IG lives on aggregate rows), so a
legacy aggregate-only family (e.g. Corrections pre-2012) can survive on
the IG leg while Direct is suppressed. expenditure_concept = "total"
then UNIONs an IG-only figure that reads as a plausible Total, and the
coverage-gap suggestion machinery -- fed the UNION'd result -- saw the
surviving IG row as coverage and stayed silent.
(a) .build_suggestions() is now fed a Direct-leg-only view of the
result (IG rows filtered out before the gap-years computation),
so the recipe hints fire for "total" exactly as they do for
"direct".
(b) Any row where IG has dollars but Direct has none for the same
(year, canonical_govid, category) is now flagged: the row's
`notes` name the recovering recipe (drawn from the Direct-leg
suggestions), and provenance gains an explicit
`expenditure_concept_direct_suppressed` boolean plus an appended
warning on `expenditure_concept_note` -- both cheap for a
downstream consumer (cog-api passes provenance through verbatim)
to test, rather than silently asserting Direct + IG when that
arithmetic didn't happen.
Measured before/after on AL state government, Corrections, 2011:
"total" already correctly returns the corpus's actual IG-only figure
($31,358,000, vs. true Direct of $521,651,000 via recipe =
"corrections_combined"), but before this fix it did so with 0
suggestions and an unqualified "Total = Direct + IG" note; after, it
fires 3 recipe hints and both the row notes and provenance say plainly
that Direct is unavailable through this basis.
C2: the 66 M/L summary_categories rows arrived via cog_pipeline PR #59
with no schema_version bump, so schema_version can't gate "total" --
a pre-#59 corpus can report any supported schema_version and still
have zero M/L category rows, in which case ig_annotated's LEFT JOIN
silently produces NA category/spend_subtype (0 rows for a specific
category, or one invisible NA-subtype group for category = NULL). New
.require_ig_categories() checks summary_categories directly and aborts
with class uscogdata_ig_categories_unsupported, naming PR #59 and
directing the user to a newer corpus.
Reconciles tests/testthat/test-views.R's v4-shaped-corpus test (whose
synthetic summary_categories carries only one E36 row) by asserting
the new guard fires against that same connection, rather than leaving
the two silently contradictory.
103 lines
4.8 KiB
R
103 lines
4.8 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/spending.R
|
|
\name{cog_spending}
|
|
\alias{cog_spending}
|
|
\title{Summarized spending by category}
|
|
\usage{
|
|
cog_spending(
|
|
govid,
|
|
years,
|
|
category = NULL,
|
|
per_capita = FALSE,
|
|
adjust_to_year = NULL,
|
|
basis = c("harmonized", "raw"),
|
|
recipe = NULL,
|
|
expenditure_concept = c("direct", "total")
|
|
)
|
|
}
|
|
\arguments{
|
|
\item{govid}{Character vector of `canonical_govid` values.}
|
|
|
|
\item{years}{Integer vector of years.}
|
|
|
|
\item{category}{Character vector of category names (from
|
|
`summary_categories.category`), or `NULL` for all categories.}
|
|
|
|
\item{per_capita}{If `TRUE`, adds `amt_per_capita_nominal` (and
|
|
`amt_per_capita_real` when `adjust_to_year` is set) using the per-year
|
|
Census F-33 population from `gov_population_yearly`. Result also gains
|
|
a `pop_source` column with values `"census_f33"` or `"unavailable"`
|
|
(the latter for gov types 4/5 and any row whose population is missing
|
|
in that year).}
|
|
|
|
\item{adjust_to_year}{Integer base year for CPI-U real-dollar conversion,
|
|
or `NULL` for nominal only.}
|
|
|
|
\item{basis}{`"harmonized"` (default) sums item codes through the
|
|
cross-vintage harmonization mapping (folding series-break-affected
|
|
codes onto a comparable target and excluding aggregate / discontinued
|
|
rows -- see the `harmonization` block in `cog_explain()`); `"raw"`
|
|
reproduces the pre-Phase-R2 behavior (published item codes, no
|
|
folding). On a corpus with `schema_version < 5` (no harmonization
|
|
tables), `basis` silently resolves to `"raw"` when left at its default
|
|
and the resolution is recorded in the provenance; explicitly passing
|
|
`basis = "harmonized"` on such a corpus aborts. Ignored when `recipe`
|
|
is set (see below).}
|
|
|
|
\item{recipe}{Optional harmonization recipe id (see [cog_recipes()]) for
|
|
multi-code cross-vintage series that a 1:1 harmonized_code mapping
|
|
can't express (e.g. a wide-era aggregate that only splits into leaf
|
|
codes in the modern era). Mutually exclusive with `category`. The
|
|
result's subtype column reads `"recipe"` and `category` reads the
|
|
recipe's label. Requires `schema_version >= 5`. A recipe query bypasses
|
|
`basis` entirely (it joins `long` directly rather than going through
|
|
the `*_annotated`/`*_annotated_harmonized` views), so the `basis`
|
|
argument is ignored and the result's provenance reports
|
|
`basis = "recipe"` with an inert `harmonization` block (`applied =
|
|
FALSE`, pointing at the `recipe` block instead) rather than a
|
|
possibly-misleading `"harmonized"`/`"raw"` value.}
|
|
|
|
\item{expenditure_concept}{`"direct"` (default) returns only the
|
|
government's own direct spending (item codes `E`/`F`/`G`), unchanged
|
|
from prior releases. `"total"` additionally UNIONs in the
|
|
intergovernmental leg -- payments to local governments (`M` codes) and
|
|
to the state government (`L` codes, excluding the `L--` family-total
|
|
rollup) -- so results gain rows with `spend_subtype ==
|
|
"intergovernmental"`. Requires the active corpus's `summary_categories`
|
|
to carry M/L rows (added by cog_pipeline PR #59); aborts with class
|
|
`uscogdata_ig_categories_unsupported` on an older corpus rather than
|
|
silently under-reporting. Mutually exclusive with `recipe` (a recipe
|
|
already defines its own component codes). **Do not sum `"total"`
|
|
results across levels of government** (e.g. state + county + city):
|
|
a state's `M12` payment to a school district is the same dollar the
|
|
district reports as its own direct `E12`, so summing both double-counts
|
|
it. This matters in particular with [cog_geographic_rollup()], which
|
|
sums across exactly that kind of multi-layer government set.
|
|
|
|
In the legacy wide era (<= FY2011), some functions are published ONLY
|
|
as an aggregate-flagged family total (e.g. Corrections' `E04`/`E05`
|
|
split), which the Direct leg excludes by construction but the IG leg
|
|
deliberately keeps (see `inst/sql/24-ig_long.sql`). For a `"total"`
|
|
query, any (year, category) where this leaves intergovernmental rows
|
|
with NO Direct counterpart is flagged: the affected rows' `notes`
|
|
name the harmonization recipe that recovers the missing Direct
|
|
component (when one exists), and
|
|
`provenance$expenditure_concept_direct_suppressed` is `TRUE` -- the
|
|
figure in those rows is the intergovernmental leg alone, not Direct +
|
|
IG.}
|
|
}
|
|
\value{
|
|
Tibble with columns `year`, `canonical_govid`, `gov_name`,
|
|
`spend_subtype`, `category`, `amt_nominal`, optional `amt_real`,
|
|
optional `amt_per_capita_nominal`, optional `amt_per_capita_real`,
|
|
optional `pop_source`, `codes_included`, `aggregate_fallback`, `notes`.
|
|
Carries a `provenance` attribute matching `inst/schemas/provenance-v1.json`.
|
|
}
|
|
\description{
|
|
One row per `(year, canonical_govid, spend_subtype, category)`. Amounts are
|
|
returned in **full U.S. dollars** (the raw corpus stores them in $1,000s;
|
|
this verb multiplies by 1000 so downstream code can freely rescale to
|
|
millions/billions). The conversion is recorded in the provenance attribute
|
|
under `transformations$units_conversion`.
|
|
}
|