Type:	Package
Title:	Optimal Selection of Imputation Methods for Pain-Related Numerical Data
Version:	0.6
Description:	A model-agnostic framework for selecting dataset-specific imputation methods for missing values in numerical data related to pain. Lotsch J, Ultsch A (2025) "A model-agnostic framework for dataset-specific selection of missing value imputation methods in pain-related numerical data" Canadian Journal of Pain (in minor revision).
Depends:	R (≥ 3.5.0)
Imports:	parallel, Rfit, methods, stats, caret, ABCanalysis, ggplot2, future, future.apply, progressr, missForest, utils, mice, miceRanger, multiUS, Amelia, mi, reshape2, DataVisualizations, abind, cowplot, twosamples, ggh4x, ggrepel, tools
LazyData:	true
Suggests:	testthat (≥ 3.0.0)
License:	GPL-3
URL:	https://github.com/JornLotsch/opImputation
Encoding:	UTF-8
Date:	2025-11-04
NeedsCompilation:	no
Packaged:	2025-11-04 12:22:21 UTC; joern
Author:	Jorn Lotsch [aut, cre], Alfred Ultsch [aut]
Maintainer:	Jorn Lotsch <j.lotsch@em.uni-frankfurt.de>
Repository:	CRAN
Date/Publication:	2025-11-07 13:50:02 UTC

Codeine metabolite concentrations in urine.

Description

Data set from a pharmacogenetic investigation that assessed the formation of morphine from codeine in the presence of variants in cytochrome P450 2D6.

Usage

data("CodeinLogMetabolitesUrine")

Details

Size 50 x 5 , stored in CodeinLogMetabolitesUrine["MOR", "M3G", "M6G", "COD", "C6G"]

Examples

data(CodeinLogMetabolitesUrine)
str(CodeinLogMetabolitesUrine)

Chromatography mass spectrometry of lipid mediators measured in blood samples.

Description

Data set from a lipidomic investigation that assessed lipid mediators in blood samples in patients.

Usage

data("LipidsPsychiatricPat")

Details

Size 94 x 8 , stored in LipidsPsychiatricPat["S1P", "C16Sphinganin", "C16Cer", "C20Cer", "C24Cer", "C24_1Cer", "C16GluCer", "C16LacCer"]

Examples

data(LipidsPsychiatricPat)
str(LipidsPsychiatricPat)

Psychophysical data from an investigation of pain thresholds.

Description

Data set from an investigation of pain thresholds to various stimuli in healthy volunteers.

Usage

data("PainThresholds")

Details

Size 125 x 8 , stored in PainThresholds["von.Frey", "von.Frey.Caps", "Heat", "Heat.Caps", "Cold", "Cold.Menth", "Pressure", "Electric"]

Examples

data(PainThresholds)
str(PainThresholds)

Psychophysical data from a clinical quantitative sensory testing study.

Description

Data set from a psychophysical investigation in a clinical quantitative sensory testing study in healthy subjects.

Usage

data("QSTpainEJPtransf")

Details

Size 72 x 19 , stored in QSTpainEJPtransf["PressureThr", "PressureTol", "TSACold", "ElectricThr", "ElectricTol", "Co2Thr", "CO2VAS", "LaserThr", "LaserVAS", "CDT", "WDT", "TSL", "CPT", "HPT", "PPT", "MPT", "MPS", "WUR", "MDT"]

Examples

data(QSTpainEJPtransf)
str(QSTpainEJPtransf)

Compare Imputation Methods for Missing Value Analysis

Description

Performs a comprehensive comparative analysis of different imputation methods on a dataset by artificially inserting missings, applying various imputation techniques, and evaluating their performance through multiple metrics and visualizations. Optionally produces a final imputed dataset using the best-performing method.

Usage

    compare_imputation_methods(
      data,
      imputation_methods = all_imputation_methods,
      imputation_repetitions = 20,
      perfect_methods_in_ABC = FALSE,
      n_iterations = 20,
      n_proc = getOption("mc.cores", 2L),
      percent_missing = 0.1,
      seed,
      mnar_shape = 1,
      mnar_ity = 0,
      low_only = FALSE,
      fixed_seed_for_inserted_missings = FALSE,
      max_attempts = 1000,
      overall_best_z_delta = FALSE,
      produce_final_imputations = TRUE,
      plot_results = TRUE,
      verbose = TRUE
    )

Arguments

Details

This function implements a model-agnostic framework for dataset-specific selection of missing value imputation methods. The analysis workflow:

1. Artificially inserts missing values into complete data

2. Applies multiple imputation methods

3. Calculates performance metrics (zDelta values)

4. Ranks methods using ABC analysis

5. Generates comprehensive visualizations

6. Optionally produces final imputed dataset using the best method

The zDelta metric represents standardized absolute differences between original and imputed values, providing a robust measure of imputation quality.

The MNAR mechanism allows testing methods under realistic scenarios:

• mnar_ity = 0: Missing Completely At Random (MCAR)

• mnar_ity > 0: Missing Not At Random with specified degree

• low_only = TRUE: Missings preferentially in lower values

• mnar_shape: Controls shape of missingness probability distribution

Final Imputation Process: When produce_final_imputations = TRUE, the function automatically:

1. Extracts the ranked list of methods from ABC analysis results

2. Filters to only univariate and multivariate methods (excludes poisoned/calibrating methods)

3. Tries each method in order of performance ranking

4. Stops at the first method that successfully produces a complete dataset with no missing values

5. Prints informative console output showing which method was used, its ABC category, score, and ranking

If all methods fail to produce a complete dataset, the function returns NULL for both imputed_data and method_used_for_imputation and prints a warning message.

Value

Returns a list containing:

Note

The function requires at least two non-calibrating imputation methods for comparison. Parallel processing can significantly improve performance on multi-core systems. Explicitly setting the seed parameter is strongly recommended for reproducibility.

When produce_final_imputations = TRUE, the function will display console output indicating which method was used for the final imputation, including its ABC category (A, B, or C), ABC score, and ranking among valid methods. This provides transparency and allows users to understand the quality of the chosen imputation method.

Author(s)

Jorn Lotsch, Alfred Ultsch

References

Lotsch J, Ultsch A. (2025). A model-agnostic framework for dataset-specific selection of missing value imputation methods in pain-related numerical data. Can J Pain (in minor revision)

See Also

impute_missings for single imputation operations

create_diagnostic_missings for creating diagnostic missing values

Examples

    # Load example data
    data_iris <- iris[,1:4]

    # Add some missings
    set.seed(42)
    for(i in 1:4) data_iris[sample(1:nrow(data_iris), 0.05*nrow(data_iris)), i] <- NA

    # Basic comparison with a subset of methods
    results <- compare_imputation_methods(
      data = data_iris,
      imputation_methods = c("mean", "median", "rSample"),
      n_iterations = 2,
      imputation_repetitions = 2,
      produce_final_imputations = FALSE,
      plot_results = FALSE,
      verbose = FALSE
    )

    # Print results
    # print(results)

    # Cleanup to avoid open sockets during R CMD check
    future::plan(future::sequential)

Create Diagnostic Missing Values in Data

Description

Introduces additional missing values into a dataset (which may already contain missings) using various missingness mechanisms: Missing Completely at Random (MCAR), Missing at Random (MAR), and Missing Not at Random (MNAR). Missing values are only inserted at positions that currently contain actual values (non-NA).

Usage

create_diagnostic_missings(
  x,
  Prob = 0.1,
  mnarity = 0,
  mnarshape = 1,
  lowOnly = FALSE,
  seed,
  maxAttempts = 1000
)

Arguments

Details

The function creates missing values using a combination of mechanisms:

• MCAR: Random missingness independent of data values (controlled by 1-mnarity)

• MAR/MNAR: Value-dependent missingness (controlled by mnarity)

The shape of the MNAR probability distribution is controlled by mnarshape. When lowOnly = TRUE, MNAR mechanism targets only low values; otherwise it targets extreme values (both high and low).

The function ensures that no row ends up with all values missing by excluding positions from the sampling pool that would create completely missing rows.

Value

A list with two elements:

Examples

# Create 10% MCAR missings
result <- create_diagnostic_missings(
  x = iris[,1:4],
  Prob = 0.1,
  mnarity = 0
)

# Create 20% missings with 50% MNAR targeting low values
result <- create_diagnostic_missings(
  x = iris[,1:4],
  Prob = 0.2,
  mnarity = 0.5,
  lowOnly = TRUE
)

Impute Missing Values Using Specified Method

Description

Fills in missing values (NA) in numeric data using a specified imputation method. Provides a unified interface to univariate, multivariate, ensemble, and diagnostic imputation approaches. The function automatically handles method-specific parameters and error recovery.

Usage

impute_missings(
  x,
  method = "rf_missForest",
  ImputationRepetitions = 10,
  seed = NULL,
  x_orig = NULL
)

Arguments

Details

This function provides access to multiple imputation algorithms through a single interface. Simply specify the desired method name via the method parameter.

Available Methods:

Univariate methods (replace each missing value independently):

• "median" - Column median

• "mean" - Column mean

• "mode" - Column mode (most frequent value)

• "rSample" - Random sample from observed values

Bagging methods (bootstrap aggregating with decision trees):

• "bag" - Single bagged tree imputation

• "bag_repeated" - Repeated bagging with median aggregation

Random forest methods (ensemble of decision trees):

• "rf_mice" - Random forest via mice package

• "rf_mice_repeated" - Repeated RF via mice

• "rf_missForest" - Random forest via missForest package (recommended)

• "rf_missForest_repeated" - Repeated RF via missForest

• "miceRanger" - Random forest via miceRanger package

• "miceRanger_repeated" - Repeated RF via miceRanger

Tree-based methods:

• "cart" - Classification and regression trees

• "cart_repeated" - Repeated CART with median aggregation

Regression methods:

• "linear" - Lasso regression (L1-regularized linear model)

• "pmm" - Predictive mean matching

• "pmm_repeated" - Repeated PMM with median aggregation

k-Nearest neighbors methods:

• "knn3", "knn5", "knn7", "knn9", "knn10" - k-NN with specified number of neighbors

Multiple imputation methods:

• "ameliaImp" - Single imputation via Amelia II

• "ameliaImp_repeated" - Multiple imputations via Amelia II

• "miImp" - Multiple imputation via mi package

Poisoned methods (require x_orig, for validation only):

• "plus" - Add systematic positive offset

• "plusminus" - Add alternating positive/negative offset

• "factor" - Multiply by constant factor

Calibrating methods (require x_orig, for benchmarking):

• "tinyNoise_0.000001" through "tinyNoise_1" - Add small random noise with specified magnitude (available magnitudes: 0.000001, 0.00001, 0.0001, 0.001, 0.01, 0.05, 0.1, 0.2, 0.5, 1)

Repeated methods: Methods ending with "_repeated" perform multiple independent imputations and return the median value across all repetitions. This typically provides more stable and robust results but requires more computation time. The number of repetitions is controlled by the ImputationRepetitions parameter.

Method selection guidance:

• For quick results: Use "median" or "mean"

• For moderate missing data: Use "rf_missForest" or "knn5"

• For high-quality results: Use "rf_missForest_repeated" or "pmm_repeated"

• For systematic comparison: Use compare_imputation_methods

Value

Returns a data frame with the same dimensions and column names as the input x, but with missing values filled in according to the specified method. If imputation fails, returns a data frame with all values set to NA.

Note

• Setting seed is strongly recommended for reproducibility

• Repeated methods provide better results but take longer to compute

• Poisoned and calibrating methods are for validation/benchmarking only

• If a method fails, the function returns NA values rather than throwing an error

• Some methods may be slow on large datasets

Author(s)

Jorn Lotsch, Alfred Ultsch

References

Lotsch J, Ultsch A. (2025). A model-agnostic framework for dataset-specific selection of missing value imputation methods in pain-related numerical data. Can J Pain (in minor revision)

See Also

compare_imputation_methods

Examples

# Load example data
data_iris <- iris[,1:4]

# Add some misisngs
set.seed(42)
for(i in 1:4) data_iris[sample(1:nrow(data_iris), 0.05*nrow(data_iris)), i] <- NA

# Simple univariate imputation with median
data_iris_imputed_median <- impute_missings(
  data_iris,
  method = "median"
)

# Show data
head(data_iris_imputed_median)