Get calibrated FCIP data

Source: R/get_fcip_calibrated_data.R

Downloads (and caches) Farm Bill FCIP calibration artifacts from the rfcipCalibrate GitHub Releases and returns a filtered data.table. Supports vectorized queries over years and common geographic & crop filters.

get_fcip_calibrated_data(
  year = as.numeric(format(Sys.Date(), "%Y")) - 3,
  dataset = "calibration_data",
  crop = NULL,
  state = NULL,
  fips = NULL,
  force = FALSE,
  control = rfcipPackage_controls()
)

Arguments

year

Numeric scalar or vector. One or more ADM years (e.g., 2020 or 2018:2022). Defaults to as.numeric(format(Sys.Date(), "%Y")) - 3. If multiple years are provided, each year is downloaded/read and row-bound.

dataset

Character (length 1). Which dataset to retrieve. One of:

  • "revenue_draw" - 500 simulated revenue draws for each observed FCIP aggregated transaction, generated using the RMA M-13 framework with ADM parameters, ensuring all menu alternatives are evaluated under the same stochastic scenarios.

  • "calibrated_revenue" - Combined dataset of calibrated yields and 500 simulated revenue draws for each observed FCIP aggregated transaction.

  • "menu_option" - All available Basic FCIP menu options for each observed FCIP aggregated transaction.

  • "calibrated_menu" - For each observed FCIP aggregated transaction, the feasible FCIP menu is constructed for the study year/location, with revenues simulated for every alternative across the same 500 correlated scenarios.

  • "calibration_data", "calibrated_yield", "calibrated_preference_lite" - additional calibration artifacts when available.

crop

Character/numeric vector. Crop identifier(s). Accepts common names (e.g., "corn", "soybeans") or commodity codes (e.g., 41). Names are converted to codes via rfcip::get_crop_codes().

state

Character/numeric vector. U.S. states as two-letter abbreviations (e.g., "ND"), full names (e.g., "North Dakota"), or FIPS state codes (e.g., 38). Normalized to 2-digit state FIPS via usmap::fips().

fips

Character/numeric vector. Full 5-digit county FIPS code(s). When provided, fips takes precedence and state/county are derived from it.

force

Logical. If TRUE, attempts to re-download each requested file even if cached. If download fails and a cached file exists, falls back to cache with a warning.

control

List of control parameters; see rfcipPackage_controls.

Value

A data.table containing the requested dataset row-bound across all requested years and filtered by the supplied crop/state/county/fips. Returns an empty data.table if no data could be loaded.

Details

For each year, the function constructs a release asset name <dataset>_<year>.rds under the GitHub tag <dataset> and downloads it to the cache (or reads from cache), then applies optional filters when the relevant columns exist: commodity_code (crop), state_code (2-digit), county_code (3-digit).

Caching

Files are stored under tools::R_user_dir("rfcipCalibrate", which = "cache"). Subsequent calls reuse cached .rds files unless force = TRUE.

Filtering precedence

  1. If fips is provided, it is normalized via clean_fips() and used to derive state (2-digit) and county (3-digit).

  2. Otherwise, if state and county are both provided:

    • If county looks like a 5-digit FIPS, split into state+county.

    • Else, resolve county names within the given state via usmap::fips().

  3. If only state is provided, filter at the state level.