Docs / Getting started
Preparing inputs
AMAP takes assembled genomes. It does not do assembly, so reads are not an input here.
The sample sheet#
A tab-separated file with a header row and exactly two columns:
sampleId fasta G26689 /data/genomes/G26689.fasta G26690 /data/genomes/G26690.fasta L4_G12345 ./assemblies/L4_G12345.fa
samples.tsv2
| 1sampleId | ⇥ | 3fasta |
|---|---|---|
| G26689 | ⇥ | /data/genomes/G26689.fasta |
| G26690 | ⇥ | /data/genomes/G26690.fasta |
| L4_G12345 | ⇥ | ./assemblies/L4_G12345.fa |
sampleId: unique, and carried into every folder and file name. Letters, digits and underscores.- A real tab between the two columns, on every line, header included. Spaces will not do.
fasta: the assembled genome, as an absolute path or one relative to where you launch Nextflow.
With spaces where the tabs go, --validate_only stops with:
✗ TSV missing 'sampleId' column. Found: ['sampleId fasta']
✗ TSV missing 'fasta' column. Found: ['sampleId fasta']
✗ Duplicate sampleIds in TSV: {''}
✗ Empty sampleId on line(s): [2, 3, 4]
FAILED: 4 critical error(s)With tabs, and paths that do not exist yet, --validate_only stops with:
✗ FASTA file not found: /data/genomes/G26689.fasta ✗ FASTA file not found: /data/genomes/G26690.fasta ✗ FASTA file not found: ./assemblies/L4_G12345.fa ✗ FAILED: 3 critical error(s)
bin/validate_inputs.py on this sheet.sampleId: The name carried through every output directory and file. Must be unique. Lineage typing puts the lineage in front, soG26689comes out asL4_G26689.fasta: Path to the assembled genome. Absolute, or relative to the directory you launch Nextflow from.
The separator has to be an actual tab. Spaces will not do, and this is the most common reason a sample sheet is rejected.
Avoid dots in sample IDs
Several scripts derive the sample name by cutting at the first dot, so G26689.1 becomes G26689 and two such samples would collide. Stick to letters, digits and underscores.
Pre-flight validation#
VALIDATE_INPUTS runs before any computation, on every run. To run only the checks and stop:
nextflow run PathoGenOmics-Lab/AMAP -profile docker \
--tsv samples.tsv --validate_onlyResults are written to results/pipeline_info/validation.log.
Genome sizelog scale
- M. tuberculosis, M. bovis: 4.35 to 4.41 Mb
- E. coli: 4.64 to 5.59 Mb
GC content% of A, C, G and T
- tuberculosis complex: 65.6%
- E. coli: 50.5 to 50.8%
N content% of the bases
- all six: under 0.01%
Sequencescontigs, log scale
- closed genomes: 1
- Sakai: 3
- CDC1551 in 40 contigs
bin/validate_inputs.py, and where the six genomes of the accuracy benchmark sit: inside every range, with no warning.What fails the run#
| Check | Threshold |
|---|---|
| Genome size | below 100 kb, or above 20 Mb |
| N content | above 10% |
| GC content | below 20% or above 80% |
| Empty sequences | any record with no bases |
| Duplicate contig headers | any repeated identifier |
| Sample sheet | missing sampleId or fasta column, no data rows, duplicate or empty sample IDs |
| FASTA path | file does not exist or cannot be parsed |
| Bakta database | not found, or no version.json or bakta.db in it |
| eggNOG database | eggnog_db.ok in it while the database is incomplete, since Nextflow then never builds it again |
| Reference files | --ref_annotation, --ref_genome or a reference argument that the run reads but that is neither on the host nor inside the container |
What only warns#
| Check | Threshold |
|---|---|
| Genome size | below 500 kb, or above 10 Mb |
| N content | above 1% |
| GC content | below 25% or above 75% |
| Assembly fragmentation | more than 100 contigs, and again above 500 |
| Short contigs | any contig under 200 bp in a multi-contig assembly |
| Non-standard characters | anything outside ATGCNRYSWKMBDHV |
| eggNOG database | a bacteria.dmnd under 100 MB, which EGGNOG_DB takes for a truncated download and builds again |
| Mycobrowser table | --mycobrowser_ref neither on the host nor inside the container, so the master table goes without Mycobrowser categories |
Warnings do not stop a run. Add --strict_validation to have them stop it too.
An eggNOG database that does not exist yet is neither: the first run that annotates builds it at --eggnog_db.
The thresholds are deliberately wide, since AMAP is not restricted to tuberculosis. A 4.4 Mb MTBC genome at 65% GC sits comfortably inside them, and so does most of the bacterial world.
Assembly quality#
The correction compares your annotation against a reference proteome, so assembly quality propagates directly into the result.
Contiguity matters. A gene broken across two contigs cannot be recovered. The more fragmented the assembly, the more reference genes turn up as missing rather than corrected.
Ns break coding sequences. A run of Ns inside a gene stops it translating, so it is dropped or flagged as a pseudogene. The 1% warning is worth taking seriously.
Contig names are kept
AMAP runs Bakta with --keep-contig-headers, so the sequence names you supplied are the ones in BAKTA/ and in the corrected annotation, and the corrected tables say which contig each gene is on. Without that option Bakta relabels everything contig_1, contig_2 and so on, and classify_cases.py stops with an error on a multi-contig assembly rather than compare genes across contigs.
Closed genomes are read as circular from their header
Bakta takes a sequence for a complete, circular replicon when the description after its name says so: complete, as NCBI's "complete genome" and "complete sequence" do, or circular=true, as Unicycler's does. It then joins the two ends, and a gene across the origin comes out whole. Lineage typing renames a genome of one sequence after its sample and keeps that description. A closed genome whose header says neither is annotated as linear, and a gene across its origin is cut in two there; add circular=true after its name to have it read as circular.
Draft assemblies
Every contig of a draft assembly is numbered from 1, so the same coordinates turn up on several contigs. The correction keys every gene on its contig as well as its start, end and strand, only ever compares genes on the same contig, and translates each one from its own contig. Cut into 40 contigs, CDC1551 gets every gene that lies within one contig exactly as the closed genome does.
Reference data#
For MTBC you need nothing else. The container bundles the H37Rv proteome, the Bakta light database, the Mycobrowser table and the pathotypr lineage markers. See containers for the full list.
For any other organism, supply your own reference with --ref_annotation and --ref_genome. See custom reference.
Next steps#
- Quickstart: run it
- Parameters: the full flag reference