> For the complete documentation index, see [llms.txt](https://doc.duaer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/getting-started/metabolic-dark-matter.md).

# Annotate an unknown feature with Duaer

In Duaer, work an MS feature that no library identified: library match, mass candidates, reference spectra, and MASST, one Duaer Data call per step.
## What metabolic dark matter is

In Duaer, metabolic dark matter is the MS features that no library identifies: an m/z or an MS/MS spectrum with no annotation.

Duaer chains single-purpose Duaer Data offerings instead of one large tool: one call per step, then decide the next step from the result.

## Steps

1. With a USI, fetch the peaks and precursor m/z with [Spectrum by USI](/getting-started/spectrum.md).
2. Match the peaks with [MassBank spectra](/getting-started/massbank.md). A score of 0.8 or more with a matching precursor is a likely identification; skip to the last step.
3. Without a match, list PubChem candidates with [Mass candidates](/getting-started/mass-candidates.md) from the precursor m/z, adduct, and ppm.
4. For the top candidates, get reference spectra with [MoNA spectra](/getting-started/mona.md) (or MassBank by InChIKey) and compare the major fragments.
5. Run [MASST](/getting-started/masst.md) to see which public datasets contain the spectrum. One seen across several studies is more likely a real metabolite.
6. For an identified or putative compound, add pathways and reactions with [RefMet](/getting-started/refmet.md), [KEGG](/getting-started/kegg.md), or [Rhea](/getting-started/rhea.md).

With only an m/z (MS1), skip the spectrum, library match, and MASST steps. A feature usually takes 3 to 8 calls.

## How to report

- Result: the compound name and InChIKey, or unknown.
- Evidence per step: the call, the top hit, and its score, ppm error, or dataset count.
- Confidence: identified for a library match, putative for a candidate with shared fragments, mass only when only the mass fits.

Mass alone never identifies a structure: glucose, galactose, and fructose share a formula.

## Skill

Give this skill to an agent to run the steps with Duaer Data.

```
---
name: duaer-metabolic-dark-matter
description: >-
  Work an unannotated metabolomics feature (an m/z or MS/MS spectrum that no library identified)
  step by step with Duaer Data. Each step is one Duaer Data call that uses 1 Duaer credit.
---

# Duaer: annotate an unknown feature (metabolic dark matter)

Metabolic dark matter is the MS features that no library identifies. This Duaer skill chains single-purpose Duaer Data calls.
Run one step, read its result, then decide the next step. Report what each call returned.

## Input

One of:

- A USI (`mzspec:...`) of a public spectrum.
- MS/MS peaks (`mz:intensity` pairs) with the precursor m/z, an adduct guess, and the ion mode.
- Only an m/z (MS1 feature) with an adduct guess. Skip steps 1, 2, and 5.

## Steps

1. **Get peaks.** For a USI, call https://skills.duaer.com/spectrum.md. Keep `peaks` and `precursorMz`.
2. **Library match.** Call https://skills.duaer.com/massbank.md with `peaks` and `ionMode`.
   A `score` of 0.8 or more with a matching precursor is a likely identification. If you have one, go to step 6.
3. **Mass candidates.** Call https://skills.duaer.com/mass-candidates.md with the precursor m/z, the adduct, and `ppm` (5 for high-resolution data).
4. **Compare candidates.** For the top candidates, call https://skills.duaer.com/mona.md with each `inchikey`
   (or https://skills.duaer.com/massbank.md with `inchikey`). Compare reference `peaks` and `precursorType` with yours.
   Shared major fragments support a candidate. No shared fragments rules it out.
5. **Where it occurs.** Call https://skills.duaer.com/masst.md with the USI or the peaks.
   `library=public` lists public datasets that contain the same spectrum. `library=gnpsLibrary` finds GNPS reference spectra.
   A spectrum seen across several studies or sample types is more likely a real metabolite than noise.
6. **Context.** For an identified or putative compound, use https://skills.duaer.com/refmet.md for the standard name and class,
   and https://skills.duaer.com/kegg.md or https://skills.duaer.com/rhea.md for pathways and reactions.

## Report

For each feature return:

- Input (USI, precursor m/z, adduct, ion mode).
- Result: the compound name and InChIKey, or `unknown`.
- Evidence per step: the call, the top hit, and its score, ppm error, or dataset count.
- Confidence: `identified` (library spectrum match), `putative` (candidate with shared fragments), `mass only`, or `unknown`.
- A next step, such as running an authentic standard.

## Rules

- Mass alone never identifies a compound. Isomers share a formula (glucose, galactose, fructose).
- Cite only returned results. Do not invent names, InChIKeys, scores, or datasets.
- One Duaer Data call per step. A feature usually takes 3 to 8 calls.

## Keys

Header: `Authorization: Bearer <Duaer key>`

Use an account key or a model API key.

Get a Duaer key: https://skills.duaer.com/keys.md

## Credits

Each successful Duaer Data call uses 1 credit, including a call that finds no match.
Empty input, a failed source, or no remaining credits uses 0.

```
## Questions

### How many credits does annotating one unknown feature use in Duaer?

Each successful Duaer Data call uses 1 credit. A feature usually takes 3 to 8 calls.

### Does Duaer determine the structure of an unknown?

Not by itself. Duaer returns evidence (library matches, candidates, and where the spectrum occurs) with a confidence level; an authentic standard confirms the structure.

## Related

- [Fetch a spectrum by USI in Duaer](https://doc.duaer.com/getting-started/spectrum.md)
- [Match spectra in MassBank with Duaer](https://doc.duaer.com/getting-started/massbank.md)
- [List mass candidates in Duaer](https://doc.duaer.com/getting-started/mass-candidates.md)
- [Find MoNA reference spectra with Duaer](https://doc.duaer.com/getting-started/mona.md)
- [Search a spectrum with MASST in Duaer](https://doc.duaer.com/getting-started/masst.md)
- [Search RefMet in Duaer](https://doc.duaer.com/getting-started/refmet.md)