# Msflo Metabolite Annotation

> Use when after MS-DIAL has completed feature detection and peak alignment on .mzML LC-HRMS data, producing an aligned feature table. Use MSFLO when you need to assign metabolite identities to detected features and filter results by significance criteria before downstream interpretation.

- Skill: `holobiomicslab/msflo-metabolite-annotation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/msflo-metabolite-annotation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/msflo-metabolite-annotation/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/msflo-metabolite-annotation

---


# msflo-metabolite-annotation

## Summary

MSFLO is a containerized metabolite annotation module that processes aligned LC-HRMS feature tables from MS-DIAL to assign metabolite identities and perform statistical analysis. This skill encapsulates the post-feature-detection annotation and filtering stage within reproducible Nextflow4MS-DIAL workflows.

## When to use

Apply this skill after MS-DIAL has completed feature detection and peak alignment on .mzML LC-HRMS data, producing an aligned feature table. Use MSFLO when you need to assign metabolite identities to detected features and filter results by significance criteria before downstream interpretation.

## When NOT to use

- Raw .mzML or .abf mass spectrometry files have not yet undergone MS-DIAL feature detection and alignment — use MS-DIAL first.
- Reference spectral libraries (MS1 and MS2) are not available or not in the required text/MSP formats.
- The input is already a fully annotated and statistically validated metabolite table; MSFLO is redundant at that stage.

## Inputs

- Aligned feature table (TSV format) from MS-DIAL containing m/z, retention time, and intensity values across samples
- MS1 reference spectral library (ms1_lib.txt)
- MS2 reference spectral library (ms2_lib.msp)
- MSFLO parameters configuration file (msflo_params.ini)

## Outputs

- Annotated feature table (TSV format) with metabolite identities, annotation scores, and statistical metrics
- Filtered feature set meeting significance and annotation confidence thresholds

## How to apply

After the Nextflow4MS-DIAL pipeline has routed aligned features through the containerized MS-DIAL module, pass the resulting feature table through the containerized MSFLO module by specifying MSFLO parameters in a configuration file named `msflo_params.ini` and placing it in the `data/` folder. MSFLO accepts the aligned feature table from MS-DIAL and uses reference MS1 and MS2 spectral libraries (named `ms1_lib.txt` and `ms2_lib.msp` in the `data/` folder) to annotate features with metabolite identities. The module applies annotation filtering and statistical tests to produce a final annotated feature table suitable for metabolomics interpretation. Configuration and library setup must be validated before pipeline execution to ensure correct annotation parameters and library formats.

## Related tools

- **Nextflow** (Workflow orchestration engine that manages containerized MSFLO execution across Docker and Singularity runtimes) — https://www.nextflow.io/
- **Docker** (Container runtime for local execution of containerized MSFLO module) — https://docs.docker.com/engine/installation/
- **Singularity** (Container runtime for MSFLO execution on high-performance computing systems) — https://www.sylabs.io/guides/3.0/user-guide/
- **MS-DIAL** (Upstream feature detection and alignment module that produces the aligned feature table consumed by MSFLO)

## Examples

```
nextflow run main.nf -profile docker
```

## Evaluation signals

- Output feature table contains metabolite annotations (non-null metabolite names or IDs) for a high proportion of input features, indicating successful library matching.
- MSFLO annotation scores or cosine similarity metrics meet expected ranges relative to reference spectral library quality and completeness.
- Statistical filtering results in a reasonable retention rate (e.g., features surviving p-value or fold-change thresholds) consistent with the biological replicate structure.
- Output file format is valid TSV with expected column headers (metabolite name, m/z, retention time, annotation confidence score, p-value, etc.).
- Pipeline execution log contains no errors during the MSFLO containerized process and reports completion of annotation and statistical steps.

## Limitations

- MSFLO annotation accuracy depends critically on the completeness and quality of the provided MS1 and MS2 reference spectral libraries; incomplete or poorly curated libraries will result in low annotation coverage.
- Configuration file parameters (msflo_params.ini) must be manually validated and pre-tested; incorrect parameter settings may produce silently incorrect results or filtered-out features.
- The workflow has been tested successfully on macOS 13.5.1 with Intel Core i7 and 16 GB memory, and on HiPerGator (Red Hat Enterprise Linux 8.8); performance and compatibility on other systems are not documented.
- Special characters in data file names are not supported and will cause errors; only underscores are safe.

## Evidence

- [other] Route aligned features through the containerized MSFLO module for annotation and statistical processing.: "Route aligned features through the containerized MSFLO module for annotation and statistical processing."
- [other] Nextflow4MS-DIAL implements a containerized workflow that routes .mzML LC-MS metabolomics data through MS-DIAL followed by MSFLO.: "Nextflow4MS-DIAL implements a containerized workflow that routes .mzML LC-MS metabolomics data through MS-DIAL followed by MSFLO, with support for both Docker and Singularity container runtimes."
- [readme] Add the MS1 and MS2 libraries to the `data/` folder and name them `ms1_lib.txt` and `ms2_lib.msp`.: "Add the MS1 and MS2 libraries to the `data/` folder and name them `ms1_lib.txt` and `ms2_lib.msp`. Example library files are available in `functional_test/sample_data/`."
- [readme] Add the MS-DIAL and MS-FLO configuration files to the `data/` folder and name them `msdial_params.txt` and `msflo_params.ini`.: "Add the MS-DIAL and MS-FLO configuration files to the `data/` folder and name them `msdial_params.txt` and `msflo_params.ini`. Example configuration files are available in"
- [readme] Both Docker and Singularity (for high-performance computing) are supported.: "Both Docker and Singularity (for high-performance computing) are supported"