Skip to contents

Calculate target importance from confidence intervals

popsim_calculate_importance.Rd

Calculates the importance of each control field for PopulationSim weighting using the inverse of the confidence interval differential. Use when you want to downweight targets with high uncertainty in synthetic population generation.

Usage

popsim_calculate_importance(target_region_ci, quadratic = FALSE, settings)

Arguments

target_region_ci

data.table. Confidence intervals for targets. Required columns:

  • variable — target variable name

  • lower — lower bound of CI

  • upper — upper bound of CI

  • total — total value for normalization Rows: one per target variable per group.

quadratic

logical(1). If TRUE, exaggerates importance by squaring and scaling. Default FALSE.

settings

list. Project settings, must include popsim_calculate_importance (logical).

Value

list. Named list mapping target variable to importance value (numeric). Returns NULL if disabled in settings.

Details

  • Accepts a data.table of confidence intervals for each target variable.

    • Required columns: variable (character), lower (numeric), upper (numeric), total (numeric)

  • For each variable, computes mean lower, upper, and total across groups.

  • Calculates percentage difference: pct_diff = (upper - lower) / total

  • Importance is set as 1 / pct_diff (smaller CI = higher importance).

  • If quadratic = TRUE, importance is squared and divided by 10 to exaggerate differences.

  • Infinite or missing importance values are set to the mean importance.

  • If total == 0, importance is set to 0.

  • Returns a named list mapping target variable to importance value.

  • If the setting popsim_calculate_importance is not set or FALSE in settings, returns NULL and uses default importance values.

  • Assumes input is a data.table; does not modify by reference.

  • Error handling: non-finite or missing importance values are replaced with the mean; messages are printed for missing settings.

Settings

  • popsim_calculate_importance (direct): enables importance calculation. Default FALSE. If not set, returns NULL and uses default importance values. Used in PopulationSim control config generation.

See also

create_importance_list, popsim_make_control_config

Examples

## Not run:
ci_dt <- data.table(variable = c('h_income', 'h_size'), lower = c(100, 50), upper = c(120, 60), total = c(110, 55))
popsim_calculate_importance(ci_dt, quadratic = TRUE, settings = list(popsim_calculate_importance = TRUE))
#> $h_income
#> [1] 3.025
#> 
#> $h_size
#> [1] 3.025
#> 
## End(Not run)