uscogdata/NEWS.md

uscogdata 0.4.0

Cohorts can be named by predicate, not just by id

cog_spending(), cog_revenue() and cog_balances() gain optional state and type arguments. Both default to NULL, so every existing call behaves exactly as before.

Passing them expresses the cohort as a subquery against canonical_fips_xwalk inside each statement, instead of round-tripping the ids through R and rendering them back into a literal IN list:

# before: resolve 20,106 ids in R, then embed them in every statement
ids <- cog_gov_search(NULL, state = "CA", type = "city")$canonical_govid
cog_spending(ids, years = 2022)

# now: the cohort never leaves the database
cog_spending(years = 2022, state = "CA", type = "city")

Measured against the production corpus, same FY2022 aggregate over the 20,106-government type = "city" cohort:

cohort expressed as	time
IN (20,106 literals)	449 ms
join against a temp cohort table	99 ms
predicate on canonical_fips_xwalk	94 ms
no cohort filter at all (the floor)	88 ms

4.8x, within 7% of the floor. The rendered IN list was 301,591 characters and was re-parsed in 5-8 separate statements per call, so the cost was paid repeatedly; the predicate's size is constant in the cohort.

state and type use the same vocabulary and the same internal coercion as cog_gov_search() -- state is a postal abbreviation ("WI") even though the crosswalk column holds a FIPS code ("55").

Supplying govid and state/type intersects them: the governments in govid that also match the predicate. Naming no cohort at all now aborts with class uscogdata_no_cohort rather than R's "argument is missing" error.

When the cohort is named by predicate there is no id list to report, so provenance$scope$govids_found/govids_missing are empty and provenance$scope$cohort carries state, type and n_governments instead. A govid-named cohort's provenance is unchanged.

cog_gov_search() and cog_balances() gain limit/offset

Pagination arrived on cog_spending()/cog_revenue() in 0.3.0; the other two verbs were left materializing everything and slicing in R. Both now take limit/offset with the same semantics: NULL default, the page applied in SQL behind a deterministic ORDER BY, and the unpaginated count returned as a total_rows attribute computed by COUNT(*) OVER() in the same scan rather than a second query.

cog_gov_search() had no LIMIT at all, which made it the one verb that returns the entire 40,336-row crosswalk when called with no filter.

Two refusals rather than silent surprises:

• cog_balances(recipe = , limit = ) aborts with class uscogdata_recipe_pagination_conflict -- a recipe's result comes from a separate query that pagination is not wired into.
• cog_gov_search() in basket mode (length(name) > 1) aborts with class uscogdata_basket_pagination_conflict. Basket mode returns one resolved row per requested name with a sidecar covering all of them; a page of that is not a page of anything the caller asked for.

DuckDB's resource budget is configurable

USCOGDATA_DUCKDB_THREADS and USCOGDATA_DUCKDB_MEMORY_LIMIT (with matching options(uscogdata.duckdb_threads = ) / options(uscogdata.duckdb_memory_limit = ) spellings) cap the DuckDB connection the package opens. Both follow the same env-var > option > default precedence as USCOGDATA_URL.

Unset, no pragma is issued at all and DuckDB's own defaults apply exactly as before -- every visible core. That is right for one interactive session on a dedicated machine and wrong for a server: where several readers share a host, each otherwise claims the whole machine and they contend. Capping measured ~5% on a single-government all-years query (502 ms at 2 threads vs 475 ms uncapped on 16 cores), which is cheap enough that a server should always cap.

This replaces a workaround in which a consumer reached into the package namespace at boot -- getFromNamespace(".ensure_session", "uscogdata")() followed by a manual SET threads -- depending both on a private name and on the session already being open.

Documentation: the corpus-access table is re-measured and honest

The README's "two ways to read the corpus" table carried figures taken before the corpus was re-chunked into row groups (cog_pipeline#93, published 2026-08-09) and reported the mirrored column as "local speed" with no number at all. Re-measured 2026-08-10 against the published corpus (pipeline_commit 3d28ddd), fresh R session per arm:

• A local mirror is roughly 60-80x faster. A one-off question costs ~12 s end to end remotely against ~0.15 s mirrored. That is the largest single difference available to a user and it is now stated outright rather than left as "local speed".
• Opening the session is the largest remote cost (~7.5 s -- manifest fetch plus 23 view registrations over HTTPS), larger than any individual query, and it lands on the first query rather than on library(uscogdata). The old table did not account for it anywhere.
• The remote cost is round-trips, not scanning. A repeat query over already-touched partitions is ~1.5 s against ~4 s cold, and a full-history query costs ~7 s whether it runs first or last.
• The corpus size is ~201 MB, not 190.6 MB -- row-group chunking added ~3.4% and the old figure was ambiguous between MB and MiB besides.
• Documented that a burst of remote queries can be rate-limited by the host (HTTP 429), which is another reason to mirror for real work.

Fixes

• cog_gov_search() now orders by population_acs DESC NULLS LAST, canonical_govid. population_acs alone is not a total order -- ties, and the entire NULLS LAST block, came back in whatever order the scan produced. That was invisible while every call returned the full result set, but it makes a paged sweep unsound: two requests can order tied rows differently, so a row is duplicated on one page and missing from the next. Unpaginated results are unchanged except for the relative order of rows that were already tied.

• An unknown state abbreviation now aborts with "Unknown state abbreviation" (class uscogdata_unknown_state) instead of base R's "subscript out of bounds". .state_abbrev_to_fips is a named character vector, so [[ on an absent name threw before the curated message could be reached -- making that message unreachable dead code in every verb that takes a state.

uscogdata 0.3.0

First public release.

uscogdata provides curated R verbs over the Civilytics US Census of Governments finance corpus: unit-level financial profiles, geographic rollups and peer comparisons, with auditable provenance on every result.

What it covers

Government types 0-3 (state, county, municipality, township), FY1967-FY2024 -- 56 fiscal years, 46,148,034 rows, 190.6 MB. There is no source data for FY1968 or FY1969. Special districts (type 4) and school districts (type 5) are out of scope pending validation.

The verbs

cog_spending(), cog_revenue() and cog_balances() for flows and holdings; cog_gov_search() to resolve place names (including basket mode for many at once); cog_find_peers() and cog_peer_compare() for cohorts; cog_geographic_rollup() for aggregates; cog_categories(), cog_recipes(), cog_manifest() and cog_explain() for metadata and provenance; and cog_mirror() for a local copy of the corpus.

Reading the corpus now works out of the box

• The package reads the published corpus over HTTPS with no configuration. Previously the default was a placeholder sentinel and no document in the package supplied a working URL, so a new user had no path to a session.
• Remote reads work at all. The partitioned view used a glob, and DuckDB cannot expand a glob over generic HTTP -- there is no directory listing to expand against. Partition paths are now enumerated from the corpus manifest, which is host-agnostic: an HTTPS mirror, a Nextcloud share and a local cog_mirror() copy all take the same path.
• Nothing is written to disk in remote mode; DuckDB fetches only the row groups a query needs.

Four things to know before your first query

• Amounts are in full US dollars. The raw Census files report thousands; the verbs multiply by 1000 on the way out. Do not multiply again.
• Multi-government aggregates disclose their coverage. The Census is a complete enumeration only in years ending in 2 and 7; every other year is a sample. Every such result carries provenance$coverage with per-year n_units_reporting.
• Absence means two different things. Before FY2012 an absent cell means Census published $0; from FY2012 it means not reported. complete = TRUE labels which.
• Series breaks reach you unasked. Catalogued breaks intersecting your query appear in provenance and in cog_explain().

Known limits

• Special districts (type 4) and school districts (type 5) are out of scope.
• Per-capita rollups exclude governments with no F-33 population, which is by design but does silently narrow a rollup.
• n_units_reporting is category-conditional and is not a response rate.
• Employee-retirement (X) codes stop at FY2016, when those systems moved to the Annual Survey of Public Pensions.

uscogdata 0.2.0

New features

• cog_spending() and cog_revenue() accept the reserved category "All Categories", returning one summed row per (year, canonical_govid, subtype) across every category inside the requested concept's subtype scope. Filtering the result to spend_subtype == "operations" gives an operating-expenditure total. cog_geographic_rollup() inherits it, which is the efficient way to build a geographic total — previously a caller had to issue one rollup per category and sum the results (cog-api#37).

  "All Categories" is not the same thing as expenditure_concept = "total". The concept chooses which subtypes are in scope; "All Categories" chooses whether the rows inside that scope are broken out or summed.

• cog_categories() advertises "All Categories" for the expenditure and revenue vocabularies, so the reserved value is discoverable.

• Coverage signposting (see "Signposting now catches partially-suppressed categories" below) now also works in category = "All Categories" mode. The recipe-suggestion candidate query used to be scoped by category, which is never a match for the reserved "All Categories" value, so provenance$suggestions always came back empty there — the one mode whose whole point is "you cannot sum the wrong scope" was silently unable to signal a wrong scope. The candidate query is now scoped by the concept's subtype allowlist instead, symmetric with how .build_verb_sql() itself scopes the summed total: Los Angeles County FY2011, category = "All Categories" still excludes $271,589,000 of aggregate-published Public Welfare (E68), but now names recipe = "welfare_cash_e68_wide" to recover it instead of reporting zero suggestions.

Documentation

• cog_geographic_rollup() and cog_peer_compare() now document that provenance$coverage's n_units_reporting is category-conditional and is not a response rate: a government that was surveyed and genuinely spends nothing in the requested category is indistinguishable from one never surveyed (uscogdata#36).