Configure column mappings

Sets up column name mappings between user data and package expectations. This function defines which columns in your datasets correspond to required roles (e.g., administrative units, year, month, live births) for all subsequent PVIEM operations.

Usage

config_pviem(
  ...,
  admin = "dist_code",
  year = "year",
  month = "month",
  birth = "live_births",
  monthly = FALSE
)

Arguments

...: Forces optional arguments to be passed by name and allows for future extensions without breaking existing code. Must be empty.
admin: [character] Column(s) identifying administrative units. Default "dist_code". For multiple levels, provide from highest to lowest (i.e., c("admin1", "admin2")).
year: [character(1)] Name of the year column (default "year")
month: [character(1)] Name of the month column (default "month")
birth: [character(1)] Name of live births column (default "live_births")
monthly: [logical(1)] Is RI data monthly? Default FALSE (yearly).

Value

[list] Invisibly returns the complete column mapping configuration.

Details

Purpose

This function creates a flexible interface between your data and PVIEM's internal functions. Instead of forcing specific column names, you can map your existing column names to the roles PVIEM expects.

How it works

The configuration is stored in the package's internal environment (pviem_env) and persists for the entire R session. All subsequent functions (e.g., validate_all_data(), compute_immunity_samples()) will use these mappings.

Data resolution modes

Monthly data (`monthly = TRUE`)

Requires: month column in ri_data
Birth seasonality: Not used (seasonality derived directly from monthly births)
Time identifier: Combination of year + month
Uniqueness: Each row must be unique by admin + year + month columns in the related datasets (e.g., RI data, birth seasonality data)

Yearly data (`monthly = FALSE`)

Requires: No month column in ri_data
Birth seasonality (optional): Used for monthly distribution of yearly births. Should contain month and birth columns with monthly birth distribution (see dummy_birth_seasonality).
Time identifier: year only
Uniqueness: Each row must be unique by admin + year columns in the related datasets (e.g., RI data, birth seasonality data)

Important notes

Call this first: Always run config_pviem() before any analysis functions
Match column names: Ensure mapped column names exist in your data
Consistency: Same mappings apply to all datasets (RI, seasonality, etc.)
Defaults: The default mappings are set to match the data structures used in the package's version <= 0.1.2.

Examples

# \donttest{
# Validate the package internal yearly RI data fails without setup because the default
# `admin` columns mapping do not match the internal data structure
try(validate_ri_data(dummy_yearly_ri_data, prep_dummy_vs_info))
#> Error in validate_ri_data(dummy_yearly_ri_data, prep_dummy_vs_info) : 
#>   Missing and/or unknown column(s) in 'ri_data' data frame:
#> • column 'prov_code' is unknown

# Validate the package internal yearly RI data works with setup but monthly RI data
# fails when `monthly` is not set to TRUE as the month column is missing
with_config(list(admin = c("prov_code", "dist_code")), {
  validate_ri_data(dummy_yearly_ri_data, prep_dummy_vs_info)
  try(validate_ri_data(dummy_monthly_ri_data, prep_dummy_vs_info))
}) # with_config automatically resets the setup after the block
#> Error in validate_ri_data(dummy_monthly_ri_data, prep_dummy_vs_info) : 
#>   Missing and/or unknown column(s) in 'ri_data' data frame:
#> • column 'month' is unknown

# Validate the package internal monthly RI data works with setup when `monthly` is
# set to TRUE, but yearly RI data fails as the month column is not expected
with_config(list(admin = c("prov_code", "dist_code"), monthly = TRUE), {
  validate_ri_data(dummy_monthly_ri_data, prep_dummy_vs_info)
  try(validate_ri_data(dummy_yearly_ri_data, prep_dummy_vs_info))
})
#> Error in validate_ri_data(dummy_yearly_ri_data, prep_dummy_vs_info) : 
#>   Missing and/or unknown column(s) in 'ri_data' data frame:
#> • column 'month' is missing
# }