That page is not here
The link that brought you here points at something that has moved or never existed. Nothing is broken on your side.
+The nearest page: Documentation
+
+
+
+
+
@@ -61,5 +74,89 @@
+
+
+
+
diff --git a/docs/about/changelog.html b/docs/about/changelog.html
index 2337032..faeb877 100644
--- a/docs/about/changelog.html
+++ b/docs/about/changelog.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
That page is not here
-
diff --git a/docs/about/citation.html b/docs/about/citation.html
index 6f0aa83..899cb2c 100644
--- a/docs/about/citation.html
+++ b/docs/about/citation.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/about/contributing.html b/docs/about/contributing.html
index 7bbf99e..a230775 100644
--- a/docs/about/contributing.html
+++ b/docs/about/contributing.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/assets/search-index.js b/docs/assets/search-index.js
index a44967e..c569a52 100644
--- a/docs/assets/search-index.js
+++ b/docs/assets/search-index.js
@@ -1,1239 +1,2 @@
/* Generated by tools/build_docs.py: the documentation, section by section, for the search box. */
-window.AMAP_DOCS_INDEX = [
-{
-"page": "Tutorial",
-"section": "",
-"url": "getting-started/tutorial.html",
-"text": "Every command spelled out, nothing assumed. It uses a real genome you can download in one line, so you can follow along and compare your numbers against the ones printed here. Those numbers come from actual runs of these commands, not from memory, made on 18 October 2026 with AMAP at commit 947a99d. The runs skipped eggNOG, with --skip_functional_annotation. None of the numbers depends on it, and the one table shown here that is written after it was made by hand from the same run, as the sample check explains. The genome is Mycobacterium tuberculosis CDC1551, corrected against the H37Rv refere"
-},
-{
-"page": "Tutorial",
-"section": "1. What you need",
-"url": "getting-started/tutorial.html#1-what-you-need",
-"text": "Nextflow and a container engine. Every tool the pipeline itself calls lives inside the AMAP image, so there is nothing else to install. The easiest way to get Nextflow is Conda. If you do not have it, Miniforge is the one to install: conda create -n nextflow-env -c conda-forge -c bioconda nextflow conda activate nextflow-env Nextflow needs Java 17 or newer. Check what you have: java -version nextflow -version Java 8 is not enough Nextflow will refuse to start on Java 8 with a message about an unsupported class file version. Install a newer JDK, for example conda install -c conda-forge openjdk="
-},
-{
-"page": "Tutorial",
-"section": "The machine",
-"url": "getting-started/tutorial.html#the-machine",
-"text": "Worth checking before you start, because this is what stops a run rather than anything you will have got wrong. Disk goes first. The container is 12 GB unpacked. The eggNOG database is built on first use and cached: AMAP skips the 60 GB Diamond core that eggNOG-mapper would otherwise fetch and builds a bacteria-only index of about 3 GB instead, on top of the metadata it downloads. Nextflow keeps every intermediate under work/, which for one genome is a few GB and grows with the sample sheet. Memory decides whether the run finishes at all. Two steps are heavy: eggNOG annotation 24 50 GB eggNOG "
-},
-{
-"page": "Tutorial",
-"section": "2. Check the plumbing before touching real data",
-"url": "getting-started/tutorial.html#2-check-the-plumbing-before-touching-real-data",
-"text": "The test profile annotates the reference genome that ships inside the container, so it needs no data of your own: nextflow run PathoGenOmics-Lab/AMAP -profile docker,test The first run pulls the AMAP image. It is around 3.4 GB compressed and 12 GB on disk, because it carries the Bakta database and the H37Rv reference files. That is a one-off; later runs reuse it. If this finishes without an error, the whole chain works."
-},
-{
-"page": "Tutorial",
-"section": "3. Get a genome",
-"url": "getting-started/tutorial.html#3-get-a-genome",
-"text": "Make a working directory and fetch an assembly: mkdir amap-tutorial && cd amap-tutorial NCBI=https://ftp.ncbi.nlm.nih.gov/genomes/all/GCF ASM=000/008/585/GCF_000008585.1_ASM858v1/GCF_000008585.1_ASM858v1_genomic curl -sL -o cdc1551.fna.gz \"$NCBI/$ASM.fna.gz\" gunzip cdc1551.fna.gz Have a look at what you got: grep '^>' cdc1551.fna >NC_002755.2 Mycobacterium tuberculosis CDC1551, complete sequence One closed contig, 4,403,837 bp. AMAP takes assembled genomes, so reads are not an input here."
-},
-{
-"page": "Tutorial",
-"section": "4. Write the sample sheet",
-"url": "getting-started/tutorial.html#4-write-the-sample-sheet",
-"text": "A tab-separated file with exactly two columns: printf 'sampleId\\tfasta\\nCDC1551\\t%s/cdc1551.fna\\n' \"$PWD\" > samples.tsv cat samples.tsv sampleId\tfasta CDC1551\t/path/to/amap-tutorial/cdc1551.fna It has to be a real tab Spaces will not do, and this is the single most common reason a sample sheet is rejected. Check with cat -t samples.tsv: real tabs show up as ^I. (cat -A does the same on Linux but is not accepted by the cat that ships with macOS.) Keep sample IDs to letters, digits and underscores. Several scripts cut the name at the first dot, so G26689.1 becomes G26689."
-},
-{
-"page": "Tutorial",
-"section": "5. Validate before committing to a long run",
-"url": "getting-started/tutorial.html#5-validate-before-committing-to-a-long-run",
-"text": "nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv --validate_only The checks write their verdict to results/pipeline_info/validation.log, which ends: tail -n 8 results/pipeline_info/validation.log --- FASTA Validation (1 samples) --- ============================================================ Results: 1 OK, 0 warnings, 0 failed Total: 0 error(s), 0 warning(s) ============================================================ ✓ PASSED — all 1 samples look good This costs seconds and catches the mistakes that would otherwise surface minutes in. Preparing inputs lists eve"
-},
-{
-"page": "Tutorial",
-"section": "6. Run it",
-"url": "getting-started/tutorial.html#6-run-it",
-"text": "nextflow run PathoGenOmics-Lab/AMAP -profile docker --tsv samples.tsv What happens, in order: lineage typing, Bakta annotation, alignment of the H37Rv proteome onto your genome, case classification, correction, eggNOG functional annotation, duplication analysis, pangenome, report. The first run also downloads and builds the eggNOG database, which is several gigabytes and dominates the wall clock. Point --eggnog_db at somewhere persistent so the next run reuses it: nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv --eggnog_db ~/databases/eggnog If the run dies partway,"
-},
-{
-"page": "Tutorial",
-"section": "7. Look at what came out",
-"url": "getting-started/tutorial.html#7-look-at-what-came-out",
-"text": "ls -F results/ AMAP/ BAKTA/ CDS_CASES/ DUPLICATIONS/ PANGENE/ PATHOTYPR/ amap_report.html final_report.html pipeline_info/ A run without eggNOG, like the ones behind this page, has no DUPLICATIONS/, PANGENE/ or final_report.html. Open results/final_report.html first. It is self-contained, so it travels by email. results/amap_report.html goes through the same run question by question, and a run without eggNOG still gets it."
-},
-{
-"page": "Tutorial",
-"section": "Did the correction do anything?",
-"url": "getting-started/tutorial.html#did-the-correction-do-anything",
-"text": "column -t -s$'\\t' results/CDS_CASES/summary/*-summary.tsv Type Number case2 2813 coordinates matched the reference exactly case3 24 coordinates matched, alignment length differed case4 1100 overlapped the reference but disagreed, resolved case1_initial 141 Bakta called it, the reference has nothing t Read that as: of 4077 Bakta calls, 2813 already agreed with the reference, 1100 had to be adjudicated, and 97 reference genes Bakta had missed were rescued. Only 11 of the 141 apparently novel genes survived scrutiny, which is what you would"
-},
-{
-"page": "Tutorial",
-"section": "Sanity check the sample",
-"url": "getting-started/tutorial.html#sanity-check-the-sample",
-"text": "column -t -s$'\\t' results/AMAP//-AMAP.qc.tsv Six of its eleven columns: genome_size n_contigs gc_pct total_cds pseudogene_count coding_density_pct 4403837 1 65.61 4014 123 91.3 65.6% GC and 91.3% coding density are what a healthy MTBC genome looks like. A number well outside that is worth investigating before trusting the rest. This table is written after eggNOG, so a run without it has none. The line above was made by running that step's own script, GET_OUTPUTS, on the corrected genes of the run behind this page, with an eggNOG table that has no rows. "
-},
-{
-"page": "Tutorial",
-"section": "The files you will actually use",
-"url": "getting-started/tutorial.html#the-files-you-will-actually-use",
-"text": "Lineage typing puts the lineage in front of the sample ID, so CDC1551 comes out as L4_CDC1551: Corrected annotation results/AMAP/L4_CDC1551/L4_CDC1551-AMAP.gff3 Same, GenBank results/AMAP/L4_CDC1551/L4_CDC1551-AMAP.gbk Proteins for downstream tools results/AMAP/L4_CDC1551/L4_CDC1551-AMAP.clean.faa Everything known per gene results/AMAP/L4_CDC1551/L4_CDC1551-AMAPmastertable.tsv Tool versions for your methods results/pipeline_info/software_versions.yml Two protein files, and they differ on purpose *-AMAP.faa has one entry per annotated gene, pseudogenes included, so it matches the GFF3 gene for "
-},
-{
-"page": "Tutorial",
-"section": "8. More than one genome",
-"url": "getting-started/tutorial.html#8-more-than-one-genome",
-"text": "Add rows. The pipeline parallelises across samples, and the pangenome and the cross-genome duplication analysis only become meaningful with several: sampleId\tfasta CDC1551\t/data/cdc1551.fna Erdman\t/data/erdman.fna Beijing_1\t/data/beijing_1.fna Past a couple of dozen, move to a cluster: nextflow run PathoGenOmics-Lab/AMAP -profile singularity,slurm \\ --tsv samples.tsv --eggnog_db /shared/databases/eggnog Deployment on HPC covers scratch, shared filesystems and where things should live."
-},
-{
-"page": "Tutorial",
-"section": "9. The same thing for another organism",
-"url": "getting-started/tutorial.html#9-the-same-thing-for-another-organism",
-"text": "Everything above assumed MTBC. For anything else you supply the trusted reference yourself, and turn off the two MTBC-specific steps. Fetch a reference and a sample. Here, E. coli O157:H7 Sakai corrected against K-12 MG1655: NCBI=https://ftp.ncbi.nlm.nih.gov/genomes/all/GCF K12=000/005/845/GCF_000005845.2_ASM584v2/GCF_000005845.2_ASM584v2_genomic SAKAI=000/008/865/GCF_000008865.2_ASM886v2/GCF_000008865.2_ASM886v2_genomic # the reference: annotation plus the genome it describes curl -sL -o ref.gbk.gz \"$NCBI/$K12.gbff. nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv ecoli.tsv "
-},
-{
-"page": "Tutorial",
-"section": "When something goes wrong",
-"url": "getting-started/tutorial.html#when-something-goes-wrong",
-"text": "Nextflow prints the work directory of the failed task. Everything you need is in it: work/ab/cd1234.../ ├── .command.sh the exact script that ran ├── .command.err stderr on its own, almost always the answer └── .exitcode Troubleshooting is organised by the error you are looking at."
-},
-{
-"page": "Tutorial",
-"section": "Where to go next",
-"url": "getting-started/tutorial.html#where-to-go-next",
-"text": "Parameters: every flag and its default How it works: what the correction actually does, and the thresholds behind it Outputs: every file the run produces"
-},
-{
-"page": "Installation",
-"section": "",
-"url": "getting-started/installation.html",
-"text": "AMAP needs two things on your machine: Nextflow, which runs the pipeline, and a container engine, which supplies every tool the pipeline calls. You do not install Bakta, Miniprot, eggNOG-mapper or any of the rest yourself; they all live inside the AMAP image. You also do not need to clone this repository. Nextflow pulls the pipeline straight from GitHub."
-},
-{
-"page": "Installation",
-"section": "1. Nextflow",
-"url": "getting-started/installation.html#1-nextflow",
-"text": "Nextflow needs Java 17 or newer, and Conda brings both: conda create -n nextflow-env conda activate nextflow-env conda install -c bioconda nextflow If you do not have Conda, Miniconda is a lightweight installer. Any other Nextflow installation works equally well, see the Nextflow documentation. AMAP requires Nextflow 24.04 or newer, which is enforced by the pipeline manifest."
-},
-{
-"page": "Installation",
-"section": "2. A container engine",
-"url": "getting-started/installation.html#2-a-container-engine",
-"text": "Pick whichever your machine allows. Docker Best on a laptop or workstation where you have root. Follow the Docker installation guide for your platform. Singularity / Apptainer The usual choice on an HPC cluster, where Docker is normally not permitted. Follow the Apptainer installation guide. Many clusters already provide it as a module: module load singularity # or: module load apptainer"
-},
-{
-"page": "Installation",
-"section": "3. Check the installation",
-"url": "getting-started/installation.html#3-check-the-installation",
-"text": "nextflow -version docker --version # or: singularity --version"
-},
-{
-"page": "Installation",
-"section": "4. Run the test profile",
-"url": "getting-started/installation.html#4-run-the-test-profile",
-"text": "Before pointing AMAP at real data, confirm the whole chain works. The test profile annotates the reference genome bundled in the container, so it needs no data of your own and nothing to download beyond the image: nextflow run PathoGenOmics-Lab/AMAP -profile docker,test The first run downloads the AMAP image, which is several gigabytes because it bundles the Bakta database and the H37Rv reference files. Expect that to take a while. Later runs reuse the cached image. Check inputs before a long run Once you have your own samples, --validate_only checks every FASTA and database path without execu"
-},
-{
-"page": "Installation",
-"section": "Running without a container",
-"url": "getting-started/installation.html#running-without-a-container",
-"text": "Possible but not recommended: you take on installing Bakta, Miniprot, eggNOG-mapper, Diamond, pangene, pathotypr, R and the report packages yourself, and pointing AMAP at each reference file with the reference arguments. The repository ships an environment.yml that reproduces the software stack under Conda: conda env create -f environment.yml conda activate amap You will still need to supply the Bakta database and the reference files, which the container would otherwise provide. See containers for what the image contains."
-},
-{
-"page": "Installation",
-"section": "Next steps",
-"url": "getting-started/installation.html#next-steps",
-"text": "Quickstart: your first real run Preparing inputs: the sample sheet and what makes a genome pass validation"
-},
-{
-"page": "Quickstart",
-"section": "",
-"url": "getting-started/quickstart.html",
-"text": "This walks from an installed Nextflow to an open report. If Nextflow or a container engine is still missing, start at installation."
-},
-{
-"page": "Quickstart",
-"section": "1. Write a sample sheet",
-"url": "getting-started/quickstart.html#1-write-a-sample-sheet",
-"text": "AMAP reads a tab-separated file with two columns, sampleId and fasta: sampleId\tfasta G26689\t/data/genomes/G26689.fasta G26690\t/data/genomes/G26690.fasta The separator must be a real tab. Paths can be absolute, or relative to where you launch Nextflow. See preparing inputs for the details and the checks AMAP runs over them."
-},
-{
-"page": "Quickstart",
-"section": "2. Check the inputs",
-"url": "getting-started/quickstart.html#2-check-the-inputs",
-"text": "Cheap, and it catches the mistakes that would otherwise surface twenty minutes into a run: nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv --validate_only"
-},
-{
-"page": "Quickstart",
-"section": "3. Run it",
-"url": "getting-started/quickstart.html#3-run-it",
-"text": "Pick what you have, and copy the command: Or start from one of these: nextflow run PathoGenOmics-Lab/AMAP -profile docker --tsv samples.tsv Docker nextflow run PathoGenOmics-Lab/AMAP -profile singularity --tsv samples.tsv Singularity nextflow run PathoGenOmics-Lab/AMAP \\ -profile singularity,slurm --tsv samples.tsv SLURM cluster Without a scheduler profile every task is capped at the machine's CPUs and 16 GB, and with the scheduler profiles at 48 CPUs and 128 GB, whichever order the profiles come in; a larger request, such as the 50 GB the eggNOG annotation asks for, is lowered to the cap."
-},
-{
-"page": "Quickstart",
-"section": "4. Read the results",
-"url": "getting-started/quickstart.html#4-read-the-results",
-"text": "Everything lands under results/ unless you set --outdir. The three things to open first: The full interactive report results/final_report.html Corrected annotation, per sample results/AMAP/{sampleId}/*-AMAP.gff3 Protein sequences for downstream tools results/AMAP/{sampleId}/*-AMAP.clean.faa Which protein file do I want? *-AMAP.faa holds every gene, pseudogenes included, so it mirrors the annotation exactly. *-AMAP.clean.faa drops pseudogenes and sequences with internal stop codons, which is what orthology, phylogenomics and dN/dS tools expect. Reach for the clean one unless you specifically ne"
-},
-{
-"page": "Quickstart",
-"section": "5. Resume an interrupted run",
-"url": "getting-started/quickstart.html#5-resume-an-interrupted-run",
-"text": "Nextflow caches completed tasks. If a run dies, restart it with -resume and it picks up where it stopped: nextflow run PathoGenOmics-Lab/AMAP -profile docker --tsv samples.tsv -resume Keep the same parameters. Changing an input invalidates the cache for every task downstream of it, which is what you want, but it does mean the run redoes that work."
-},
-{
-"page": "Quickstart",
-"section": "Common variations",
-"url": "getting-started/quickstart.html#common-variations",
-"text": "A non-MTBC organism. Lineage typing and Mycobrowser are specific to tuberculosis, so turn them off and supply your own reference: nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv \\ --skip_typing --skip_mycobrowser \\ --genus Escherichia --species \"Escherichia coli\" \\ --ref_annotation my_reference.gbk --ref_genome my_reference.fasta See custom reference. Just the corrected genes. If you do not need functional annotation, duplications, the pangenome or the report, stop after the correction step. It is much faster, and leaves the corrected genes as a table wi"
-},
-{
-"page": "Quickstart",
-"section": "Next steps",
-"url": "getting-started/quickstart.html#next-steps",
-"text": "Running AMAP: profiles, schedulers and larger runs Parameters: the full reference How it works: what the correction actually does"
-},
-{
-"page": "Preparing inputs",
-"section": "",
-"url": "getting-started/inputs.html",
-"text": "AMAP takes assembled genomes. It does not do assembly, so reads are not an input here."
-},
-{
-"page": "Preparing inputs",
-"section": "The sample sheet",
-"url": "getting-started/inputs.html#the-sample-sheet",
-"text": "A tab-separated file with a header row and exactly two columns: sampleId\tfasta G26689\t/data/genomes/G26689.fasta G26690\t/data/genomes/G26690.fasta L4_G12345\t./assemblies/L4_G12345.fa sampleId: The name carried through every output directory and file. Must be unique. Lineage typing puts the lineage in front, so G26689 comes out as L4_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 "
-},
-{
-"page": "Preparing inputs",
-"section": "Pre-flight validation",
-"url": "getting-started/inputs.html#pre-flight-validation",
-"text": "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_only Results are written to results/pipeline_info/validation.log."
-},
-{
-"page": "Preparing inputs",
-"section": "What fails the run",
-"url": "getting-started/inputs.html#what-fails-the-run",
-"text": "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 "
-},
-{
-"page": "Preparing inputs",
-"section": "What only warns",
-"url": "getting-started/inputs.html#what-only-warns",
-"text": "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 "
-},
-{
-"page": "Preparing inputs",
-"section": "Assembly quality",
-"url": "getting-started/inputs.html#assembly-quality",
-"text": "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 c"
-},
-{
-"page": "Preparing inputs",
-"section": "Reference data",
-"url": "getting-started/inputs.html#reference-data",
-"text": "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."
-},
-{
-"page": "Preparing inputs",
-"section": "Next steps",
-"url": "getting-started/inputs.html#next-steps",
-"text": "Quickstart: run it Parameters: the full flag reference"
-},
-{
-"page": "Parameters",
-"section": "",
-"url": "user-guide/parameters.html",
-"text": "Every AMAP parameter, what it defaults to, and when you would change it. Run nextflow run PathoGenOmics-Lab/AMAP --help for the same list at the terminal. Pipeline parameters take two dashes (--tsv). Nextflow's own options take one (-profile, -resume)."
-},
-{
-"page": "Parameters",
-"section": "Input and output",
-"url": "user-guide/parameters.html#input-and-output",
-"text": "--tsv Sample sheet with sampleId and fasta columns, tab separated. Not needed with -profile test. file samples.tsv Yes --outdir Directory for results. string results No"
-},
-{
-"page": "Parameters",
-"section": "Skip options",
-"url": "user-guide/parameters.html#skip-options",
-"text": "--skip_typing Skip pathotypr lineage typing. Required for non-MTBC organisms. boolean false --skip_functional_annotation Stop after annotation correction. Skips eggNOG, duplications, pangenome and the report. boolean false --skip_mycobrowser Skip Mycobrowser functional categories. Auto-enabled when --genus is not Mycobacterium and a custom reference is set. boolean false Their effect on the output tree is covered under outputs."
-},
-{
-"page": "Parameters",
-"section": "Annotation",
-"url": "user-guide/parameters.html#annotation",
-"text": "--genus Genus passed to Bakta. string \"Mycobacterium\" --species Species passed to Bakta. string \"Mycobacterium tuberculosis\" Bakta uses these to pick naming conventions and reference sets, so setting them correctly improves the baseline annotation that AMAP then corrects."
-},
-{
-"page": "Parameters",
-"section": "Resources",
-"url": "user-guide/parameters.html#resources",
-"text": "--max_cpus Ceiling on CPUs for any single process. integer the machine's CPUs --max_memory Ceiling on memory for any single process. string 16.GB --max_time Ceiling on wall-clock time for any single process. string 72.h --scratch Use node-local scratch for I/O-heavy processes. On by default in the HPC profiles. boolean false These are ceilings, not requests. Each process asks for what it needs and is then clamped to these values, so lowering them makes AMAP fit a smaller machine rather than making it run faster. The defaults are a single machine's. The HPC profiles raise them to 48 CPUs and 12"
-},
-{
-"page": "Parameters",
-"section": "Validation and information",
-"url": "user-guide/parameters.html#validation-and-information",
-"text": "--validate_only Run input validation and stop. boolean false --strict_validation Stop on validation warnings too, not only on errors. boolean false --help Print the help text and exit. boolean false --version Print pipeline and Nextflow versions and exit. boolean false"
-},
-{
-"page": "Parameters",
-"section": "Custom reference",
-"url": "user-guide/parameters.html#custom-reference",
-"text": "Supply both to annotate any prokaryote against your own trusted annotation. --ref_annotation Trusted reference annotation, GFF3 or GenBank. file null --ref_genome Trusted reference genome, FASTA. file null They must be given together; setting only one is an error. See custom reference for what AMAP does with them."
-},
-{
-"page": "Parameters",
-"section": "Reference and database arguments",
-"url": "user-guide/parameters.html#reference-and-database-arguments",
-"text": "You almost certainly do not need these Every file below ships inside the Docker and Singularity images, under /reference/. Running with -profile docker or -profile singularity picks them up automatically. They exist for running without a container, for swapping in updated reference files, or for adapting the pipeline by hand. --bakta_db Bakta database directory, inside the container or on the host. /data/bakta_db/db-light --eggnog_db Pre-formatted eggNOG database directory. eggnog_db --pathotyper_snps Lineage marker SNPs for pathotypr. /reference/snps_lineages.tsv --pathotyper_ref Reference FA"
-},
-{
-"page": "Parameters",
-"section": "Nextflow options worth knowing",
-"url": "user-guide/parameters.html#nextflow-options-worth-knowing",
-"text": "These belong to Nextflow rather than AMAP, so they take a single dash. -profile Selects execution profiles, comma separated: docker, singularity, slurm, sge, pbs, test. -resume Reuse cached results from the previous run. -work-dir Where intermediate files go. Defaults to ./work, and it gets large. -process.queue Override the scheduler queue or partition. -process.clusterOptions Extra flags passed to the scheduler, such as '--account=mygroup'. See running AMAP for how the profiles combine."
-},
-{
-"page": "Running AMAP",
-"section": "",
-"url": "user-guide/running.html",
-"text": "Nextflow runs the pipeline straight from GitHub, so there is nothing to clone and nothing to keep up to date by hand. nextflow run PathoGenOmics-Lab/AMAP -profile docker --tsv samples.tsv"
-},
-{
-"page": "Running AMAP",
-"section": "Profiles",
-"url": "user-guide/running.html#profiles",
-"text": "A profile is a bundle of settings. You normally combine one container profile with one executor profile. docker container Runs every process in the AMAP Docker image. singularity container Same image via Singularity or Apptainer. standard container No container. Every tool must already be on PATH. slurm executor Submits each process as a SLURM job. sge executor Submits to Sun Grid Engine or Univa Grid Engine. pbs executor Submits to PBS or Torque. lsf executor Submits to IBM Spectrum LSF. test data Small bundled dataset, for checking the installation. highmem resources Raises the ceilings to 4"
-},
-{
-"page": "Running AMAP",
-"section": "On a laptop or workstation",
-"url": "user-guide/running.html#on-a-laptop-or-workstation",
-"text": "nextflow run PathoGenOmics-Lab/AMAP -profile docker --tsv samples.tsv CPUs are auto-detected and memory is capped at 16 GB. Raise both if the machine allows: nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv --max_cpus 8 --max_memory 32.GB A handful of genomes is fine locally. Beyond about twenty, a cluster is worth the setup."
-},
-{
-"page": "Running AMAP",
-"section": "On an HPC cluster",
-"url": "user-guide/running.html#on-an-hpc-cluster",
-"text": "nextflow run PathoGenOmics-Lab/AMAP -profile singularity,slurm --tsv samples.tsv Each process becomes its own scheduler job, with up to 200 running at once, so Bakta, Miniprot and eggNOG parallelise across all your samples. Defaults reach 48 CPUs and 128 GB per job, and every process carries a time limit so nothing sits in the queue forever. To match your site's queues and accounting: nextflow run PathoGenOmics-Lab/AMAP \\ -profile singularity,slurm \\ --tsv samples.tsv \\ --max_cpus 64 --max_memory 256.GB \\ -process.queue long \\ -process.clusterOptions '--account=mygroup' Dep"
-},
-{
-"page": "Running AMAP",
-"section": "Non-MTBC organisms",
-"url": "user-guide/running.html#non-mtbc-organisms",
-"text": "Lineage typing and Mycobrowser categories are specific to tuberculosis. Turn them off and bring your own reference: nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv \\ --skip_typing --skip_mycobrowser \\ --genus Escherichia --species \"Escherichia coli\" \\ --ref_annotation my_reference.gbk --ref_genome my_reference.fasta See custom reference."
-},
-{
-"page": "Running AMAP",
-"section": "Resuming",
-"url": "user-guide/running.html#resuming",
-"text": "Nextflow caches every completed task, so an interrupted run picks up where it stopped: nextflow run PathoGenOmics-Lab/AMAP -profile singularity,slurm \\ --tsv samples.tsv -resume Keep the parameters identical. Changing an input invalidates that task and everything downstream, which is correct behaviour but does mean the work is redone. The cache lives in the work directory, so do not delete it between a run and its resume."
-},
-{
-"page": "Running AMAP",
-"section": "Running only part of the pipeline",
-"url": "user-guide/running.html#running-only-part-of-the-pipeline",
-"text": "--skip_functional_annotation stops after the correction step. You get the corrected genes as a table with their proteins and sequences (*.AMAP.tsv, .faa, .fna) and the case tables, and skip eggNOG, duplications, the pangenome and the report. The GFF3 and GenBank files are written after eggNOG, so they are skipped too. Much faster when the corrected genes are all you are after: nextflow run PathoGenOmics-Lab/AMAP -profile docker \\ --tsv samples.tsv --skip_functional_annotation"
-},
-{
-"page": "Running AMAP",
-"section": "What a run produces",
-"url": "user-guide/running.html#what-a-run-produces",
-"text": "Beyond the results themselves, results/pipeline_info/ holds the execution report, the timeline, the DAG, a trace with per-process resource usage, software_versions.yml with the exact version of every tool, and params.yml with the parameters used. Those last two are what you want when writing up methods."
-},
-{
-"page": "Running AMAP",
-"section": "Next steps",
-"url": "user-guide/running.html#next-steps",
-"text": "Outputs: what every file is Troubleshooting: when a run fails"
-},
-{
-"page": "Outputs",
-"section": "",
-"url": "user-guide/outputs.html",
-"text": "Everything lands under --outdir, results/ by default, in one subdirectory per pipeline stage. {sampleId} below is the sample's name as lineage typing leaves it, L4_G26689 for sample G26689, or the sample ID alone under --skip_typing."
-},
-{
-"page": "Outputs",
-"section": "Where to look first",
-"url": "user-guide/outputs.html#where-to-look-first",
-"text": "The whole analysis, interactive results/final_report.html Each genome and each gene, question by question results/amap_report.html Corrected annotation for a sample results/AMAP/{sampleId}/*-AMAP.gff3 Proteins for downstream tools results/AMAP/{sampleId}/*-AMAP.clean.faa Everything known about every gene results/AMAP/{sampleId}/*-AMAPmastertable.tsv Tool versions for your methods section results/pipeline_info/software_versions.yml"
-},
-{
-"page": "Outputs",
-"section": "The full tree",
-"url": "user-guide/outputs.html#the-full-tree",
-"text": "results/ ├── AMAP/ │ └── {sampleId}/ │ ├── *-AMAP.faa # Corrected proteins, all genes including pseudogenes │ ├── *-AMAP.clean.faa # No pseudogenes, no internal stops │ ├── *-AMAP.fna # Corrected nucleotide sequences │ ├── *-AMAP"
-},
-{
-"page": "Outputs",
-"section": "The key files",
-"url": "user-guide/outputs.html#the-key-files",
-"text": ""
-},
-{
-"page": "Outputs",
-"section": "*-AMAP.gff3 and *-AMAP.gbk",
-"url": "user-guide/outputs.html#-amapgff3-and--amapgbk",
-"text": "The corrected annotation, which is the point of the pipeline. The GFF3 is spec-compliant: gene features parent their CDS features, attributes are URL-escaped, ##sequence-region pragmas are emitted per contig, and eggNOG annotation rides along as Ontology_term, eC_number, COG_category, KEGG_ko, KEGG_Pathway and PFAMs. The sequences are appended after ##FASTA. Two kinds of gene carry marks, written the way NCBI writes them: Pseudogenes have pseudo=true in the GFF3 and /pseudo in the GenBank, with the reason in Note and /note: internal stop codons, a frameshift or lost stop that makes the frame r"
-},
-{
-"page": "Outputs",
-"section": "*-AMAP.faa versus *-AMAP.clean.faa",
-"url": "user-guide/outputs.html#-amapfaa-versus--amapcleanfaa",
-"text": "*-AMAP.faa mirrors the annotation exactly, pseudogenes included, so gene counts match the GFF3. *-AMAP.clean.faa drops the genes AMAP calls pseudogenes, those with pseudo=true in the GFF3, and any sequence with an internal stop codon, and strips the terminal stop. This is the file for orthology, phylogenomics, pangenome tools and dN/dS, all of which expect valid translations. It has fewer sequences than the GFF3 has genes, by design."
-},
-{
-"page": "Outputs",
-"section": "*-AMAPmastertable.tsv",
-"url": "user-guide/outputs.html#-amapmastertabletsv",
-"text": "One row per gene, joining the corrected coordinates, the Bakta annotation, the eggNOG assignment (COG category, description, preferred name, GO, EC, KEGG, PFAMs, CAZy) and, for MTBC, the Mycobrowser functional category. This is the table to load when you want to ask a question about the annotation."
-},
-{
-"page": "Outputs",
-"section": "*-AMAP.qc.tsv",
-"url": "user-guide/outputs.html#-amapqctsv",
-"text": "One row per sample: genome size, contig count, N50, GC%, total CDS, how many of them AMAP calls pseudogenes (those with pseudo=true in the GFF3), hypothetical protein percentage, mean and median gene length, coding density, and the eggNOG annotation rate. Useful for spotting the sample that went wrong."
-},
-{
-"page": "Outputs",
-"section": "CDS_CASES/",
-"url": "user-guide/outputs.html#cds_cases",
-"text": "The audit trail for the correction. Each case table lists the genes that fell into it, so you can see exactly what was changed and why. The correction algorithm explains the cases; *-summary.tsv aggregates the counts across samples and feeds the report. Its last three columns say which sample the counts are for: Sequence is the name its files carry (L4_G26689), Lineage what typing called it (Untyped under --skip_typing) and Sample its ID in the sample sheet (G26689)."
-},
-{
-"page": "Outputs",
-"section": "What a healthy summary looks like",
-"url": "user-guide/outputs.html#what-a-healthy-summary-looks-like",
-"text": "Two real runs, those of the tutorial, to calibrate expectations. On the left, M. tuberculosis CDC1551 against the bundled H37Rv reference. On the right, E. coli O157:H7 Sakai against K-12 MG1655, using a custom reference. case2, exact match 2813 3324 case3, length differs 24 31 case4, resolved conflict 1100 507 case1_kept, genuinely novel 11 1387 rv_missing, rescued 97 133 total_cds before correction 4077 5367 The one number that differs by two orders of magnitude is case 1, and that is biology: CDC1551 is the same species as the reference so almost nothing is genuinely new, while O157:H7 carr"
-},
-{
-"page": "Outputs",
-"section": "PANGENE/pangenome.Rtab",
-"url": "user-guide/outputs.html#pangenepangenomertab",
-"text": "The gene presence/absence matrix of the whole run, the one both reports draw the pangenome from: one row per gene, one column per sample, 1 where pangene found the gene in that sample's genome. Every genome is searched with the same proteins, the reference proteome and the genes no reference gene matches, so a gene with a 1 in every column is one all the samples share. A gene is named after its reference gene (Rv1506c) or, when no reference gene matches it, after one sample's copy of it (L4_CDC1551_01396, the ID in that sample's master table)."
-},
-{
-"page": "Outputs",
-"section": "final_report.html",
-"url": "user-guide/outputs.html#final_reporthtml",
-"text": "Self-contained, so it travels by email. Covers per-sample quality, missing reference genes by lineage, PE/PPE family distribution, KEGG pathways, duplication communities and network topology, the pangenome (core, softcore, shell, cloud, frequency spectrum, presence/absence heatmaps), COG and Mycobrowser distributions, case statistics and the associated tests, plus a searchable master-table explorer."
-},
-{
-"page": "Outputs",
-"section": "amap_report.html",
-"url": "user-guide/outputs.html#amap_reporthtml",
-"text": "One self-contained file, organised by the questions a run raises: how each genome annotated, where genes are missing or broken on the reference, one gene in every genome, what the correction changed, the pseudogenes by lineage, what lies outside the reference, and the functional profile. Written with or without the functional annotation. The interactive report goes through it."
-},
-{
-"page": "Outputs",
-"section": "Effect of the skip options",
-"url": "user-guide/outputs.html#effect-of-the-skip-options",
-"text": "--skip_typing: No PATHOTYPR/ directory. Samples keep their original IDs instead of being renamed by lineage. --skip_functional_annotation: The run stops after correction. No DUPLICATIONS/, PANGENE/ or final_report.html, and AMAP/ holds only the corrected table and sequences, *.AMAP.tsv, *.AMAP.faa and *.AMAP.fna, without the GFF3, the GenBank or the master table. You still get BAKTA/ and CDS_CASES/, including *_corrected.tsv with the corrected coordinates, and amap_report.html, without its eggNOG sections. --skip_mycobrowser: *-AMAP.MycoBrowser.tsv is written empty and the Mycobrowser sections"
-},
-{
-"page": "Outputs",
-"section": "Next steps",
-"url": "user-guide/outputs.html#next-steps",
-"text": "How it works: what produced all this Duplication metrics: reading the network numbers"
-},
-{
-"page": "The report",
-"section": "",
-"url": "user-guide/report.html",
-"text": "Every run ends in one file, results/final_report.html. It is self-contained: all the figures, tables and JavaScript are embedded, so it opens with no network and survives being emailed to someone who has never heard of Nextflow. To see what the sections look like before running anything, open the example report: a rendered report for twelve MTBC genomes across four lineages. The example uses generated data The twelve samples in it are synthetic. The distributions are drawn around a real M. tuberculosis CDC1551 run, so the shapes are representative, but no conclusion should be drawn from the nu"
-},
-{
-"page": "The report",
-"section": "What is in it",
-"url": "user-guide/report.html#what-is-in-it",
-"text": ""
-},
-{
-"page": "The report",
-"section": "Overview",
-"url": "user-guide/report.html#overview",
-"text": "Dataset composition, then a per-sample quality panel: CDS counts, correction rates and missing reference genes. The annotation quality tab carries coding density, hypothetical percentage and genome size, which is where an outlier sample declares itself before you have gone any further."
-},
-{
-"page": "The report",
-"section": "Annotation results",
-"url": "user-guide/report.html#annotation-results",
-"text": "CDS distribution per lineage, the genes with no counterpart in the reference, and the correction summary: how many genes fell into each case and what the adjudication did with them. Read this alongside the correction algorithm. Missing reference genes get both a heatmap, for spotting a gene absent from a whole lineage rather than one sample, and a searchable table."
-},
-{
-"page": "The report",
-"section": "Functional annotation",
-"url": "user-guide/report.html#functional-annotation",
-"text": "COG categories from eggNOG, Mycobrowser functional categories for MTBC, and a comparison against the reference distribution. Each has its own per-category breakdown in counts and percentages, with the statistical tests alongside. PE/PPE gene families get their own section, since they are both the hardest part of an MTBC genome to annotate and usually the most interesting. The pseudogenes close it: how many AMAP called in each sample, lineage by lineage, a sample with none at 0, the same genes the QC table counts and the GFF3 marks pseudo=true. The master table's note column says why each is a "
-},
-{
-"page": "The report",
-"section": "KEGG pathways",
-"url": "user-guide/report.html#kegg-pathways",
-"text": "The most represented metabolic pathways, and how they differ between lineages."
-},
-{
-"page": "The report",
-"section": "Duplications",
-"url": "user-guide/report.html#duplications",
-"text": "Community sizes, cross-genome homologous pairs and the network topology metrics. Duplication metrics explains what each number means."
-},
-{
-"page": "The report",
-"section": "Pangenome",
-"url": "user-guide/report.html#pangenome",
-"text": "Core, softcore, shell and cloud classification, the gene frequency spectrum, and presence/absence heatmaps."
-},
-{
-"page": "The report",
-"section": "CDS statistics",
-"url": "user-guide/report.html#cds-statistics",
-"text": "How many genes fall in each case, lineage by lineage: box and violin plots with Dunn's tests between lineages, the share of each case in every lineage, a heatmap of the means, and a table per case with the count, mean, median and spread of each lineage."
-},
-{
-"page": "The report",
-"section": "Master table explorer",
-"url": "user-guide/report.html#master-table-explorer",
-"text": "Every gene of every sample in one searchable, sortable table, with the functional annotation attached. Useful for answering a specific question without leaving the report."
-},
-{
-"page": "The report",
-"section": "What changes when steps are skipped",
-"url": "user-guide/report.html#what-changes-when-steps-are-skipped",
-"text": "--skip_typing: Everything still renders, but every sample is grouped under Untyped, so the per-lineage comparisons have a single group and the statistical tests drop out. --skip_mycobrowser: The Mycobrowser and PE/PPE sections are omitted. COG, KEGG, pangenome and duplications are unaffected. This is automatic for non-MTBC organisms. --skip_functional_annotation: No report at all. The run stops after correction."
-},
-{
-"page": "The report",
-"section": "Rendering it yourself",
-"url": "user-guide/report.html#rendering-it-yourself",
-"text": "The report is bin/report/report_AMAP.Rmd, rendered by the FINAL_REPORT process. To iterate on it without running the pipeline: python3 bin/report/demo/make_demo.py demo_inputs docker run --rm -v \"$PWD:/w\" -w /w paururo/amap:latest \\ Rscript -e 'rmarkdown::render(\"bin/report/report_AMAP.Rmd\", output_file=\"/w/demo.html\", params=list(version=\"v1.0.1\", cog_file=\"/w/demo_inputs/input_cog.txt\", Keep it self-contained Nothing in the Rmd, header.html or styles.css may point at a remote URL. pandoc will fetch and inline a remote resource when the machine rendering ha"
-},
-{
-"page": "The interactive report",
-"section": "",
-"url": "user-guide/amap-report.html",
-"text": "Next to final_report.html, every run now writes results/amap_report.html: one file that answers, section by section, the questions a run raises. Did each genome annotate well? Where on the reference are genes missing or broken? What happened to one gene in every genome? What did the correction change? Every table filters, sorts and saves as CSV, every figure saves as SVG, and a click on a genome or a gene opens it. It is written with or without the functional annotation. It needs only what the correction leaves, so a run with --skip_functional_annotation, which gets no final_report.html, still"
-},
-{
-"page": "The interactive report",
-"section": "The sections",
-"url": "user-guide/amap-report.html#the-sections",
-"text": "1. Did each genome annotate well? One row per genome: lineage, genome size, contigs and N50, Bakta's calls and AMAP's genes, the share of the reference genes it has, and how many are missing, pseudogenes, partial, found more than once or outside the reference. A value far from those of comparable genomes is flagged (see How a value is flagged). A click on a genome opens it: its numbers, and its genes in each state, each list searchable and saved as CSV. 2. Where on the reference are genes missing or broken? Every reference gene at its place on the reference, one row per genome, the genomes gro"
-},
-{
-"page": "The interactive report",
-"section": "Gene states",
-"url": "user-guide/amap-report.html#gene-states",
-"text": "Each reference gene gets one state in each genome, from the genes that name it in the genome's final annotation, AMAP/
-
diff --git a/docs/deployment/hpc.html b/docs/deployment/hpc.html
index 70740be..089a902 100644
--- a/docs/deployment/hpc.html
+++ b/docs/deployment/hpc.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/deployment/troubleshooting.html b/docs/deployment/troubleshooting.html
index 7c2b30f..2ac6ff5 100644
--- a/docs/deployment/troubleshooting.html
+++ b/docs/deployment/troubleshooting.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/documentation.html b/docs/documentation.html
index e246cee..6ec2675 100644
--- a/docs/documentation.html
+++ b/docs/documentation.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/getting-started/inputs.html b/docs/getting-started/inputs.html
index d576b49..547e148 100644
--- a/docs/getting-started/inputs.html
+++ b/docs/getting-started/inputs.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
diff --git a/docs/getting-started/installation.html b/docs/getting-started/installation.html
index fb12cd6..8ad5d7a 100644
--- a/docs/getting-started/installation.html
+++ b/docs/getting-started/installation.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/getting-started/quickstart.html b/docs/getting-started/quickstart.html
index d39b609..e78a28e 100644
--- a/docs/getting-started/quickstart.html
+++ b/docs/getting-started/quickstart.html
@@ -4,12 +4,12 @@
-
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/user-guide/amap-report.html b/docs/user-guide/amap-report.html
index b6e1a1b..3cc4268 100644
--- a/docs/user-guide/amap-report.html
+++ b/docs/user-guide/amap-report.html
@@ -3,12 +3,12 @@
-
-
diff --git a/docs/user-guide/custom-reference.html b/docs/user-guide/custom-reference.html
index 4062578..5b12c30 100644
--- a/docs/user-guide/custom-reference.html
+++ b/docs/user-guide/custom-reference.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
-
-
-
diff --git a/docs/user-guide/parameters.html b/docs/user-guide/parameters.html
index 103d8d3..1778bee 100644
--- a/docs/user-guide/parameters.html
+++ b/docs/user-guide/parameters.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/user-guide/report.html b/docs/user-guide/report.html
index 889a029..0979b1c 100644
--- a/docs/user-guide/report.html
+++ b/docs/user-guide/report.html
@@ -3,12 +3,12 @@
-
-
+ PathoGenOmics LabGPL-3.0AMAP 1.0.1
diff --git a/docs/user-guide/running.html b/docs/user-guide/running.html
index 5360303..64e485d 100644
--- a/docs/user-guide/running.html
+++ b/docs/user-guide/running.html
@@ -19,9 +19,9 @@
-
+
-
+
Skip to the content
-
diff --git a/tools/build_docs.py b/tools/build_docs.py
index c9f58d4..db2fb7e 100644
--- a/tools/build_docs.py
+++ b/tools/build_docs.py
@@ -25,6 +25,7 @@
from __future__ import annotations
import argparse
+import functools
import html
import json
import re
@@ -38,15 +39,15 @@
# a .md file is built into a page; an .html path is a page written by hand and
# only gets its place in the list.
PAGES = [
- ("Getting started", "getting-started/tutorial.md", "Tutorial", "From an empty folder to a corrected genome, with the numbers of a real run."),
("Getting started", "getting-started/installation.md", "Installation", "Nextflow, a container engine, and running without one."),
- ("Getting started", "getting-started/quickstart.md", "Quickstart", "From an installed Nextflow to an open report."),
+ ("Getting started", "getting-started/quickstart.md", "Quickstart", "The front page's three steps as a page, about 10 minutes once installed."),
+ ("Getting started", "getting-started/tutorial.md", "Tutorial", "One real genome, start to finish, with every number."),
("Getting started", "getting-started/inputs.md", "Preparing inputs", "The sample sheet, the genomes, and the checks run on them."),
("User guide", "user-guide/parameters.md", "Parameters", "Every option, its default, and when to change it."),
("User guide", "user-guide/running.md", "Running AMAP", "Profiles, schedulers and larger runs."),
("User guide", "user-guide/outputs.md", "Outputs", "Every folder and file, and what a healthy run looks like."),
- ("User guide", "user-guide/report.md", "The report", "What each section of final_report.html shows."),
- ("User guide", "user-guide/amap-report.md", "The interactive report", "amap_report.html, question by question, with or without eggNOG."),
+ ("User guide", "user-guide/report.md", "The full report", "What each section of final_report.html shows."),
+ ("User guide", "user-guide/amap-report.md", "The report by question", "amap_report.html, question by question, with or without eggNOG."),
("User guide", "user-guide/custom-reference.md", "Custom reference", "Any organism, against a trusted annotation of your own."),
("How it works", "how-it-works.html", "Step by step, illustrated", "One gene at a time, from Bakta's call to what AMAP keeps."),
("How it works", "how-it-works/index.md", "Overview", "What goes into a decision, and the five outcomes."),
@@ -79,10 +80,13 @@
'l1.4-1.4M17.7 6.3l1.4-1.4"/>'
)
THEME_BOOT = (
- ''
+ ''
)
INLINE_TAGS = re.compile(r"", re.I)
+# What figures.js looks for to draw: a page with none of these needs neither it nor its data.
+FIGURE_HOOK = re.compile(r"\bdata-(fig|inputs|outcomes|metro|dup)(?=[\s=>])")
ALERTS = {"NOTE": "Note", "TIP": "Tip", "IMPORTANT": "Important", "WARNING": "Warning", "CAUTION": "Caution"}
FIGURE_MARK = re.compile(r"^$")
@@ -343,13 +347,260 @@ def strip_front_matter(lines: list[str]) -> list[str]:
return lines
+# ── Inline code ──
+#
+# A chip of code never splits inside a word. Up to SHORT_CODE characters it
+# does not wrap at all; a longer one wraps only at a space or after a /, _ or
+# ., so a path or a long option name comes apart where it reads in pieces.
+# Each piece is a span that does not wrap, with a {html.escape(text)}'
+ return f"{code_pieces(text)}"
+
+
+def chips_in(fragment: str) -> str:
+ """The same treatment for the of a figure written as HTML."""
+ return re.sub(r"([^<]*)", lambda m: code_chip(html.unescape(m.group(1))), fragment)
+
+
+# ── Options ──
+#
+# Every --option of the parameters page has a row there with an id, and a
+# chip of code naming one anywhere else in the docs links to it.
+
+PARAMETERS = "user-guide/parameters.md"
+
+
+@functools.lru_cache(maxsize=None)
+def parameter_rows() -> list[dict]:
+ """The --option rows of the parameters page: flag, section, cells."""
+ rows, section, head = [], "", []
+ for line in (DOCS / PARAMETERS).read_text(encoding="utf-8").splitlines():
+ heading = re.match(r"^##\s+(.*)$", line)
+ if heading:
+ section = heading.group(1).strip()
+ continue
+ if not line.startswith("|"):
+ head = []
+ continue
+ cells = [c.strip() for c in re.split(r"(? set[str]:
+ return {row["flag"] for row in parameter_rows()}
+
+
+def switches() -> set[str]:
+ """Options that take no value: what follows one on a command line is not its value."""
+ return {row["flag"] for row in parameter_rows() if row["cells"].get("Type") == "boolean"} | {"--rm", "--help", "--version"}
+
+
+# Nextflow's own options that take a value.
+NF_VALUED = {"-profile", "-work-dir", "-c", "-r"}
+
+
+# ── Code blocks ──
+
+SHELL = {"bash", "sh", "console", "shell"}
+TOKEN = re.compile(r"""(?:[^\s'"]|'[^']*'|"(?:\\.|[^"\\])*")+|\S+""")
+LONG_TOKEN = 36
+
+
+def open_quote(line: str, quote: str | None) -> str | None:
+ """The quote still open at the end of a line of shell, given the one open
+ at its start."""
+ i = 0
+ while i < len(line):
+ ch = line[i]
+ if quote is None:
+ if ch == "\\":
+ i += 2
+ continue
+ if ch == "#" and (i == 0 or line[i - 1].isspace()):
+ return None
+ if ch in "'\"":
+ quote = ch
+ elif ch == quote:
+ quote = None
+ elif ch == "\\" and quote == '"':
+ i += 2
+ continue
+ i += 1
+ return quote
+
+
+def shell_token(token: str, kind: str) -> str:
+ """One word of a command, which never wraps inside itself; a long path
+ may, after a /."""
+ if len(token) > LONG_TOKEN and "/" in token:
+ pieces = re.findall(r"[^/]*/+|[^/]+", token)
+ inner = "".join(f'{html.escape(p)}' for p in pieces)
+ return f'{inner}'
+ return f'{html.escape(token)}'
+
+
+def shell_line(line: str) -> str:
+ """A line of shell as words: flags (.f), their values (.v), other words
+ (.t) and a comment (.c). The spaces stay between the words, so a long
+ line wraps there and only there."""
+ out, at, tokens = [], 0, list(TOKEN.finditer(line))
+ k = 0
+ while k < len(tokens):
+ m = tokens[k]
+ out.append(html.escape(line[at:m.start()]))
+ word = m.group(0)
+ if word.startswith("#"):
+ out.append(f'{html.escape(line[m.start():])}')
+ at = len(line)
+ break
+ if re.match(r"^--?[A-Za-z]", word):
+ nxt = tokens[k + 1] if k + 1 < len(tokens) else None
+ valued = (
+ (word.startswith("--") and "=" not in word and word not in switches()) or word in NF_VALUED or word.startswith("-process.")
+ )
+ if valued and nxt and not re.match(r"^(-|#|\\$|\||&&|;|>)", nxt.group(0)):
+ value = nxt.group(0)
+ pair = shell_token(word, "f") + html.escape(line[m.end():nxt.start()]) + shell_token(value, "v")
+ out.append(f'{pair}' if len(word) + len(value) < 32 else pair)
+ at = nxt.end()
+ k += 2
+ continue
+ out.append(shell_token(word, "f"))
+ else:
+ out.append(shell_token(word, "t"))
+ at = m.end()
+ k += 1
+ out.append(html.escape(line[at:]))
+ return "".join(out)
+
+
+def shell_html(lines: list[str], prompts: bool) -> str:
+ """Each line of a shell block as a .ln, which wraps with a hanging
+ indent. A line that starts a command gets a $ prompt, which Copy leaves
+ out; a line that carries one on, after a backslash or inside a quote or
+ a loop, does not."""
+ out = []
+ carried = False
+ quote = None
+ depth = 0
+ for n, line in enumerate(lines):
+ stripped = line.strip()
+ indent = len(line) - len(line.lstrip(" "))
+ starts = prompts and stripped and not carried and quote is None and depth == 0 and not stripped.startswith("#")
+ prompt = '$ ' if starts else ""
+ # Inside a quote that spans lines is another program's text (an R
+ # call, say): its words still wrap only between them, uncoloured.
+ body = shell_line(line) if quote is None else re.sub(r"\S+", lambda m: shell_token(m.group(0), "t"), line)
+ style = f' style="--i:{indent}"' if indent else ""
+ end = "\n" if n + 1 < len(lines) else ""
+ out.append(f'{prompt}{body}{end}')
+ quote = open_quote(line, quote)
+ carried = stripped.endswith("\\")
+ if quote is None and not carried and stripped:
+ first = stripped.split()[0]
+ closes = re.search(r"\b(done|fi|esac)\b", stripped)
+ if first in ("for", "while", "until", "if", "case") and not closes:
+ depth += 1
+ elif first in ("done", "fi", "esac"):
+ depth = max(depth - 1, 0)
+ return "".join(out)
+
+
+def tsv_html(lines: list[str]) -> str:
+ """A tab-separated file, with each tab drawn. Copy takes the real tabs."""
+ return "\n".join(
+ '\t'.join(html.escape(cell) for cell in line.split("\t")) for line in lines
+ )
+
+
+CHANGELOG_EMOJI = re.compile("[\U0001F000-\U0001FAFF☀-➿⬀-⯿️]")
+MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
+
+
+def version_heading(text: str) -> tuple[str, str, str]:
+ """A version of the changelog as the page names it: '[1.0.1] - 2026-07-25'
+ becomes ('1.0.1, 25 July 2026', 'v1-0-1', '1.0.1')."""
+ if re.fullmatch(r"\[?Unreleased\]?", text.strip(), re.I):
+ return "On main, not yet released", "unreleased", "Unreleased"
+ m = re.match(r"^\[?([\d.]+)\]?(?:\s*-\s*(\d{4})(?:-(\d{2})-(\d{2}))?)?", text.strip())
+ if not m:
+ return text, slugify(text, {}), text
+ version, year, month, day = m.groups()
+ when = f"{int(day)} {MONTHS[int(month) - 1]} {year}" if day else (year or "")
+ return (f"{version}, {when}" if when else version), "v" + version.replace(".", "-"), version
+
+
+# The room a table has on a 360 px phone (326 px), with a margin for an
+# estimate that runs about 10% wide: measured, tables estimated at 341 fit
+# and those at 391 overflow. Then what a character takes there, code or
+# text, and a cell's padding.
+PHONE_TABLE = 360
+PHONE_CHAR = 7.8
+PHONE_CELL = 20
+
+
+def phone_width(head: list[str], body: list[list[str]]) -> float:
+ """About the narrowest a table can be: each column as wide as its widest
+ word or unbreakable chip, the first column's chips whole."""
+ columns = [0.0] * len(head)
+ for row in [head] + body:
+ for k, cell in enumerate(row[: len(head)]):
+ units = []
+ for m in re.finditer(r"`([^`]+)`", cell):
+ code = m.group(1).strip()
+ if k == 0 or len(code) <= SHORT_CODE:
+ units.append(len(code) + 1.5)
+ else:
+ units.append(max(len(p) for t in code.split() for p in re.findall(r"[^/_.]*[/_.]+|[^/_.]+", t)) + 1.5)
+ units += [len(w) for w in plain(re.sub(r"`[^`]+`", " ", cell)).split()]
+ columns[k] = max([columns[k]] + units)
+ return sum(c * PHONE_CHAR + PHONE_CELL for c in columns)
+
+
+def first_sentence(text: str, limit: int = 160) -> str:
+ m = re.match(r"(.+?[.:])(\s|$)", text)
+ cut = m.group(1) if m else text
+ return cut if len(cut) <= limit else cut[:limit].rsplit(" ", 1)[0] + "..."
+
+
class Renderer:
def __init__(self, source: str):
self.source = source # markdown path relative to docs/, e.g. user-guide/outputs.md
+ self.root = "../" * source.count("/")
+ self.changelog = source == CHANGELOG[0]
+ self.version: tuple[str, str] | None = None # the changelog's version being read: (slug, label)
self.seen: dict[str, int] = {}
self.headings: list[tuple[int, str, str]] = [] # (level, text, slug)
self.sections: list[dict] = [] # for the search index
+ self.extra: list[dict] = [] # search entries of their own: callouts
self.figures: list[str] = []
+ self.words = 0 # of running text, for the reading time
# Links
@@ -373,20 +624,37 @@ def link(self, target: str) -> str:
# Inline
- def inline(self, text: str) -> str:
+ def inline(self, text: str, links: bool = True, whole: bool = False) -> str:
+ """An inline span as HTML. With links, a chip of code that names an
+ option of the parameters page links to its row there; whole keeps
+ every chip on one line, as the name of a table's row."""
keep: list[str] = []
+ unlinked: dict[str, str] = {}
def stash(fragment: str) -> str:
keep.append(fragment)
return f"\x00{len(keep) - 1}\x00"
- text = re.sub(r"(`+)(.+?)\1", lambda m: stash(f"{html.escape(m.group(2).strip())}"), text)
+ def code(m: re.Match) -> str:
+ raw = m.group(2).strip()
+ chip = f'{html.escape(raw)}' if whole else code_chip(raw)
+ flag = raw.split(" ")[0]
+ if links and flag in options() and self.source != PARAMETERS:
+ marker = stash(f'{chip}')
+ unlinked[marker] = chip
+ return marker
+ return stash(chip)
+
+ text = re.sub(r"(`+)(.+?)\1", code, text)
text = re.sub(r"\\([\\`*_{}\[\]()#+\-.!|<>])", lambda m: stash(html.escape(m.group(1))), text)
text = re.sub(r"<(https?://[^>\s]+)>", lambda m: stash(f'{html.escape(m.group(1))}'), text)
text = INLINE_TAGS.sub(lambda m: stash(m.group(0)), text)
def link(m: re.Match) -> str:
label, target = m.group(1), m.group(2).strip().split(" ")[0]
+ # A link's own text keeps its chips plain: no link inside a link.
+ for marker, chip in unlinked.items():
+ label = label.replace(marker, stash(chip))
return stash(f'') + label + stash("")
text = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", link, text)
@@ -403,23 +671,29 @@ def link(m: re.Match) -> str:
def blocks(self, lines: list[str]) -> str:
out: list[str] = []
i = 0
+ # A text block right after a shell block is what that command prints.
+ after_shell = False
while i < len(lines):
line = lines[i]
stripped = line.strip()
if not stripped:
i += 1
continue
+ shell = False
figure = FIGURE_MARK.match(stripped)
if figure:
name = figure.group(1)
if name in DERIVED:
- out.append(DERIVED[name](self, lines))
+ out.append(chips_in(DERIVED[name](self, lines)))
elif name in FIGURES:
- self.figures.append(name)
- out.append(FIGURES[name])
+ # Only a drawing that figures.js draws needs it loaded.
+ if FIGURE_HOOK.search(FIGURES[name]):
+ self.figures.append(name)
+ out.append(chips_in(FIGURES[name]))
else:
raise SystemExit(f"docs/{self.source}: no figure called {name!r}")
i += 1
+ after_shell = False
continue
if stripped.startswith("\n"
+ + (note or "\n")
+ body
+ f'\n'
+ f'\n'
+ (f'\n' if figures else "")
+ "".join(f'\n' for d in data)
+ (f'\n' if figures else "")
+ + tail
+ "\n\n"
)
@@ -1286,60 +1678,115 @@ def source_lines(path: str) -> list[str]:
return strip_front_matter((DOCS / path).read_text(encoding="utf-8").splitlines())
+def version_line(root: str) -> str:
+ """Which AMAP the pages describe: main, while it is ahead of the last release."""
+ ahead = any(name.lower() == "unreleased" and notes for name, notes in releases())
+ version = released()
+ if ahead:
+ return (f'Describes AMAP on main, ahead of {version}: '
+ f'what changed
')
+ return f'Describes AMAP {version}
'
+
+
def doc_page(position: int) -> tuple[Path, str, list[dict]]:
section, path, title, description = PAGES[position]
renderer = Renderer(path)
content = renderer.blocks(source_lines(path))
+ if renderer.changelog:
+ content = content.replace("documented in this file", "documented on this page")
root = "../" * path.count("/")
+ # The changelog's contents are its versions; its categories repeat in each.
+ levels = (2,) if renderer.changelog else (2, 3)
toc = "".join(
f'{html.escape(text)} '
for level, text, slug in renderer.headings
- if level in (2, 3)
+ if level in levels
)
+ h2s = [(text, slug) for level, text, slug in renderer.headings if level == 2]
+ # Under the h1: how long the page takes to read, and below the width where
+ # the contents column shows, the contents themselves, folded.
+ minutes = max(1, round(renderer.words / 200))
+ under = f'\n'
+ if h2s:
+ under += (
+ 'On this page
'
+ + "".join(f'- {html.escape(text)}
' for text, slug in h2s)
+ + "
\n"
+ )
+ end = content.find("")
+ if end >= 0:
+ content = content[: end + 5] + "\n" + under + content[end + 5 :]
+ to_top = '\n' if len(h2s) >= 6 else ""
prev_page = PAGES[position - 1] if position > 0 else None
next_page = PAGES[position + 1] if position + 1 < len(PAGES) else None
- pager = '