# Feature Metadata Annotation

> Use when you have processed mass spectrometry data consisting of three separate tables (quantification features, sample metadata, and spectral annotations) and need to combine them into a single, queryable artifact that preserves relationships between features, samples, and their chemical.

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

---


# feature-metadata-annotation

## Summary

Integrate quantification tables, metadata tables, and spectral data into a unified JSON schema for interactive mass spectrometry feature exploration. This skill bridges raw multi-modal mass spec outputs into a format suitable for browser-based visualization and downstream statistical analysis.

## When to use

You have processed mass spectrometry data consisting of three separate tables (quantification features, sample metadata, and spectral annotations) and need to combine them into a single, queryable artifact that preserves relationships between features, samples, and their chemical properties for interactive exploration or statistical workflows.

## When NOT to use

- Input quantification table is already in JSON format or pre-processed into a single combined object.
- Spectral data is unavailable or only MS1 precursor m/z is known without fragmentation spectra.
- Sample metadata cannot be reliably linked to quantification table rows by sample identifier.

## Inputs

- Quantification table (TSV/CSV: features × samples with abundance values)
- Metadata table (TSV/CSV: samples × descriptors with treatment, batch, and replicate information)
- Spectral data (mzML or equivalent format containing MS1 and MS/MS spectra with m/z and retention time)

## Outputs

- dashboard_data.json (JSON text file with feature, metadata, and spectral annotations in unified schema)
- Interactive visualization artifact compatible with msFeaST Dashboard bundle

## How to apply

Execute the msfeast_pipeline Jupyter notebook with your quantification table (feature abundances × samples), metadata table (sample descriptors), and spectral data (m/z, retention time, MS/MS spectra) as inputs. The pipeline processes these three sources to produce a JSON text file conforming to the dashboard data schema, which embeds feature identifiers, sample annotations, and spectral metadata in a hierarchical structure. Validate that the generated JSON contains all required fields: feature-level data (m/z, RT, spectral references), sample-level metadata (treatment, batch, replicate), and abundance values. The output JSON is then loadable into the msFeaST Dashboard bundle for interactive visualization or can be parsed programmatically for downstream analysis.

## Related tools

- **msFeaST** (Python module that executes data integration pipeline to unify quantification, metadata, and spectral tables into JSON schema) — https://github.com/kevinmildau/msFeaST
- **jupyter-notebook** (Interactive environment hosting msfeast_pipeline_mushroom_type_comparison.ipynb for running feature-metadata integration with user-defined file paths)
- **msFeaST Dashboard bundle** (Browser-based visualization tool (HTML/JavaScript) that loads and renders the output JSON for interactive feature exploration) — https://github.com/kevinmildau/msFeaST

## Examples

```
conda activate msfeast_environment; jupyter-notebook; # then open msfeast_pipeline_mushroom_type_comparison.ipynb, update data filepaths to your quantification_table.csv, metadata_table.csv, spectral_data.mzML, and execute all cells to generate dashboard_data.json
```

## Evaluation signals

- Generated JSON parses without errors and can be loaded into msFeaST Dashboard bundle without schema validation failures.
- JSON structure contains all three data layers: feature identifiers with m/z and retention time, sample metadata fields, and quantification abundance values accessible by feature and sample keys.
- Row/column counts in JSON match input quantification table dimensions (n features × m samples) with no data loss or duplication.
- Dashboard dataview tab successfully displays loaded data with searchable features, filterable metadata, and interactive spectral visualization.
- Spot-check: manual verification that 3–5 randomly selected features have correct abundance values, metadata linkages, and associated spectral annotations from input sources.

## Limitations

- msFeaST pre-processing and pipeline workflow has been tested on macOS and Linux; Windows support is currently being worked on.
- R installation within conda environment may experience path caching issues if rscript is invoked before conda R installation; workaround requires terminal closure and re-activation of the conda environment.
- Interactive dashboard requires a desktop web browser (Firefox, Chrome, Edge, Safari); mobile or headless environments are not supported.
- Spectral data must be in mzML format or compatible mass spec output; other formats require pre-conversion.
- No changelog is available; undocumented schema changes between versions may cause backward compatibility issues with older dashboard_data.json files.

## Evidence

- [readme] quantification table, metadata table, and spectral data processing: "complete example of quantification table, metadata table, and spectral data processing"
- [other] JSON schema validation and dashboard loading: "Validate that the generated JSON contains required fields for interactive visualization and can be loaded in the msFeaST Dashboard bundle."
- [readme] pipeline output format: "The jupyter-notebook pipeline produces the a text file in json format that can be interactively explored in the interactive dashboard"
- [readme] three-table integration workflow: "download the *msFeaST_Dashboard_bundle.html* and the ready made data from notebooks\data\omsw_pleurotus_ms2deepscore\dashboard_data.json"
- [readme] user parameterization for custom data: "To make use of your own data, change the data filepath arguments to your own data file location and run the pipeline."