uscogdata/NEWS.md

uscogdata 0.1.0 (development)

Multi-government aggregates now disclose their reporting coverage

• The Census of Governments 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 rolls up 597 governments in FY2012 and 112 in FY2019 — an 18%-to-98% swing the return value said nothing about, so a statewide total resting on a fifth of the universe looked exactly like one resting on all of it.

• cog_geographic_rollup(), cog_peer_compare() and cog_find_peers() gain coverage:

  value	effect
  "all" (default)	every unit that reported that year — unchanged behaviour
  "census"	census years only; aborts if the range holds none rather than returning nothing
  "consistent"	only units reporting in every requested year — a balanced panel

• Regardless of mode, every result now carries provenance$coverage with per-year n_units_reporting, n_units_expected and is_census_year, plus provenance$coverage_mode. cog_explain() prints a "Reporting coverage" section. So the default mode can no longer mislead silently.

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

• On cog_peer_compare() the 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.

• On cog_find_peers(), coverage 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.

complete = TRUE: absent cells, labelled with why they are absent

• cog_spending() and cog_revenue() gain complete, defaulting to FALSE (today's behaviour). With complete = TRUE the requested grid is filled from the corpus's code_set table and every row carries a new value_source column:

  value_source	meaning	amt_nominal
  reported	the corpus carries this cell	as published
  census_zero	dense-source year (≤ FY2011), cell absent — Census published $0	0
  not_reported	sparse-source year (≥ FY2012), cell absent — unknown	NA

  The NA is deliberate and is the whole point: filling a modern absence with 0 would invent data, which is precisely the error the corpus's representation contract exists to prevent.

• This restores information the reader lost when the corpus was sparsified (SB194, cog_pipeline#64) — a wide-era query whose cells were all $0 had begun returning nothing at all — and improves on what came before it, since the pre-sparsification corpus could not distinguish a published zero from an unreported cell either.

• The grid is scoped to each government's own type, so a county is never filled with cells only a state can report.

• Needs a corpus published from 2026-07-29 onward (when representation and code_set began shipping); aborts with class uscogdata_representation_unavailable otherwise. Gated on the manifest listing those tables rather than on schema_version, which was never bumped for the change. Not available with recipe or expenditure_concept = "total" — neither draws its cells from code_set.

• provenance$completion reports applied, rows_filled, and the per-year absence_means rule; cog_explain() prints a "Completion" section.

Corpus-wide series breaks now reach users (corpus_break_refs)

• Four catalogued series breaks carry fin_code = "ALL" — caveats about the corpus as a whole rather than about one item code. series_break_refs is built by matching fin_code against the item codes in the result, and no row's item_code is ever the literal "ALL", so none of them could ever be surfaced: SB085 (dollar precision across the 1976/1977 boundary), SB087 (imputation exclusion from FY2002), SB194 (the dense → sparse representation change at FY2012) and SB086 (the government id scheme change at FY2017).
• Provenance gains corpus_break_refs, selected on the break-year window alone and disjoint from series_break_refs by construction, so a consumer can tell a whole-result caveat from a break in one series. cog_explain() prints them under their own "Corpus-wide caveats" heading. cog-api passes provenance through verbatim, so the field appears there without an API change.
• SB194 is the one that made this urgent: a query spanning FY2011 → FY2012 crosses the boundary where an absent cell stops meaning "Census published $0" and starts meaning "not reported", and until now nothing said so.

Bundled fixture regenerated against the sparsified corpus

• inst/extdata/fixture_corpus/ now tracks the corpus published on 2026-07-29 (pipeline_commit 83f9715, schema v6). The wide era no longer stores explicit zeros: FY2011 fell from 2,864,212 rows to 496,004, of which none are $0. Absence now means two different things — in a dense_source year (≤ FY2011) an absent cell means Census published $0; in a sparse_source year (≥ FY2012) it means not reported. The corpus carries that rule in two new tables the fixture now ships, representation.parquet and code_set.parquet, alongside census_collection_coverage.parquet and lineage_events.parquet (all ten publish-tree metadata tables, up from six). Catalogued upstream as series break SB194.
• cog_categories() gains an assistance spending subtype: the J-prefix aid/benefit codes (J19, J67, J68, J85) are categorised now that the upstream crosswalk covers every flow code carrying dollars.
• Two consequences worth knowing about, both visible in provenance rather than in returned dollars. The harmonization block's na_rows_excluded counts only rows that exist, so wide-era codes that were zero-padded no longer appear there. Coverage-gap suggestions are presence-based for the same reason, so a recipe whose component codes were all $0 for a given government-year is no longer suggested for it.
• tests/testthat/test-fixture-vintage.R pins these structural facts, so a fixture left behind by a future publish fails loudly instead of letting the suite pass against a corpus that no longer exists.

Breaking: corpus schema_version 4 (Phase P canonical ids)

• The package now requires corpus schema_version = 4 (MinCorpusSchema / MaxCorpusSchema in DESCRIPTION are both 4); older corpora built against schema 3 are rejected by cog_open() with a clear version-mismatch error. canonical_govid is now uniformly 12 characters across every vintage the corpus covers (previously a mix of 9-char legacy ids and 12-char FIPS ids depending on source year) — every hardcoded canonical_govid literal from a pre-Phase-P corpus is now invalid and must be re-resolved via cog_gov_search() or the new canonical_alias lookup table. canonical_fips_xwalk gains four columns (legacy_govs_id, census_geoid, id_source; confidence is renamed to pop_confidence) and a companion canonical_alias table ships in the corpus for mapping legacy/alternate ids onto the current canonical namespace. The bundled fixture corpus (inst/extdata/fixture_corpus/) has been regenerated against the Phase P publish tree, now ships the full canonical_fips_xwalk and canonical_alias master tables alongside the 2019-2020 long partitions, and is reproducible via data-raw/regenerate_fixture_corpus.R.

Clearer errors when USCOGDATA_URL is unconfigured or returns non-JSON

• cog_open() now aborts with the uscogdata_url_not_configured error class when the resolved corpus URL still contains the placeholder REPLACE_WITH_SHARE_TOKEN sentinel (or is empty). The message lists both remediation paths (Sys.setenv(USCOGDATA_URL = ...) and options(uscogdata.url = ...)) and points at the bundled fixture for offline testing. Previously the package proceeded to fetch the placeholder URL, cached the resulting HTML welcome page, and failed downstream with a cryptic jsonlite lexical-error.
• .fetch_or_cache_manifest() now parses the HTTP response body before persisting it. Non-JSON responses (login pages, 404 HTML) raise uscogdata_invalid_manifest with the URL, Content-Type, and underlying parse error — and never write to the on-disk cache.
• Manifest cache writes are now atomic (write to manifest.json.tmp.<pid> in cache_dir, then file.rename over the target), so an interrupted fetch cannot replace a previously-good cache.
• Existing caches with non-JSON content (poisoned by the prior code path) are silently refetched instead of returning a parse error to the caller.
• Local USCOGDATA_URL paths whose manifest.json is not valid JSON now surface the same uscogdata_invalid_manifest class with file context.

Per-capita denominators now use per-year Census F-33 population

• cog_spending() and cog_revenue() previously divided all years' amounts by a single ACS 2018-2022 estimate (canonical_fips_xwalk.population_acs), producing biased per-capita values for time-series analysis. They now divide by the F-33 population recorded on each gov-year via the new gov_population_yearly view. Result tibbles gain a pop_source column with values "census_f33" or "unavailable". notes is updated to concatenate multiple notes with "; ".

Peer cohorts can be set to a chosen year

• cog_find_peers() adds a year argument (default: most recent year for which the target has an observed population in gov_population_yearly). The returned column previously named population_acs is now population and reflects the cohort year's vintage. The cohort year is attached to the returned tibble as attr(x, "cohort_year").
• cog_peer_compare() now stamps a cohort_year column on its result (read from the peers tibble's attribute) and records cohort_year plus cohort_govids in provenance. When the caller supplies a bare character vector instead of a cog_find_peers() result, cohort_year is NA.

Rollups exclude govs missing population

• cog_geographic_rollup(per_capita = TRUE) drops rows whose government has pop_source == "unavailable" and records the dropped govids in provenance$rollup$excluded_govids. This excludes special districts (type 4) and school districts (type 5) from per-capita rollups by design.

New: vignette and provenance metadata

• New vignette population-denominators covers the four population sources, the type-4/5 coverage gap, the popyear quirk, and how to build moving-window peer cohorts manually.
• Provenance gains transformations$per_capita$popyear_range and pop_source_counts. cog_explain() renders both.

New features

• cog_gov_search() gains a basket mode: passing vector name / state / type arguments resolves multiple place names in one call and returns a tibble of canonical rows in input order, ready to pipe into cog_spending() / cog_revenue(). Per-row resolution follows an exact-then-substring matching algorithm with deterministic disambiguation; ambiguous and missing entries are surfaced via a sidecar audit tibble plus a single console summary message.
• New exports cog_basket_resolution() and cog_basket_unresolved() expose the basket sidecar for iterative query refinement.

Breaking changes

• The first formal of cog_gov_search() was renamed from pattern to name. All existing call sites in cog_explorer/ and the package itself use positional first-arg, so this rename is non-breaking in practice. Callers that pass pattern = ... by name must update to name = ....