separation-metric-normalization
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Converts a series of retention times from LC-MS data into a normalized quantitative separation efficiency score (0–1) that encodes compound-separation performance at omics scale. This skill enables standardized comparison of gradient performance across different experiments and chemical spaces.
When to use
Apply this skill when you have extracted retention times from top MS1 features across an LC-MS run and need a single, comparable metric to evaluate how effectively a gradient spreads compounds across the chromatographic window. Use it to benchmark gradient performance before, during, or after Bayesian optimization of LC-MS methods, or to compare gradient performance across multiple runs or conditions.
When NOT to use
- Input retention time sequence is empty or contains fewer than 2 features — the metric cannot meaningfully encode separation.
- Gradient time range (rtRange) is zero or negative — the function requires a positive window to normalize against.
- Raw MS data has not yet been processed to extract MS1 features; pass processed ms1Spectrum objects or retention time arrays, not raw mzML/netCDF files.
Inputs
- rtSeq: ordered sequence of retention times (float array, in minutes) from top MS1 features
- rtRange: tuple or list of (gradient_start, gradient_end) in minutes
- ms1Spectrum objects or extracted m/z and intensity pairs from LC-MS data
Outputs
- separation_efficiency: float scalar in [0, 1] representing normalized separation performance
- validation_status: boolean or string indicating whether output is valid and realistic
How to apply
Extract a series of retention times (rtSeq) from the top detected MS1 features and record the gradient time range (rtRange, in minutes) defining when the gradient begins and ends. Pass both rtSeq and rtRange to the sepEfficiency function, which calculates the distribution and spacing of retention times across the usable gradient window. The function returns a normalized float value between 0 (no separation) and 1 (complete separation). Validate that the output falls within [0, 1] and reflects realistic separation performance for the input feature set by spot-checking against visual inspection of the base peak chromatogram and the number of resolved features.
Related tools
- bago (Python package providing sepEfficiency function to compute normalized separation efficiency from retention times) — https://github.com/huaxuyu/bago
- pyopenms (Read raw LC-MS data and extract MS1 scans for retention time extraction)
- scikit-learn (Optional preprocessing (e.g., StandardScaler) for retention time normalization before sepEfficiency calculation)
Examples
from bago import sepEfficiency; rt_seq = [2.3, 5.1, 8.7, 12.4, 15.9]; rt_range = (1.0, 20.0); sep_eff = sepEfficiency(rt_seq, rt_range); print(f'Separation efficiency: {sep_eff:.3f}')
Evaluation signals
- Output value is a float strictly within [0.0, 1.0]; values outside this range indicate a function error.
- For a known well-separated gradient (e.g., many features evenly distributed across rtRange), sepEfficiency should be > 0.6; for co-eluting compounds, < 0.3.
- Retention times in rtSeq are monotonically increasing and all fall within rtRange boundaries.
- Recomputing sepEfficiency on the same rtSeq and rtRange produces identical output (deterministic).
- Separation efficiency increases when rtSeq becomes more evenly distributed across rtRange (e.g., adding separated features increases the metric).
Limitations
- The metric assumes that higher spacing of retention times across the gradient window reflects better separation; it does not measure mass spectral quality, identity confidence, or quantification accuracy.
- Omics-scale evaluation depends on complete and unbiased detection of MS1 features; missing features or instrument dropout will underestimate true separation efficiency.
- The normalized [0, 1] scale is relative to the input rtRange; changing the gradient time window will change the same compound set's efficiency score, making cross-experiment comparisons valid only if rtRange is held constant.
- No changelog provided; exact implementation details of the sepEfficiency encoding function are not documented in the article.
Evidence
- [methods] sepEfficiency function definition and inputs: "The sepEfficiency function calculates separation efficiency using a series of retention times extracted from LC-MS data, producing a singular metric that encodes compound-separation performance for"
- [other] Workflow steps for applying sepEfficiency: "Extract or receive a series of retention times (rtSeq) from the top detected MS1 features and the gradient time range (rtRange, in minutes) defining when the gradient begins and ends. Compute"
- [other] Output normalization and validation: "Return a normalized float value between 0 (no separation) and 1 (complete separation) that quantifies how effectively the gradient spreads compounds across the chromatographic window. Validate the"
- [readme] Omics-scale separation evaluation: "Separation efficiency was defined to evaluate the performance of a gradient."
- [readme] Purpose of separation encoding in BAGO: "Wonder how omics-scale evaluation is achieved? Read more about [encodings]."
1---2name: separation-metric-normalization-23description: Use when you have extracted retention times from top MS1 features across an LC-MS run and need a single, comparable metric to evaluate how effectively a gradient spreads compounds across the chromatographic window.4license: CC-BY-4.05---67# separation-metric-normalization89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Converts a series of retention times from LC-MS data into a normalized quantitative separation efficiency score (0–1) that encodes compound-separation performance at omics scale. This skill enables standardized comparison of gradient performance across different experiments and chemical spaces.1314## When to use1516Apply this skill when you have extracted retention times from top MS1 features across an LC-MS run and need a single, comparable metric to evaluate how effectively a gradient spreads compounds across the chromatographic window. Use it to benchmark gradient performance before, during, or after Bayesian optimization of LC-MS methods, or to compare gradient performance across multiple runs or conditions.1718## When NOT to use1920- Input retention time sequence is empty or contains fewer than 2 features — the metric cannot meaningfully encode separation.21- Gradient time range (rtRange) is zero or negative — the function requires a positive window to normalize against.22- Raw MS data has not yet been processed to extract MS1 features; pass processed ms1Spectrum objects or retention time arrays, not raw mzML/netCDF files.2324## Inputs2526- rtSeq: ordered sequence of retention times (float array, in minutes) from top MS1 features27- rtRange: tuple or list of (gradient_start, gradient_end) in minutes28- ms1Spectrum objects or extracted m/z and intensity pairs from LC-MS data2930## Outputs3132- separation_efficiency: float scalar in [0, 1] representing normalized separation performance33- validation_status: boolean or string indicating whether output is valid and realistic3435## How to apply3637Extract a series of retention times (rtSeq) from the top detected MS1 features and record the gradient time range (rtRange, in minutes) defining when the gradient begins and ends. Pass both rtSeq and rtRange to the sepEfficiency function, which calculates the distribution and spacing of retention times across the usable gradient window. The function returns a normalized float value between 0 (no separation) and 1 (complete separation). Validate that the output falls within [0, 1] and reflects realistic separation performance for the input feature set by spot-checking against visual inspection of the base peak chromatogram and the number of resolved features.3839## Related tools4041- **bago** (Python package providing sepEfficiency function to compute normalized separation efficiency from retention times) — https://github.com/huaxuyu/bago42- **pyopenms** (Read raw LC-MS data and extract MS1 scans for retention time extraction)43- **scikit-learn** (Optional preprocessing (e.g., StandardScaler) for retention time normalization before sepEfficiency calculation)4445## Examples4647```48from bago import sepEfficiency; rt_seq = [2.3, 5.1, 8.7, 12.4, 15.9]; rt_range = (1.0, 20.0); sep_eff = sepEfficiency(rt_seq, rt_range); print(f'Separation efficiency: {sep_eff:.3f}')49```5051## Evaluation signals5253- Output value is a float strictly within [0.0, 1.0]; values outside this range indicate a function error.54- For a known well-separated gradient (e.g., many features evenly distributed across rtRange), sepEfficiency should be > 0.6; for co-eluting compounds, < 0.3.55- Retention times in rtSeq are monotonically increasing and all fall within rtRange boundaries.56- Recomputing sepEfficiency on the same rtSeq and rtRange produces identical output (deterministic).57- Separation efficiency increases when rtSeq becomes more evenly distributed across rtRange (e.g., adding separated features increases the metric).5859## Limitations6061- The metric assumes that higher spacing of retention times across the gradient window reflects better separation; it does not measure mass spectral quality, identity confidence, or quantification accuracy.62- Omics-scale evaluation depends on complete and unbiased detection of MS1 features; missing features or instrument dropout will underestimate true separation efficiency.63- The normalized [0, 1] scale is relative to the input rtRange; changing the gradient time window will change the same compound set's efficiency score, making cross-experiment comparisons valid only if rtRange is held constant.64- No changelog provided; exact implementation details of the sepEfficiency encoding function are not documented in the article.6566## Evidence6768- [methods] sepEfficiency function definition and inputs: "The sepEfficiency function calculates separation efficiency using a series of retention times extracted from LC-MS data, producing a singular metric that encodes compound-separation performance for"69- [other] Workflow steps for applying sepEfficiency: "Extract or receive a series of retention times (rtSeq) from the top detected MS1 features and the gradient time range (rtRange, in minutes) defining when the gradient begins and ends. Compute"70- [other] Output normalization and validation: "Return a normalized float value between 0 (no separation) and 1 (complete separation) that quantifies how effectively the gradient spreads compounds across the chromatographic window. Validate the"71- [readme] Omics-scale separation evaluation: "Separation efficiency was defined to evaluate the performance of a gradient."72- [readme] Purpose of separation encoding in BAGO: "Wonder how omics-scale evaluation is achieved? Read more about [encodings]."
HolobiomicsLab