# Ms Finder Format Export

> Use when after completing MS-CleanR filtering (blank subtraction, background removal, RSD/RMD thresholding) and feature clustering steps, when you have a consolidated set of representative features and need structural identification via MS/MS spectral matching.

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

---


# MS-FINDER Format Export

## Summary

Convert filtered and clustered LC-MS features from MS-CleanR into MS-FINDER-compatible input format (m/z, retention time, MS/MS spectra) to enable in silico compound annotation using hydrogen rearrangement rules scoring across multiple metabolite databases.

## When to use

After completing MS-CleanR filtering (blank subtraction, background removal, RSD/RMD thresholding) and feature clustering steps, when you have a consolidated set of representative features and need structural identification via MS/MS spectral matching. Use when your data includes MS/MS spectra (DDA or DIA mode with fragment information); MS1-only data will fail at this stage.

## When NOT to use

- Input data contains only MS1 spectra without MS/MS fragments (MS-CleanR will crash in the first filtering step; MS-FINDER requires fragmentation data)
- Features have already been annotated via external tools and merged — skip to results prioritization rather than re-exporting
- LC-MS data acquired in full-scan mode only (no data-dependent or data-independent MS/MS collection)

## Inputs

- MS-CleanR clustered feature set (m/z, retention time, MS/MS spectra per representative feature)
- Feature metadata (sample class, ionization mode origin)
- MS/MS fragmentation spectra (centroided or profile mode)

## Outputs

- MS-FINDER-formatted input file(s) with feature m/z, retention time, and MS/MS spectra
- MS-FINDER annotation results (compound ID, HRR score, database match, structural predictions)
- Unified annotation table (feature → top-ranked compound match with confidence metrics)

## How to apply

Load the cleaned feature set output from MS-CleanR clustering (containing m/z, retention time, and associated MS/MS spectra for each representative feature). Format each feature into MS-FINDER input specification: organize m/z and retention time as continuous values, embed full MS/MS fragmentation spectrum with peak intensities, and structure as a text-based or binary format compatible with MS-FINDER 3.30+. Configure MS-FINDER annotation parameters to activate hydrogen rearrangement rules (HRR) scoring and select target databases (e.g., MassBank, GNPS, in-house libraries). Execute MS-FINDER in silico search and parse output to extract per-feature compound ID, match score, database source, and predicted molecular structure. Consolidate all annotation results into a unified table keyed by feature m/z and retention time.

## Related tools

- **MS-FINDER** (In silico annotation engine using hydrogen rearrangement rules (HRR) scoring to identify compounds from MS/MS spectra against multiple databases) — http://prime.psc.riken.jp/compms/index.html
- **MS-CleanR** (Upstream feature filtering and clustering; produces the cleaned feature set that is exported to MS-FINDER) — https://github.com/eMetaboHUB/MS-CleanR
- **MS-DIAL** (Prerequisite peak detection and MS/MS data processing (v4.00+); generates the peak list input consumed by MS-CleanR) — http://prime.psc.riken.jp/compms/index.html

## Examples

```
# After MS-CleanR filtering and clustering, export features to MS-FINDER format:
# In R, within MS-CleanR workflow:
# mscleanr::export_to_msfinder(cleaned_features, output_file="features_for_msfinder.msp", hrr_scoring=TRUE, databases=c("MassBank", "GNPS"))
```

## Evaluation signals

- MS-FINDER input file is successfully parsed without format errors; feature count and MS/MS spectrum counts match the input feature set
- Annotation results contain non-empty compound IDs and HRR scores for ≥70% of queried features (expected hit rate for known metabolites in populated databases)
- Consolidated annotation table is keyed by feature m/z and retention time with no missing values in score and database origin columns
- Multiple database query results are captured and ranked consistently; database priority prioritization logic is applied correctly during consolidation
- Export can be validated by spot-checking 3–5 features: verify that m/z and retention time in output match input, and that top annotation score is reasonable (HRR scores typically 0–100)

## Limitations

- Requires MS/MS spectra for all features; MS1-only data will cause MS-CleanR to crash before export is attempted
- MS-FINDER annotation quality depends on database completeness and quality; known metabolites will have higher match confidence than unknown compounds
- Hydrogen rearrangement rules (HRR) scoring is optimized for small organic molecules; performance may degrade for large polymers or atypical adducts
- Multiple database querying increases runtime; large feature sets (>10,000 features) with many databases can require hours
- At least 3 blank and 3 QC samples must be labeled in MS-DIAL sample list for proper blank ratio analysis upstream; missing blanks will compromise feature filtering quality before export

## Evidence

- [readme] all selected features are exported to MS-FINDER program for in silico-based annotation using hydrogen rearrangement rules (HRR) scoring system: "all selected features are exported to MS-FINDER program for in silico-based annotation using hydrogen rearrangement rules (HRR) scoring system"
- [readme] multiple databases can be queried and each annotation results will be handled by MS-CleanR: "At this step, multiple databases can be queried and each annotation results will be handled by MS-CleanR"
- [other] Format feature data (m/z, retention time, MS/MS spectra) into MS-FINDER compatible input format: "Format feature data (m/z, retention time, MS/MS spectra) into MS-FINDER compatible input format"
- [readme] All features without MS/MS will be discarded during the first step: "All features without MS/MS will be discarded during the first step. If data contain MS1 only, the first MS-CleanR step will crash"
- [other] Parse MS-FINDER results and consolidate per-feature annotations: "Parse MS-FINDER results and consolidate per-feature annotations (compound ID, score, database match, structural predictions) into a unified annotation table"