Package 'uscogdata'

Canonical govid(s): a character vector, or a data frame with a 'canonical_govid' column (e.g. from [cog_gov_search()]). 'NULL' to name the cohort by 'state'/'type' instead.

Integer vector of fiscal years.

Optional character vector of categories to keep. One of '"Fund Balances"', '"Insurance Trust Balances"', '"Retirement System Holdings"'. There is deliberately no 'subtype' argument: for holdings, 'category' is a strict coarsening of 'balance_subtype' (unlike the money verbs, where the two axes cross), so every combination would be either redundant or empty. 'category = "Fund Balances"' is exactly the 'general' family ('W01'/'W31'/'W61'). 'balance_subtype' is returned, so a finer split is one 'dplyr::filter()' away. The reserved pseudo-category '"All Categories"' (see [cog_spending()]) is **not** supported here and errors with class 'uscogdata_all_categories_unsupported': it sums a concept's subtype scope, and holdings are a stock with no concept vocabulary to sum across. Omit 'category' to get every category broken out instead.

Divide holdings by population. Note this is a **stock per resident** (reserves per person), which is *not* comparable to [cog_spending()]'s per-capita figures – those are a flow per person.

Deflate to this year's dollars (CPI-U).

Accepted for uniformity with the money verbs, but currently a **no-op**: 'harmonization_map' carries no balance-code rows, so harmonized and raw space are identical for holdings. Reported in 'provenance$basis_note'.

Optional harmonization recipe id (see [cog_recipes()]). '"cash_securities_z77_wide"' and '"cash_securities_z78_wide"' bridge the wide era to the modern one.

Name the cohort by predicate instead of by id: 'state' is a 2-letter USPS abbreviation (or a FIPS code) and 'type' is one of '"state"', '"county"', '"city"', '"township"' (or the integer '0:3') – the same vocabulary, and the same internal coercion, as [cog_gov_search()]. Both default to 'NULL'.

The cohort is then expressed as a subquery against 'canonical_fips_xwalk' inside each statement rather than round-tripped through R as a literal id list. For a fleet-scale cohort that is the difference between a 301,591-character 'IN' list re-parsed in 5–8 statements per call and a constant-size predicate: measured at **94 ms versus 449 ms** for the same FY2022 aggregate over the 20,106-government 'type = "city"' cohort, within 7

Supplying 'govid' **and** 'state'/'type' INTERSECTS them – the governments in 'govid' that also match the predicate – rather than one silently taking precedence. Naming no cohort at all ('govid', 'state' and 'type' all 'NULL') aborts with class 'uscogdata_no_cohort'.

When the cohort is named by predicate, 'provenance$scope$govids_found' and 'govids_missing' are empty – there is no id list to report against – and 'provenance$scope$cohort' carries 'state', 'type' and 'n_governments' instead. A 'govid'-named cohort reports exactly as before.

Maximum number of result rows to return, pushed into the SQL rather than applied after materializing every row. 'NULL' (default) returns everything. Cannot be combined with 'recipe' – see 'offset' and 'total_rows'.

Rows to skip before 'limit' starts counting (0-based). Ignored if 'limit' is 'NULL'; defaults to '0L' when 'limit' is set.

A tibble returned by basket-mode [cog_gov_search()].

Logical. If 'TRUE', keeps the 'candidates' list-column (full-schema match candidates per input row). Default 'FALSE'.

A tibble returned by basket-mode [cog_gov_search()].

Either 'NULL' (default, every row: expenditure, revenue and balance), '"spending"', '"revenue"', or '"balance"'.

Optional regex matched case-insensitively against the 'category' column (e.g. '"Police"' or '"Tax"').

A tibble returned by a 'cog_*' verb.

'"print"' (default) for a human-readable cli summary; returns 'result' invisibly for chaining. '"list"' returns the raw provenance list (identical to 'attr(result, "provenance")').

Character scalar — 'canonical_govid' of the target.

Integer scalar. Cohort vintage. When 'NULL' (default), uses the most recent year for which the target has an observed population in 'gov_population_yearly'.

If ‘TRUE' (default) restrict peers to the target’s 'govs_type'.

If ‘TRUE' restrict peers to the target’s 'fips_state'. Default 'FALSE'.

Length-2 numeric vector giving lower/upper bounds.

If 'TRUE' (default) 'pop_range' is multiplied by the target's population at 'year' to produce absolute bounds. If 'FALSE', 'pop_range' is interpreted as absolute population counts.

Integer cap on the number of peers returned.

Survey-cycle handling; see [cog_peer_compare()]. Here it governs the cohort VINTAGE when 'year' is 'NULL': '"census"' snaps to the most recent census year with an observed population, so a cohort is not built from a sample year in which most of the candidate universe is absent. '"consistent"' needs a year range, which cohort selection does not have, so it selects like '"all"' and is carried on the result as 'attr(x, "coverage")' for [cog_peer_compare()].

Named list with any non-empty subset of elements named 'state', 'county', 'city'. Each element is a character vector of 'canonical_govid' values. At least one layer required.

Single category name or character vector (passed through to [cog_spending()]), or the reserved '"All Categories"' for one summed row per '(year, canonical_govid, subtype)' covering every category in the concept's scope. '"All Categories"' is the efficient way to build a geographic total: without it a caller must issue one rollup per category and sum the results themselves.

Integer vector of years.

If ‘TRUE', per-capita uses each gov’s own per-year population from 'gov_population_yearly'. Govs with missing population are excluded from the result.

Integer base year for CPI-U conversion, or 'NULL'.

'"primary"' (default), '"direct"', or '"total"' – see [cog_spending()] for the three concepts. '"total"' is refused here because combining Total across multiple layers of government double-counts intergovernmental transfers (a state's payment to a school district is the same dollar the district reports as its own Direct spending); '"primary"' and '"direct"' combine safely.

How to handle the Census of Governments survey cycle, which is a **complete census only in years ending in 2 and 7** – every other year is a sample, and the sample varies enormously (on the bundled fixture, Wisconsin's 608-city universe reports 597 governments in FY2012 and 112 in FY2019).

* '"all"' (default) – every unit that reported that year. Unchanged behaviour, so existing code keeps working. * '"census"' – census years only. Aborts if the requested range holds none, rather than silently returning nothing. * '"consistent"' – only units reporting in *every* requested year, giving a balanced panel.

Regardless of mode, 'provenance$coverage' always carries per-year 'n_units_reporting', 'n_units_expected' and 'is_census_year', and 'provenance$coverage_mode' records the mode. 'is_census_year' is a statement about the **survey calendar**, never a claim of completeness: FY1967 is a census year in which only 97 of Wisconsin's 608 cities report. 'n_units_reporting' is the number that tells the truth.

Character vector of place name(s). Length 1 = utility mode; length >1 = basket mode.

2-letter USPS abbreviation (e.g. '"FL"'), FIPS integer (e.g. '12'), or 'NULL'. In basket mode, length 1 recycles across all entries; otherwise must match 'length(name)'.

Government type: integer in '0:3' or one of '"state"', '"county"', '"city"', '"township"', or 'NA'/'NULL'. Per-row optional in basket mode (recycles from length 1). Excluded types '4'/'5' (or '"special_district"' / '"school_district"') trigger an explanatory message and an empty result.

Maximum number of rows to return, applied in SQL. 'NULL' (default) returns every match – which, with no other filter, is the entire crosswalk. Utility mode only: pagination has no meaning in basket mode, where the result is one resolved row per requested name in input order, and is refused there with class 'uscogdata_basket_pagination_conflict'.

Rows to skip before 'limit' starts counting (0-based). Ignored if 'limit' is 'NULL'; defaults to '0L' when 'limit' is set.

Destination directory. Created if missing.

Subset of 'c("long", "metadata", "docs")' controlling which manifest sections to mirror.

If 'TRUE', re-copy even when the local SHA matches.

If 'TRUE', show a cli progress bar.

Character scalar.

A tibble from [cog_find_peers()] or a character vector of 'canonical_govid's.

Character scalar or vector.

Integer vector.

Default 'TRUE' — peer compare usually normalizes by population.

Integer base year for CPI-U conversion or 'NULL'.

'"primary"' (default), '"direct"', or '"total"' – see [cog_spending()] for the three concepts. '"total"' is refused here because combining Total across peer sets counts intergovernmental transfers twice; '"primary"' and '"direct"' combine safely.

How to handle the Census of Governments survey cycle, which is a **complete census only in years ending in 2 and 7** – every other year is a sample, and the sample varies enormously (on the bundled fixture, Wisconsin's 608-city universe reports 597 governments in FY2012 and 112 in FY2019).

* '"all"' (default) – every unit that reported that year. Unchanged behaviour, so existing code keeps working. * '"census"' – census years only. Aborts if the requested range holds none, rather than silently returning nothing. * '"consistent"' – only units reporting in *every* requested year, giving a balanced panel.

Regardless of mode, 'provenance$coverage' always carries per-year 'n_units_reporting', 'n_units_expected' and 'is_census_year', and 'provenance$coverage_mode' records the mode. 'is_census_year' is a statement about the **survey calendar**, never a claim of completeness: FY1967 is a census year in which only 97 of Wisconsin's 608 cities report. 'n_units_reporting' is the number that tells the truth.

The comparison target is exempt from '"consistent"' balancing – it is the subject of the comparison, not a member of the cohort – and the 'summary_*' quantiles are computed AFTER the filter, so they describe the cohort actually returned. 'n_units_reporting' counts peers only, against the cohort size: "3 of your 15 peers reported in FY2019".

Optional regex matched case-insensitively against 'recipe_id' or 'label'.

Character vector of 'canonical_govid' values, or 'NULL' to name the cohort by 'state'/'type' instead. One of 'govid', 'state', or 'type' is required.

Integer vector of years.

Character vector of category names (from 'summary_categories.category'), or 'NULL' for all categories broken out one row each. The reserved value '"All Categories"' instead returns a single summed row per '(year, canonical_govid, subtype)', covering every category inside the requested concept's subtype scope. It cannot be combined with other category names, and it is not the same thing as 'revenue_concept = "total"': the concept chooses which subtypes are in scope, '"All Categories"' chooses whether rows inside that scope are broken out or summed. Because the result keeps one row per 'revenue_subtype', filtering the returned frame to 'revenue_subtype == "own_source"' gives an own-source revenue total.

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).

Integer base year for CPI-U real-dollar conversion, or 'NULL' for nominal only.

'"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).

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.

Which of Census's two published revenue concepts to return. Concepts are defined as sets of the crosswalk's 'revenue_subtype' values – never as item-code first letters, which cannot classify correctly (prefix 'Y' spans revenue, expenditure and balance codes, and prefix 'X' does the same):

* '"general"' (default) – Census General Revenue: 'own_source' + 'federal' + 'state' + 'local_aid'. The manual defines this concept by subtraction (section 4.3: *"General revenue comprises all revenue except that classified as liquor store, utility, or insurance trust revenue"*), so utility ('A91'-'A94'), liquor store ('A90') and insurance trust revenue are all excluded. * '"total"' – Census Total Revenue: every revenue subtype, i.e. 'general' plus utility, liquor store, and insurance trust revenue ('Y01'/'Y02'/'Y04'/'Y11'/'Y12'/'Y51'/'Y52' and the employee-retirement 'X01'/'X02'/'X05'/'X08').

The two are related by Census's own identity, 'Total Revenue = General + Utility + Liquor Store + Insurance Trust'.

Note that the employee-retirement ('X') codes stop at FY2016, when those systems moved out of the annual finance file into the separate Annual Survey of Public Pensions, so a '"total"' series steps down at the FY2016/FY2017 seam for reasons that are about collection scope rather than revenue (series breaks 'SB197'-'SB202').

If 'TRUE', fill the requested grid so that a cell the corpus does not carry still appears, labelled with **why** it is missing, and add a 'value_source' column to every row:

* '"reported"' — the corpus carries this cell. * '"census_zero"' — dense-source year ('<= FY2011'), cell absent: Census published '$0'. 'amt_nominal' is '0'. * '"not_reported"' — sparse-source year ('>= FY2012'), cell absent: the government did not report, and the value is unknown. 'amt_nominal' is 'NA', **not** '0' — writing a zero there would invent data.

The grid comes from the corpus's 'code_set' table, scoped to each government's own type, so a county is never filled with cells only a state can report. Reported rows are passed through untouched.

Defaults to 'FALSE' (the historical behaviour: absent cells simply do not appear). Needs a corpus published from 2026-07-29 onward, which is when 'representation'/'code_set' began shipping; aborts with class 'uscogdata_representation_unavailable' otherwise. Not available with 'recipe' or with 'expenditure_concept = "total"' (class 'uscogdata_complete_unsupported') — neither draws its cells from 'code_set'.

Maximum number of result rows to return, pushed into the SQL query itself ('LIMIT'/'OFFSET') rather than applied after the full result is materialized. 'NULL' (the default) returns every matching row, exactly as before this parameter existed. Mutually exclusive with 'recipe' and with 'complete = TRUE' – see 'offset' and 'total_rows'.

Rows to skip before 'limit' starts counting (0-based). Ignored if 'limit' is 'NULL'; defaults to '0L' when 'limit' is set.

Name the cohort by predicate instead of by id: 'state' is a 2-letter USPS abbreviation (or a FIPS code) and 'type' is one of '"state"', '"county"', '"city"', '"township"' (or the integer '0:3') – the same vocabulary, and the same internal coercion, as [cog_gov_search()]. Both default to 'NULL'.

The cohort is then expressed as a subquery against 'canonical_fips_xwalk' inside each statement rather than round-tripped through R as a literal id list. For a fleet-scale cohort that is the difference between a 301,591-character 'IN' list re-parsed in 5–8 statements per call and a constant-size predicate: measured at **94 ms versus 449 ms** for the same FY2022 aggregate over the 20,106-government 'type = "city"' cohort, within 7

Supplying 'govid' **and** 'state'/'type' INTERSECTS them – the governments in 'govid' that also match the predicate – rather than one silently taking precedence. Naming no cohort at all ('govid', 'state' and 'type' all 'NULL') aborts with class 'uscogdata_no_cohort'.

When the cohort is named by predicate, 'provenance$scope$govids_found' and 'govids_missing' are empty – there is no id list to report against – and 'provenance$scope$cohort' carries 'state', 'type' and 'n_governments' instead. A 'govid'-named cohort reports exactly as before.

Character vector of 'canonical_govid' values, or 'NULL' to name the cohort by 'state'/'type' instead. One of 'govid', 'state', or 'type' is required.

Integer vector of years.

Character vector of category names (from 'summary_categories.category'), or 'NULL' for all categories broken out one row each. The reserved value '"All Categories"' instead returns a single summed row per '(year, canonical_govid, subtype)', covering every category inside the requested concept's subtype scope. It cannot be combined with other category names, and it is not the same thing as 'expenditure_concept = "total"': the concept chooses which subtypes are in scope, '"All Categories"' chooses whether rows inside that scope are broken out or summed. Because the result keeps one row per 'spend_subtype', filtering the returned frame to 'spend_subtype == "operations"' gives an operating-expenditure total.

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).

Integer base year for CPI-U real-dollar conversion, or 'NULL' for nominal only.

'"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).

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.

Which spending concept to return. Concepts are defined as sets of the crosswalk's 'spend_subtype' values – never as item-code first letters, which cannot classify correctly (prefix 'Y' alone spans revenue, expenditure, and balance codes):

* ‘"primary"' (default) – the government’s own service provision: 'operations' + 'capital' + 'assistance' subtypes. * ‘"direct"' – Census’s published Direct Expenditure: 'primary' plus 'interest' (interest on debt) and 'insurance_benefits' (insurance trust benefit payments, e.g. pensions – Census manual section 5.2.2.1 includes payments to retirees in Direct). * '"total"' – 'direct' plus the intergovernmental leg: payments to local governments ('M' codes), to the state government ('L' codes, excluding the 'L–' family-total rollup), and state payments to school systems ('Q11'/'Q12'/'Q18'), 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. When 'category = "All Categories"' is combined with 'expenditure_concept = "total"', this detection cannot run (it keys on per-category rows, which all-categories mode collapses to one literal value), so 'expenditure_concept_direct_suppressed' is 'NA' rather than a possibly-false 'FALSE'; query an explicit 'category' to get a real answer.

If 'TRUE', fill the requested grid so that a cell the corpus does not carry still appears, labelled with **why** it is missing, and add a 'value_source' column to every row:

* '"reported"' — the corpus carries this cell. * '"census_zero"' — dense-source year ('<= FY2011'), cell absent: Census published '$0'. 'amt_nominal' is '0'. * '"not_reported"' — sparse-source year ('>= FY2012'), cell absent: the government did not report, and the value is unknown. 'amt_nominal' is 'NA', **not** '0' — writing a zero there would invent data.

The grid comes from the corpus's 'code_set' table, scoped to each government's own type, so a county is never filled with cells only a state can report. Reported rows are passed through untouched.

Defaults to 'FALSE' (the historical behaviour: absent cells simply do not appear). Needs a corpus published from 2026-07-29 onward, which is when 'representation'/'code_set' began shipping; aborts with class 'uscogdata_representation_unavailable' otherwise. Not available with 'recipe' or with 'expenditure_concept = "total"' (class 'uscogdata_complete_unsupported') — neither draws its cells from 'code_set'.

Maximum number of result rows to return, pushed into the SQL query itself ('LIMIT'/'OFFSET') rather than applied after the full result is materialized. 'NULL' (the default) returns every matching row, exactly as before this parameter existed. Mutually exclusive with 'recipe' and with 'complete = TRUE' – see 'offset' and 'total_rows'.

Rows to skip before 'limit' starts counting (0-based). Ignored if 'limit' is 'NULL'; defaults to '0L' when 'limit' is set.

Name the cohort by predicate instead of by id: 'state' is a 2-letter USPS abbreviation (or a FIPS code) and 'type' is one of '"state"', '"county"', '"city"', '"township"' (or the integer '0:3') – the same vocabulary, and the same internal coercion, as [cog_gov_search()]. Both default to 'NULL'.

The cohort is then expressed as a subquery against 'canonical_fips_xwalk' inside each statement rather than round-tripped through R as a literal id list. For a fleet-scale cohort that is the difference between a 301,591-character 'IN' list re-parsed in 5–8 statements per call and a constant-size predicate: measured at **94 ms versus 449 ms** for the same FY2022 aggregate over the 20,106-government 'type = "city"' cohort, within 7

Supplying 'govid' **and** 'state'/'type' INTERSECTS them – the governments in 'govid' that also match the predicate – rather than one silently taking precedence. Naming no cohort at all ('govid', 'state' and 'type' all 'NULL') aborts with class 'uscogdata_no_cohort'.

When the cohort is named by predicate, 'provenance$scope$govids_found' and 'govids_missing' are empty – there is no id list to report against – and 'provenance$scope$cohort' carries 'state', 'type' and 'n_governments' instead. A 'govid'-named cohort reports exactly as before.