# Sample Group Injection Aggregation

> Use when when you have picked and annotated MS1 features from replicate injections of the same sample and need to produce a unified feature matrix indexed by sample (not injection).

- Skill: `holobiomicslab/sample-group-injection-aggregation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/sample-group-injection-aggregation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/sample-group-injection-aggregation/raw
- Safety review: pending
- 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/sample-group-injection-aggregation

---


# sample-group-injection-aggregation

## Summary

Consolidate multiple injections of the same sample and merge features across sample groups defined in the sequence file to enable group-level statistical analysis and comparative metabolomics. This skill is essential in high-throughput untargeted metabolomics workflows where replicate injections must be unified before group-wise comparisons.

## When to use

When you have picked and annotated MS1 features from replicate injections of the same sample and need to produce a unified feature matrix indexed by sample (not injection). Use this skill after background filtering, adduct merging, and feature annotation are complete—particularly in FIA-MS FullScan Unknowns or semi-targeted workflows where the sequence file defines sample groupings and you plan to perform downstream group comparisons or statistical tests.

## When NOT to use

- Input is already a sample-level feature table (no injection replicates to merge).
- You need to preserve injection-level variance for QC trend analysis or time-series monitoring across a sample batch.
- Sample groupings in the sequence file are malformed, missing, or do not reflect the biological design (validate sequence metadata first).

## Inputs

- picked and annotated MS1 feature list (mzTab or feature table format with intensity values per injection)
- sequence file (.csv) with sample identifiers, group assignments, and injection replicates
- feature annotation results (e.g., from SEARCH_ACCURATE_MASS and MERGE_FEATURES)

## Outputs

- sample-level feature matrix (rows = samples, columns = m/z × RT features, values = aggregated intensities)
- group-annotated feature table with sample-group metadata preserved
- feature list with sample-level quality metrics (e.g., coefficient of variation across replicates)

## How to apply

After filtering features by blank signal intensity and merging adducts of the same compound, apply MERGE_INJECTIONS to consolidate all injections belonging to the same sample into a single row, typically by summing or averaging feature intensities across replicates. Then apply STORE_FEATURES_SAMPLE_GROUP to merge features across the sample groups (e.g., case vs. control cohorts) specified in the sequence file metadata. The rationale is to reduce the injection dimension while preserving sample-level biological variability; grouping enforces consistent handling of the sample structure defined in the input sequence configuration, ensuring that downstream statistical tests operate on the intended sample-group contrasts rather than on individual injections.

## Related tools

- **SmartPeak** (orchestrates the full workflow including MERGE_INJECTIONS and STORE_FEATURES_SAMPLE_GROUP steps) — https://github.com/AutoFlowResearch/SmartPeak
- **SmartPeakGUI** (provides interactive configuration and monitoring of injection/sample merging and group storage operations) — https://github.com/AutoFlowResearch/SmartPeak
- **SmartPeakCLI** (enables command-line execution of injection and group merging workflows without GUI) — https://github.com/AutoFlowResearch/SmartPeak
- **OpenMS** (provides underlying feature merging and intensity aggregation algorithms)
- **BFAIR** (post-processing and statistical analysis of aggregated sample-group features) — https://github.com/AutoFlowResearch/BFAIR

## Evaluation signals

- Verify that the number of rows in the output feature table equals the number of unique samples (not injections) in the sequence file.
- Check that sample-level feature intensities are non-negative and within expected range (e.g., no NaN or negative values after aggregation).
- Confirm that group assignments are correctly propagated: all samples in a group should share the same group label in the output metadata.
- Compute coefficient of variation (CV) for aggregated intensities across replicate injections; high CV (>50%) may indicate injection-level variability worth investigating.
- Validate that the number of features per sample is consistent after merging (no unexpected loss or gain of features due to missing values or aggregation errors).

## Limitations

- Injection merging assumes all replicates of a sample use the same or compatible MS parameters; mismatched acquisition settings may produce misleading aggregate intensities.
- If the sequence file lacks explicit group labels or sample metadata, STORE_FEATURES_SAMPLE_GROUP may fail or create uninformative groupings; preprocessing and validation of the sequence file is mandatory.
- Aggregation (e.g., sum or mean) of intensities across injections can mask outlier injections or instrumental drift; no robust outlier detection is described in the workflow.
- The workflow does not explicitly handle unbalanced designs (e.g., differing numbers of replicates per sample or missing injections); such cases may require manual sequence file curation or post-hoc filtering.

## Evidence

- [methods] Merge injections belonging to the same sample using MERGE_INJECTIONS: "Merge injections belonging to the same sample using MERGE_INJECTIONS."
- [methods] Merge features across sample groups specified in the sequence file using STORE_FEATURES_SAMPLE_GROUP: "Merge features across sample groups specified in the sequence file using STORE_FEATURES_SAMPLE_GROUP."
- [intro] SmartPeak automates all steps from peak detection and integration over calibration curve optimization, to quality control reporting: "The workflow automates all steps from peak detection and integration over calibration curve optimization, to quality control reporting."
- [readme] The collection of examples is located at src/example/data directory of the SmartPeak source code. The directory contains examples of different kinds of data in .mzML format and their corresponding configuration files.: "The collection of examples is located at ``src/example/data`` directory of the SmartPeak source code."