pairwise-similarity-scoring-weighted-metrics
Summary
Compute composite similarity scores for feature pair alignments in LC-MS metabolomics by combining weighted retention time, m/z, and cosine similarity components. This skill enables systematic parameter optimization to identify optimal weight ranges that maximize alignment accuracy against known compound identities.
When to use
After anchor selection and RT mapping spline fitting, when you have a fitted metabCombiner object with pre-aligned feature pair candidates and need to determine which parameter weights (A for RT, B for m/z, C for similarity score) best discriminate true metabolite matches from false positives in your LC-MS dataset pair. Use this when you have ground truth shared compound identities available to validate parameter choices.
When NOT to use
- When no ground truth / known shared compound identities are available to validate parameter choices against
- When your fitted metabCombiner object has not yet completed the Anchor Selection and RT Mapping Spline step
- When datasets have already been combined and reduced; this skill operates on pre-alignment candidate objects
Inputs
- fitted metabCombiner object with pre-aligned feature pair candidates
- retention-time spline mapping from prior anchor selection step
- ground truth table of shared known compound identities across dataset pair
- parameter grid specification (A, B, C ranges and step sizes)
Outputs
- scores table indexed by parameter triplet (A, B, C) with accuracy/F1-score metrics
- optimal parameter ranges (e.g., A ∈ [50, 70], B ∈ [14, 15], C ∈ [0.3, 0.4])
- count and precision of correctly matched feature pairs per parameter set
How to apply
Define a three-dimensional parameter grid spanning the full weight space: A ∈ [50, 120] in steps of 10 (RT weight), B ∈ [5, 15] (m/z weight), and C ∈ [0, 1] in steps of 0.1 (cosine similarity weight). Call evaluateParams() over the complete grid, computing pairwise similarity scores for each triplet using the weighted metric that combines retention time deviation, m/z distance, and cosine similarity components. For each parameter set, compare predicted feature pair alignments against known shared metabolite identities (ground truth from your reference datasets) and record accuracy or F1-score metrics. Generate a scores table indexed by parameter triplets and identify contiguous high-scoring regions to extract optimal ranges. For plasma metabolomics datasets, empirical evidence suggests smaller A values (50–70), higher B values (14–15), and average C values (0.3–0.4) yield best performance.
Related tools
- metabCombiner (R package that provides the evaluateParams() function to compute similarity scores over a parameter grid and the data structures (fitted object, feature pair candidates) required for scoring) — https://github.com/hhabra/metabCombiner
- R (Programming language environment in which metabCombiner runs and parameter grid iteration/evaluation is implemented)
- mgcv (Underlying R package used for spline-based retention time mapping, which provides the RT component of the weighted similarity metric)
Examples
evaluateParams(metabCombinerObj, A = seq(50, 120, 10), B = 5:15, C = seq(0, 1, 0.1), groundTruth = knownCompounds) |> filter(F1_score > 0.8) |> group_by(A, B, C)
Evaluation signals
- Scores table is non-empty, indexed by all (A, B, C) triplets in the defined grid, and contains numeric accuracy/F1-score values
- Optimal parameter ranges form contiguous regions in the grid (not scattered singleton values) and show monotonic or smooth score gradients across parameter space
- Precision of correctly matched feature pairs at optimal parameters exceeds baseline or random assignment; F1-score or accuracy is substantially higher in the extracted optimal region than at grid boundaries
- Parameter set optimizing shared known identities also maximizes count of true positive matches and minimizes false positive rate when compared against ground truth
- Extracted optimal ranges (e.g., A ∈ [50, 70]) are narrower and more specific than the initial search grid, indicating genuine convergence rather than grid-wide plateau
Limitations
- Performance of optimal parameters is tightly coupled to the reference datasets and their shared compound identity annotations; parameters optimized on one pair of LC-MS datasets may not transfer directly to other conditions (e.g., different ionization, MS/MS resolution, or sample matrix)
- evaluateParams() requires ground truth labels of known shared metabolite identities; results are only as reliable as the completeness and accuracy of the reference compound list
- High-dimensional grid search (3D parameter space) is computationally expensive; runtime scales with grid resolution and number of feature pair candidates in the fitted object
- Optimal parameter ranges may exhibit local plateaus or multiple local optima; contiguous high-scoring regions should be validated visually or with independent test data before adoption
Evidence
- [other] 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.: "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."
- [other] 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 components.: "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"
- [other] 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.: "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."
- [other] 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.: "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 determines a list possible feature pair alignments (FPAs) and determines their validity through a pairwise similarity score.: "metabCombiner determines a list possible feature pair alignments (FPAs) and determines their validity through a pairwise similarity score."
1---2name: pairwise-similarity-scoring-weighted-metrics3description: Use when after anchor selection and RT mapping spline fitting, when you have a fitted metabCombiner object with pre-aligned feature pair candidates and need to determine which parameter weights (A for RT, B for m/z, C for similarity score) discriminate true metabolite matches from false positives.4license: CC-BY-4.05---67# pairwise-similarity-scoring-weighted-metrics89## Summary1011Compute composite similarity scores for feature pair alignments in LC-MS metabolomics by combining weighted retention time, m/z, and cosine similarity components. This skill enables systematic parameter optimization to identify optimal weight ranges that maximize alignment accuracy against known compound identities.1213## When to use1415After anchor selection and RT mapping spline fitting, when you have a fitted metabCombiner object with pre-aligned feature pair candidates and need to determine which parameter weights (A for RT, B for m/z, C for similarity score) best discriminate true metabolite matches from false positives in your LC-MS dataset pair. Use this when you have ground truth shared compound identities available to validate parameter choices.1617## When NOT to use1819- When no ground truth / known shared compound identities are available to validate parameter choices against20- When your fitted metabCombiner object has not yet completed the Anchor Selection and RT Mapping Spline step21- When datasets have already been combined and reduced; this skill operates on pre-alignment candidate objects2223## Inputs2425- fitted metabCombiner object with pre-aligned feature pair candidates26- retention-time spline mapping from prior anchor selection step27- ground truth table of shared known compound identities across dataset pair28- parameter grid specification (A, B, C ranges and step sizes)2930## Outputs3132- scores table indexed by parameter triplet (A, B, C) with accuracy/F1-score metrics33- optimal parameter ranges (e.g., A ∈ [50, 70], B ∈ [14, 15], C ∈ [0.3, 0.4])34- count and precision of correctly matched feature pairs per parameter set3536## How to apply3738Define a three-dimensional parameter grid spanning the full weight space: A ∈ [50, 120] in steps of 10 (RT weight), B ∈ [5, 15] (m/z weight), and C ∈ [0, 1] in steps of 0.1 (cosine similarity weight). Call evaluateParams() over the complete grid, computing pairwise similarity scores for each triplet using the weighted metric that combines retention time deviation, m/z distance, and cosine similarity components. For each parameter set, compare predicted feature pair alignments against known shared metabolite identities (ground truth from your reference datasets) and record accuracy or F1-score metrics. Generate a scores table indexed by parameter triplets and identify contiguous high-scoring regions to extract optimal ranges. For plasma metabolomics datasets, empirical evidence suggests smaller A values (50–70), higher B values (14–15), and average C values (0.3–0.4) yield best performance.3940## Related tools4142- **metabCombiner** (R package that provides the evaluateParams() function to compute similarity scores over a parameter grid and the data structures (fitted object, feature pair candidates) required for scoring) — https://github.com/hhabra/metabCombiner43- **R** (Programming language environment in which metabCombiner runs and parameter grid iteration/evaluation is implemented)44- **mgcv** (Underlying R package used for spline-based retention time mapping, which provides the RT component of the weighted similarity metric)4546## Examples4748```49evaluateParams(metabCombinerObj, A = seq(50, 120, 10), B = 5:15, C = seq(0, 1, 0.1), groundTruth = knownCompounds) |> filter(F1_score > 0.8) |> group_by(A, B, C)50```5152## Evaluation signals5354- Scores table is non-empty, indexed by all (A, B, C) triplets in the defined grid, and contains numeric accuracy/F1-score values55- Optimal parameter ranges form contiguous regions in the grid (not scattered singleton values) and show monotonic or smooth score gradients across parameter space56- Precision of correctly matched feature pairs at optimal parameters exceeds baseline or random assignment; F1-score or accuracy is substantially higher in the extracted optimal region than at grid boundaries57- Parameter set optimizing shared known identities also maximizes count of true positive matches and minimizes false positive rate when compared against ground truth58- Extracted optimal ranges (e.g., A ∈ [50, 70]) are narrower and more specific than the initial search grid, indicating genuine convergence rather than grid-wide plateau5960## Limitations6162- Performance of optimal parameters is tightly coupled to the reference datasets and their shared compound identity annotations; parameters optimized on one pair of LC-MS datasets may not transfer directly to other conditions (e.g., different ionization, MS/MS resolution, or sample matrix)63- evaluateParams() requires ground truth labels of known shared metabolite identities; results are only as reliable as the completeness and accuracy of the reference compound list64- High-dimensional grid search (3D parameter space) is computationally expensive; runtime scales with grid resolution and number of feature pair candidates in the fitted object65- Optimal parameter ranges may exhibit local plateaus or multiple local optima; contiguous high-scoring regions should be validated visually or with independent test data before adoption6667## Evidence6869- [other] 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.: "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."70- [other] 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 components.: "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"71- [other] 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.: "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."72- [other] 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.: "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."73- [intro] `metabCombiner` determines a list possible feature pair alignments (FPAs) and determines their validity through a pairwise similarity score.: "`metabCombiner` determines a list possible feature pair alignments (FPAs) and determines their validity through a pairwise similarity score."
