# Missing Value Imputation Method Dispatch

> Use when you have a metabolomics data matrix with missing-not-at-random (MNAR) left-censored values and need to apply multiple imputation methods to the same data in a standardized way, compare their outputs, or integrate the imputation step into a larger pre-processing pipeline.

- Skill: `holobiomicslab/missing-value-imputation-method-dispatch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/missing-value-imputation-method-dispatch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/missing-value-imputation-method-dispatch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/missing-value-imputation-method-dispatch

---


# missing-value-imputation-method-dispatch

> **License: noncommercial** — confirm your use is a permitted (noncommercial) purpose before applying; commercial use requires a separate license (see `metadata.tool_license`). <!-- asb-license-banner -->
## Summary

Route a missing-value matrix to one of multiple left-censored imputation methods (GSimp, QRILC, kNN-TN) via a wrapper function that handles method selection, parameter passing, and output collection. This skill is essential when comparing or selecting the best imputation strategy for metabolomics data with left-censored missingness.

## When to use

You have a metabolomics data matrix with missing-not-at-random (MNAR) left-censored values and need to apply multiple imputation methods to the same data in a standardized way, compare their outputs, or integrate the imputation step into a larger pre-processing pipeline. The missing values must represent values below a detection limit (LOQ/LOD) rather than random missingness.

## When NOT to use

- Your data contains MCAR (missing completely at random) or MAR (missing at random) missingness rather than MNAR left-censored values — use non-truncated imputation methods (e.g., Amelia, missForest) with bounds set to (-∞, +∞) instead.
- Your data are already fully imputed or contain no missing values — the wrapper is designed only for datasets with NA entries that require imputation.
- You are comparing imputation methods and need traceability of Gibbs sampler convergence — you must configure the wrapper to set the `gibbs` parameter to record missing element trajectories across MCMC iterations.

## Inputs

- data matrix (data.frame or matrix) with missing values as NA
- method parameter (string: 'GSimp', 'QRILC', 'kNN-TN', or 'HM')
- optional: imputation-specific parameters (e.g., iters_each, iters_all, initial, lo, hi for GSimp)
- optional: initialization method or pre-imputed matrix (e.g., QRILC-imputed values for scaling reference)

## Outputs

- imputed data matrix (data.frame) with no NA values
- method identifier label for result tracking
- optional: Gibbs sampler trace arrays (gibbs_res) if tracing specified missing positions

## How to apply

Load the log-transformed, initialized, and scaled data matrix (or raw matrix if using a full wrapper) into the dispatch function along with a method identifier string ('GSimp', 'QRILC', or 'kNN-TN'). Parse the method argument to route execution to the appropriate handler function. For GSimp, configure bounds (lo=-Inf, hi='min' for left-censored data), iteration counts (e.g., iters_each=50, iters_all=10), and prediction model (e.g., 'glmnet_pred'). For QRILC and kNN-TN, apply log-transformation before routing and exponential transformation after imputation. Capture the imputed matrix output from the selected method and return it indexed by method name. The wrapper abstracts method-specific preprocessing requirements (scaling, transformation, initialization) so that downstream evaluation functions can consume standardized outputs.

## Related tools

- **Impute_wrapper.R** (Contains the wrapper functions that dispatch method selection and route matrices to GSimp, QRILC, kNN-TN handlers; includes pre_processing_GS_wrapper for one-step preprocessing and GSimp imputation) — https://github.com/WandeRum/GSimp
- **GSimp.R** (Provides the core GS_impute function implementing Gibbs sampler MNAR imputation with configurable bounds, iterations, and prediction models) — https://github.com/WandeRum/GSimp
- **GSimp_evaluation.R** (Contains MNAR generation and evaluation functions to assess performance metrics (RMSE, bias) across imputed matrices from all dispatched methods) — https://github.com/WandeRum/GSimp
- **imputeLCMD R package** (Provides impute.QRILC function used by the QRILC wrapper for quantile regression imputation of left-censored data)
- **Trunc_KNN** (Contains imputeKNN function and truncation-based kNN imputation algorithm used by the kNN-TN wrapper (Shah et al., 2017)) — https://github.com/WandeRum/GSimp

## Examples

```
source('Impute_wrapper.R'); source('GSimp.R'); after_GS_imp <- pre_processing_GS_wrapper(untargeted_data); after_QRILC_imp <- sim_QRILC_wrapper(log(untargeted_data)) %>% exp(); after_trKNN_imp <- sim_trKNN_wrapper(log(untargeted_data)) %>% exp()
```

## Evaluation signals

- Verify that the returned matrix has no NA values and the same dimensions as the input data.
- Confirm that the method label matches the requested method and is correctly indexed in the output (e.g., results_GSimp, results_QRILC).
- Check that log-transformation was applied before dispatch to QRILC and kNN-TN and that exponential transformation was applied to their outputs to recover original scale.
- For GSimp, validate that the imputed matrix respects the bounds (lo=-Inf, hi='min') by confirming that no imputed left-censored values exceed the minimum of the non-missing values in their respective variables.
- Compare imputed values against known true values (using simulated data) by computing RMSE or bias; dispatch success is signaled by method-comparable performance metrics reported by GSimp_evaluation.R functions.

## Limitations

- The wrapper assumes input data has been log-transformed for non-normal metabolomics distributions; if data violate normality assumptions post-transformation, imputation accuracy may degrade.
- QRILC and kNN-TN require pre-initialization (e.g., QRILC imputation or quantile-based fill) before scaling and Gibbs sampling; poor initialization may bias final results.
- GSimp convergence depends on iteration counts (iters_each, iters_all); the README notes that smaller iterations (iters_all=10, iters_each=50) will not severely affect accuracy but may under-converge for highly sparse datasets.
- kNN-TN uses fixed k=3 neighbors in the README example; this parameter is not exposed as a wrapper argument, limiting adaptability to datasets with varying sparsity or correlation structure.
- The wrapper does not handle missing values in covariates or sample metadata — only the main data matrix is imputed.

## Evidence

- [other] Impute_wrapper.R contains wrapper functions that dispatch missing-value matrices to different imputation methods, including GSimp, QRILC, and kNN-TN, with pre_processing_GS_wrapper available as part of the wrapper function suite.: "Impute_wrapper.R contains wrapper functions that dispatch missing-value matrices to different imputation methods, including GSimp, QRILC, and kNN-TN"
- [readme] The README describes wrapper functions for different imputation methods in the context of the GSimp approach.: "wrapper functions for different MNAR imputation methods (GSimp, QRILC, and kNN-TN)"
- [readme] The pre_processing_GS_wrapper function unifies preprocessing and method dispatch in one call.: "All aboved steps has been wrapped into the *pre_processing_GS_wrapper* function for a one-step processing and imputation."
- [readme] Specific bounds are configured for left-censored missing values where the upper bound is the minimum.: "lo=-Inf, hi='min' are default setting for left-censored missing values where the upper bound is set to the minimum value of non-missing part"
- [readme] The wrapper implementation shows method-specific preprocessing (log-transformation, QRILC initialization, scaling, then GSimp imputation).: "Log transformation # data_raw_log <- data_raw %>% log() # Initialization # data_raw_log_qrilc <- impute.QRILC(data_raw_log) %>% extract2(1) # Centralization and scaling"
- [readme] Comparison of three different imputation methods via wrappers is demonstrated in the README.: "We compared GSimp with other left-censored missing imputation/substitution methods: QRILC, kNN-TN, and HM"
- [readme] The iteration parameters control convergence of the Gibbs sampler within the wrapper.: "iters_each is the number of iterations for imputing each missing variable (default=100). iters_all is the number of iterations for imputing the whole data matrix (default=20)."