docs: recast NEWS around the first public release
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.
This commit is contained in:
@@ -21,3 +21,33 @@ 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.
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user