jared
da2839f885
NEWS described changes relative to states no user had ever seen -- 'Breaking: corpus schema_version 4', 'the package now requires...' -- across the whole pre-release development. To someone deciding whether to depend on this, that reads as instability. 0.3.0 is written as an announcement: what it covers, the verbs, that reading the corpus now works out of the box, four things to know before a first query, and the known limits. The 0.2.0 changelog is kept verbatim. The 0.1.0 development log is dropped; that history is in git. cog_explain() now documents what provenance actually holds, since the README points readers at it -- in particular why series_break_refs and corpus_break_refs are separate fields rather than one list.
54 lines
2.1 KiB
R
54 lines
2.1 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/explain.R
|
|
\name{cog_explain}
|
|
\alias{cog_explain}
|
|
\title{Explain a verb result's provenance}
|
|
\usage{
|
|
cog_explain(result, format = c("print", "list"))
|
|
}
|
|
\arguments{
|
|
\item{result}{A tibble returned by a `cog_*` verb.}
|
|
|
|
\item{format}{`"print"` (default) for a human-readable cli summary;
|
|
returns `result` invisibly for chaining. `"list"` returns the raw
|
|
provenance list (identical to `attr(result, "provenance")`).}
|
|
}
|
|
\value{
|
|
Either `result` (invisibly) or the provenance list.
|
|
}
|
|
\description{
|
|
Prints the structured provenance attached to a tibble returned by any
|
|
`cog_*` verb, or returns it as a list for downstream use (MCP tools,
|
|
dashboards, JSON export).
|
|
}
|
|
\section{Two kinds of series break}{
|
|
|
|
Catalogued breaks reach you without being asked for, in two disjoint
|
|
fields, because a caveat about one series and a caveat about the whole
|
|
corpus are different claims:
|
|
|
|
* **`series_break_refs`** — breaks matched against the item codes actually
|
|
present in this result. A break in one code you queried.
|
|
* **`corpus_break_refs`** — breaks catalogued with `fin_code = "ALL"`,
|
|
which are statements about the corpus rather than about any one code:
|
|
dollar precision across the 1976/1977 boundary (`SB085`), imputation
|
|
exclusion from FY2002 (`SB087`), the FY2012 dense-to-sparse
|
|
representation change (`SB194`), and the FY2017 government-identifier
|
|
change (`SB086`). These are selected on the break-year window alone.
|
|
|
|
`SB194` is the one most likely to matter: a query spanning FY2011 to FY2012
|
|
crosses the boundary where an absent cell stops meaning "Census published
|
|
$0" and starts meaning "not reported".
|
|
}
|
|
|
|
\section{Other provenance blocks}{
|
|
|
|
`transformations$units_conversion` records the `$1,000s`-to-dollars
|
|
multiply that every amount column has already had applied.
|
|
`transformations$per_capita` records the population denominator and its
|
|
year range. `coverage` and `coverage_mode` appear on multi-government
|
|
results (see [cog_geographic_rollup()]). `completion` appears when
|
|
`complete = TRUE`. `balance_caveats` appears on [cog_balances()] results.
|
|
}
|
|
|