R/rfcipPackage_controls.R
rfcipPackage_controls.RdInitializes a named list of control parameters used across FCIP-related packages, including (i) package access tokens read from environment variables, (ii) standard unit-structure code groupings, and (iii) simulation / rounding / optimization controls with sensible defaults that can be overridden.
rfcipPackage_controls(
harvest_price_inclusion_plans = c(2, 5, 17, 27, 32, 35, 68, 88),
non_price_risk_plans = c(1, 4, 16, 26, 31, 67, 87, 90),
rma_rounding = TRUE,
yield_ratio_cup_and_cap = TRUE,
yield_benchmark_ratio_limits = c(0.5, 2),
continuous_integration_session = FALSE,
adm_decoy_state_abb = "ND",
free_acres_factor = 0.1,
area_chosen_max_factor = 0.01,
set_seed = NULL,
DEoptim_strategy = 2,
DEoptim_itermax = 1000,
DEoptim_trace = FALSE,
DEoptim_reltol = sqrt(.Machine$double.eps),
DEoptim_steptol = 100,
preference_estimation_method = "penalty",
preference_logit_scale = 1,
preference_likelihood_sign_penalty = FALSE,
preference_selection_criterion = "rank_gap",
preference_selection_penalty = 1,
preference_compute_standard_errors = FALSE,
developer_mode = FALSE,
local_adm_directory = NULL,
local_sob_directory = NULL,
local_col_directory = NULL,
local_adm_compressed_directory = NULL,
reference_amount_shock = NULL,
allowed_insurance_options = NULL
)Numeric/integer vector. Plan codes whose guarantee
may be raised by the harvest price – the "-RP" member of each plan family. Default is
c(2, 5, 17, 27, 32, 35, 68, 88): RP (2), ARP / GRIP-HRO (5), MP-HPO (17),
PACE-RP (27), SCO-RP (32), STAX-RP (35), MCO-RP (68), ECO-RP (88). Verified against
rfcipCalcPass::adm_insurance_plans; note 17 is Margin Protection with Harvest
Price Option, so 16 (plain MP) does not belong here.
Numeric/integer vector. Plan codes carrying no price risk, so
revenue-to-count is valued at the elected price – the "-YP" member of each family.
Default is c(1, 4, 16, 26, 31, 67, 87, 90): YP (1), AYP / GRP (4), MP (16),
PACE-YP (26), SCO-YP (31), MCO-YP (67), ECO-YP (87), APH (90). The "-RPHPE" variants
(3, 6, 28, 33, 36, 69, 89) belong to neither list by design: their guarantee is not
raised by the harvest price, but revenue-to-count is still valued at it.
Logical(1) or numeric(1). If FALSE, disables RMA-style rounding.
If TRUE, uses package defaults for RMA-style rounding. If numeric, it is interpreted
as a multiplier on the number of digits passed to round() (i.e., round(x, n * rma_rounding)).
Logical(1). If TRUE, enforces a 0.50–1.50 "cup & cap"
on yield ratios. Default is TRUE.
Numeric length-2. Lower and upper bound on
historical_yield / approved_yield for a pool to be benchmarked in
calibrate_yield(). A reported mean outside this range is not on the same
measurement basis as the calibration, and scaling to it is a larger error than
not benchmarking at all. Defaults to c(0.5, 2).
Logical(1). If TRUE, uses a small deterministic subset
of the Actuarial Data Master (ADM) YTD ZIP archive (safe/fast for CI). See build_min_adm().
Character scalar. State abbreviation indicating which state's decoy ADM
to use. Default is "ND".
Numeric scalar. Proportion of free acres allowed (e.g., 0.10 for 10%).
Default is 0.10. When a policy change results in a 100\
to drop coverage entirely, the per-acre out-of-pocket cost can become zero. To approximate chosen
acres consistent with the revealed budget (the pre-policy total out-of-pocket expenditure), the
simulator applies this factor in place of a zero cost.
Numeric scalar. Maximum area chosen as a fraction of total (e.g., 0.01 for 1%).
Default is 0.01. After computing provisional acres via free_acres_factor, the simulator caps
the result at:
$$max\_acres = (1 + area\_chosen\_max\_factor) \times revealed\_acres$$
where revealed\_acres is the pre-policy observed acres (optionally weighted by the number of competing
post-policy alternatives).
Optional integer. Seed for reproducible optimization. If NULL, uses 20250630.
Integer. Differential evolution strategy passed to DEoptim::DEoptim.control().
Default is 2. See DEoptim::DEoptim.control() for strategy definitions.
Integer. Maximum iterations (population generations) passed to
DEoptim::DEoptim.control(). Default is 1000.
Logical(1) or integer. Passed to DEoptim::DEoptim.control() to control progress
printing. Default is FALSE.
Relative convergence tolerance. The algorithm stops if it is unable to reduce the value
by a factor of reltol * (abs(val) + reltol) after steptol steps. Passed to
DEoptim::DEoptim.control(). Defaults to sqrt(.Machine$double.eps), about 1.5e-8.
see reltol. Passed to DEoptim::DEoptim.control(). Default is 10.
Character(1). Calibration engine: "penalty" (default,
the heuristic merit loss), "penalty_smooth" (same loss with softmax rank terms),
or "likelihood" (multinomial-logit MLE).
Numeric(1). Scale \(\sigma\) for the logit / softmax terms. Default 1.
Logical(1). If TRUE, add the marginal-utility sign /
MRS penalties to the logit objective (penalized likelihood). Default FALSE (pure logit;
required for valid AIC/BIC).
Character(1). Model-selection rule used by select_models():
one of "rank_gap" (default), "penalized_loss", "aic", "bic", "oos".
Numeric(1). Complexity penalty \(\lambda\) for "penalized_loss". Default 1.
Logical(1). If TRUE and
preference_estimation_method = "likelihood", compute parameter standard errors from a
numerical Hessian at the optimum. Default FALSE.
Logical(1). If TRUE, enables developer-oriented behavior. Default is FALSE.
Character. Root directory containing locally stored
ADM tables saved as <year>_<dataset>.rds under a <year>/ subfolder.
Character. Root directory containing locally stored SOB tables.
Character. Root directory containing locally stored COL tables.
ADM tables saved as <year>_<dataset>.rds under a <year>/ subfolder.
Character. Root directory containing locally stored compressed ADM tables.
Character. Column name for reference amount shocks
Character List. allowed insurance options names
A named list of controls containing:
GitHub tokens (CALCPASS_TOKEN, CALIBRATE_TOKEN, rfcipPRF_TOKEN,
rfcipEvaluator_TOKEN, rfcipPreferences_TOKEN, rfcipReporter_TOKEN,
rfcipReSim_TOKEN, rAgroClimate_TOKEN, fcipSupplementalLab_TOKEN):
each resolves its per-package environment variable, falling back to GH_PAT and then
GITHUB_PAT; NULL when none is set, so gh::gh() can use its own
credential discovery.
Unit-structure code groupings: optional_unit_codes, basic_unit_codes,
enterprise_unit_codes, whole_farm_unit_codes.
Simulation/optimization controls: the remaining named elements corresponding to the function arguments.
Other helpers:
apply_default_policy_options(),
clear_rfcipCalibrate_cache()
controls <- rfcipPackage_controls()
names(controls)
#> [1] "rfcipCalcPass_TOKEN" "rfcipCalibrate_TOKEN"
#> [3] "rfcipPRF_TOKEN" "rfcipEvaluator_TOKEN"
#> [5] "rfcipPreferences_TOKEN" "rfcipReporter_TOKEN"
#> [7] "rfcipReSim_TOKEN" "rAgroClimate_TOKEN"
#> [9] "fcipSupplementalLab_TOKEN" "local_adm_directory"
#> [11] "local_adm_compressed_directory" "local_sob_directory"
#> [13] "local_col_directory" "optional_unit_codes"
#> [15] "basic_unit_codes" "enterprise_unit_codes"
#> [17] "whole_farm_unit_codes" "allowed_insurance_options"
#> [19] "reference_amount_shock" "harvest_price_inclusion_plans"
#> [21] "non_price_risk_plans" "rma_rounding"
#> [23] "yield_ratio_cup_and_cap" "yield_benchmark_ratio_limits"
#> [25] "continuous_integration_session" "adm_decoy_state_abb"
#> [27] "free_acres_factor" "area_chosen_max_factor"
#> [29] "set_seed" "DEoptim_strategy"
#> [31] "DEoptim_itermax" "DEoptim_trace"
#> [33] "DEoptim_reltol" "DEoptim_steptol"
#> [35] "preference_estimation_method" "preference_logit_scale"
#> [37] "preference_likelihood_sign_penalty" "preference_selection_criterion"
#> [39] "preference_selection_penalty" "preference_compute_standard_errors"
#> [41] "developer_mode"
controls$optional_unit_codes
#> [1] "UD" "UA" "OU" "" NA