feat: fiscal-year periods and survey-year helpers (#77, R side)

NAMESPACE

@@ -6,6 +6,7 @@ export(cog_basket_unresolved)
 export(cog_categories)
 export(cog_explain)
 export(cog_find_peers)
+export(cog_fiscal_periods)
 export(cog_geographic_rollup)
 export(cog_gov_search)
 export(cog_manifest)
@@ -14,3 +15,4 @@ export(cog_peer_compare)
 export(cog_recipes)
 export(cog_revenue)
 export(cog_spending)
+export(cog_survey_year)

NEWS.md

@@ -1,3 +1,37 @@
+# uscogdata (development version)
+
+## Fiscal-year periods for each row
+
+`year` is the Census survey year, and a survey year covers different months for
+different governments. Census files a government's fiscal year under survey year Y
+when it ended between July 1 of Y-1 and June 30 of Y. For a county, city or township,
+"2017" means July 2016 to June 2017 with a June 30 year end, October 2015 to
+September 2016 with a September 30 year end, and January to December 2016 with a
+December 31 year end.
+
+`cog_spending()`, `cog_revenue()` and `cog_balances()` gain `fiscal_period = FALSE`.
+With `fiscal_period = TRUE`, every row gains three columns at the end:
+`fiscal_year_end`, an MMDD integer such as `630`, and `period_start` and `period_end`,
+the first and last day the row covers. They come from that government-year's own
+fiscal year end, so a change of fiscal year is respected, and they are `NA` where the
+corpus has no value. The provenance gains `transformations$fiscal_period`. The default
+returns the same columns and provenance as before.
+
+```r
+cog_spending("121011212191", years = 2020, category = "Police", fiscal_period = TRUE)
+```
+
+`cog_fiscal_periods(govid, years)` returns the months each survey year covers for
+each government. `cog_survey_year(govid, date)` returns the survey year whose period
+contains a date, which places an event against the corpus's `year`.
+
+State governments follow a different rule: survey year Y holds the fiscal year ending
+in calendar year Y. It changes the months for three states, Alabama and Michigan
+(September 30) and Texas (August 31). Census's 2004 and 2006 technical documentation
+lists them as exceptions to the June 30 window, and the published corpus agrees for
+survey year 2020. The same documentation lists the District of Columbia, so it gets
+the state rule too, although the data has not confirmed it.
+
 # uscogdata 0.4.0
 
 ## Cohorts can be named by predicate, not just by id

R/balances.R

@@ -53,15 +53,21 @@
 #'   `total_rows`.
 #' @param offset Rows to skip before `limit` starts counting (0-based).
 #'   Ignored if `limit` is `NULL`; defaults to `0L` when `limit` is set.
+#' @param fiscal_period If `TRUE`, add `fiscal_year_end`, `period_start` and
+#'   `period_end` to every row, as [cog_spending()] does. Holdings are a stock
+#'   measured at the end of the fiscal year, so `period_end` is the date the
+#'   balance describes and `period_start` is the start of that fiscal year.
+#'   Defaults to `FALSE`, which leaves the result unchanged.
 #'
 #' @return 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.
+#'   nominal per-capita column to deflate otherwise), and `fiscal_year_end`,
+#'   `period_start` and `period_end` when `fiscal_period = TRUE`. Amounts are
+#'   full US dollars.
 #'
 #'   Carries a `provenance` attribute matching
 #'   `inst/schemas/provenance-v1.json`, whose `balance_caveats` block reports
@@ -79,7 +85,7 @@ cog_balances <- function(govid = NULL, years, category = NULL,
                          per_capita = FALSE, adjust_to_year = NULL,
                          basis = c("harmonized", "raw"), recipe = NULL,
                          state = NULL, type = NULL,
-                         limit = NULL, offset = NULL) {
+                         limit = NULL, offset = NULL, fiscal_period = FALSE) {
   call <- match.call()
   basis <- match.arg(basis, c("harmonized", "raw"))
   # Coerce FIRST, validate second: .validate_verb_inputs() asserts
@@ -102,6 +108,7 @@ cog_balances <- function(govid = NULL, years, category = NULL,
   # validator's own doc comment for the incident that made that matter.
   .validate_verb_inputs(govid, years, category, per_capita, adjust_to_year,
                         recipe)
+  .validate_fiscal_period_arg(fiscal_period)
 
   # Same semantics as the money verbs (R/pagination.R). Only the `recipe`
   # conflict applies here: cog_balances() has no `complete` argument, and a
@@ -174,6 +181,7 @@ cog_balances <- function(govid = NULL, years, category = NULL,
   if (!is.null(adjust_to_year)) {
     result <- .attach_real_dollars(result, adjust_to_year, per_capita)
   }
+  if (fiscal_period) result <- .attach_fiscal_period(result, con)
 
   prov <- .build_provenance(
     verb = "cog_balances", call = call, govid = govid, years = years,
@@ -189,6 +197,9 @@ cog_balances <- function(govid = NULL, years, category = NULL,
   prov$scope$govids_found   <- scope$found
   prov$scope$govids_missing <- scope$missing
   prov$scope$cohort <- .cohort_provenance(con, cohort)
+  if (fiscal_period) {
+    prov$transformations$fiscal_period <- .fiscal_period_provenance(result)
+  }
 
   prov$balance_caveats <- .balance_caveats(
     con, prov$codes_summed$observed, years