jared
24e67791a0
Adds full @description, @details (algorithm), @examples on cog_gov_search(); examples on cog_basket_resolution() / cog_basket_unresolved(); NEWS.md entry covering the new mode and the pattern->name rename; pkgdown reference entries for the two new exports.
95 lines
3.4 KiB
R
95 lines
3.4 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/search.R
|
|
\name{cog_gov_search}
|
|
\alias{cog_gov_search}
|
|
\title{Search for governments by name, state, and/or type}
|
|
\usage{
|
|
cog_gov_search(name = NULL, state = NULL, type = NULL)
|
|
}
|
|
\arguments{
|
|
\item{name}{Character vector of place name(s). Length 1 = utility mode;
|
|
length >1 = basket mode.}
|
|
|
|
\item{state}{2-letter USPS abbreviation (e.g. `"FL"`), FIPS integer
|
|
(e.g. `12`), or `NULL`. In basket mode, length 1 recycles across
|
|
all entries; otherwise must match `length(name)`.}
|
|
|
|
\item{type}{Government type: integer in `0:3` or one of `"state"`,
|
|
`"county"`, `"city"`, `"township"`, or `NA`/`NULL`. Per-row optional
|
|
in basket mode (recycles from length 1). Excluded types `4`/`5` (or
|
|
`"special_district"` / `"school_district"`) trigger an explanatory
|
|
message and an empty result.}
|
|
}
|
|
\value{
|
|
A tibble of `canonical_fips_xwalk` rows. In utility mode, all
|
|
matches sorted by `population_acs` desc. In basket mode, resolved
|
|
rows in input order, with `attr(., "resolution")` set to the
|
|
sidecar tibble.
|
|
}
|
|
\description{
|
|
Resolves human-readable place names into rows of `canonical_fips_xwalk`,
|
|
the cross-vintage canonical-government registry. Operates in two modes:
|
|
}
|
|
\details{
|
|
* **Utility mode** (single `name`, the original behavior): returns all
|
|
rows whose `gov_name` matches the regex case-insensitively, sorted by
|
|
`population_acs` descending. Useful for exploratory lookups.
|
|
* **Basket mode** (`length(name) > 1`): resolves each input row to a
|
|
single canonical govid and returns a tibble in input order, suitable
|
|
for piping straight into [cog_spending()] / [cog_revenue()] /
|
|
[cog_geographic_rollup()]. Carries an audit sidecar accessible via
|
|
[cog_basket_resolution()] / [cog_basket_unresolved()].
|
|
|
|
|
|
**Basket-mode resolution algorithm** (per input row):
|
|
1. Filter `canonical_fips_xwalk` by `state` and (if non-NA) `type`.
|
|
2. **Exact pass:** case-insensitive equality against `gov_name`.
|
|
Single hit -> resolved. Multiple -> step 4.
|
|
3. **Substring fallback:** case-insensitive regex against `gov_name`.
|
|
Single hit -> resolved (`match_method = "substring"`). Zero hits ->
|
|
`status = "no_match"`. Multiple hits -> step 4.
|
|
4. **Disambiguation:** if matches share one `govs_type`, pick the
|
|
largest-population row (`status = "largest_pop"`). If they span >=2
|
|
types, no row is added (`status = "ambiguous"`); the user should
|
|
re-run with `type` specified.
|
|
|
|
Resolved rows form the returned tibble in input order. Unresolved
|
|
inputs (`ambiguous` / `no_match`) appear only in the sidecar.
|
|
}
|
|
\examples{
|
|
\dontrun{
|
|
# Utility mode — exploratory regex lookup
|
|
cog_gov_search("broward", state = "FL")
|
|
|
|
# Basket mode — resolve a known cohort
|
|
basket <- cog_gov_search(
|
|
name = c("BROWARD COUNTY", "SAN DIEGO CITY", "AUSTIN CITY"),
|
|
state = c("FL", "CA", "TX")
|
|
)
|
|
basket
|
|
|
|
# Inspect resolution audit
|
|
cog_basket_resolution(basket)
|
|
|
|
# Pipe into a spending query
|
|
library(dplyr)
|
|
basket |> cog_spending(years = 2019:2020, category = "Police")
|
|
|
|
# Iteratively refine ambiguous matches
|
|
partial <- cog_gov_search(
|
|
name = c("Broward", "San Diego"), # San Diego is ambiguous
|
|
state = c("FL", "CA")
|
|
)
|
|
cog_basket_unresolved(partial)
|
|
refined <- cog_gov_search(
|
|
name = c("Broward", "San Diego"),
|
|
state = c("FL", "CA"),
|
|
type = c(NA, "city") # disambiguate
|
|
)
|
|
}
|
|
}
|
|
\seealso{
|
|
[cog_basket_resolution()], [cog_basket_unresolved()],
|
|
[cog_spending()], [cog_revenue()].
|
|
}
|