Metabolomics Annotation

<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

---
name: bio-metabolomics-annotation
description: Metabolite annotation and structural identification using SIRIUS, CSI:FingerID,
  GNPS, or MetFrag.
tool_type: mixed
primary_tool: metabolomics
measurable_outcome: Execute skill workflow successfully with valid output within 15
  minutes.
allowed-tools:
- read_file
- run_shell_command
---

# 🏷️ Metabolite Annotation

Metabolite annotation and structural identification against spectral libraries. Supports SIRIUS/CSI:FingerID, GNPS, and MetFrag.

## CLI Reference

```bash
python omicsclaw.py run met-annotate --demo
python omicsclaw.py run met-annotate --input <features.csv> --output <dir>
```

## Why This Exists

- **Without it**: LC-MS peaks remain anonymous "features" defined only by m/z and retention time
- **With it**: Converts features into candidate chemical structures via spectral networking and in-silico fragmentation
- **Why OmicsClaw**: Centralizes access to fragmented knowledgebases (SIRIUS, GNPS, MetFrag)

## Workflow

1. **Calculate**: Extract pure MS2 spectra representations.
2. **Execute**: Query spectral libraries or generate fragmentation trees.
3. **Assess**: Score candidate chemical formulas and structures.
4. **Generate**: Output structural mappings of features to molecules.
5. **Report**: Tabulate top compound identifications with confidence tiers.

## Example Queries

- "Annotate these metabolomics features using SIRIUS"
- "Match MS2 spectra against GNPS libraries"

## Output Structure

```
output_directory/
├── report.md
├── result.json
├── annotated.csv
├── figures/
│   └── chemical_class_distribution.png
├── tables/
│   └── compound_identifications.csv
└── reproducibility/
    ├── commands.sh
    ├── environment.yml
    └── checksums.sha256
```

## Safety

- **Local-first**: Local database matching where possible; transparent interactions for external APIs (like GNPS).
- **Disclaimer**: Requires OmicsClaw reporting structures and disclaimers.
- **Audit trail**: Hyperparameters and operational flow states are logged fully.

## Integration with Orchestrator

**Trigger conditions**:
- Automatically invoked dynamically based on tool metadata and user intent matching.

**Chaining partners**:
- `peak-detection` — Upstream feature extraction
- `met-diff` — Downstream structural interpretation of significant hits

## Citations

- [SIRIUS](https://doi.org/10.1038/s41592-019-0344-8)
- [GNPS](https://doi.org/10.1038/nbt.3597)
- [MetFrag](https://doi.org/10.1186/s13321-016-0115-9)

<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->