unit-test-design-for-analytical-chemistry
Summary
Design and implement pytest unit tests to validate mass spectrometry feature detection and annotation modules, ensuring correctness of adduct labeling, ion mass matching, and feature table outputs against reference datasets with quantified false-positive and false-negative rates.
When to use
When implementing or modifying metabolomics feature detection pipelines (e.g., adduct detection, m/z matching, feature labeling) where correctness directly impacts downstream analysis. Unit tests are essential when mass-matching logic, adduct offset calculations, or ion type recognition could introduce systematic errors in feature annotation.
When NOT to use
- Feature table is already manually curated and does not require algorithmic validation of adduct assignments.
- Adduct detection module has not yet been implemented or is still in exploratory prototyping phase without stable mass-matching logic.
- Input data lacks ground-truth or reference annotations needed to establish expected test outcomes.
Inputs
- Feature table (CSV or compatible format) with observed m/z values
- Reference adduct mass offsets (e.g., [M+NH4]+ = +17.0266 Da)
- Mass tolerance threshold (e.g., ppm window for m/z matching)
- Expected feature annotations or ground-truth adduct labels
Outputs
- Pytest test suite with passing/failing cases for each adduct type
- Unit test report quantifying accuracy, false positives, and false negatives
- Labeled feature table with validated adduct annotations
- Verification report listing assigned labels and their correctness
How to apply
Define reference feature sets with known adduct types and their theoretical m/z values. Construct pytest test cases that compare observed adduct labels against expected labels for each ion species (e.g., [M+NH4]+ at +17.0266 Da, [M+K]+ at +38.9815 Da). Implement mass-matching validation tests that verify correct assignment within a specified mass tolerance window (e.g., ppm threshold). Run pytest to execute all test cases and generate a report documenting assigned labels, their accuracy, and quantification of false positives. Use test output to validate that the detection module correctly identifies all adduct types without spurious assignments before deploying to production feature tables.
Related tools
Examples
pytest tests/test_adduct_detection.py -v --tb=short
Evaluation signals
- All adduct types ([M+NH4]+, [M+K]+, [M+H2O+H]+, [M-H2O+H]+) are correctly identified in test reference set with 100% recall on known features.
- False-positive rate on reference feature set is zero or below acceptable threshold (no spurious adduct assignments).
- Mass-matching validation confirms observed m/z values fall within the specified tolerance window of theoretical adduct masses.
- Test report quantifies accuracy as a percentage and explicitly lists features where adduct labels match expected ground-truth annotations.
- Pytest output shows no test failures and all assertions for mass offset calculations pass.
Limitations
- Unit tests can only validate behavior on reference datasets; performance on unseen, real-world feature tables may differ if data distribution or noise characteristics are not represented in test set.
- Adduct detection accuracy depends critically on mass tolerance parameter; tests must be re-run if tolerance is adjusted, and results may not generalize across different MS instruments or acquisition modes.
- False-negative detection (missed adducts due to weak signal or co-elution) is difficult to test without comprehensive ground-truth that itself requires independent validation.
Evidence
- [other] Run pytest unit tests to validate that the adduct detection correctly identifies each adduct type on a reference feature set and reports no false positives.: "Run pytest unit tests to validate that the adduct detection correctly identifies each adduct type on a reference feature set and reports no false positives."
- [other] Implement mass-matching logic to scan an input feature table and assign adduct labels by comparing observed m/z values against theoretical adduct masses within a specified mass tolerance window.: "Implement mass-matching logic to scan an input feature table and assign adduct labels by comparing observed m/z values against theoretical adduct masses within a specified mass tolerance window."
- [other] Define adduct mass offsets for [M+NH4]+ (+17.0266 Da), [M+K]+ (+38.9815 Da), [M+H2O+H]+ (+19.0184 Da), and [M-H2O+H]+ (+1.0078 Da) in the adduct detection module.: "Define adduct mass offsets for [M+NH4]+ (+17.0266 Da), [M+K]+ (+38.9815 Da), [M+H2O+H]+ (+19.0184 Da), and [M-H2O+H]+ (+1.0078 Da) in the adduct detection module."
- [other] Generate a labeled feature table with adduct annotations and produce a verification report listing assigned labels and their accuracy.: "Generate a labeled feature table with adduct annotations and produce a verification report listing assigned labels and their accuracy."
1---2name: unit-test-design-for-analytical-chemistry3description: Use when when implementing or modifying metabolomics feature detection pipelines (e.g., adduct detection, m/z matching, feature labeling) where correctness directly impacts downstream analysis.4license: CC-BY-4.05---67# unit-test-design-for-analytical-chemistry89## Summary1011Design and implement pytest unit tests to validate mass spectrometry feature detection and annotation modules, ensuring correctness of adduct labeling, ion mass matching, and feature table outputs against reference datasets with quantified false-positive and false-negative rates.1213## When to use1415When implementing or modifying metabolomics feature detection pipelines (e.g., adduct detection, m/z matching, feature labeling) where correctness directly impacts downstream analysis. Unit tests are essential when mass-matching logic, adduct offset calculations, or ion type recognition could introduce systematic errors in feature annotation.1617## When NOT to use1819- Feature table is already manually curated and does not require algorithmic validation of adduct assignments.20- Adduct detection module has not yet been implemented or is still in exploratory prototyping phase without stable mass-matching logic.21- Input data lacks ground-truth or reference annotations needed to establish expected test outcomes.2223## Inputs2425- Feature table (CSV or compatible format) with observed m/z values26- Reference adduct mass offsets (e.g., [M+NH4]+ = +17.0266 Da)27- Mass tolerance threshold (e.g., ppm window for m/z matching)28- Expected feature annotations or ground-truth adduct labels2930## Outputs3132- Pytest test suite with passing/failing cases for each adduct type33- Unit test report quantifying accuracy, false positives, and false negatives34- Labeled feature table with validated adduct annotations35- Verification report listing assigned labels and their correctness3637## How to apply3839Define reference feature sets with known adduct types and their theoretical m/z values. Construct pytest test cases that compare observed adduct labels against expected labels for each ion species (e.g., [M+NH4]+ at +17.0266 Da, [M+K]+ at +38.9815 Da). Implement mass-matching validation tests that verify correct assignment within a specified mass tolerance window (e.g., ppm threshold). Run pytest to execute all test cases and generate a report documenting assigned labels, their accuracy, and quantification of false positives. Use test output to validate that the detection module correctly identifies all adduct types without spurious assignments before deploying to production feature tables.4041## Related tools4243- **pytest** (Execute unit tests to validate adduct detection, mass-matching logic, and feature labeling correctness; report test results and accuracy metrics) — https://github.com/fermo-metabolomics/FERMO44- **fermo_core** (Provides the adduct detection and mass-matching implementation being validated by unit tests) — https://github.com/fermo-metabolomics/fermo_core4546## Examples4748```49pytest tests/test_adduct_detection.py -v --tb=short50```5152## Evaluation signals5354- All adduct types ([M+NH4]+, [M+K]+, [M+H2O+H]+, [M-H2O+H]+) are correctly identified in test reference set with 100% recall on known features.55- False-positive rate on reference feature set is zero or below acceptable threshold (no spurious adduct assignments).56- Mass-matching validation confirms observed m/z values fall within the specified tolerance window of theoretical adduct masses.57- Test report quantifies accuracy as a percentage and explicitly lists features where adduct labels match expected ground-truth annotations.58- Pytest output shows no test failures and all assertions for mass offset calculations pass.5960## Limitations6162- Unit tests can only validate behavior on reference datasets; performance on unseen, real-world feature tables may differ if data distribution or noise characteristics are not represented in test set.63- Adduct detection accuracy depends critically on mass tolerance parameter; tests must be re-run if tolerance is adjusted, and results may not generalize across different MS instruments or acquisition modes.64- False-negative detection (missed adducts due to weak signal or co-elution) is difficult to test without comprehensive ground-truth that itself requires independent validation.6566## Evidence6768- [other] Run pytest unit tests to validate that the adduct detection correctly identifies each adduct type on a reference feature set and reports no false positives.: "Run pytest unit tests to validate that the adduct detection correctly identifies each adduct type on a reference feature set and reports no false positives."69- [other] Implement mass-matching logic to scan an input feature table and assign adduct labels by comparing observed m/z values against theoretical adduct masses within a specified mass tolerance window.: "Implement mass-matching logic to scan an input feature table and assign adduct labels by comparing observed m/z values against theoretical adduct masses within a specified mass tolerance window."70- [other] Define adduct mass offsets for [M+NH4]+ (+17.0266 Da), [M+K]+ (+38.9815 Da), [M+H2O+H]+ (+19.0184 Da), and [M-H2O+H]+ (+1.0078 Da) in the adduct detection module.: "Define adduct mass offsets for [M+NH4]+ (+17.0266 Da), [M+K]+ (+38.9815 Da), [M+H2O+H]+ (+19.0184 Da), and [M-H2O+H]+ (+1.0078 Da) in the adduct detection module."71- [other] Generate a labeled feature table with adduct annotations and produce a verification report listing assigned labels and their accuracy.: "Generate a labeled feature table with adduct annotations and produce a verification report listing assigned labels and their accuracy."
