docs: a sheriff-contract city is not a real zero for Police (#80)

R/coverage.R

@@ -93,17 +93,21 @@
 #'     that year, in ANY category. This is a statement about survey collection,
 #'     independent of what was asked for: "of the governments you named, how
 #'     many did Census actually collect data from this year?" It separates
-#'     sampling (not collected) from real zeros (collected but spends nothing
-#'     in your category).
+#'     sampling (not collected) from collected governments with no rows in
+#'     your category.
 #'   * `n_units_reporting` -- how many of those appear with rows for the
-#'     SPECIFIC category you requested. This is always <= n_units_collected:
-#'     a government can be collected but have no rows for "Police" because it
-#'     contracts policing to the county sheriff, not because it wasn't
-#'     surveyed.
+#'     SPECIFIC category you requested. This is always <= n_units_collected.
+#'     A collected government can have no "Police" rows and still pay for
+#'     policing: the rows leave out intergovernmental expenditure, so a city
+#'     that pays the county sheriff and reports the payment as
+#'     intergovernmental (code `M62`) has none. Of 34 cities with documented
+#'     sheriff contracts, nine of 102 city-years (FY2012, FY2017 and FY2022;
+#'     corpus build of 2026-10-26) looked like this, and the other 93 reported
+#'     direct Police spending (uscogdata#80).
 #'
 #' `n_units_reporting` therefore conflates two very different things: a unit
-#' that was not collected (sampling) and a unit that was collected but spends
-#' nothing in that category. The ratio n_units_collected / n_units_expected is
+#' that was not collected (sampling) and a unit that was collected but has no
+#' rows in that category, which need not mean it spends nothing there. The ratio n_units_collected / n_units_expected is
 #' the true collection rate; n_units_reporting / n_units_collected measures
 #' category participation among collected units.
 #'

R/peers.R

@@ -247,24 +247,30 @@ cog_find_peers <- function(target_govid,
 #'
 #'   * `n_units_expected` -- how many governments you asked about.
 #'   * `n_units_collected` -- how many of those appear in the corpus at all
-#'     that year (in ANY category), separating sampling from real zeros.
+#'     that year (in ANY category), separating governments Census did not
+#'     collect from governments it did.
 #'   * `n_units_reporting` -- how many have rows for the SPECIFIC category you
-#'     requested. This is always <= n_units_collected: a government can be
-#'     collected but have no rows for "Police" because it contracts policing
-#'     to the county sheriff, not because it wasn't surveyed.
+#'     requested. This is always <= n_units_collected. A collected government
+#'     can have no "Police" rows and still pay for policing: the rows leave out
+#'     intergovernmental expenditure, so a city that pays the county sheriff
+#'     and reports the payment as intergovernmental (code `M62`) has none. Of
+#'     34 cities with documented sheriff contracts, nine of 102 city-years
+#'     (FY2012, FY2017 and FY2022; corpus build of 2026-10-26) looked like
+#'     this, and the other 93 reported direct Police spending.
 #'
 #' **`n_units_reporting` is category-conditional** and therefore **not a
 #' response rate**: `n_units_reporting / n_units_expected` conflates sampling
-#' (never collected) with real zeros (collected but spends nothing in your
-#' category). Use `n_units_collected / n_units_expected` for the true
+#' (never collected) with collected governments that have no rows in your
+#' category. Use `n_units_collected / n_units_expected` for the true
 #' collection rate, and `n_units_reporting / n_units_collected` for category
 #' participation among collected units.
 #'
 #' In FY2022, a census year, 393 of Georgia's 567 cities report
 #' `category = "Police"`. Of the other 174, 32 were not collected and 142 were
-#' collected with no Police rows. Contracting policing to the county sheriff is
-#' one reason a city lands in the second group; the counters do not say how many
-#' of the 142 do.
+#' collected with no Police rows. A city that contracts with the county sheriff
+#' lands in the second group only when it reports no direct Police spending, for
+#' example when it files the payment as intergovernmental expenditure; the
+#' counters do not say how many of the 142 do.
 #'
 #' A census year and a sample year collect different sets of governments, so
 #' participation across the two mixes a change in which governments were

R/rollup.R

@@ -67,24 +67,30 @@
 #'
 #'   * `n_units_expected` -- how many governments you asked about.
 #'   * `n_units_collected` -- how many of those appear in the corpus at all
-#'     that year (in ANY category), separating sampling from real zeros.
+#'     that year (in ANY category), separating governments Census did not
+#'     collect from governments it did.
 #'   * `n_units_reporting` -- how many have rows for the SPECIFIC category you
-#'     requested. This is always <= n_units_collected: a government can be
-#'     collected but have no rows for "Police" because it contracts policing
-#'     to the county sheriff, not because it wasn't surveyed.
+#'     requested. This is always <= n_units_collected. A collected government
+#'     can have no "Police" rows and still pay for policing: the rows leave out
+#'     intergovernmental expenditure, so a city that pays the county sheriff
+#'     and reports the payment as intergovernmental (code `M62`) has none. Of
+#'     34 cities with documented sheriff contracts, nine of 102 city-years
+#'     (FY2012, FY2017 and FY2022; corpus build of 2026-10-26) looked like
+#'     this, and the other 93 reported direct Police spending.
 #'
 #' **`n_units_reporting` is category-conditional** and therefore **not a
 #' response rate**: `n_units_reporting / n_units_expected` conflates sampling
-#' (never collected) with real zeros (collected but spends nothing in your
-#' category). Use `n_units_collected / n_units_expected` for the true
+#' (never collected) with collected governments that have no rows in your
+#' category. Use `n_units_collected / n_units_expected` for the true
 #' collection rate, and `n_units_reporting / n_units_collected` for category
 #' participation among collected units.
 #'
 #' In FY2022, a census year, 393 of Georgia's 567 cities report
 #' `category = "Police"`. Of the other 174, 32 were not collected and 142 were
-#' collected with no Police rows. Contracting policing to the county sheriff is
-#' one reason a city lands in the second group; the counters do not say how many
-#' of the 142 do.
+#' collected with no Police rows. A city that contracts with the county sheriff
+#' lands in the second group only when it reports no direct Police spending, for
+#' example when it files the payment as intergovernmental expenditure; the
+#' counters do not say how many of the 142 do.
 #'
 #' A census year and a sample year collect different sets of governments, so
 #' participation across the two mixes a change in which governments were

vignettes/coverage-counters.Rmd

@@ -71,13 +71,25 @@ The counters split the governments you named into three groups each year:
    in years ending in 2 or 7 and from a sample in other years, so in a sample year
    this group includes every government outside that year's sample.
 2. `n_units_collected - n_units_reporting` governments were collected that year but
-   have no rows in your category. A city that contracts its policing to the county
-   sheriff lands here for `category = "Police"`. Its Police spending is a real zero.
+   have no rows in your category. The rows come from the concept you asked for, and
+   the default `"primary"` concept leaves out intergovernmental expenditure. A city
+   that pays the county sheriff to police it and reports the payment as
+   intergovernmental expenditure lands here for `category = "Police"`, although it
+   spends money on policing.
 3. `n_units_reporting` governments have rows in your category.
 
 A government in the first group and a government in the second group look the same in
 the result: neither has a row. Only `n_units_collected` tells them apart.
 
+A government in the second group does not necessarily spend nothing in your category.
+The published corpus, as of its 2026-10-26 build, has Police spending for every one of
+34 cities with documented county sheriff contracts in California and Washington, in
+each of FY2012, FY2017 and FY2022. In 93 of those 102 city-years the city reports
+direct Police spending and counts as reporting. In the other nine it reports the
+payment only as intergovernmental Police expenditure, code `M62`, and lands in the
+second group. For a single government, `cog_spending()` with
+`expenditure_concept = "total"` adds the intergovernmental rows.
+
 # Georgia cities and Police spending
 
 Build the list of Georgia cities with `cog_gov_search()` and roll their Police
@@ -216,8 +228,9 @@ attr(police_2022, "provenance")$coverage
 On the published corpus, as of its 2026-10-26 build, the chunk returns 567 expected,
 535 collected and 393 reporting. The 174 cities without Police rows split into 32
 that Census did not collect and 142 that were collected and have no Police rows.
-Contracting policing to the county sheriff is one reason a city lands in the second
-group; the counters do not say how many of the 142 do.
+A city that contracts with the county sheriff lands in the second group only when it
+reports no direct Police spending, for example when it files the payment as
+intergovernmental expenditure. The counters do not say how many of the 142 do.
 
 # Peer comparisons count peers only