# Annotate your own data

## One assembly

```bash
metapathways run \
  -i sample.fasta \
  -o results \
  -d /data/MPDB
```

The sample output is `results/sample/`; the run-wide report is `results/reports/`. Input can be nucleotide FASTA, compressed FASTA, or amino-acid FASTA with `--input_format fasta-amino`. GFF and GenBank are output formats, not accepted primary inputs of this CLI.

Choose references and inspect the plan:

```bash
metapathways run -i sample.fasta -o results -d /data/MPDB \
  --annotation_dbs swissprot cazy --annotation_algorithm FAST --dryrun
```

A dry run checks dependencies and writes the execution plan and logs without executing annotation tasks. It can create sample directory scaffolding; it does not produce a completed biological report.

## Read mapping

Paired reads in separate files:

```bash
metapathways run -i sample.fasta -o results -d /data/MPDB \
  -1 sample_R1.fastq.gz -2 sample_R2.fastq.gz
```

Interleaved paired reads:

```bash
metapathways run -i sample.fasta -o results -d /data/MPDB \
  -1 sample.interleaved.fastq.gz --interleaved
```

Single-end reads use `-1` alone. With no reads, abundance calculation is skipped. `-1` and `-2` must identify different files; MP now rejects identical paired input paths, including aliases to the same file. The paired command passes the actual reverse file to CoverM.

Historical output generated by the incorrect mate selection must not be treated as corrected merely because it appears in a report. Repeating the annotation command with the corrected reads can reuse completed annotation stages and recompute mapping. The portal copies existing abundance values; it does not certify their provenance or rerun mapping.

## Interpreting feature and hit counts

Protein search statistics distinguish alignment rows from distinct query ORFs;
multiple hits for one ORF count once in the latter. ORF identifiers are counted
in full, without assuming a particular naming format. Counts from different
reference databases can overlap.

rRNA prediction and rRNA taxonomic annotation are separate outputs. MP uses
barrnap's GFF annotations to identify the subunit when extracted FASTA headers
contain only coordinates, and retains support for older headers containing the
subunit name. Alignment lengths include both endpoints and are independent of
alignment direction. A predicted rRNA feature need not have a qualifying
taxonomic hit.

## Multiple assemblies

Pass a directory of FASTA files to `-i`; each file becomes a sample with its own output directory. Use unique, simple filenames and `--samples` to select a subset. Read mapping arguments apply to one sample only: run separate commands for samples with different FASTQs. CPU/memory budgets are per invocation, so independent MP commands do not share a global resource limit.

## Stage controls

Stage flags accept `yes`, `skip` or `redo`. For example:

```bash
metapathways run -i sample.fasta -o results -d /data/MPDB \
  --COMPUTE_TPM redo -1 sample_R1.fastq.gz -2 sample_R2.fastq.gz
```

`yes` reuses valid outputs, `redo` executes the stage again, and `skip` requires any needed downstream inputs to already exist. `--force_redo` forces all annotation stages. Changes to tracked inputs or outputs invalidate task receipts. See the [workflow guide](workflow.md) before skipping dependencies.