metabolomic-data-structure-formatting
Summary
Convert raw mass-spectrometry metabolomic data into standardized QIIME 2 artifact formats (FeatureTable[Frequency] and MassSpectrometryFeatures) to enable downstream chemical tree construction and phylogenetic diversity analysis. This skill bridges peak-detection pipelines (MZmine2) and chemically-informed feature comparison.
When to use
Apply this skill after peak detection in MZmine2 has produced an MGF file (containing MS1 and MS2 spectra) and a feature abundance table (CSV or BIOM), but before running q2-qemistree tree construction or any QIIME 2-based metabolomic analysis. Use it when you have LC-MS/MS untargeted metabolomic profiles that need to be harmonized into a standard artifact format for reproducible, tool-agnostic downstream processing.
When NOT to use
- Data is already in QIIME 2 artifact format (.qza files) — skip import and proceed directly to tree construction.
- MGF file lacks MS2 spectra or has unmatched MS1 entries — troubleshoot peak detection in MZmine2 first.
- Feature table contains pre-aggregated or taxonomically classified rows — formatting assumes unaggregated MS1 features only.
Inputs
- MGF file with MS1 and MS2 spectra (from MZmine2 peak detection)
- Feature abundance table in CSV or BIOM format (peak areas per sample, from MZmine2)
Outputs
- QIIME 2 artifact of type MassSpectrometryFeatures (.qza)
- QIIME 2 artifact of type FeatureTable[Frequency] (.qza)
How to apply
First, export the peak-detection results from MZmine2 as two files: (1) an MGF file containing both MS1 and MS2 spectral information, and (2) a feature abundance table in CSV or BIOM format. Validate the MGF file for completeness—ensure every MS1 entry has a corresponding MS2 entry and that no formatting errors are present. Then, import both files into QIIME 2 artifact format using qiime tools import, specifying the MGF as type MassSpectrometryFeatures and the abundance table as type FeatureTable[Frequency]. QIIME 2 will validate schema compliance and report errors if MS1/MS2 pairing is incomplete or if the feature table has malformed entries, halting the import if needed. This produces standardized, versioned artifacts suitable for meta-analyses and reproducible comparative metabolomic workflows.
Related tools
- MZmine2 (Upstream peak detection and MS feature extraction; produces MGF and feature abundance tables consumed by this formatting skill) — http://mzmine.github.io
- QIIME 2 (Artifact framework and validation engine;
qiime tools import performs the format conversion and schema validation) — https://docs.qiime2.org
Examples
qiime tools import --input-path feature-table.biom --output-path feature-table.qza --type FeatureTable[Frequency] && qiime tools import --input-path sirius.mgf --output-path sirius.mgf.qza --type MassSpectrometryFeatures
Evaluation signals
- QIIME 2 import command completes without schema validation errors and produces .qza artifacts with correct type annotations.
- MGF file validation passes: all MS1 entries have corresponding MS2 entries (error message reports unmatched pairs if present).
- Feature table dimensions match between input CSV/BIOM and output artifact (sample count, feature count, abundance range preserved).
- Artifact can be successfully read and queried using
qiime qemistree subcommands in downstream tree-building steps.
- Metadata (m/z, retention time, spectral similarity) embedded in MGF headers survive import and are accessible in artifact.
- No features are silently dropped or renamed during import (output feature count equals input feature count).
Limitations
- MGF formatting errors (missing MS1/MS2 pairings, malformed headers) will halt import with an error message; troubleshooting must occur upstream in MZmine2.
- QIIME 2 import does not validate chemical plausibility of m/z or retention time values; garbage-in garbage-out holds.
- Feature table must have samples as columns and features (MS1 m/z × RT combinations) as rows; transpose-then-import if reversed.
- Only ~70–90% of MS1 features typically receive downstream fingerprint predictions in q2-qemistree due to MS2 spectral quality and user-defined tolerances (e.g., ppm-max, zodiac-threshold); features without fingerprints are filtered out post-hierarchy construction.
- SIRIUS version compatibility: q2-qemistree was initially developed for SIRIUS 4.0.1 and has been adapted for versions ≥4.4.29; older or newer versions may fail.
Evidence
- [readme] To generate a tree that relates the MS1 features in your experiment, we need to pre-process mass-spectrometry data (.mzXML, .mzML or .mzDATA files) using MZmine2 and produce the following inputs: 1. An MGF file with both MS1 and MS2 information.: "To generate a tree that relates the MS1 features in your experiment, we need to pre-process mass-spectrometry data (.mzXML, .mzML or .mzDATA files) using MZmine2 and produce the following inputs: 1."
- [readme] If the MGF file has formatting errors (eg. no MS1 are included in the MGF, or if an MS1 entry does not have a corresponding MS2 entry), then an appropriate error message will help users troubleshoot this step before proceeding forward.: "If the MGF file has formatting errors (eg. no MS1 are included in the MGF, or if an MS1 entry does not have a corresponding MS2 entry), then an appropriate error message will help users troubleshoot"
- [readme] We import these files into the appropriate QIIME 2 artifact formats as follows: qiime tools import --input-path feature-table.biom --output-path feature-table.qza --type FeatureTable[Frequency]: "We import these files into the appropriate QIIME 2 artifact formats as follows: qiime tools import --input-path feature-table.biom --output-path feature-table.qza --type FeatureTable[Frequency]"
- [other] Load the feature table (abundance matrix) and feature metadata (m/z, retention time, and/or spectral similarity annotations) into QIIME 2 artifact format.: "Load the feature table (abundance matrix) and feature metadata (m/z, retention time, and/or spectral similarity annotations) into QIIME 2 artifact format."
- [readme] MS1 features without fingerprints are filtered out of this feature table. This is done because SIRIUS predicts molecular substructures for a subset of features (typically for 70-90% of all MS1 features) in an experiment: "MS1 features without fingerprints are filtered out of this feature table. This is done because SIRIUS predicts molecular substructures for a subset of features (typically for 70-90% of all MS1"
1---2name: metabolomic-data-structure-formatting3description: Use when after peak detection in MZmine2 has produced an MGF file (containing MS1 and MS2 spectra) and a feature abundance table (CSV or BIOM), but before running q2-qemistree tree construction or any QIIME 2-based metabolomic analysis.4license: CC-BY-4.05---67# metabolomic-data-structure-formatting89## Summary1011Convert raw mass-spectrometry metabolomic data into standardized QIIME 2 artifact formats (FeatureTable[Frequency] and MassSpectrometryFeatures) to enable downstream chemical tree construction and phylogenetic diversity analysis. This skill bridges peak-detection pipelines (MZmine2) and chemically-informed feature comparison.1213## When to use1415Apply this skill after peak detection in MZmine2 has produced an MGF file (containing MS1 and MS2 spectra) and a feature abundance table (CSV or BIOM), but before running q2-qemistree tree construction or any QIIME 2-based metabolomic analysis. Use it when you have LC-MS/MS untargeted metabolomic profiles that need to be harmonized into a standard artifact format for reproducible, tool-agnostic downstream processing.1617## When NOT to use1819- Data is already in QIIME 2 artifact format (.qza files) — skip import and proceed directly to tree construction.20- MGF file lacks MS2 spectra or has unmatched MS1 entries — troubleshoot peak detection in MZmine2 first.21- Feature table contains pre-aggregated or taxonomically classified rows — formatting assumes unaggregated MS1 features only.2223## Inputs2425- MGF file with MS1 and MS2 spectra (from MZmine2 peak detection)26- Feature abundance table in CSV or BIOM format (peak areas per sample, from MZmine2)2728## Outputs2930- QIIME 2 artifact of type MassSpectrometryFeatures (.qza)31- QIIME 2 artifact of type FeatureTable[Frequency] (.qza)3233## How to apply3435First, export the peak-detection results from MZmine2 as two files: (1) an MGF file containing both MS1 and MS2 spectral information, and (2) a feature abundance table in CSV or BIOM format. Validate the MGF file for completeness—ensure every MS1 entry has a corresponding MS2 entry and that no formatting errors are present. Then, import both files into QIIME 2 artifact format using `qiime tools import`, specifying the MGF as type `MassSpectrometryFeatures` and the abundance table as type `FeatureTable[Frequency]`. QIIME 2 will validate schema compliance and report errors if MS1/MS2 pairing is incomplete or if the feature table has malformed entries, halting the import if needed. This produces standardized, versioned artifacts suitable for meta-analyses and reproducible comparative metabolomic workflows.3637## Related tools3839- **MZmine2** (Upstream peak detection and MS feature extraction; produces MGF and feature abundance tables consumed by this formatting skill) — http://mzmine.github.io40- **QIIME 2** (Artifact framework and validation engine; `qiime tools import` performs the format conversion and schema validation) — https://docs.qiime2.org4142## Examples4344```45qiime tools import --input-path feature-table.biom --output-path feature-table.qza --type FeatureTable[Frequency] && qiime tools import --input-path sirius.mgf --output-path sirius.mgf.qza --type MassSpectrometryFeatures46```4748## Evaluation signals4950- QIIME 2 import command completes without schema validation errors and produces .qza artifacts with correct type annotations.51- MGF file validation passes: all MS1 entries have corresponding MS2 entries (error message reports unmatched pairs if present).52- Feature table dimensions match between input CSV/BIOM and output artifact (sample count, feature count, abundance range preserved).53- Artifact can be successfully read and queried using `qiime qemistree` subcommands in downstream tree-building steps.54- Metadata (m/z, retention time, spectral similarity) embedded in MGF headers survive import and are accessible in artifact.55- No features are silently dropped or renamed during import (output feature count equals input feature count).5657## Limitations5859- MGF formatting errors (missing MS1/MS2 pairings, malformed headers) will halt import with an error message; troubleshooting must occur upstream in MZmine2.60- QIIME 2 import does not validate chemical plausibility of m/z or retention time values; garbage-in garbage-out holds.61- Feature table must have samples as columns and features (MS1 m/z × RT combinations) as rows; transpose-then-import if reversed.62- Only ~70–90% of MS1 features typically receive downstream fingerprint predictions in q2-qemistree due to MS2 spectral quality and user-defined tolerances (e.g., ppm-max, zodiac-threshold); features without fingerprints are filtered out post-hierarchy construction.63- SIRIUS version compatibility: q2-qemistree was initially developed for SIRIUS 4.0.1 and has been adapted for versions ≥4.4.29; older or newer versions may fail.6465## Evidence6667- [readme] To generate a tree that relates the MS1 features in your experiment, we need to pre-process mass-spectrometry data (.mzXML, .mzML or .mzDATA files) using MZmine2 and produce the following inputs: 1. An MGF file with both MS1 and MS2 information.: "To generate a tree that relates the MS1 features in your experiment, we need to pre-process mass-spectrometry data (.mzXML, .mzML or .mzDATA files) using MZmine2 and produce the following inputs: 1."68- [readme] If the MGF file has formatting errors (eg. no MS1 are included in the MGF, or if an MS1 entry does not have a corresponding MS2 entry), then an appropriate error message will help users troubleshoot this step before proceeding forward.: "If the MGF file has formatting errors (eg. no MS1 are included in the MGF, or if an MS1 entry does not have a corresponding MS2 entry), then an appropriate error message will help users troubleshoot"69- [readme] We import these files into the appropriate QIIME 2 artifact formats as follows: qiime tools import --input-path feature-table.biom --output-path feature-table.qza --type FeatureTable[Frequency]: "We import these files into the appropriate QIIME 2 artifact formats as follows: qiime tools import --input-path feature-table.biom --output-path feature-table.qza --type FeatureTable[Frequency]"70- [other] Load the feature table (abundance matrix) and feature metadata (m/z, retention time, and/or spectral similarity annotations) into QIIME 2 artifact format.: "Load the feature table (abundance matrix) and feature metadata (m/z, retention time, and/or spectral similarity annotations) into QIIME 2 artifact format."71- [readme] MS1 features without fingerprints are filtered out of this feature table. This is done because SIRIUS predicts molecular substructures for a subset of features (typically for 70-90% of all MS1 features) in an experiment: "MS1 features without fingerprints are filtered out of this feature table. This is done because SIRIUS predicts molecular substructures for a subset of features (typically for 70-90% of all MS1"
HolobiomicsLab 