Reproducibility seed management

reproducibility-seed-management

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

Summary

Set a random seed before applying stochastic imputation algorithms (e.g., random forest) to ensure deterministic, reproducible results across multiple runs of the same analysis. This is essential for validating findings and enabling collaboration in computational metabolomics workflows.

When to use

Before invoking random forest imputation (impute_rf) or any other stochastic algorithm on a MetaboSet expression matrix. Seed-setting is mandatory when reproducibility is required—either for method validation, peer review, or when sharing analysis code with collaborators. The seed must be set after all deterministic preprocessing steps (marking NAs, flagging features, drift correction) but immediately before the first stochastic operation.

When NOT to use

• When analyzing real-time or streaming data where each run intentionally samples from a different random state.
• In exploratory data analysis where multiple imputation runs are intentionally used to assess imputation uncertainty or sensitivity.
• When the computational workflow is already deterministic (e.g., no stochastic algorithms are used).

Inputs

• MetaboSet object with expression matrix (exprs slot) containing marked NA values
• Integer seed value (arbitrary but documented)

Outputs

• MetaboSet object with reproducibly imputed expression matrix
• Documented seed value (in code comments or methods section)

How to apply

Call a seed-setting function (e.g., set.seed() in R) with a fixed integer value immediately before invoking impute_rf() on the MetaboSet object. The seed value should be arbitrary but documented (e.g., in the script header or methods section). After setting the seed, apply impute_rf() first on good-quality (non-flagged) features, then optionally again with all_features=TRUE to impute flagged features. The entire imputation pipeline will then produce identical numerical results on any system running the same R and dependency versions, making the workflow reproducible and auditable.

Related tools

• notame (Provides impute_rf() function and MetaboSet data structure for random forest imputation; seed management is applied within this workflow) — https://github.com/hanhineva-lab/notame
• missForest (Underlying random forest imputation engine called by notame's impute_rf(); requires seed control for reproducibility)
• R (Provides set.seed() function for controlling random number generator state)
• doParallel (Enables parallel random forest imputation; seed must be managed consistently across parallel workers)

Examples

set.seed(42); notame::impute_rf(metaboset_obj); notame::impute_rf(metaboset_obj, all_features=TRUE)

Evaluation signals

• Re-running the imputation pipeline with the same seed produces byte-for-byte identical imputed values in the exprs matrix.
• Changing only the seed value (holding all other parameters constant) produces different but deterministic imputed values on subsequent runs.
• The seed value is explicitly documented in the analysis script or supplementary methods, allowing independent reproduction by other researchers.
• Numerical results (downstream statistics, multivariate model coefficients) remain stable across multiple runs using the same seed, but diverge when using different seeds.
• Version information for R, missForest, doParallel, and notame is recorded alongside the seed to document the computational environment.

Limitations

• Seed management only guarantees reproducibility within the same major versions of R and dependent packages (missForest, doParallel, notame). Minor or patch updates may alter random number generation algorithms, breaking reproducibility across package versions.
• Parallel processing (via doParallel) requires additional care: setting a seed on the main thread does not automatically propagate to worker processes. Reproducibility across different numbers of parallel workers may require specialized seed distribution.
• Random forest imputation is stochastic in nature; a fixed seed produces consistent point estimates but does not quantify imputation uncertainty. Multiple imputation strategies (with different seeds or explicit Bayesian methods) are needed to assess the impact of missing data on inference.
• The notame package API is described as 'still quite experimental, and breaking changes are possible,' which may alter or remove seed-management interfaces between releases.

Evidence

• [other] Set a seed number for reproducibility.: "Set a seed number for reproducibility. 4. Apply impute_rf() on good-quality (non-flagged) features to predict missing values via random forest regression"
• [other] The implementation we use (from the missForest package) can be parallelized: "The implementation we use (from the missForest package) can be parallelized"
• [other] Load the libraries (doParallel is used for parallel processing): "Load the libraries (doParallel is used for parallel processing)"
• [other] The package API is still quite experimental, and breaking changes are possible: "The package API is still quite experimental, and breaking changes are possible"