Missing doses imputation

Impute missing doses based on the observed doses in ri_data with respect to the target-reference pairs defined in sample_pair argument. The imputation can be performed using different assumptions.

Usage

impute_missing_doses(
  ri_data,
  ...,
  doses_ratio = deprecated(),
  sample_pair = NULL,
  imputation_mode = NULL,
  sample_mode = NULL,
  bandwidth = 1,
  zero.rm = TRUE,
  .sampler_args = rlang::list2()
)

Arguments

ri_data: [data.frame] Contains the routine immunization data as defined in dummy_yearly_ri_data or dummy_monthly_ri_data (see RI data section in details).
...: Forces optional arguments to be passed by name and allows for future extensions without breaking existing code. Must be empty.
doses_ratio: [data.frame] This argument is deprecated as of version 0.2.0 and will be removed in future versions. Ratios are now computed internally within this functions, so there is no need to compute them separately.
sample_pair: [list<character(1) = character(1)>] Named list where each name is a dose (e.g. 'OPV1') we would like to impute (we see as target) and the corresponding value is the reference (i.e. 'OPV0') we would like to use as denominator (we see as reference) to compute the ratios (target/reference) during the missing doses imputation. The reference may represent live births or any other dose. When NULL, the default value is computed using the get_default_sample_pair().
imputation_mode: ['stochastic' | 'deterministic' | 'custom'] Indicates the imputation assumption to use when imputing missing doses (see Imputation assumptions section in details).
sample_mode: [character(1) | function(1)] Indicates the sampling approach to use. The options to choose from, depend on the imputation_mode value (see Imputation assumptions section in details).
bandwidth: [numeric(1)] Indicates the standard deviation of the Gaussian kernel to use when sample_mode = "gaussian". The value has to be chosen carefully. Too small values might lead to very localised sampling and thus less accurate imputation, while too large values might lead to almost uniform sampling and thus less accurate imputation as well. So chose a value that is large enough to allow sampling from a reasonable range of years or months but not too large to be close to uniform sampling. The default value is 1.
zero.rm: [logical(1)] If TRUE (default), zeros are removed during the imputation of missing doses.
.sampler_args: [list] A list of additional arguments to pass to the custom sampling function when imputation_mode = "custom". This allows users to provide extra parameters required by their custom sampling function without modifying the main function signature.

Value

[data.frame] ri_data with missing values filled.

Details

RI data structure

The column names for administrative units, year, month (if applicable) and birth cohort should match those defined in admin, year, month (if monthly = TRUE in config_pviem()) and birth arguments in config_pviem() respectively. For instance, if admin = c("province", "district"), then ri_data should contain two administrative unit columns named province and district. year, month and birth columns should also be named according to the corresponding arguments in config_pviem(). In addition to these columns, ri_data should contain columns for each vaccine dose following the naming convention defined in vs_info (e.g., "OPV0", "IPV1", etc.). Each of these columns should contain the number of doses administered for that vaccine dose in each admin unit-year (or admin unit-year-month if monthly = TRUE in config_pviem()).

This data is allowed to have missing values (NA) only for vaccine dose columns.

Imputation assumptions

The imputation can be performed using different assumptions defined in imputation_mode argument. The options are:

'stochastic' (default): Impute missing values using the bootstrapping approach. The sample_mode argument options for this imputation assumption are:
- 'uniform' (default for this imputation assumption): Assumes equal probability of sampling a missing value from any observed value across the time period for a given administrative unit and vaccine dose.
- 'position': Assigns higher sampling probability to observed values that are temporally closer to the missing value. This approach assumes that the vaccination patterns are more similar in closer years or months.
- 'gaussian': Similar to 'position' but applies Gaussian-shaped weights with mean 0 and standard deviation equal to bandwidth, providing a smooth decay in probability as temporal distance increases.
'deterministic': Impute missing values using the mean, the median, the minimum or the maximum of the observed values. The sample_mode argument options for this imputation assumption are:
- 'mean' (default for this imputation mode): Impute missing values using the mean of all non-null ratios for each missing value.
- 'min': Impute missing values using the minimum of all non-null ratios for each missing value.
- 'max': Impute missing values using the maximum of all non-null ratios for each missing value.
'custom': Impute missing values using a custom function. In this case, the sample_mode argument should be a function with the format fun(r, na_idx, notnull_idx, ...) where:
- r: is a numeric vector of ratios (computed based on sample_pair) of a specific vaccine dose in a specific administrative unit.
- na_idx: is an integer vector of indices of missing values in r.
- notnull_idx: is an integer vector of indices of non-missing and non-zero (if zero.rm is TRUE) values in r.
- ...: additional arguments passed to the function.

Note

The imputation is not done directly on the dose counts but rather on the ratios between target-reference pairs defined in sample_pair and the result is multiplied by the reference value to obtain the imputed dose count.