jared
a5f86d87b3
- .detect_direct_suppressed() keys on (year, canonical_govid, category); all-categories mode collapses category to one literal value, so the key collides and the detector silently reports FALSE instead of "unknown". Report NA there instead, and stop isTRUE() in .build_provenance() from collapsing that NA back to FALSE. Schema widened to allow null. - Refuse complete = TRUE + category = "All Categories": the completion grid has no per-category cells left to fill once categories are collapsed, so the prior silent 0-rows-filled result was never actually checked. - cog_balances(category = "All Categories") returned zero rows with no error. .validate_verb_inputs() gains allow_all_categories (default FALSE); .verb_spendrev() passes TRUE, cog_balances() does not, so the three verbs share one place to reject it instead of drifting again. - Fix the false `subtype = "operations"` argument claim (no such argument exists) in NEWS.md and an internal spending.R comment. Adds three covering tests to test-all-categories.R for the three behaviour changes above.
82 lines
3.4 KiB
R
82 lines
3.4 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/balances.R
|
|
\name{cog_balances}
|
|
\alias{cog_balances}
|
|
\title{Cash and security holdings for one or more governments}
|
|
\usage{
|
|
cog_balances(
|
|
govid,
|
|
years,
|
|
category = NULL,
|
|
per_capita = FALSE,
|
|
adjust_to_year = NULL,
|
|
basis = c("harmonized", "raw"),
|
|
recipe = NULL
|
|
)
|
|
}
|
|
\arguments{
|
|
\item{govid}{Canonical govid(s): a character vector, or a data frame with a
|
|
`canonical_govid` column (e.g. from [cog_gov_search()]).}
|
|
|
|
\item{years}{Integer vector of fiscal years.}
|
|
|
|
\item{category}{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.}
|
|
|
|
\item{per_capita}{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.}
|
|
|
|
\item{adjust_to_year}{Deflate to this year's dollars (CPI-U).}
|
|
|
|
\item{basis}{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`.}
|
|
|
|
\item{recipe}{Optional harmonization recipe id (see [cog_recipes()]).
|
|
`"cash_securities_z77_wide"` and `"cash_securities_z78_wide"` bridge the
|
|
wide era to the modern one.}
|
|
}
|
|
\value{
|
|
Tibble with columns `year`, `canonical_govid`, `gov_name`,
|
|
`balance_subtype`, `category`, `amt_nominal`, `codes_included`,
|
|
`aggregate_fallback`, plus optional `amt_per_capita_nominal` and
|
|
`pop_source` (when `per_capita = TRUE`), optional `amt_real` (when
|
|
`adjust_to_year` is set), and optional `amt_per_capita_real` (only when
|
|
**both** `per_capita = TRUE` and `adjust_to_year` are set -- there is no
|
|
nominal per-capita column to deflate otherwise). Amounts are full US
|
|
dollars.
|
|
|
|
Carries a `provenance` attribute matching
|
|
`inst/schemas/provenance-v1.json`, whose `balance_caveats` block reports
|
|
`not_gaap`, `not_gaap_note`, `coverage_window` (measured year extents for
|
|
every balance subtype in the mounted corpus, not only the observed ones)
|
|
and `truncated` (the observed subtypes whose coverage falls short of the
|
|
requested years). `expenditure_concept`/`revenue_concept` are `NA` --
|
|
holdings are a stock, not a flow, so neither concept vocabulary applies.
|
|
}
|
|
\description{
|
|
Returns Census cash-and-security holdings (`category_type = "balance"`):
|
|
fund balances, retirement system holdings and insurance trust balances.
|
|
}
|
|
\section{Holdings are not GAAP fund balance}{
|
|
|
|
Census holdings are **gross** -- no liabilities are netted -- so a reserve
|
|
ratio built from them overstates what is actually available. They are not
|
|
comparable to a GAAP fund balance from an ACFR.
|
|
}
|
|
|