Feature pair alignment parameter optimization

feature-pair-alignment-parameter-optimization

Summary

Systematically optimize the three-component weighted scoring function (retention time weight A, m/z weight B, similarity weight C) used to rank feature pair alignments in untargeted LC-MS metabolomics by grid search and validation against known shared metabolite identities. This skill is essential when combining disparately-acquired datasets where alignment quality directly determines downstream statistical power and metabolite identification accuracy.

When to use

After anchor selection and retention-time spline mapping have produced a candidate list of feature pair alignments, but before final scoring and reduction of the combined table. Use this skill when you have access to ground-truth metabolite identities (shared known compounds) across both datasets that can serve as a validation benchmark, and when the default or previously-used parameter ranges produce suboptimal precision or recall in matching known metabolites.

When NOT to use

• Input datasets lack ground-truth metabolite identities or shared known compound annotations — optimization cannot be validated without a benchmark.
• Feature pair candidates have not yet undergone anchor selection and RT spline mapping — evaluateParams() requires pre-aligned candidates as input.
• Datasets are already merged or the combined table has been reduced — parameter optimization must occur before final reduction step.

Inputs

• fitted metabCombiner object with pre-aligned feature pair candidates
• retention-time spline mapping from prior Anchor Selection and RT Mapping step
• ground-truth metabolite identities (shared known compounds) from both plasma datasets

Outputs

• scores table indexed by parameter triplet (A, B, C)
• accuracy or F1-score metrics for each parameter combination
• optimal parameter ranges (A, B, C intervals)
• contiguous high-scoring parameter regions

How to apply

Construct a three-dimensional parameter grid: A (retention-time weight) = seq(50, 120, 10), B (m/z weight) = 5:15, and C (similarity score weight) = seq(0, 1, 0.1). For each triplet (A, B, C), invoke evaluateParams() on the pre-aligned metabCombiner object to recompute pairwise similarity scores using the weighted metric combining retention time, m/z, and cosine similarity components. Evaluate each parameter set by counting correctly matched feature pairs against ground-truth shared known compound identities from the plasma reference datasets, recording accuracy or F1-score for each triplet. Generate a scores table indexed by parameter triplet and identify contiguous high-scoring regions. Extract optimal ranges by locating parameter combinations that maximize both count and precision of correctly matched pairs; the article demonstrates that A ∈ [50, 70], B ∈ [14, 15], C ∈ [0.3, 0.4] produce superior performance on human plasma metabolomics datasets.

Related tools

• metabCombiner (R package providing evaluateParams() function to compute pairwise similarity scores over parameter grid and validate against known metabolite identities) — github.com/hhabra/metabCombiner
• R (host language for metabCombiner and grid construction (seq, : operators, data frame indexing))
• mgcv (underlying dependency for retention-time spline mapping (gam function) that feeds into parameter optimization)

Examples

grid_params <- expand.grid(A = seq(50, 120, 10), B = 5:15, C = seq(0, 1, 0.1)); scores <- evaluateParams(metabCombiner_object, A = grid_params$A, B = grid_params$B, C = grid_params$C, ground_truth = shared_metabolites)

Evaluation signals

• Scores table contains entries for all parameter triplets in the grid with no missing combinations; each row corresponds to unique (A, B, C) tuple.
• Optimal parameter ranges form contiguous regions in 3D space (not scattered isolated points); identified ranges match known shared identity precision and recall.
• F1-score or accuracy metrics for optimal parameter set (e.g., A ∈ [50, 70], B ∈ [14, 15], C ∈ [0.3, 0.4]) exceed baseline or default-parameter performance by measurable margin.
• Correctly matched feature pairs (true positives against ground truth) are concentrated within the identified optimal ranges and sparse outside them.
• Parameter sensitivity analysis shows smooth gradient in performance across grid, not discontinuous jumps (indicating robust optimization rather than overfitting to noise).

Limitations

• Optimization is specific to the reference datasets and their known metabolite annotations; optimal ranges may not transfer directly to datasets with different acquisition conditions, ionization modes, or metabolite coverage.
• Grid search is exhaustive and computationally expensive for fine-grained resolution; coarser grid spacing (e.g., A = seq(50, 120, 20)) may miss local optima but reduces runtime.
• Results depend critically on the completeness and accuracy of ground-truth metabolite identities; biased or incomplete reference annotations will bias parameter selection.
• No changelog or version history found in the repository, limiting assessment of parameter stability across metabCombiner releases.

Evidence

• [full_text] parameter_grid_definition: "Define a three-dimensional parameter grid with A = seq(50, 120, 10), B = 5:15, and C = seq(0, 1, 0.1) representing RT weight, m/z weight, and similarity score weight respectively."
• [full_text] evaluateParams_call: "Call evaluateParams() over the complete grid, computing pairwise similarity scores for each parameter combination using the weighted metric combining retention time, m/z, and cosine similarity"
• [full_text] validation_against_known_compounds: "Evaluate each parameter set against known shared metabolite identities (ground truth) from the plasma reference datasets, recording the count and precision of correctly matched feature pairs."
• [full_text] optimal_ranges_identified: "Smaller A values (50-70), higher B values (14-15), and average C values (0.3-0.4) are the best scores based on the shared known identities contained in the pair of plasma datasets."
• [intro] metabcombiner_alignment_workflow: "metabCombiner determines a list possible feature pair alignments (FPAs) and determines their validity through a pairwise similarity score."