Chromatographic coelution detection

chromatographic-coelution-detection

Summary

Detect and group coeluting features (isotopes and adducts) within configurable m/z and retention time windows to construct empirical compound clusters. This skill identifies metabolite-related ion signals that share the same chromatographic peak, enabling pre-annotation of putative metabolites before MS2 matching.

When to use

Apply this skill after feature detection when you have a feature table with m/z, retention time, and intensity columns, and you need to group features into empirical compounds (putative metabolites) that account for isotopologue patterns and multiple adduct forms arising from a single underlying analyte.

When NOT to use

• Input is already a validated set of empirical compounds or annotated metabolites; skip to MS1/MS2 annotation workflows.
• m/z tolerance or rt tolerance values are unknown and cannot be estimated from your instrument's calibration or literature; consult your analytical method first.
• Feature table is in a non-standard format (not TSV) or lacks retention time information; convert or enrich the table before grouping.

Inputs

• Feature table (TSV format with m/z, retention time, and intensity columns)
• Ionization mode specification (positive or negative)
• Adduct definitions for the detected polarity

Outputs

• empCpd.json file containing empirical compound groups
• JSON structure with fields: list_of_features, median_mz, median_rt, pre-annotation

How to apply

Load the feature table (TSV format) from asari_results and invoke khipu's build_empCpds command, specifying ionization mode and configurable m/z tolerance (default 5 ppm) and retention time tolerance (default 2 seconds). The algorithm clusters features by matching isotope mass differences and charge-state patterns within these windows, then serializes grouped features to JSON with median m/z, median rt, list_of_features, and pre-annotation fields. Validate the output JSON structure to confirm all required fields are present and that feature groupings are chemically plausible (e.g., isotope spacing matches expected Δm/z for 13C, 2H, etc.).

Related tools

• khipu (Constructs empirical compound groups from feature tables using configurable m/z and retention time tolerances; performs clustering of isotopes and adducts based on mass difference patterns) — https://github.com/shuzhao-li-lab/khipu
• Asari (Produces the feature table (TSV format) that serves as input to the coelution detection workflow) — https://github.com/shuzhao-li/asari
• Python (Execution environment and scripting for invoking khipu commands and validating JSON output)

Examples

khipu build_empCpds preferred_Feature_table.tsv --mz_tolerance 5 --rt_tolerance 2 --ionization_mode positive --adduct_definitions default

Evaluation signals

• JSON output file is valid and parseable with all required fields (list_of_features, median_mz, median_rt, pre-annotation) present for each empirical compound group.
• Grouped features within each empirical compound satisfy the specified m/z tolerance (default 5 ppm) and retention time tolerance (default 2 seconds) constraints.
• Observed mass differences between grouped features match expected isotope shifts (e.g., 1.003 Da for 13C–12C, 0.5 Da for doubly charged ions) or known adduct mass differences (e.g., 0.495 Da for [M+Na]+ vs [M+H]+).
• No singleton features are incorrectly merged across distinct empirical compounds; verify that feature groups are chemically coherent.
• Median m/z and median rt values calculated from list_of_features align with the consensus values in the JSON output.

Limitations

• Default tolerances (5 ppm m/z, 2 seconds rt) may require tuning for instruments with different mass accuracy or chromatographic resolution; users with high-resolution or narrow-window chromatography should validate empirically.
• Coelution detection assumes that isotope and adduct patterns follow standard ionization chemistry; unusual or atypical ion formations (e.g., dimers, in-source fragmentation) may produce false groupings or negatives.
• Retention time tolerance is absolute (in seconds) rather than relative, which may cause under-grouping in long gradient methods where retention time drift is significant.
• Pre-annotation assigns labels based on mass difference heuristics but does not validate against reference standards or MS2 spectra; chemical plausibility should be confirmed downstream.

Evidence

• [other] The build_empCpds command groups features into empirical compounds by matching isotopes and adducts with configurable mz tolerance (default 5 ppm) and rt tolerance (default 2 seconds), producing a JSON file containing grouped features with their mz and rt values.: "grouping features into empirical compounds by matching isotopes and adducts with configurable mz tolerance (default 5 ppm) and retention time tolerance (default 2 seconds)"
• [other] Invoke khipu via the build_empCpds command with configurable m/z tolerance (default 5 ppm) and retention time tolerance (default 2 seconds), specifying ionization mode and adduct definitions for the detected polarity.: "Invoke khipu via the build_empCpds command with configurable m/z tolerance (default 5 ppm) and retention time tolerance (default 2 seconds), specifying ionization mode and adduct definitions"
• [other] Serialize the empirical compound collection to JSON format, including list_of_features, median m/z, median rt, and pre-annotation fields for each group.: "Serialize the empirical compound collection to JSON format, including list_of_features, median m/z, median rt, and pre-annotation fields"
• [intro] pre-annotation to group featues to empirical compounds (khipu): "pre-annotation to group featues to empirical compounds (khipu)"
• [other] Load the preferred feature table (TSV format) from the asari_results subdirectory.: "Load the preferred feature table (TSV format) from the asari_results subdirectory"