# Composite Mass Track Assembly And Peak Detection

> Use when after mass tracks have been aligned across all samples into a MassGrid (via sample-wise or centroid-based alignment), you have a unified set of m/z features tracked across the entire study.

- Skill: `holobiomicslab/composite-mass-track-assembly-and-peak-detection` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/composite-mass-track-assembly-and-peak-detection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/composite-mass-track-assembly-and-peak-detection/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/composite-mass-track-assembly-and-peak-detection

---


# composite-mass-track-assembly-and-peak-detection

## Summary

Assemble aligned mass tracks from multiple LC-MS samples into a composite mass track, then detect elution peaks on this composite map using statistics-guided local maxima detection. This approach prioritizes mass resolution and selectivity, avoiding repeated peak detection on individual samples and improving reproducibility across the cohort.

## When to use

After mass tracks have been aligned across all samples into a MassGrid (via sample-wise or centroid-based alignment), you have a unified set of m/z features tracked across the entire study. Use this skill when you need to identify reproducible, high-confidence peaks across the cohort by detecting peaks on the aggregate signal rather than individually per sample, especially for studies with ≤10 samples using anchor-first alignment or larger studies using centroid-based alignment.

## When NOT to use

- Input mass tracks have not yet been aligned across samples into a MassGrid — run mass alignment first.
- RT calibration has not been performed — composite assembly requires rt_cal_dict; apply chromatograms.rt_lowess_calibration before this step.
- You need to detect peaks on individual samples independently (e.g., single-sample metabolomics, where cohort-level assembly is not applicable).

## Inputs

- aligned_MassGrid (object containing per-sample mass tracks aligned across cohort)
- per-sample_rt_calibration_dictionaries (rt_cal_dict keyed by sample ID)
- intensity_alignment_matrix (composite signal per m/z feature × sample)

## Outputs

- CompositeMap.FeatureTable (peak detections mapped to samples with areas/intensities)
- cmap.pickle (serialized composite map object for traceability)
- full_Feature_table.tsv (all detected features meeting SNR >2 and peakshape >0.5)

## How to apply

Construct composite mass tracks by summing aligned intensity values across all samples after retention time (RT) calibration has been applied. Feed each composite mass track to peaks.stats_detect_elution_peaks, which uses scipy.signal.find_peaks (local maxima method) with adaptive prominence filtering (minimum 1/3 of min_peak_height, default 1e5 intensity units) and optional detrending or smoothing. Evaluate detected peaks against peakshape >0.5 (gaussian fit quality) and signal-to-noise ratio (SNR) >2 using peaks.evaluate_gaussian_peak_on_intensity_list. This statistic-guided approach leverages the composite signal to reduce noise while preserving selectivity. Map detected features back to individual samples via RT alignment dictionaries (rt_cal_dict per sample) to extract per-sample peak areas and intensities, recording results in CompositeMap.FeatureTable.

## Related tools

- **scipy.signal.find_peaks** (Local maxima detection with prominence control on composite mass track intensity)
- **scipy.signal.detrend** (Optional smoothing/detrending of mass track before peak detection)
- **asari.peaks.stats_detect_elution_peaks** (Primary peak detection function that wraps find_peaks with adaptive prominence and noise filtering) — https://github.com/shuzhao-li/asari
- **asari.peaks.evaluate_gaussian_peak_on_intensity_list** (Quality filtering of detected peaks by gaussian peakshape and SNR metrics) — https://github.com/shuzhao-li/asari
- **asari.chromatograms.rt_lowess_calibration** (Pre-requisite RT calibration per sample to enable accurate peak mapping back to individual samples) — https://github.com/shuzhao-li/asari
- **asari.MassGrid** (Data structure holding aligned mass tracks across samples; input to composite assembly) — https://github.com/shuzhao-li/asari

## Examples

```
python3 -m asari.main process -i mydir/projectx_dir --mode pos
```

## Evaluation signals

- All detected peaks satisfy peakshape >0.5 (gaussian fit quality) and SNR >2 as recorded in CompositeMap.FeatureTable.
- Peak positions (m/z, RT) are consistent across samples where the feature is present; verify by inspecting full_Feature_table.tsv for features with >1 sample.
- cmap.pickle object is successfully serialized and can be deserialized without errors, confirming internal data structure integrity.
- Composite peak intensity values sum approximately to the sum of per-sample intensities (accounting for RT alignment shifts), validating that alignment and summing was correct.
- Feature count in preferred_Feature_table.tsv (filtered for selectivity) is lower than full_Feature_table.tsv, showing that QC filtering was applied.

## Limitations

- Peak detection relies on local maxima and prominence control; overlapping or severely tailed peaks may not resolve into separate features.
- Composite assembly assumes that RT calibration landmarks (mSelectivity >0.99, prominence >20% of peak height) exist in most samples; sparse landmark peaks will degrade calibration accuracy.
- Adaptive prominence threshold (default 1/3 of min_peak_height = 1e5) may suppress weak but reproducible features in low-abundance studies; user adjustment is necessary.
- Mass resolution advantages (0.001 amu binning, 5 ppm tolerance) assume high-resolution MS data; centroid data with coarser m/z spacing will reduce mass separation gains.

## Evidence

- [methods] Build composite mass tracks by summing aligned intensity values across all samples after RT calibration. Feed each composite mass track to peaks.stats_detect_elution_peaks, which uses scipy.signal.find_peaks (local maxima method) with adaptive prominence filtering (minimum 1/3 of min_peak_height, default 1e5).: "Build composite mass tracks by summing aligned intensity values across all samples after RT calibration. Detect elution peaks on composite mass tracks using peaks.stats_detect_elution_peaks with"
- [intro] Peak detection on a composite map instead of repeated on individual samples.: "Peak detection on a composite map instead of repeated on individual samples"
- [methods] Evaluate peaks with peaks.evaluate_gaussian_peak_on_intensity_list for peakshape >0.5 and SNR >2.: "evaluate peaks with peaks.evaluate_gaussian_peak_on_intensity_list for peakshape >0.5 and SNR >2"
- [methods] Map detected features back to individual samples via RT alignment dictionaries to extract peak areas and intensities, recording results in CompositeMap.FeatureTable.: "Map detected features back to individual samples via RT alignment dictionaries to extract peak areas and intensities, recording results in CompositeMap.FeatureTable"
- [intro] Statistics guided peak detection based on local maxima and prominence with selective use of smoothing.: "Statistics guided peak dection, based on local maxima and prominence, selective use of smoothing"
- [intro] Reproducible tracking and backtracking between features and mass tracks (EICs).: "Reproducible, track and backtrack between features and mass tracks (EICs)"