irit-mcp: tools for AI agents
irit-mcp is a Model Context Protocol server that gives AI
agents (Claude Code, Claude Desktop and other MCP clients) the irit tools as typed tools. Each call
runs the real sheetgen, leanqc, isotable, seqplan or dblock binary, and is written to a run record
with a replay.sh that repeats the same commands without any AI.
It also wraps thirteen third-party tools, so a whole run is recorded and replayable the same way.
For the microbial isolate path (trim, assemble, annotate, check quality, classify, type, find
resistance genes): fastp, Shovill, Flye, Medaka, Bakta, CheckM2, GTDB-Tk, mlst and AMRFinderPlus,
plus CoverM for the depth of an isolate by read mapping and Kleborate for Klebsiella typing,
virulence and resistance scores. assembly_stats gives QUAST-style assembly statistics (N50, L50,
N90, GC, Ns), computed by isotable.
For metagenomes, from reads to metagenome-assembled genomes (MAGs): MEGAHIT, CoverM and MetaBAT2,
then CheckM2 and GTDB-Tk on the bins. See Third-party tools.
Agents for bioinformatics fail in three documented ways (see
landscape): they invent command-line
flags, they carry on after a tool has refused bad input, and they leave no record that lets a
result be reproduced without the AI. irit-mcp handles each one:
- Invented flags. Every tool has a JSON schema with
additionalProperties: false. An unknown parameter is refused before anything runs, and the error lists the parameters that do exist. Paths must exist, enums and ranges are checked, and database ids follow dblock’s own rules. - Carrying on after a failure. A non-zero exit comes back as an MCP error (
isError: true) with the tool’s stderr and exit status, never as a result the agent could mistake for success. - No record. Every call goes into a run folder: exact argv, tool version, working folder,
SHA-256 of every input and output, times, exit status.
replay.shre-runs the commands and checks each output’s hash against the record.
The server is a thin layer. It runs the binaries as subprocesses, so the CLI stays the single source of truth for what each tool does. The one exception: it links isotable’s output parsers, so the fastp, CheckM2, GTDB-Tk, mlst and AMRFinderPlus values it returns are read exactly as isotable grades them.
Install and register
Section titled “Install and register”Build it (it is a standalone crate for now), and have the irit binaries on PATH or in a folder:
cargo build --release --manifest-path mcp/Cargo.toml # mcp/target/release/irit-mcpcargo build --release -p sheetgen -p leanqc -p isotable -p dblockClaude Code (the server runs in the folder Claude Code was started in):
claude mcp add irit -- /path/to/irit-mcp --bin-dir /path/to/irit/target/releaseAny client that takes a JSON config (Claude Desktop’s claude_desktop_config.json, a project
.mcp.json, …):
{ "mcpServers": { "irit": { "command": "/path/to/irit-mcp", "args": ["--bin-dir", "/path/to/irit/target/release", "--runs-dir", "/data/project/irit-runs"] } }}| Option | Effect |
|---|---|
--bin-dir DIR |
Folder holding the irit binaries (env IRIT_BIN_DIR). Default: search PATH. |
--tool-path NAME=PATH |
Where a third-party tool is (fastp, shovill, flye, medaka_consensus, bakta, checkm2, gtdbtk, mlst, amrfinder, megahit, coverm, metabat2, kleborate, rasusa). Repeatable. Default: search PATH. |
--runs-dir DIR |
Where run records go (env IRIT_RUNS_DIR). Default ./irit-runs. |
--run-id ID |
Name of this session’s run folder. Default <UTC time>-<pid>. The server refuses to start when that folder already holds a record, so a second session can’t overwrite the first one’s. |
--root DIR |
Folder the tools may write in. Default: the server’s working folder. |
--allow-outside-root |
Turn the root check off, so tools can write anywhere the server’s user can. Not recommended. |
Tools run in the server’s working folder, and relative paths in parameters are resolved there.
Where tools may write
Section titled “Where tools may write”Every path a tool would write to must resolve inside the root: sheetgen output and link_into,
leanqc outdir, isotable output and mqc, fastp out1, out2, json and html, Shovill, Bakta and
CheckM2 outdir, GTDB-Tk out_dir and scratch_dir, mlst outfile, json and novel, AMRFinderPlus
output, mutation_all, protein_output and nucleotide_output, dblock.toml and dblock.lock in the project_dir
of dblock_add and dblock_fetch (the folder and each file are checked, since dblock writes
through a symlinked dblock.toml), and dblock_add’s store. “Resolve” means after .. and
symlinks, including a symlink that doesn’t point anywhere yet: qc -> /elsewhere or ../x.csv is
refused, a symlink to a folder inside the root is fine. Absolute paths are accepted if they land
inside the root.
leanqc writes its reports by name into outdir, so a symlink already in that folder
(qc/s_leanqc.json -> /elsewhere) would be written through: the call is refused if any symlink
in outdir resolves outside the root. sheetgen’s link_into is exempt: sheetgen only creates
links there and never writes through an existing one.
A missing folder on the way to an output is created by the server just before the tool runs
(trim/s1_R1.fastq.gz creates trim/; asm/s1 as Shovill’s outdir creates asm/). Only
folders for checked outputs are created, so they are inside the root too; a file standing where
a folder should be (reads.fq/out.json) is refused. The call’s record lists them as dirs, and
replay.sh runs mkdir -p on them before the call, so a replay works from a clean folder.
The run records folder (--runs-dir, ./irit-runs by default, so usually inside the root) is
never a valid target, even with --allow-outside-root: an output of
irit-runs/<run>/replay.sh is refused.
Inputs (FASTQ files, results folders, sheets, schemas, catalogs, project_dir for the read-only
dblock tools) may be anywhere the server can read.
Limits of these checks: they run before the tool starts, so a symlink created or swapped in between (by another process on the machine) is not caught; the server guards against a confused or misled agent, not against a local attacker racing it. Hard links (a file in the root that shares its data with one outside) are not detected.
The dblock store that comes from the environment (DBLOCK_STORE, else $XDG_DATA_HOME/dblock,
else ~/.local/share/dblock) or from a store = line already in dblock.toml is not checked: it
was chosen by whoever set up the machine or project, not by the agent.
Existing outputs are only replaced when the call says so:
- sheetgen
output, isotableoutput/mqc: an existing file (or symlink) is refused unless the call passesoverwrite: true. - leanqc
outdir: a folder that already has entries is refused unlessoverwrite: true; an empty or missing folder is fine. - sheetgen
link_intohas nooverwrite: sheetgen itself refuses to replace a link that points elsewhere. - fastp, mlst and AMRFinderPlus outputs work like sheetgen
output. Shovill, Bakta and CheckM2outdirand GTDB-Tkout_dirwork like leanqcoutdir. Note that CheckM2 empties itsoutdirbefore it writes. dblock_addanddblock_fetchupdatedblock.toml/dblock.lockin place, as dblock does. The transport is stdio; streamable HTTP is not built in yet.
Optional parameters can be left out; the tool’s own default then applies.
sheetgen
Section titled “sheetgen”Sample sheet from folders of FASTQ files (sheetgen).
| Parameter | Type | Meaning |
|---|---|---|
dirs |
list of folders (required) | Folders to scan recursively. |
output |
file | Write the sheet here (inside the root); otherwise it is only returned. |
overwrite |
boolean | Replace output if it exists. Default false. |
format |
nfcore | qiime2 |
Layout when no schema is given. |
pipeline |
owner/name |
Use this pipeline’s schema_input.json from Nextflow’s cache. |
schema |
file | Use this schema. Not together with pipeline. |
set |
object | Fixed column values, e.g. {"strandedness": "auto"}. |
link_into |
folder | Write clean symlinks there and list those. |
name_from_dir, long, relative, no_pair_numeric, allow_merge, allow_unchecked |
booleans | As the CLI flags. |
Returns columns, rows (objects, up to 1,000), row_count and sheetgen’s notes in stderr.
leanqc
Section titled “leanqc”Read QC (leanqc).
| Parameter | Type | Meaning |
|---|---|---|
files |
list of files (required) | FASTQ/FASTA, plain or compressed. |
outdir |
folder | Default leanqc. Inside the root. |
overwrite |
boolean | Allow an outdir that already has files. Default false. |
threads |
1-64 | Files processed at once. |
dup_distinct |
integer | Distinct sequences tracked for duplication. |
phred |
33 | 64 | Quality encoding instead of detecting it. |
no_html |
boolean | JSON and TSV only. |
Returns summary (files and counts per verdict) and per file: verdict, fails and warns
(check name and detail), reads, mean_len, gc_percent, q30_percent, encoding warnings,
and the JSON and HTML report paths. If leanqc exits 0 but no *_leanqc.json report appeared or
changed in outdir, the result is an error (no_reports) rather than an empty summary.
isotable
Section titled “isotable”One graded row per sample (isotable).
| Parameter | Type | Meaning |
|---|---|---|
dirs |
list of folders (required) | Results folders. Include the folder holding Shovill’s outdirs: the assembly statistics come from each contigs.fa, and Shovill’s depth estimate from its shovill.log. |
sheet |
file | Sample sheet to join on (recommended). |
mode |
isolate | mag |
Grading rules. |
output, mqc |
files | Also write the TSV / MultiQC table (inside the root). |
overwrite |
boolean | Replace output / mqc if they exist. Default false. |
require |
list of reads, q30, contigs, n50, completeness, contamination, kraken, gtdb, depth, mlst, amr, kleborate |
Required measurements; [] turns the check off. |
min_reads, max_contigs, min_n50 |
integers | Thresholds. |
min_q30, min_busco, min_completeness, max_contamination |
0-100 | Thresholds (%). |
min_depth |
number | Warn below this mean depth from read mapping (coverm_genome), fail below half. Default 20; 0 turns it off. |
Returns counts per status and samples, each with status, reasons (a list) and values
(the other columns).
assembly_stats
Section titled “assembly_stats”QUAST-style statistics of assembly FASTA files (plain or gzip), computed by isotable
(isotable assembly-stats --json, see isotable). Takes seconds,
and is recorded and replayed like any call (its stdout, the JSON, is hash-checked).
| Parameter | Type | Meaning |
|---|---|---|
assemblies |
list of files (required) | Shovill’s contigs.fa, Flye’s assembly.fasta, a reference genome, … |
min_contig |
integer | Contigs shorter than this are left out of every statistic except contigs_all and length_all. Default 500, QUAST’s default, so the numbers match a QUAST report on the same file. Always passed explicitly, so the record says which cut-off was used. |
Returns assemblies, one object per file: assembly (the path as given), min_contig,
contigs, total_length, largest_contig, n50, l50, n90, l90, gc_percent (G+C over
A+C+G+T), ns_per_100kbp, contigs_1kb (contigs of 1000 bp or more), contigs_all and
length_all (every contig). On the paper redo’s three K. pneumoniae Shovill assemblies it gave
71, 128 and 146 contigs in all and 38, 58 and 55 of 500 bp or more, N50 661,397, 364,313 and
304,235, as reported in the paper redo; Kleborate’s own contig
statistics give the same N50.
seqplan
Section titled “seqplan”Isolates per sequencing run at a target coverage (seqplan). Writes nothing.
| Parameter | Type | Meaning |
|---|---|---|
kit |
kit id (required) | e.g. miseq-v3, nextseq-p1, novaseq-x-1.5b, minion-r10.4.1; seqplan --list-kits lists them. |
reads |
e.g. 2x150 |
Read configuration. Default: the kit’s first listed one. |
organism or genome_size |
preset id, or bp with k/M/G | Exactly one. Presets use NCBI’s expected genome size. |
coverage |
number | Target mean coverage. Default 50. |
usable, imbalance |
numbers | Usable fraction of the run (default 0.8 Illumina, 1.0 nanopore) and barcode-imbalance margin (default 1.3). |
samples |
integer | Isolates to sequence: adds runs needed and cost per isolate for them. |
run_price, currency |
number, label | The user’s own run price. There are no built-in prices. |
Returns plan: bases and read pairs per isolate, the kit’s output range with its basis and
source, and isolates per run, runs and costs at both ends of the range (low, high).
dblock_*
Section titled “dblock_*”Reference databases (dblock). All take project_dir (default: the working folder)
and catalog (extra catalog JSON).
| Tool | Extra parameters | Returns |
|---|---|---|
dblock_catalog |
tool |
databases: id, download, on_disk, description, licence_note |
dblock_add |
ids (required), store |
dblock’s message; dblock.toml in outputs |
dblock_plan |
plan text: free space and fetch mode per database. Downloads nothing, but creates the (empty) store folder if missing, to measure its free space. |
|
dblock_fetch |
confirm (required, must be true), ids, stream, keep_archive |
dblock’s message; dblock.lock in outputs |
dblock_verify |
deep |
report |
dblock_check |
report |
|
dblock_env |
env (variable → path) and shell (export lines) |
reads_verify
Section titled “reads_verify”Runs sheetgen verify on read files or folders. It checks gzip integrity (every
member, CRC and length), FASTQ structure, and MD5/SHA-256 against md5 files or ENA (ena, network,
opt-in; runs names the accession for files whose name has none). The result has the per-file
report. The call is an error (reads_have_problems) when any file is corrupt, doesn’t match, or is
not listed, and the report is still there. The JSON report has timings, so replay.sh re-runs the
check without comparing its output.
cooccur
Section titled “cooccur”Runs cooccur on a genome × sample table (coverm_abundance’s
output). Parameters: table, output (edge list TSV), summary (JSON; default next to the output),
measure, taxonomy (GTDB-Tk summaries, for CPR labels), method (rho or spearman),
min_prevalence, fdr, min_stat, positive_only, seed (default 1, so a replay matches). The
result includes the summary, with the CPR–non-CPR pairs that pass.
gtdbprep_place
Section titled “gtdbprep_place”Runs gtdbprep place: GTDB-Tk tree placement on the laptop data for genomes
gtdbprep_ani didn’t assign. Parameters: genome_dir, extension, work,
skip_assigned (gtdbprep_ani’s work folder), data_path (or $GTDBTK_DATA_PATH), env (GTDB-Tk
2.8.0 with gPlace, or $GTDBPREP_ENV), max_memory (default 6G), cpus. The result lists
place.tsv’s rows. GTDB-Tk’s logs and the gPlace call log are volatile.
Third-party tools
Section titled “Third-party tools”Nineteen tools wrap sixteen programs irit doesn’t ship. Each one is pinned to an upstream version: its
parameters are exactly the flags that version has, read from its source at that release tag (for
Shovill, mlst and AMRFinderPlus also compared with --help of the Bioconda package).
Nothing else is offered, so an agent can’t pass a flag the program doesn’t know.
| MCP tool | Program | Pinned version | Flags read from | Bioconda |
|---|---|---|---|---|
fastp |
fastp | 1.4.0 | src/main.cpp |
fastp=1.4.0 |
shovill |
Shovill | 1.4.2 | bin/shovill (setOptions and the checks after it) |
shovill=1.4.2 |
flye |
Flye | 2.9.6 (--version: 2.9.6-b1802) |
flye/main.py (the argparse block and _check_input) |
flye=2.9.6 |
medaka |
Medaka medaka_consensus |
2.2.2 | scripts/medaka_consensus (its getopts string) |
medaka=2.2.2 |
bakta |
Bakta | 1.12.2 | bakta/utils.py, DB check from bakta/db.py |
bakta=1.12.2 |
checkm2 |
CheckM2 predict |
1.1.0 | checkm2/main.py |
checkm2=1.1.0 |
gtdbtk_classify_wf |
GTDB-Tk classify_wf |
2.8.0 | gtdbtk/cli.py, data folders from config/common.py |
gtdbtk=2.8.0 |
mlst |
mlst | 2.35.0 | bin/mlst (setOptions and the main block) |
mlst=2.35.0 |
amrfinder |
AMRFinderPlus amrfinder |
4.2.7 | amrfinder.cpp, DB files from amrfinder_update.cpp and amrfinder_index.cpp |
ncbi-amrfinderplus=4.2.7 |
megahit |
MEGAHIT | 1.2.9 | src/megahit (parse_option) |
megahit=1.2.9 |
coverm_contig |
CoverM contig |
0.8.0 | src/cli.rs and coverm contig --full-help |
coverm=0.8.0 |
coverm_genome |
CoverM genome |
0.8.0 | src/cli.rs and coverm genome --full-help |
coverm=0.8.0 |
coverm_abundance |
CoverM genome |
0.8.0 | as coverm_genome |
coverm=0.8.0 |
semibin2 |
SemiBin2 single_easy_bin, and multi_easy_bin with multi |
2.6.0 | SemiBin2 single_easy_bin --help, SemiBin2 multi_easy_bin --help and SemiBin/main.py of the Bioconda package |
semibin=2.6.0 |
semibin2_concatenate |
SemiBin2 concatenate_fasta |
2.6.0 | SemiBin2 concatenate_fasta --help and concatenate_fasta in SemiBin/utils.py |
semibin=2.6.0 |
galah |
galah cluster |
0.6.3 | galah cluster --full-help of the Bioconda package (src/cluster_argument_parsing.rs) |
galah=0.6.3 with skani=0.4.0 (but see galah) |
kleborate |
Kleborate | 3.2.4 | kleborate/__main__.py and kleborate --help of the pip package |
kleborate=3.2.4 (but see kleborate: pip is lighter) |
metabat2 |
MetaBAT 2 | 2.18 | metabat2 --help of the Bioconda package (MetaBAT) |
metabat2=2.18 |
rasusa |
Rasusa reads |
5.1.0 | rasusa reads --help of the Bioconda package (src/cli.rs) |
rasusa=5.1.0 |
Bioconda’s current Shovill is 1.4.2, not the older 1.1.0: 1.4.x added --plasmid, changed
--mincov’s default to 2 and needs at least 8 GB for --ram.
How they work:
- Finding the program. The server looks on
PATH, or where--tool-path NAME=PATHsays. If the program isn’t there, the call fails withtool_unavailableand an install hint, e.g.conda install -c conda-forge -c bioconda bakta=1.12.2. Nothing is run. - Versions. The first line of the program’s
--versiongoes into the run record. If the version isn’t the pinned one, the call still runs, but its result has awarningsentry. Every result also hasversionandchecked_against. - Warnings on stderr. Some warnings a tool prints still matter after a zero exit; they go into
warnings(result and record): CheckM2’s scikit-learnInconsistentVersionWarning(models saved with another scikit-learn, which “might lead to … invalid results”) and AMRFinderPlus’sWARNING:lines, and gtdbprep’swarning:lines (a genome left out of the ANI screen). AMRFinderPlus from a conda environment that isn’t activated getsCONDA_PREFIXset to that environment (found from the program’s path), as activation would; the database is always passed with--database, so that doesn’t change which one is used. - Warnings from the outputs. Some results look fine by exit status but aren’t; these also go
into
warnings. All of them were seen in the depth experiment:-
Shovill. Its genome-size estimate collapses at low depth (0.01–0.11 Mb for a 5.5 Mb genome at 5–10×). Shovill then subsamples the reads to that size and assembles a fragment, with exit 0. The server reads
shovill.logand warns in three cases:- Shovill subsampled to a size under 1 Mb, or to more than twice the assembly.
- The assembly is over twice the estimate. Shovill’s depth figure is then too high; the warning gives the real depth over the assembly.
gsizewas given and the assembly is under 70% of it.
A separate warning comes when the depth over the assembly is under 15×.
-
mlst. With no
scheme, mlst picks one by best allele matches. When it then assigns no ST, the scheme may be another species’ (a fragmented K. pneumoniae gotecoli_achtman_4). -
CheckM2. A call with more than 20 genomes warns before running. 48 genomes peaked at 7.7 GiB on an 8 GB laptop.
-
CoverM genome. When the assembly has a
shovill.logbeside it, Shovill’s depth estimate is compared with the mapped depth; a difference of more than 1.5× is a warning (Shovill divides by its own genome-size estimate unless givengsize). -
Kleborate. An assembly with no row (its species check found no species Kleborate types), a species outside the K. pneumoniae species complex under the
kpscpreset, a weak species match, and Kleborate’s own QC warnings (e.g.ambiguous_bases).
-
- Checks before running. Inputs must exist and look right: FASTQ for fastp and Shovill, FASTA for Bakta, CheckM2, GTDB-Tk, mlst and AMRFinderPlus (plain or gzip; bzip2, xz and zstd are refused, and so is an empty file). Databases are checked for the files the program itself needs (below), so a wrong path fails in a second instead of after an hour.
- Databases. Pass the path, or leave it out to use the variable the program reads (
BAKTA_DB,CHECKM2DB,GTDBTK_DATA_PATH,AMRFINDER_DB, as set when the server started). With the variable unset too, the server uses the one database of that kind locked indblock.lockin its working folder, and the result’swarningsnames it; two candidates are refused. The server resolves it before running and records it.dblock_envshows the paths of databases that dblock manages. mlst’s PubMLST schemes come with the installed mlst (or$MLST_DBDIR): the server finds them from the program’s own path and hashes them into the record (below). - Failure. A non-zero exit is
tool_failed, as for the irit tools. An exit status of 0 without the files the program always writes ismissing_outputs: it is recorded as a failed call andreplay.shdoesn’t rerun it. - Results. Each result has a small summary parsed from the outputs (below). fastp, CheckM2,
GTDB-Tk, mlst and AMRFinderPlus outputs are read with isotable’s own parsers. If the summary
can’t be read, the result is an error (
output_unreadable), not an empty list. - Time. Shovill, Bakta, CheckM2 and GTDB-Tk can run for minutes to hours. The call returns when the program ends; an MCP client with a short request timeout may give up first.
- Names isotable can join. isotable finds outputs by name and joins them by sample. Shovill
always writes
<outdir>/contigs.fa, which would make every assembly samplecontigs, so: mlst’soutfilemust containmlstand end in.tsv, and with one assembly the sample part of the name (s1.mlst.tsv→s1) becomes mlst’s--label, the name in its FILE column; AMRFinderPlus’soutputmust containamrfinderand end in.tsv, and isotable takes the sample from it (s1.amrfinder.tsv→s1);coverm_genome’soutputmust containcovermand end in.tsv(s1.coverm.tsv→s1); Kleborate names its rows after the assembly file, sokleboraterefusescontigs.faand other fixed assembler names (use Shovill’slink_as, e.g.genomes/s1.fna). Other names are refused with a message saying why. isotable reads Shovill’scontigs.fa(whenshovill.logis beside it) as the sample named after its folder (asm/s1→s1), so name eachoutdirafter its sample.
The large databases are not hashed into the run record (they are tens of GB). Only their small
version files are: Bakta’s version.json, GTDB-Tk’s metadata/metadata.txt, AMRFinderPlus’s
version.txt. Use dblock_verify to check a database itself. One exception: a GTDB-Tk skani/
database of at most 512 MB, such as the one gtdbprep_ani builds (9 MB for B. subtilis), is
hashed into gtdbtk_classify_wf’s inputs, under the real path of its files, so the record says
exactly which references the ANI screen compared against.
gtdbtk_classify_wf adds a warnings entry (in its result and its record) when data_path is
neither inside a dblock store ($DBLOCK_STORE or the default, or a path in the working folder’s
dblock.lock) nor a folder an earlier call of the same run wrote (gtdbprep_ani’s
<work>/gtdbtk_data). The call still runs, but nothing in the record then says what that folder
held beyond the files above, and replay.sh will use whatever it holds at replay time.
Trims and filters reads, and writes a JSON and an HTML report.
| Parameter | Type | Meaning |
|---|---|---|
in1 |
file (required) | Read 1 FASTQ. |
in2 |
file | Read 2, for paired-end data. |
out1, out2 |
files | Trimmed reads. out2 needs in2 and out1; paired input with out1 needs out2. |
json |
file (required) | JSON report. Name it <sample>.fastp.json so isotable finds it. |
html |
file | HTML report. Default: json with .html. |
overwrite |
boolean | Replace existing outputs. Default false. |
thread |
1-16 | Worker threads. |
compression |
1-9 | gzip level for .gz outputs. |
detect_adapter_for_pe, correction |
booleans | Paired-end only. |
adapter_sequence, adapter_sequence_r2 |
A/C/G/T/N | Adapters, instead of detecting them. |
disable_adapter_trimming, trim_poly_g, disable_trim_poly_g, cut_front, cut_tail, cut_right, dedup, overrepresentation_analysis, phred64 |
booleans | As the fastp flags. |
trim_front1, trim_tail1, cut_window_size (1-1000), cut_mean_quality (1-36), qualified_quality_phred, unqualified_percent_limit (0-100), n_base_limit, average_qual, length_required |
integers | As the fastp options. |
report_title |
text | HTML report title. |
Returns report (JSON and HTML paths) and summary: reads_raw, reads_trimmed,
bases_trimmed, q30_trimmed (%), q30_bases and duplication (%).
Not offered: --stdin, --stdout, --interleaved_in, --unpaired1/2, splitting, UMI and
merging options, and --dont_overwrite (the server enforces overwrite itself).
shovill
Section titled “shovill”Assembles one isolate from paired-end Illumina reads.
| Parameter | Type | Meaning |
|---|---|---|
r1, r2 |
files (required) | Read 1 and read 2 FASTQ (e.g. fastp’s out1, out2). |
outdir |
folder (required) | Output folder; the assembly is <outdir>/contigs.fa. One per sample. |
overwrite |
boolean | Allow an outdir that has files. Default false. |
link_as |
file | Also make this path (e.g. genomes/s1.fna) a relative link to <outdir>/contigs.fa, so CheckM2, GTDB-Tk and gtdbprep_ani name the genome after the sample. Recorded (links) and recreated by replay.sh (ln -sfn). Not inside outdir. |
assembler |
spades, skesa, megahit, velvet |
Default spades. |
gsize |
text | Genome size like 2.8M, 4500K, 5000000. Default: estimated from the reads. |
depth |
integer | Sub-sample to this depth; 0 turns it off. Default 150. |
minlen, mincov |
numbers | Drop short or low-coverage contigs; 0 lets Shovill choose. |
namefmt |
text | Contig names, one counter like s1_%05d. |
cpus |
integer | |
ram |
number, at least 8 | GB; Shovill 1.4.2 refuses less than 8 and more than the machine has. |
plasmid |
boolean | SPAdes plasmid mode (assembler: spades only). |
kmers |
text | Comma-separated k-mer sizes, e.g. 31,55,77. |
trim, noreadcorr, nostitch, nocorr, keepfiles |
booleans | As the Shovill flags. nocorr skips Pilon, the slowest step. |
The server always sends --force (Shovill refuses any existing folder without it, even an empty
one) and refuses an outdir whose absolute path has spaces or shell characters: Shovill pastes it
unquoted into a shell command. Returns contigs_file and assembly: contigs, total_length,
n50, longest and gc_percent, counted from contigs.fa. Every output is volatile:
contigs.fa headers carry the date (date=YYYYMMDD), and neither SPAdes nor SKESA gave the
same assembly twice from identical reads in every test (see the volatile table). The contig
count, total length and N50 go into the run record (assembly), and replay.sh prints the
replayed assembly’s beside them. isotable reads
contigs.fa itself (contigs, length, N50, counted as QUAST does), so give it the folder that
holds the outdirs.
Not offered: --opts (free text pasted into the assembler’s shell command), --tmpdir (Shovill
makes its own), --check.
Assembles one isolate from long reads: ONT R10.4.1 reads basecalled with hac or sup (the default
read_type, nano-hq), older ONT reads, or PacBio. See
Nanopore reads to isolate results on a laptop for a measured run.
| Parameter | Type | Meaning |
|---|---|---|
reads |
list of files (required) | Long-read FASTQ or FASTA files of one isolate (plain or gzip). |
read_type |
nano-hq, nano-raw, nano-corr, pacbio-hifi, pacbio-raw, pacbio-corr |
Default nano-hq. |
outdir |
folder (required) | Output folder; the assembly is <outdir>/assembly.fasta. One per sample. |
overwrite |
boolean | Allow an outdir that has files (Flye then continues from them; prefer an empty folder). |
link_as |
file | As Shovill’s: a link named after the sample to <outdir>/assembly.fasta. |
genome_size |
text | Like 5.5m or 5000000. Needed for asm_coverage. |
asm_coverage |
integer | Use only the longest reads up to this depth for the first stage. Not with meta. |
threads, iterations, min_overlap, read_error |
numbers | As the Flye flags. |
meta, keep_haplotypes, no_alt_contigs, scaffold |
booleans | As the Flye flags. |
deterministic |
boolean | Build disjointigs single-threaded so identical runs give identical assemblies (slower). |
Returns assembly_file, assembly (contigs, total_length, n50, longest, gc_percent)
and contigs: per contig its length, depth and whether Flye closed it into a circle, from
assembly_info.txt. A complete bacterial genome is one circular chromosome plus circular
plasmids. Every output is volatile (multi-threaded runs differ; flye.log has times); the contig
count, length and N50 go into the run record, as for Shovill. isotable reads assembly.fasta when
flye.log is beside it.
Small plasmids. Default mode missed a 4,999 bp resistance plasmid at 11x (chromosome 98x)
that meta found, and Flye closed several small plasmids as two or three copies in one circle.
For each circular contig up to 300 kb, irit-mcp measures how much of its sequence (21-mers) occurs
more than once in it. Above half, it warns that genes there are counted more than once and the
length isn’t the plasmid’s. On the nanopore runs, multi-copy contigs scored 0.92–1.0 and all
others at most 0.2 (measurements).
Deep data. asm_coverage limits only the first stage: the later stages map every read. On
the laptop, K. pneumoniae AF38 (5.7 Mb, 2.58 Gb of reads, about 450x) went over the 8 GB cap in
Flye’s consensus stage with asm_coverage 50 and was killed. Subsample deep data with
rasusa first (this project uses 100x).
Not offered: --extra-params (free text into Flye’s configuration), --resume,
--resume-from, --stop-after, --polish-target, and the deprecated --subassemblies,
--plasmids, --trestle and --hifi-error.
rasusa
Section titled “rasusa”Randomly subsamples reads to a target, for deep long-read data before Flye or to test how results hold at lower depth. Rasusa (Hall, JOSS 2022, doi:10.21105/joss.03941).
| Parameter | Type | Meaning |
|---|---|---|
reads |
list of files (required) | One FASTQ/FASTA file, or read 1 then read 2 of a pair (pairs are kept together). Plain or gzip. |
outputs |
list of files (required) | One per input, same order; .gz gives gzip. |
coverage + genome_size |
number + text | Target depth, e.g. 100 and 5.7mb. |
bases |
text | Target bases, e.g. 570mb. |
num |
integer | Target reads (of each file for a pair). |
frac |
number | Target fraction, above 0 and at most 1. |
seed |
integer | Default 1, so the same call keeps the same reads. |
overwrite |
boolean | Replace existing outputs. |
Give exactly one of coverage, bases, num and frac. With the same seed the output is
byte-identical (checked on 2,000 reads of AHB29: same MD5 twice), so the outputs are not volatile
and replay.sh compares their hashes. Returns output_files.
Not offered: --one-pass / --probability (approximate counts), --strict, alignment formats,
and the compression and format overrides (the file name decides).
medaka
Section titled “medaka”Polishes a long-read draft (Flye’s assembly.fasta) with the same reads, using medaka_consensus.
| Parameter | Type | Meaning |
|---|---|---|
reads |
file (required) | The long reads (FASTQ or FASTA). |
draft |
file (required) | The draft assembly FASTA. |
outdir |
folder (required) | Must be empty; the result is <outdir>/consensus.fasta. |
link_as, overwrite |
file, boolean | As Flye’s; overwrite only replaces the link. |
model |
text | A medaka model, e.g. r1041_e82_400bps_bacterial_methylation. Needed when the read headers don’t name the basecalling model, which is the case for many archive downloads. |
bacteria |
boolean | --bacteria: pick the bacterial model from the read headers. |
threads, batch_size |
integers | As -t and -b. batch_size sets memory use (Medaka’s default 100 peaked at 7.36 GiB on a 6 Mb genome; 50 at 4.78 GiB and 25 at 3.66 GiB, with the same consensus and no slower). Use 50 or 25 on 8 GB machines. |
medaka_consensus is a bash script with short options only, so its arguments are separate words
(-i reads.fq), and a path starting with - gets ./ in front. Its version comes from medaka --version beside it. Returns assembly_file and assembly for consensus.fasta, and
model_file. Medaka downloads a named model the first time it is used (into its package’s
data/ folder), so the server reads the model file Medaka logged (“Using model: …”). It adds that
file to the call’s inputs with its SHA-256, and replay.sh notes it. isotable reads
consensus.fasta when consensus_probs.hdf is beside it, and then leaves out the Flye draft of
the same sample.
Not offered: -f (reuses or replaces old intermediate files; the server wants an empty outdir
instead), -x, -B, -M, -p, -g, -r and -q.
Annotates one genome assembly.
| Parameter | Type | Meaning |
|---|---|---|
genome |
file (required) | Assembly, FASTA. |
db |
folder | Bakta database (with version.json). Default $BAKTA_DB. |
outdir |
folder (required) | Output folder. |
overwrite |
boolean | Allow an outdir that has files. Default false. |
prefix |
name | Output file prefix. Default: the genome file name without its last extension, as Bakta does. |
genus, species, strain, plasmid |
text | Organism. |
translation_table |
11, 4 or 25 | |
gram |
positive, negative, unknown |
Sent as +, -, ?. |
locus, locus_tag |
text | Checked with Bakta’s own rules. |
min_contig_length, threads |
integers | |
complete, keep_contig_headers, compliant, meta |
booleans | As the Bakta flags. |
skip |
list of trna, tmrna, rrna, ncrna, ncrna_region, crispr, cds, pseudo, sorf, gap, ori, filter, plot |
Sent as --skip-<step>. |
The database check follows Bakta 1.12.2’s own: version.json with date, major, minor and
type; major version 6; and all the files Bakta opens, including psc.dmnd (full) or
pscc.dmnd (light). dblock’s bakta-db-v6-full and bakta-db-v6-light pass.
The server always sends --force (Bakta refuses an existing folder without it), and always sends
--prefix, so the output names are known. Returns summary_file and summary, the numbers from
<prefix>.txt: sequences (length, count, gc, n50, …), annotation (cdss, trnas, rrnas,
hypotheticals, …) and bakta (software and database version).
Not offered: --proteins, --hmms, --regions, --replicons, --prodigal-tf, --tmp-dir,
--debug, --verbose.
checkm2
Section titled “checkm2”Completeness and contamination of genomes or MAGs (checkm2 predict).
| Parameter | Type | Meaning |
|---|---|---|
genomes |
list of files | FASTA files. Give this or genome_dir. |
genome_dir |
folder | Folder of FASTA files. |
extension |
text | With genome_dir: which files. Default .fna. |
outdir |
folder (required) | Output folder. |
overwrite |
boolean | Allow an outdir that has files. CheckM2 then deletes them first. |
db |
file or folder | The DIAMOND .dmnd file, or a folder with exactly one. Default $CHECKM2DB. |
threads |
integer | |
model |
auto, general, specific, both |
both is --allmodels. |
lowmem |
boolean | Less RAM, slower. Use on 8-16 GB machines. |
ttable |
integer | Translation table, from the list CheckM2 accepts. |
genes, remove_intermediates |
booleans | As the CheckM2 flags. |
The server always sends --force, since CheckM2 refuses a non-empty folder without it. Returns
report (the quality_report.tsv path) and genomes: genome, completeness, contamination.
gtdbtk_classify_wf
Section titled “gtdbtk_classify_wf”GTDB taxonomy for the genomes in a folder.
| Parameter | Type | Meaning |
|---|---|---|
genome_dir |
folder (required) | One genome per file. |
extension |
text | Default fna; use fna.gz for gzipped files. |
out_dir |
folder (required) | Output folder. |
overwrite |
boolean | Allow an out_dir that has files. |
data_path |
folder | GTDB-Tk reference data (the release folder). Default $GTDBTK_DATA_PATH. Sent to GTDB-Tk as GTDBTK_DATA_PATH and recorded in env. |
prefix |
name | Default gtdbtk. |
cpus, pplacer_cpus |
integers | Use pplacer_cpus: 1 on a laptop. |
scratch_dir |
folder | pplacer writes a memory-mapped file here: much less RAM, slower. |
full_tree, place_species, keep_intermediates, write_single_copy_genes, genes |
booleans | As the GTDB-Tk flags. |
force |
boolean | GTDB-Tk’s --force: carry on when one genome fails. It does not mean overwrite. |
min_af |
0-1 | Minimum alignment fraction for a species match. |
min_perc_aa |
0-100 | Minimum % of amino acids in the MSA. |
The data check reads metadata/metadata.txt (it must have VERSION_DATA) and wants the folders
classify_wf reads: markers, masks, metadata, mrca_red, pplacer, radii, split,
taxonomy and skani.
Returns summary_files and genomes: genome, gtdb (classification) and, when GTDB-Tk filled
them, classification_method, closest_genome_reference, closest_genome_ani, msa_percent,
warnings and note. Only summaries written by this call are read, so a stale ar53 file from an
earlier run is ignored.
Laptop options in GTDB-Tk 2.8.0, checked against the research notes:
--scratch_dirand--pplacer_cpusexist, and are offered.- No
--skip_ani_screen. Since 2.7, classify_wf always runs the skani ANI screen first, and no command-line option skips it. So the placement-only data (dblockgtdbtk-r232-placement, noskani/) can’t run classify_wf by itself: the server refuses it and points togtdbprep_ani, whose<work>/gtdbtk_dataadds a small skani database, and to the placement test for genomes the screen doesn’t assign. - The split tree needs its files. Unless
full_treeis set, the data must holdsplit/backbone/pplacer/gtdbtk_package_backbone.refpkgandsplit/class_level/tree_mapping.tsv. Without them pplacer would fail after the ANI screen and marker steps, so the server refuses first. GTDB’s mock database has an emptysplit/and needsfull_tree: true. - No
--max_memory. That is a gPlace option. GTDB-Tk calls pplacer by name, so gPlace is used through applacershim onPATH(see the same page), not through a GTDB-Tk flag. --mash_dbwent away in GTDB-Tk 2.5.0 (skani replaced Mash) and isn’t offered.
gtdbprep_ani
Section titled “gtdbprep_ani”The laptop route to a GTDB species: gtdbprep ani screens the
genomes locally, fetches only the reference sketches skani would compare (into a per-user cache),
and runs GTDB-Tk’s own ANI screen on them. It needs GTDB-Tk 2.8 with skani 0.3.1, the screen index
and the placement-lite data, not the 85 GB skani database. This is an irit binary, so it comes from
--bin-dir or PATH like sheetgen.
| Parameter | Type | Meaning |
|---|---|---|
genome_dir |
folder (required) | One genome per file; the file name is the genome’s name. |
extension |
text | Default fna. |
index |
folder | Screen index: meta.json, refs.bin, markers.idx (dblock gtdbtk-r232-ani-screen). Default: the ANI-screen index locked in ./dblock.lock. |
data_path |
folder | GTDB-Tk data with taxonomy/, radii/, metadata/ (dblock gtdbtk-r232-placement-lite). Default $GTDBTK_DATA_PATH; sent as --data. |
work |
folder (required) | Work folder inside the root. |
overwrite |
boolean | Allow a work folder that has files. |
source |
text | Where sketches missing from the cache come from: a path or URL of an unpacked sketches.db, a URL with {part} (with part_size), or gtdb (range reads of GTDB’s own archive). Network; ask the user first. Omit when everything is cached. |
part_size |
integer | Bytes per part, for a {part} source only. |
cache |
folder | Default $XDG_CACHE_HOME/irit/gtdbprep-ani, else ~/.cache/irit/gtdbprep-ani, resolved when the server starts and sent as --cache. |
skani |
file or name | Default: skani in the GTDB-Tk environment or on PATH. |
species_only |
boolean | Fetch only references that could give the species call: same species, fewer downloads. |
fetch_jobs |
1-16 | Range requests at once. |
env |
folder | Conda/micromamba environment with GTDB-Tk 2.8. Default $GTDBPREP_ENV; sent as --env. |
cpus |
integer | Default 4. |
The sketch cache may be outside the root, unlike other outputs: it is shared by every run on the
machine, and gtdbprep only adds sketches it has checked against the index. It may not be inside
the run records. The record hashes the genomes, the index’s meta.json and refs.bin (not the
1.7 GB markers.idx: dblock verify covers it) and the three data files the screen reads.
*.log and the gzip file are volatile; everything else in work was identical in two runs.
The cache isn’t part of the record, so on another machine replay.sh fetches the sketches again
from the recorded --source (GTDB’s server for gtdb), or fails without one; a comment above the
call in replay.sh says which. When sketches are missing and no source is given, the error says
how many and how many MB, so the network use can be weighed before allowing it.
Returns genomes (per genome: assigned_by_ani, species, taxonomy, reference, ani, af,
markers, candidates, and used with species_only; a genome skani could not sketch has
screened: false and a note), warnings, stdout (gtdbprep’s own lines: sketches
cached and fetched, times) and data_path_for_classify. That folder, <work>/gtdbtk_data, is a
complete GTDB-Tk data folder: links to the placement-lite data plus the small skani database.
Passed as gtdbtk_classify_wf’s data_path, it gives GTDB-Tk’s usual summary files, and since
it is an output of a recorded call, the record shows where it came from:
{"name": "gtdbprep_ani", "arguments": {"genome_dir": "genomes", "index": "/db/gtdbtk-r232-ani-screen/ani-screen-r232", "work": "ani/w", "species_only": true}}{"name": "gtdbtk_classify_wf", "arguments": {"genome_dir": "genomes", "data_path": "ani/w/gtdbtk_data", "out_dir": "gtdbtk", "pplacer_cpus": 1}}On the B. subtilis 168 assembly from the laptop run, with every
sketch cached: gtdbprep_ani took 15 s (s__Bacillus subtilis, GCF_000009045.1, ANI 100), then
gtdbtk_classify_wf 4.8 s (classification_method: ani_screen). After deleting both output
folders, replay.sh recreated them and matched all 32 outputs.
A genome the screen does not assign still needs tree placement, which classify_wf on this data
can’t do on a laptop yet (gPlace through a pplacer shim; see
the placement test).
Multi-locus sequence type of assemblies, with the PubMLST schemes bundled with mlst.
| Parameter | Type | Meaning |
|---|---|---|
contigs |
list of files (required) | Assemblies, FASTA. Usually one: Shovill’s contigs.fa. |
outfile |
file (required) | Tab-separated table. Must contain mlst and end in .tsv; name it <sample>.mlst.tsv. |
overwrite |
boolean | Replace existing outputs. Default false. |
label |
text | Name in the FILE column instead of the path; one assembly only. Default: the sample part of outfile. |
json, novel |
files | Also write JSON / novel alleles (FASTA). |
scheme |
name | Force a scheme, e.g. saureus, ecoli_achtman_4 (mlst then sets minscore to 0). |
full |
boolean | Header row plus STATUS and SCORE columns; isotable reads this layout too. |
minid, mincov, minscore |
0-100 | As the mlst options. |
threads |
integer | BLAST threads. |
Returns outfile and results, one per assembly: sample (the name isotable joins on), file,
scheme, st and alleles (with full: the table’s own columns). mlst marks a novel allele ~
and a partial one ?, and gives ST - when no scheme matched. database_version is the date in
the data’s VERSION.txt (2025-12-29 for Bioconda’s mlst 2.35.0).
The PubMLST data mlst types with is part of the record. mlst 2.35.0 reads it from $MLST_DBDIR, or
else from db/ next to the real path of the mlst script (Bioconda’s layout). After locating the
program, the server asks it where (mlst --help prints the resolved --datadir and --blastdb, so
a wrapper script in front of mlst is followed; if it prints none, db/ next to the program’s real
path is used) and hashes VERSION.txt, scheme_species_map.tab, the BLAST database of every
allele (blast/mlst.fa.*) and each scheme’s profile table (pubmlst/<scheme>/<scheme>.txt): about
180 files. The allele files themselves are covered by the BLAST database built from them. A set
$MLST_DBDIR is recorded and exported by replay.sh.
Not offered: --csv and --legacy (isotable reads the tab-separated layout), --blastdb and
--datadir (the schemes come with the installed mlst, or $MLST_DBDIR), --fofn, --exclude, and the listing
options (--list, --longlist, --info, --check).
amrfinder
Section titled “amrfinder”Antimicrobial resistance genes and point mutations with AMRFinderPlus.
| Parameter | Type | Meaning |
|---|---|---|
nucleotide |
file | Assembly, FASTA. |
protein |
file | Proteins, FASTA (e.g. Bakta’s <prefix>.faa). Give nucleotide, protein or both. |
gff |
file | Protein locations (e.g. Bakta’s <prefix>.gff3). Needs protein; required with both inputs. |
annotation_format |
bakta, genbank, microscope, patric, pgap, prodigal, prokka, pseudomonasdb, rast, standard |
Which tool wrote the GFF. Needs gff. |
database |
folder | AMRFinderPlus database. Default $AMRFINDER_DB. |
organism |
name | E.g. Escherichia, Staphylococcus_aureus: point mutations and organism-specific genes. Checked against the database. |
plus |
boolean | Also virulence, stress and other “plus” genes. |
report_common |
boolean | Needs organism and plus. |
report_all_equal, print_node |
booleans | As the flags. |
ident_min |
-1 or 0-1 | -1 (default): curated cut-offs. |
coverage_min |
0-1 | Default 0.5. |
translation_table |
1-33 | Default 11. |
name |
text | Adds a first Name column with this text. |
output |
file (required) | Report. Must contain amrfinder and end in .tsv; name it <sample>.amrfinder.tsv. |
mutation_all, protein_output, nucleotide_output |
files | Need organism, protein, nucleotide respectively. |
threads |
integer | |
overwrite |
boolean | Replace existing outputs. Default false. |
The database check follows amrfinder 4.2.7’s own: the folder has version.txt and the other files
amrfinder_update downloads (AMR.LIB, AMRProt.fa, AMR_CDS.fa, fam.tsv, taxgroup.tsv,
…); it is indexed (AMRProt.fa.phr, AMR.LIB.h3m, AMR_CDS.fa.nin, and with organism and a
nucleotide input the organism’s AMR_DNA-<organism>.fa BLAST index); database_format_version.txt
is not newer than 4.2.7; and the data version is at least 2025-09-22.2 (dataVer_min in
amrfinder.cpp). An unindexed folder (the raw files from NCBI) is refused with a hint to run
amrfinder_index or to fetch it with dblock, which indexes it. dblock’s
amrfinderplus-db-4.2-2026-10-29.1 passes.
Returns database_version, report and summary: amr_genes (what isotable reports),
counts_by_type (AMR, STRESS, VIRULENCE, …) and hits, each with element_symbol,
element_name, type, subtype, class, subclass, method, contig_id or protein_id,
coverage_of_reference and identity_to_reference.
Not offered: --update and --force_update (they change the database outside the record; fetch
a pinned one with dblock instead), --blast_bin, --hmmer_bin, --pgap, --gpipe_org, --parm
(NCBI’s testing options), --debug, --log, --quiet, --list_organisms, --database_version
and --nucleotide_flank5_output / _size.
kleborate
Section titled “kleborate”Typing of Klebsiella (and Escherichia) assemblies with Kleborate 3. The default kpsc preset
(K. pneumoniae species complex) runs Kleborate’s species check (Mash), then MLST, the
yersiniabactin (ybt), colibactin (clb), aerobactin (iuc), salmochelin (iro) and rmpADC loci, rmpA2,
the virulence and resistance scores, acquired resistance genes and mutations, a ciprofloxacin
prediction, wzi and Kaptive’s K and O loci. Needs mash and minimap2 on PATH.
| Parameter | Type | Meaning |
|---|---|---|
assemblies |
list of files (required) | FASTA (plain or gzip), named after the samples: Kleborate names each row after the file without its extension. contigs.fa, assembly.fasta and the like are refused; two files with the same name too. |
outdir |
folder (required) | Output folder; an existing one with files needs overwrite. |
preset |
kpsc, kosc, escherichia |
Default kpsc (unless modules is given alone). escherichia runs ECTyper, whose first run downloads about 900 MB. |
modules |
list of module names | More modules, or (without preset) only these; kleborate --list_modules lists them. Kleborate then names its table <first module>_output.txt, which isotable doesn’t read. |
overwrite |
boolean | Default false. |
Kleborate 3.2.4 writes each assembly to the table of its species, whatever the preset:
klebsiella_pneumo_complex_output.txt (KpSC), klebsiella_oxytoca_complex_output.txt or
escherichia_output.txt; typing columns of a species the preset doesn’t cover say Not Tested.
An assembly of any other species gets no row (Kleborate prints “does not match any specified
species” and skips it). So no table is required of a call; the result’s warnings name the
assemblies without a row, and those outside the KpSC under kpsc.
Returns tables (the ones the call wrote) and assemblies, one object per row: strain, table,
species, species_match, QC_warnings, ST, virulence_score, resistance_score,
num_resistance_classes, num_resistance_genes, Yersiniabactin/YbST, Colibactin/CbST,
Aerobactin/AbST, Salmochelin/SmST, RmpADC/RmST, rmpA2, K_locus, K_type,
K_locus_confidence, K_locus_identity, the same four for the O locus, and amr: the resistance
columns that found something (e.g. Bla_ESBL_acquired: CTX-M-15). - means not found.
Kleborate’s databases ship inside its Python package (kleborate/modules/*/data: Mash sketches,
MLST alleles and profiles, AMR genes) and Kaptive’s (kaptive/data, the K and O locus references).
The server finds them from the program’s path (<prefix>/lib/python3.*/site-packages, following a
shell wrapper that execs the real script) and hashes them into the record with Kaptive’s
METADATA (its version): 117 files for the pip install. bundled_data_files_hashed says how many;
when none are found, a warning says so.
Install: Bioconda’s kleborate=3.2.4 also installs ECTyper, whose post-link script downloads a
900 MB Mash sketch. pip’s (pip install kleborate==3.2.4) doesn’t, but needs pandas added and
Kaptive 3.2.x: Kleborate 3.2.4 imports kaptive.database, which Kaptive 3.3 no longer has
(pip install kleborate==3.2.4 kaptive==3.2.2 pandas, with mash and minimap2 from Bioconda), as
the real-tools workflow does. --outdir is passed as a word of its own: Kleborate looks for
--outdir in its arguments before parsing them and refuses --outdir=x.
Measured on the laptop (2026-11-14, pip install, 4 GB cap): 34-40 s per K. pneumoniae assembly.
BfR-EC-20867 from the paper redo: K. pneumoniae (strong match),
ST716 (the paper’s), ybt 14 on ICEKp12 (the paper reports ybt in this isolate) and no clb, iuc, iro
or rmpADC, virulence score 1, resistance score 1, K locus KL110 and O locus OL2α.1 (both
“Typeable”). Its resistance genes match Table 1 except blaTEM-1, which Kleborate didn’t report.
Two runs gave byte-identical tables (replay.sh matched them). Not offered: --resume,
--trim_headers (isotable reads either; full headers name the module) and the per-module options
of --help_all.
megahit
Section titled “megahit”Assembles a metagenome (one sample, or several as a co-assembly) for binning. Writes
<outdir>/final.contigs.fa.
| Parameter | Type | Meaning |
|---|---|---|
r1, r2 |
lists of files | Paired reads (FASTQ, plain or gzip), paired in order. Several runs of one sample go in one call. |
single |
list of files | Single-end or merged reads. |
outdir |
folder (required) | Output folder; an existing one with files needs overwrite. |
memory_gb |
number, 0.5-4096 | Memory for building the de Bruijn graph. Default 4: MEGAHIT’s own default is 90% of the machine’s RAM, which ignores a memory cap (cgroup, container) and gets the process killed under one. Keep it below the cap. Passed in bytes, since a value below 1 would be read as a fraction. |
threads |
integer | MEGAHIT’s default is every logical CPU. |
presets |
meta-sensitive or meta-large |
MEGAHIT’s presets (more k-mers for low-coverage members; or large, complex samples such as soil). |
k_list |
text | Ascending odd k-mer sizes in 15-255, steps of at most 28, e.g. 21,29,39,59,79,99,119,141. |
min_contig_len, min_count |
integers | Shortest contig written (default 200); minimum (k+1)-mer multiplicity (default 2). |
The server always sends --force (MEGAHIT refuses any existing folder without it, even an empty
one; it only skips that check) and refuses a read file with a comma in its name (MEGAHIT splits
the lists on commas). Every output is volatile, as with Shovill: the log has times, and the
contigs aren’t known to be byte-identical between runs. The contig count, length and N50 are
recorded instead, and replay prints them beside the replayed assembly’s. Not offered:
--continue, --tmp-dir (MEGAHIT writes under outdir), --keep-tmp-files, --no-hw-accel,
--mem-flag and the graph-cleaning options.
The bins’ taxonomy: gtdbprep_ani assigns bins of known species. GTDB-Tk’s classify_wf can’t
place the rest on dblock’s gtdbtk-r232-placement-lite data: it always aligns against GTDB’s
reference MSA, which placement-lite leaves out, and fails with msa/gtdb_r232_bac120.faa does not exist. Until that is solved, place them with the full GTDB-Tk data, or outside irit-mcp with
gtdbtk identify, gtdbtk align --skip_gtdb_refs and classify with the ANI screen skipped (see
the MAG laptop test).
coverm_contig
Section titled “coverm_contig”Maps each sample’s reads to the contigs and writes a per-contig coverage table. With methods: ["metabat"] the table is MetaBAT2’s depth input (contigName, contigLen, totalAvgDepth, then
depth and variance per sample). CoverM then counts only reads of at least 97% identity, as
MetaBAT’s own jgi_summarize_bam_contig_depths does.
| Parameter | Type | Meaning |
|---|---|---|
reference |
file (required) | Contigs, FASTA: MEGAHIT’s final.contigs.fa. |
r1, r2 |
lists of files | One read pair per sample. Each pair is a column; more samples help binning (differential coverage). |
single |
list of files | Single-end FASTQ, one per sample (ENA serves some runs only that way); a column each, after the pairs. Give r1/r2, single, or both. |
output |
file (required) | The table (TSV). |
mapper |
strobealign (default), minimap2-sr, bwa-mem |
The aligner CoverM runs. |
methods |
list | mean (CoverM’s default), trimmed_mean, covered_fraction, covered_bases, variance, length, count, reads_per_base, rpkm, tpm, or metabat on its own. |
min_read_percent_identity, min_read_aligned_percent |
percentages | Read filters. |
threads |
integer | CoverM’s default is 1. |
bam_cache_dir |
folder | Also keep each sample’s BAM (--bam-file-cache-directory): <folder>/<reference file name>.<read 1 file name>.bam, sorted by coordinate. These are the bams of semibin2. Two samples whose read 1 files have the same name are refused (they would share a BAM). |
Returns the number of contigs in the table and, per sample, the reads mapped and their percentage
from CoverM’s log, and the BAM paths with bam_cache_dir. A cached BAM’s header records the
temporary folder CoverM sorted in (samtools sort -T /tmp/coverm_fifo.<random>/...), so its bytes
differ between identical runs: BAMs are volatile outputs, and replay.sh says that a later call
read a BAM that differs (the alignments don’t). Measured (2026-11-14, this project’s laptop, 8 GB
cap, 6 threads): the Crystal Geyser sample’s 9.7 million trimmed reads with bam_cache_dir in
104 s at 4.69 GiB (cgroup peak), a 1.05 GB BAM; the depth table was byte-identical to the one of the
earlier run without the cache. Not offered: BAM input (--bam-files),
--cache-unfiltered-bam-files, --discard-unmapped, the --*-params options (free text passed to
the aligner), sharding and pre-built indexes.
coverm_genome
Section titled “coverm_genome”The depth of an isolate by read mapping: maps the isolate’s paired reads to its own assembly
(coverm genome --single-genome, all contigs one genome) and writes a table of the mean depth and
the fraction of the assembly covered. Shovill’s own figure (“Estimated sequencing depth”) is read
bases over the genome size it used, its own k-mer estimate unless gsize was given; in the
depth experiment it was about 3× too high at 20× without gsize.
| Parameter | Type | Meaning |
|---|---|---|
assembly |
file (required) | The isolate’s assembly, e.g. Shovill’s contigs.fa. |
r1, r2 |
files (required) | The isolate’s reads (FASTQ, plain or gzip), e.g. fastp’s trimmed reads. |
output |
file (required) | The table (TSV). Must contain coverm and end in .tsv; name it <sample>.coverm.tsv. |
mapper |
strobealign (default), minimap2-sr, bwa-mem |
The aligner CoverM runs. |
min_read_percent_identity, min_read_aligned_percent |
percentages | Read filters. Default 0. |
threads |
integer | CoverM’s default is 1. |
overwrite |
boolean | Default false. |
The methods are fixed: mean (CoverM’s mean leaves out 75 bp at each contig end) and
covered_fraction. --min-covered-fraction=0 is always passed: CoverM’s default (10%) reports a
genome covered less than that as depth 0, which would hide a wrong pairing of reads and assembly.
Returns genomes (per genome: sample, the name isotable joins on, mapped_depth and
covered_fraction in %) and mapped (reads mapped and their percentage, from CoverM’s log), and
a warning when a shovill.log beside the assembly gives a depth more than 1.5× off.
Measured on the laptop (2026-11-14): BfR-EC-20867’s trimmed MiSeq reads (1.4 million) on its Shovill assembly in 26 s, 4 threads, under a 4 GB cap: 50.34× mean depth, 99.99% of the assembly covered, 99.99% of reads mapped. Shovill had estimated 51×; the paper reports 49.0×. Two runs gave the same table.
metabat2
Section titled “metabat2”Bins the contigs into genomes by depth and tetranucleotide frequency. Writes
<outdir>/<prefix>.<n>.fa, one FASTA per bin, ready for checkm2 (genome_dir the outdir,
extension fa), gtdbprep_ani and gtdbtk_classify_wf, and then isotable with mode: mag.
| Parameter | Type | Meaning |
|---|---|---|
contigs |
file (required) | The assembly, FASTA. |
depth |
file | coverm_contig’s metabat table (its header is checked). Without it MetaBAT2 bins on tetranucleotide frequency alone, which works poorly. |
outdir |
folder (required) | Folder for the bins; created by the server. |
prefix |
text | Bin name prefix, default bin. |
min_contig |
integer, at least 1500 | Shortest contig binned (default 2500). |
min_bin_size |
integer | Smallest bin written, in bp (default 200000). |
seed |
integer, 1 or more | Default 1 here: MetaBAT2’s own default (0) draws a random seed, so its bins would differ between runs. |
threads |
integer | MetaBAT2’s default is every core. |
unbinned, no_sample_depths |
booleans | Also write <prefix>.unbinned.fa; leave per-sample depths out of the bin headers. |
Returns each bin’s contigs, length, N50 and GC, the bin count and the binned length. MetaBAT2 has
no --version, so the version is the first line of its --help (on stderr), in the record and in
replay.sh’s version check. It fails (exit 1, “no large target contigs”) when no contig reaches
min_contig.
semibin2
Section titled “semibin2”Bins one sample’s contigs with SemiBin2 (SemiBin2 single_easy_bin), a binner that embeds contigs
with a neural network before clustering them. Writes <outdir>/output_bins/<tag>_<n>.fa (plain
FASTA) and <outdir>/contig_bins.tsv. Two ways to run it:
- A pretrained model (
environment) withdepth,coverm_contig’s metabat table of this one sample, or with one BAM. SemiBin2 2.6.0 ships models forhuman_gut,dog_gut,cat_gut,mouse_gut,pig_gut,chicken_caecum,human_oral,ocean,soil,built_environment,wastewaterandglobal(get_model_pathin itsutils.py); useglobalwhen none matches. SemiBin2 only accepts a MetaBAT depth table together with a pretrained model, and only a single-sample one. - Its own model, trained on this sample (self-supervised), from
bams: one sorted BAM per sample, all mapped to these contigs, whichcoverm_contigkeeps withbam_cache_dir. This did not fit in 8 GB (below). - Several samples binned together (
multi, SemiBin2multi_easy_bin): see Multi-sample binning below.
| Parameter | Type | Meaning |
|---|---|---|
contigs |
file (required) | One sample’s assembly, FASTA. With multi, semibin2_concatenate’s concatenated.fa. |
outdir |
folder (required) | Output folder; one with files needs overwrite (SemiBin2 replaces output_bins/ and its tables). |
multi |
boolean | Multi-sample binning (multi_easy_bin). Default false. |
environment |
one of the twelve above | Use that pretrained model. Needed with depth; with bams, exactly one BAM. |
depth |
file | coverm_contig’s metabat table with one sample (its header is checked: five columns). |
bams |
list of files | Coordinate-sorted BAMs (checked: SO:coordinate in the header; SemiBin2 runs bedtools genomecov on them). |
tag |
text | Bin file prefix, default SemiBin. Give each sample its own: galah and CoverM name genomes after the file. |
min_len |
integer, at least 500 | Shortest contig binned. Default: SemiBin2 picks 1000 or 2500 bp from the assembly (2500 for the sample below). |
minfasta_kbs |
integer | Smallest bin written, in kb (default 200). |
seed |
integer | Default 1 here; without a seed SemiBin2’s results may differ between runs. |
threads |
integer | SemiBin2’s default is every CPU. |
The server always passes --compression=none (SemiBin2’s default is gzip; plain FASTA is what
checkm2 with extension: fa and galah read here) and --engine=cpu (the same bins on a
machine with a GPU). Returns each bin’s contigs, length, N50 and GC, the bin count and the binned
length. SemiBinRun.log is volatile; recluster_bins_info.tsv names the output folder, so it only
matches when replayed into the same path, as replay.sh does. Not offered: --semi-supervised
(mmseqs2 and GTDB, over 100 GB), --abundance (strobealign-aemb files, which SemiBin2 only takes
from five samples on), long-read mode, CRAM, --separator, and the training and graph settings.
Measured on 2026-11-14 on this project’s laptop (12 cores, 30 GB, shared: 1-minute load 8-29), each step under an 8 GB no-swap cap, 6 threads, on the Crystal Geyser sample of the MAG laptop test (its MEGAHIT contigs and CoverM depth table):
| Run | Wall | Peak (cgroup) | Bins | Mb binned | high* / medium / low (isotable MAG mode) |
Bins with contamination ≥ 10% |
|---|---|---|---|---|---|---|
| MetaBAT2 (earlier run, same contigs and depth) | 2.6 s | 0.24 GiB | 23 | 24.4 | 4 / 13 / 6 | 1 |
SemiBin2 global, depth |
74-109 s (54 s through irit-mcp) | 1.11-1.48 GiB | 25 | 26.7 | 4 / 11 / 10 | 2 |
SemiBin2 ocean, depth |
59 s | 0.88 GiB | 26 | 26.3 | 3 / 13 / 10 | 2 |
SemiBin2 soil, depth |
54 s | 0.85 GiB | 27 | 26.8 | 3 / 12 / 12 | 2 |
| SemiBin2 trained on the sample, one BAM | killed after 244 s and 398 s | 8 GB cap |
- On this CPR-rich groundwater sample the pretrained models gave 2-4 more bins than MetaBAT2 and 2-2.4 Mb more binned sequence, but not better bins: 15-16 of them were at least 50% complete with under 10% contamination, against MetaBAT2’s 17. No model was trained on groundwater. Other data may differ; this is one sample.
- Two runs of
globalwith seed 1 gave byte-identical bins (recluster_bins_info.tsvdiffered only by the output folder it names), and so did the call through irit-mcp (othertag). - Self-supervised training does not fit in 8 GB. It was killed at the cap twice, in its first
training epoch (about 3 minutes each, of 15). SemiBin2 2.6.0 builds min(500 × contigs, 4 million)
random contig pairs as feature rows every epoch (
train_selfinself_supervised_model.py), about 2.2 million pairs for the 4,455 split contigs here; the batch size doesn’t change that. A call withoutenvironmenttherefore carries a warning before it runs, and a SemiBin2 killed in training gets a hint to use a pretrained environment. On 32 GB or more it should run. - CheckM2 (
lowmem) on the 25-27 bins: 356-461 s, 3.5-4.4 GiB.
Multi-sample binning: semibin2_concatenate and multi
Section titled “Multi-sample binning: semibin2_concatenate and multi”SemiBin2’s multi-sample mode bins each sample’s own assembly, but with the coverage of every sample as features, which separates genomes that one sample’s coverage can’t. Three calls:
semibin2_concatenate(SemiBin2 concatenate_fasta) joins the samples’ contigs into<outdir>/concatenated.fa, each contig renamed<sample>:<contig>. SemiBin2 takes the sample name from the file name up to its first dot, and every MEGAHIT assembly isfinal.contigs.fa, so the server links each file as<outdir>/inputs/<sample>.fa(recorded, and made again byreplay.sh) under the name given insamples.coverm_contigwithconcatenated.faasreference, every sample’s reads andbam_cache_dir: one BAM per sample, all against the same contigs.semibin2withmulti: true,contigsthe concatenated file andbamsthose BAMs (SemiBin2 multi_easy_bin). It trains a model for each sample in turn (self-supervised; there are no pretrained models for this mode) and bins each sample’s contigs with it.
{"name": "semibin2_concatenate", "arguments": {"contigs": ["asm/s1/final.contigs.fa", "asm/s2/final.contigs.fa", "asm/s3/final.contigs.fa"], "samples": ["s1", "s2", "s3"], "outdir": "multi/concat"}}{"name": "coverm_contig", "arguments": {"reference": "multi/concat/concatenated.fa", "r1": ["trim/s1_1.fastq.gz", "trim/s2_1.fastq.gz", "trim/s3_1.fastq.gz"], "r2": ["trim/s1_2.fastq.gz", "trim/s2_2.fastq.gz", "trim/s3_2.fastq.gz"], "output": "multi/mean.tsv", "bam_cache_dir": "multi/bams", "threads": 6}}{"name": "semibin2", "arguments": {"contigs": "multi/concat/concatenated.fa", "multi": true, "outdir": "multi/sb", "bams": ["multi/bams/concatenated.fa.s1_1.fastq.gz.bam", "multi/bams/concatenated.fa.s2_1.fastq.gz.bam", "multi/bams/concatenated.fa.s3_1.fastq.gz.bam"], "threads": 6}}{"name": "checkm2", "arguments": {"genome_dir": "multi/sb/bins", "extension": "fa", "outdir": "checkm2", "lowmem": true}}Parameter (semibin2_concatenate) |
Type | Meaning |
|---|---|---|
contigs |
list of files (required) | Each sample’s assembly, FASTA (plain or gzip); two or more, each file once. |
samples |
list of names (required) | One per file, same order: letters, digits, _, - (no dot, which SemiBin2 cuts at, nor :, its separator). |
outdir |
folder (required) | Output folder; one with files needs overwrite. |
min_len |
integer | Leave out shorter contigs (--min-len). Default: none left out. |
semibin2 with multi checks that every contig name has a sample in front and that each sample’s
contigs are together (as semibin2_concatenate writes them), and refuses environment, depth and
fewer than two BAMs; it warns when the BAMs and samples differ in number. Bins are written per sample
to <outdir>/samples/<sample>/output_bins/<tag>_<n>.fa, and SemiBin2 copies all of them to
<outdir>/bins/<sample>_<tag>_<n>.fa: run checkm2 and galah on that one folder (the sample in
each name keeps them apart), and isotable mode mag on the CheckM2 report. The result lists each
bin with its sample. SemiBinRun.log of both tools is volatile; the bins, features
(samples/<sample>/data.csv) and models (model.pt) were byte-identical between two runs with
seed 1 (on the two-genome mock below), and recluster_bins_info.tsv names the output folder, as in
single-sample mode.
Measured on 2026-11-15 on this project’s laptop (12 cores, 30 GB, shared: 1-minute load 3-25),
each step under an 8 GB no-swap cap, 6 threads, on three filtrate samples of one site: the Crystal
Geyser time series, BioProject PRJNA297582 (SRR2638367, SRR2638368, SRR2638369: “filtrate 05”, “06”
and “07”). Each run was read from ENA with its MD5 checked and cut to 0.5 Gb with rasusa (seed 1):
3.49-3.51 million reads per sample. ENA serves these runs as unpaired reads (every read /1), and
coverm_contig then took pairs only, so CoverM 0.8.0 was run by hand with --single for the depths
and BAMs (the same contig subcommand, methods and BAM cache); everything else went through
irit-mcp. coverm_contig has taken single since.
| Step | Wall | Peak (cgroup) | Result |
|---|---|---|---|
megahit (single), per sample |
13-19 min | 1.2-1.3 GiB | 24.3-28.5 Mb, N50 851-1,106 bp; 544-718 contigs of 4 kb or more |
semibin2_concatenate |
0.9 s | 0.09 GiB | 101,916 contigs |
CoverM, the three samples to concatenated.fa, BAMs kept |
152 s | 2.59 GiB | 71-73% of reads mapped; BAMs of 304-314 MB |
semibin2 multi |
48 min (training 13-18 min per sample) | 4.33 GiB | 14 bins, 19.6 Mb |
checkm2 lowmem, the 50 bins below |
458 s | 5.47 GiB |
The same three assemblies binned four ways, graded by isotable mode mag on one CheckM2 report:
| Binning | Wall | Bins | Mb binned | high* / medium / low |
≥ 50% complete, < 10% contamination | Contamination ≥ 10% |
|---|---|---|---|---|---|---|
| MetaBAT2, the sample’s own depth | under 1 s per sample | 11 | 18.7 | 4 / 5 / 2 | 9 | 1 |
| MetaBAT2, depth of all three samples | under 1 s per sample | 11 | 21.0 | 5 / 4 / 2 | 9 | 0 |
SemiBin2 global, the sample’s own depth |
17-21 s per sample | 14 | 20.3 | 5 / 5 / 4 | 10 | 0 |
SemiBin2 multi |
48 min for the three | 14 | 19.6 | 5 / 5 / 4 | 10 | 0 |
- Multi-sample binning fitted in 8 GB here, at 4.3 GiB. Its training holds 1,000 random contig
pairs per contig of 4 kb or more as feature rows each epoch (
train_self; such contigs are split in two for must-link pairs), so the peak follows the sample with the most of them: 718 here (718,000 pairs). Single-sample training of the deeper sample above (about 2,200 such contigs, 2.2 million pairs) was killed at the cap; where between the two the limit lies was not measured. Amulticall carries a warning with these numbers before it runs. - Training is the slow part: 13-18 minutes per sample at 15 epochs, against about 20 seconds
per sample for a pretrained model. The epochs and batch size don’t change the peak (the pair
arrays are built whole each epoch);
--ml-thresholdwould (fewer contigs split, fewer pairs), but wasn’t needed here, so the training settings are still not offered. - On these samples it binned no better than the pretrained
globalmodel: the same bin count and tiers, and nearly the same bins: 13 of the 14 had 93-100% of their length in oneglobalbin of the same sample. These are three filtrates of one site, at 0.5 Gb each; other data may differ. Giving MetaBAT2 all three samples’ depth removed its one contaminated bin. - On the two-genome mock of the real-tools workflow (the SKESA assembly of the S. aureus reads and
a MEGAHIT assembly of the M. genitalium pairs),
semibin2multitook 179-201 s at 0.74-0.79 GiB and put each genome in one bin (2.77 and 0.57 Mb); two runs gave byte-identical bins, features and models. The workflow runs this route. The real run above was not repeated.
Dereplicates genomes, typically the bins of several samples, with galah (galah cluster): genomes
within an ANI (default 95%, a species) and aligned fraction of each other form a cluster, and one
genome represents it. skani does the comparisons. Writes <outdir>/clusters.tsv
(representative<TAB>member lines, paths as given) and <outdir>/representatives.txt, one path per
line, which coverm_abundance takes as genome_list. No copies are made: galah refuses a copy
folder that has files, which a replay in the same folder would hit.
| Parameter | Type | Meaning |
|---|---|---|
genomes |
list of files | Genome FASTA files. |
genome_dirs |
list of folders | Folders of genomes, matched by extension (default fa, MetaBAT2’s and SemiBin2’s). Give this and/or genomes. |
outdir |
folder (required) | Where clusters.tsv and representatives.txt go; an existing one needs overwrite. |
ani |
percent, 80-100 | Default 95. |
min_aligned_fraction |
percent | galah’s default 15. |
precluster_ani |
percent, at most ani |
galah’s default 90. |
checkm2_report |
file | A CheckM2 quality_report.tsv listing every genome. Each cluster’s best genome by quality_formula represents it; without a report, the first genome given does (and a warning says so). |
min_completeness, max_contamination |
percent | Leave genomes out by CheckM2’s numbers (need checkm2_report). |
quality_formula |
Parks2020_reduced (galah’s default), completeness-4contamination, completeness-5contamination |
How the representative is chosen. galah’s dRep formula is not offered: it needs CheckM 1’s strain heterogeneity. |
small_genomes |
boolean | skani’s settings for genomes under about 20 kb. |
threads |
integer | Default 1 here (below). |
Checks before running: genomes are named after their files (without the FASTA extension), as
galah, CheckM2 and CoverM name them, so two files with one name (bin.1.fa of two samples) are
refused: give each sample’s bins their own prefix (metabat2 prefix, semibin2 tag). galah
takes one --checkm2-quality-report and panics when a genome is missing from it (“Failed to find
CheckM statistics”), so the server checks that every genome has a row and refuses the call
otherwise: run checkm2 once over all the genomes (its genomes list).
Returns the clusters (sorted, with their members and sizes), the number of genomes given and of
clusters, and the genomes left out by the quality filters. With more than one thread galah 0.6.3
writes clusters.tsv and representatives.txt in a different order each run (the same clusters:
checked on 48 bins, sorted files identical); with one they were byte-identical. One thread is the
default, and with more both files are volatile. One thread was fast enough: 48 bins in 0.84 s.
Install: Bioconda’s galah=0.6.3 also installs CheckM2 with TensorFlow (about 1 GB) for
--run-checkm2, which irit-mcp doesn’t use. galah itself only needs skani on PATH:
micromamba create -n galah -c conda-forge -c bioconda skani=0.4.0, then micromamba install -n galah --no-deps -c conda-forge -c bioconda galah=0.6.3 (1 MB). Not offered: --run-checkm2,
CheckM 1 and dRep quality tables, FastANI and finch, contig clustering, --reference-genomes,
--low-memory.
Measured (2026-11-14, same laptop and cap): the 23 MetaBAT2 bins and the 25 SemiBin2 global bins
of the Crystal Geyser sample, with one CheckM2 report for all 48 (the two reports joined by hand), in
0.84 s and 84 MB: 24 clusters, 22 of them a MetaBAT2 bin and a SemiBin2 bin of the same genome, one
of three and one single SemiBin2 bin. 12 representatives came from each binner.
coverm_abundance
Section titled “coverm_abundance”Each genome’s abundance in each sample: maps every sample’s reads to a set of genomes
(coverm genome with --genome-fasta-files, all genomes in one reference) and writes one table, a
row per genome plus unmapped, and per sample <read 1 file> Relative Abundance (%), Mean,
Covered Fraction and Read Count columns (CoverM’s dense layout). This is the genome × sample
table a co-occurrence analysis across samples takes.
| Parameter | Type | Meaning |
|---|---|---|
genome_list |
file | A list of genome paths, one per line: galah’s <outdir>/representatives.txt. Read again on replay, so the genomes follow a re-run galah. |
genomes, genome_dirs, extension |
as for galah |
Instead of genome_list: genome files, or folders of them. One folder alone is passed to CoverM as a folder (-d), so a replay takes whatever it then holds. Names must be unique. |
r1, r2 |
lists of files (required) | One read pair per sample. Columns are named after the read 1 file, so name the files after the samples; two read 1 files with one name are refused. |
output |
file (required) | The table (TSV). |
min_covered_fraction |
percent: 0, or 1-100 | Default 0 here (CoverM’s own is 10). |
mapper, min_read_percent_identity, min_read_aligned_percent, threads |
As for coverm_contig. |
|
overwrite |
boolean | Default false. |
Why a separate tool from coverm_genome: that one is for an isolate (one assembly, one genome,
--single-genome, isotable’s naming and the Shovill depth check); this one is many genomes and
many samples, for MAGs.
What the numbers mean (cited, the CoverM paper,
Equation 1, and its README): a genome’s
relative abundance is its share of the summed mean coverage of all the genomes given, times the
fraction of the sample’s reads that aligned to any of them, so it estimates the share of cells and
is a share of all reads; the unmapped row holds “the reads that did not map to any of the provided
genomes”. Two things follow, which is why the genomes should be one dereplicated set given in one
call: abundances are only comparable across samples when every sample was mapped to the same set,
and a genome left out leaves its reads unmapped or on its relatives.
min_covered_fraction: CoverM reports a genome covered less than this as 0 in that sample, and
CoverM 0.8.0 refuses the count method unless it is 0 (“does not calculate the covered
fraction”). So the default is 0, and the table’s Covered Fraction column lets a later step set its
own presence threshold. With a value above 0 the table has no Read Count columns (a warning says
so). Values between 0 and 1 are refused: CoverM would read them as fractions.
Returns, per sample, the reads mapped and their percentage (from CoverM’s log), the unmapped
percentage and how many genomes have an abundance above 0; and the genome count and the columns per
sample. Not offered: --dereplicate (galah is its own recorded step), sharding, BAM input, sparse
output.
Measured (2026-11-14, same laptop and cap, 6 threads): the 24 galah representatives above, with the Crystal Geyser sample’s trimmed reads split into two halves of 2.43 million pairs as two “samples”: 91 s, 1.90 GiB. 41.5% and 41.7% of the reads mapped (73.3% map to the whole assembly); all 24 genomes were detected in both halves. A two-sample stand-in test checks the table’s layout; this real run checks the layout and the time and memory, not biology (both halves are one sample).
Example: several samples to a genome × sample table
Section titled “Example: several samples to a genome × sample table”{"name": "coverm_contig", "arguments": {"reference": "asm/s1/final.contigs.fa", "r1": ["trim/s1_1.fastq.gz"], "r2": ["trim/s1_2.fastq.gz"], "output": "depth/s1.depth.tsv", "methods": ["metabat"], "threads": 6}}{"name": "semibin2", "arguments": {"contigs": "asm/s1/final.contigs.fa", "depth": "depth/s1.depth.tsv", "environment": "global", "outdir": "bins/s1", "tag": "s1", "threads": 6}}... the same for s2, s3, ... (or metabat2 with prefix s2, ...){"name": "checkm2", "arguments": {"genomes": ["bins/s1/output_bins/s1_0.fa", "..."], "outdir": "checkm2", "lowmem": true}}{"name": "galah", "arguments": {"genome_dirs": ["bins/s1/output_bins", "bins/s2/output_bins"], "checkm2_report": "checkm2/quality_report.tsv", "min_completeness": 50, "max_contamination": 10, "outdir": "derep"}}{"name": "coverm_abundance", "arguments": {"genome_list": "derep/representatives.txt", "r1": ["trim/s1_1.fastq.gz", "trim/s2_1.fastq.gz"], "r2": ["trim/s1_2.fastq.gz", "trim/s2_2.fastq.gz"], "output": "abundance.tsv", "threads": 6}}CheckM2 over many bins in one call needs memory (48 genomes peaked at 7.7 GiB, above); galah takes
one report, so for more bins than fit, join the batches’ quality_report.tsv files under one
header line (outside irit-mcp, for now).
Example: an isolate from reads to resistance genes
Section titled “Example: an isolate from reads to resistance genes”A session an agent might run (paths shortened):
{"name": "fastp", "arguments": {"in1": "reads/s1_R1.fastq.gz", "in2": "reads/s1_R2.fastq.gz", "out1": "trim/s1_R1.fastq.gz", "out2": "trim/s1_R2.fastq.gz", "json": "trim/s1.fastp.json"}}{"name": "shovill", "arguments": {"r1": "trim/s1_R1.fastq.gz", "r2": "trim/s1_R2.fastq.gz", "outdir": "asm/s1", "assembler": "skesa", "ram": 8, "link_as": "genomes/s1.fna"}}{"name": "dblock_env", "arguments": {}}{"name": "bakta", "arguments": {"genome": "asm/s1/contigs.fa", "prefix": "s1", "outdir": "bakta/s1", "skip": ["plot"]}}{"name": "checkm2", "arguments": {"genomes": ["genomes/s1.fna"], "outdir": "checkm2", "lowmem": true}}{"name": "gtdbprep_ani", "arguments": {"genome_dir": "genomes", "index": "/db/ani-screen-r232", "work": "ani", "species_only": true}}{"name": "gtdbtk_classify_wf", "arguments": {"genome_dir": "genomes", "data_path": "ani/gtdbtk_data", "out_dir": "gtdbtk", "pplacer_cpus": 1}}{"name": "mlst", "arguments": {"contigs": ["asm/s1/contigs.fa"], "outfile": "typing/s1.mlst.tsv"}}{"name": "amrfinder", "arguments": {"nucleotide": "asm/s1/contigs.fa", "organism": "Staphylococcus_aureus", "plus": true, "output": "typing/s1.amrfinder.tsv"}}{"name": "isotable", "arguments": {"dirs": ["trim", "asm", "checkm2", "gtdbtk", "typing"]}}None of the folders (trim/, asm/, genomes/, …) need to exist first. CheckM2 and GTDB-Tk
name genomes after the file, so Shovill’s link_as makes genomes/s1.fna a link to
asm/s1/contigs.fa: the genome is s1 in their results and isotable joins it. isotable’s default
isolate requirements (reads, Q30, contigs, N50, completeness) are then all met.
The run’s replay.sh then has lines like these:
want_ext_version fastp 'fastp 1.4.0'want_ext_version gtdbtk 'gtdbtk: version 2.8.0 Copyright 2017 Pierre-Alain Chaumeil, ...'
# call 001: fastp (ok, 2026-11-10T09:12:03.120Z)cd /data/demo || exit 1step 001 0 ext fastp --in1=reads/s1_R1.fastq.gz --in2=reads/s1_R2.fastq.gz ...
# call 005: gtdbtk_classify_wf (ok, 2026-11-10T09:58:40.002Z)cd /data/demo || exit 1GTDBTK_DATA_PATH=/home/u/.local/share/dblock/gtdbtk-r232/release232; export GTDBTK_DATA_PATHstep 005 0 ext gtdbtk classify_wf --genome_dir=asm --out_dir=gtdbtk --pplacer_cpus=1 --scratch_dir=scratchExample: a metagenome to MAGs
Section titled “Example: a metagenome to MAGs”{"name": "fastp", "arguments": {"in1": "reads/m1_1.fastq.gz", "in2": "reads/m1_2.fastq.gz", "out1": "trim/m1_1.fastq.gz", "out2": "trim/m1_2.fastq.gz", "json": "trim/m1.fastp.json"}}{"name": "megahit", "arguments": {"r1": ["trim/m1_1.fastq.gz"], "r2": ["trim/m1_2.fastq.gz"], "outdir": "asm/m1", "memory_gb": 6, "threads": 6}}{"name": "coverm_contig", "arguments": {"reference": "asm/m1/final.contigs.fa", "r1": ["trim/m1_1.fastq.gz"], "r2": ["trim/m1_2.fastq.gz"], "output": "depth/m1.depth.tsv", "methods": ["metabat"], "threads": 6}}{"name": "metabat2", "arguments": {"contigs": "asm/m1/final.contigs.fa", "depth": "depth/m1.depth.tsv", "outdir": "bins/m1", "threads": 6}}{"name": "checkm2", "arguments": {"genome_dir": "bins/m1", "extension": "fa", "outdir": "checkm2", "lowmem": true, "threads": 6}}{"name": "gtdbprep_ani", "arguments": {"genome_dir": "bins/m1", "extension": "fa", "work": "ani", "species_only": true}}{"name": "gtdbtk_classify_wf", "arguments": {"genome_dir": "bins/m1", "extension": "fa", "data_path": "ani/gtdbtk_data", "out_dir": "gtdbtk", "pplacer_cpus": 1}}{"name": "isotable", "arguments": {"dirs": ["checkm2", "gtdbtk"], "mode": "mag"}}isotable’s MAG mode gives each bin a MIMAG tier from CheckM2’s completeness and contamination.
Use CheckM2’s lowmem for more than a few bins under 8 GB: at its default DIAMOND block size it
was killed at an 8 GB cap on 23 MAGs, and with lowmem it peaked at 5.6 GiB.
The laptop test ran this on a groundwater metagenome inside 8 GB.
describe_run, list_runs
Section titled “describe_run, list_runs”describe_run (run_id, default the current run) returns the paths of replay.sh and the
RO-Crate and a summary of each call: tool, status, version, exit status, error, warnings and output
paths. detail: true returns every call’s full record instead (command, environment, every input and
output with SHA-256), which can be tens of kB per call; call_id returns one call in full.
list_runs lists the runs in the runs folder with call counts.
Errors
Section titled “Errors”Every tool result carries call_id and run_id. Failures have isError: true and an error
field:
error |
Meaning |
|---|---|
invalid_parameter |
Refused before running; field and message say why. Recorded, not replayed. |
tool_failed |
The tool ran and exited non-zero; exit_status, stderr, stdout. Its outputs must not be used. |
tool_unavailable |
The binary was not found or could not start. |
no_reports |
leanqc exited 0 but wrote no report; there is no QC result. |
missing_outputs |
A third-party tool exited 0 but didn’t write the files it always writes; message lists them. Recorded as failed. |
output_unreadable |
sheetgen, isotable or a third-party tool exited 0 but its output could not be read back. |
A parameter that isn’t in the schema is refused by the MCP layer itself, with the list of valid names.
Run records
Section titled “Run records”One folder per server session, irit-runs/<run-id>/, rewritten after every call:
irit-runs/20261110T074754Z-41022/ run.json every call, in order replay.sh re-runs the successful calls and checks the outputs ro-crate-metadata.json the same, as a Workflow Run RO-Crate calls/001.stdout each call's stdout and stderr calls/001.stderrA call in run.json (from a real session, with paths shortened and lists trimmed):
{ "id": 2, "mcp_tool": "leanqc", "status": "ok", "params": {"files": ["reads/s1_R1.fastq", "reads/s1_R2.fastq"], "outdir": "qc", "no_html": true}, "program": "/opt/irit/bin/leanqc", "argv": ["leanqc", "--outdir=qc", "--no-html", "--", "reads/s1_R1.fastq", "reads/s1_R2.fastq"], "version": "leanqc 0.1.0", "cwd": "/data/demo", "started": "2026-11-10T07:47:54.881Z", "ended": "2026-11-10T07:47:54.900Z", "exit_status": 0, "inputs": [ {"path": "/data/demo/reads/s1_R1.fastq", "size": 21890, "sha256": "0d434ae6..."} ], "outputs": [ {"path": "/data/demo/qc/s1_R1_leanqc.json", "size": 12991, "sha256": "fbc19cfa..."} ], "stdout": "calls/002.stdout", "stderr": "calls/002.stderr", "env": {"DBLOCK_STORE": "/home/u/.local/share/dblock"}}version is the first line the tool printed for --version; it is left out when --version failed
or printed nothing. Third-party calls also have "external": true.
status is ok, failed (non-zero exit), rejected (invalid parameters, with error) or
error (binary missing). Inputs are the files the call reads; a folder input (sheetgen, isotable)
is listed file by file. Outputs are the files under the call’s output paths that are new or changed
after it ran. “Changed” compares size, modification time, inode number and inode change time (on
Unix), and the SHA-256 of files under 1 MB, so a rewrite with the same size inside the same
timestamp tick is still seen. An output path that is itself a symlink (qc -> /scratch/qc) is
followed; symlinks inside it (sheetgen’s link_into) are recorded with symlink_to.
Calls whose output paths overlap (the same path, or one inside the other) run one after the other, so each call’s outputs are only its own; other calls run in parallel.
Environment
Section titled “Environment”env holds the environment that decided where the tool looked or wrote, as the resolved value the
server computed with the tool’s own rules. The server passes exactly these values to the tool, so
the record and the run agree, and replay.sh exports them before the call:
| Tool | Recorded | Resolved from |
|---|---|---|
dblock_* (except catalog) |
DBLOCK_STORE |
$DBLOCK_STORE, else $XDG_DATA_HOME/dblock, else $HOME/.local/share/dblock |
sheetgen with pipeline |
NXF_HOME |
$NXF_HOME, else $HOME/.nextflow |
gtdbtk_classify_wf |
GTDBTK_DATA_PATH |
data_path, else $GTDBTK_DATA_PATH, else the one locked in ./dblock.lock |
Bakta, CheckM2 and AMRFinderPlus get their database as a flag (--db, --database_path,
--database), resolved the same way from BAKTA_DB, CHECKM2DB and AMRFINDER_DB, so it is in
argv.
With pipeline, the schema_input.json sheetgen will use (same lookup as sheetgen: the
assets/<name> checkout, else the newest clone) is also hashed into inputs.
Not captured: PATH and other variables, locale, the user, the machine; a store = line in
dblock.toml (it wins over DBLOCK_STORE, and dblock.toml is hashed as an input instead); ~/
in such a line, which dblock expands with the replaying user’s HOME; the contents of the dblock
store and of the Nextflow cache beyond the one schema file.
Options are always written as --name=value and positional arguments after --, so a file name
starting with - can’t be read as a flag.
Replaying
Section titled “Replaying”sh irit-runs/<run-id>/replay.sh # binaries from PATHIRIT_BIN_DIR=/opt/irit/bin sh irit-runs/<run-id>/replay.sh # or from a folderThird-party tools (fastp, shovill, flye, medaka_consensus, bakta, checkm2, gtdbtk, mlst, amrfinder, megahit, coverm, metabat2, kleborate, rasusa) are always taken from
PATH, so activate their conda environment first. IRIT_BIN_DIR applies to the irit tools only.
Some third-party outputs differ between two identical runs. They are recorded with
"volatile": true and their hash, and replay.sh only checks that they exist (check_exists).
Every other output is checked by hash. The lists come from running each tool twice with the same
inputs and paths in the real-tools workflow (below) and comparing every file:
| Tool | Volatile outputs | Why they differ |
|---|---|---|
| fastp | .html |
The HTML report; the JSON report is identical. |
| shovill | everything | shovill.log has times and the machine’s CPUs and RAM; every contigs.fa header carries the date, so it differs on another day. SPAdes 3.15.5 gave different contigs in two identical runs (2,803,881 bp both times, same ST). SKESA’s were identical in the real-tools workflow, but SKESA 2.5.1 with 8 CPUs gave 57 contigs once and 56 twice from identical reads in the laptop run. |
| gtdbprep ani | .log, .gz |
Logs; the gzip header of GTDB-Tk’s unassigned-hits file carries a time. |
| mlst | .json |
Same values, keys in another order (mlst writes it without sorting, and Perl randomises hash order). The TSV is identical. |
| bakta | .log, .gbff, .embl, .json, .svg |
Run times and dates (GenBank LOCUS date; in the JSON only run.start and run.end). |
| checkm2 | checkm2.log |
Timestamps. |
| gtdbtk | .log, gtdbtk.json, .gz |
Timestamps (in gtdbtk.json only each step’s start and end); gzip headers carry a time. |
| megahit | everything | The log has times; final.contigs.fa differed between two identical runs in the real-tools workflow (same 92 contigs, 3,384,504 bp and N50 both times), and so did the intermediate contigs. Replay compares the assembly’s contig count, length and N50, as for Shovill. |
| coverm_contig | none | Three runs on the same assembly and reads gave identical depth tables (MAG laptop test); it differs on replay only when the assembly it reads did. |
| coverm_genome | none | Byte-identical table on replay on the laptop (BfR-EC-20867, 4 threads). |
| kleborate | none | Byte-identical tables on replay on the laptop (BfR-EC-20867). Not yet checked by the real-tools workflow. |
| metabat2 | none | With the seed irit-mcp passes (1 unless set), a second run gave identical bins and bin.BinMembers.txt; bin.BinInfo.txt names the output folder. MetaBAT2’s own default seed is random. |
The script warns when a tool’s --version (its first line) differs from the recorded one (a tool whose version
couldn’t be read in the run gets one “version unknown” line instead), exports each call’s recorded
env, re-runs each successful call in its original folder (stdout and stderr go to replay/NNN.* beside the script), then checks
the SHA-256 of every output (the last version, if several calls wrote the same file), and of stdout
where stdout is the result (a sheet or table not written to a file, dblock catalog, dblock env).
It exits 0 only if every command exits as it did and every hash matches, apart from the outputs
that follow a changed input (below). Failed and rejected calls appear as comments.
Outputs made from a volatile output. A volatile output can feed later calls: CheckM2 and
GTDB-Tk read Shovill’s assembly, isotable reads CheckM2’s report. If the replayed assembly is a
different one, those outputs differ too, and that is not a fault of theirs. So before re-running a
call, replay.sh checks every input of it that an earlier call of the run wrote (check_in). If
one differs from what the call read in the run, the call’s outputs are checked with check_from:
a different one is printed as differs, made by call NNN from an input that differs and counted,
but does not fail the replay. A missing one is treated the same way (missing, made by call NNN ...): a binner given other contigs can make other bins, and SemiBin2 numbers its bins by cluster,
so the run’s sb_1.fa may not exist after a replay. An output that is missing, or that differs,
although every input it was made from matched, still fails the replay. The last line then says how many outputs matched and how
many differ only because of such an input. For an assembly, replay.sh also prints its contig
count, length and N50 against the run’s (assembly_note), e.g.
replay: call 009: assembly /data/b168/asm/b168/contigs.fa is now 56 contigs, 4151999 bp, N50 185951; the run had 57 contigs, 4152275 bp, N50 185951replay: call 013 reads /data/b168/genomes/b168.fna, which differs from the runreplay: differs, made by call 013 from an input that differs: /data/b168/checkm2/quality_report.tsvreplay: 12 commands re-run, 27 of 31 outputs match; 4 differ only because a file they were made from differs (see above)A successful dblock_fetch is not repeated by default, since it would download the databases
again: the script prints that it skipped it, the exact command is in a comment, and the check of the
dblock.lock it wrote is skipped too. Run with IRIT_REPLAY_FETCH=1 to fetch again:
IRIT_REPLAY_FETCH=1 sh irit-runs/<run-id>/replay.shEverything taken from a call (arguments, paths, versions, env values) is single-quoted, and every comment line is written through one helper that escapes newlines, carriage returns and other control characters, so a value can’t end a comment and start a command. The server also refuses control characters in every path and text parameter, so they never reach a tool’s argv. An excerpt:
want_version leanqc 'leanqc 0.1.0'
# call 002: leanqc (ok, 2026-11-10T07:47:54.881Z)cd /data/demo || exit 1step 002 0 irit leanqc --outdir=qc --no-html -- reads/s1_R1.fastq reads/s1_R2.fastq
# call 005: leanqc (rejected, 2026-11-10T07:47:54.946Z)# not run: phred: 40 is not 33 or 64
# outputscheck fbc19cfa4e3a31daabbaec0ffda5e39ae9614937132f8f9e7cabfcdfc8d7a735 /data/demo/qc/s1_R1_leanqc.jsonRO-Crate
Section titled “RO-Crate”ro-crate-metadata.json follows the Process Run Crate
profile 0.6 (RO-Crate 1.3): one CreateAction per call that ran, with the tool as a
SoftwareApplication (softwareVersion), inputs as object, outputs as result, start and end
times, and FailedActionStatus for failed calls. The root Dataset has a description and a
license (CC0 1.0, for the run record itself; the data files keep their own terms). run.json,
replay.sh and every calls/NNN.stdout / .stderr are listed in hasPart.
The data files are not copied in; they are referenced by file:// URI, so the crate describes the
run but does not carry the data.
Safety
Section titled “Safety”- No shell. The binaries are started with an argument vector; nothing passes through a
shell.
replay.shsingle-quotes every value and escapes comments (see Replaying); control characters are refused in parameters. - Writes stay in the root and don’t replace existing files without
overwrite: true(see Where tools may write). - Downloads need confirmation.
dblock_fetchrefuses unlessconfirm: true, and its description tells the agent to show the userdblock_planfirst. dblock itself still refuses databases that won’t fit on disk. - No deleting tools.
dblock removeis not exposed. - Stdin is closed for every tool, so nothing can wait for input.
Tested
Section titled “Tested”- Unit tests: parameter checks and argument vectors for every tool (missing paths, bad enums,
out-of-range numbers,
schemawithpipeline, unconfirmed fetch, unsafe database ids, unknown parameters, control characters, writes outside the root through.., absolute paths and symlinks, overwriting), resolved environment, shell quoting,replay.shgeneration, output detection (symlinked output folders, same-size rewrites), serialising overlapping calls,run.jsonand RO-Crate writing, and parsing of the tables and dblock output. - A
replay.shbuilt from hostile values (newlines, carriage returns, quotes,$(...), backticks, leading dashes) in every field it is generated from passessh -n, and running it with stub tools creates nothing but its ownreplay/folder. - An integration test starts
irit-mcpover stdio, speaks raw JSON-RPC (initialize, tools/list, tools/call), runsleanqcon a generated FASTQ pair, checks the run record against the files on disk, deletes the reports, runsreplay.shand gets the same SHA-256 for every output. It then changes an input and checks thatreplay.shfails and names the file that differs. A second one replays the review’s cases: leanqc into a symlinkedoutdir, a second leanqc refused withoutoverwrite, sheetgen refused for a file outside the root and for a newline inset, and the replay of that session. No network. - Third-party tools: unit tests map parameters to argv for each tool and check the refusals
(wrong file type, gzip and empty inputs, contradictory flags, out-of-range values, database
folders missing a file or of the wrong version, GTDB-Tk data without
skani/, flags that don’t exist in the pinned version such asskip_ani_screenandmax_memory). An integration test (Unix only) puts shell-script stand-ins for fastp, bakta, checkm2 and gtdbtk onPATH. Each stand-in refuses any flag the wrapper isn’t allowed to send. The test runs the isolate path over stdio, checks the summaries, a failed run, an exit 0 without outputs, a version warning and the run record, then deletes the outputs, replays and gets the same hashes. A second test checks the install hint when a tool is missing. A third runs stand-ins for shovill, mlst and amrfinder (with a stand-in indexed database from$AMRFINDER_DB), then the real isotable binary, and checks that the mlst row (labelled froms1.mlst.tsv) and the AMRFinderPlus report join to samples1although the assembly iscontigs.fa, then replays. A fourth uses a Shovill stand-in whose assembly changes every run and a CheckM2 stand-in whose report holds the genome’s size: after deleting every output folder,replay.shsucceeds, prints the new assembly’s contigs, length and N50 beside the run’s, and reports CheckM2’s report and isotable’s row as following it, while fastp’s JSON still matches; a fastp JSON changed by hand still fails the replay. - With the real programs: the opt-in workflow
mcp-real-tools.ymlinstalls fastp 1.4.0, Bakta 1.12.2, CheckM2 1.1.0 and GTDB-Tk 2.8.0 from Bioconda (one environment each), fetches the Bakta light and CheckM2 databases throughdblock_addanddblock_fetch, and runs the four tools through irit-mcp on Mycoplasma genitalium G37 (reads simulated from it for fastp) and on GTDB’s mock database and test genome for GTDB-Tk. It runs each tool twice to find the volatile outputs, deletes the outputs and runsreplay.sh. It only runs by hand:gh workflow run mcp-real-tools.yml. First result (2026-11-10): all calls succeeded; fastp 40,000 reads, Bakta 522 CDSs / 36 tRNAs / 3 rRNAs, CheckM2 98.9% complete and 0.08% contaminated, GTDB-Tk classified the mock test genome with ANI 100.replay.shthen re-ran 11 commands and all 41 outputs matched (run). Since then it also installs Shovill 1.4.2, mlst 2.35.0 and AMRFinderPlus 4.2.7, fetchesamrfinderplus-db-4.2-2026-10-29.1withdblock_fetch(dblock runsamrfinder_index), and runs fastp → Shovill (SKESA, 30x, no Pilon) → mlst → AMRFinderPlus on real Illumina reads of S. aureus ERR044595 (nf-core/bacass’s 1M-pair test files), AMRFinderPlus on Bakta’s proteins and GFF3 for M. genitalium, and Bakta with the dblock AMRFinderPlus database as itsamrfinderplus-db/latest(a folder of links, noamrfinder_update). Results (2026-11-11): Shovill 2,760,249 bp in under 3 minutes; mlstsaureusST22 (EMRSA-15’s type); AMRFinderPlusmecA,mecR1,blaZ,blaI,tet(38),mepA, and the point mutationsgyrA_S84L,parC_S80F,dfrB_A135T; isotable joined fastp, mlst and AMRFinderPlus into one passing row forsa; Bakta’s own AMRFinderPlus step ran on the dblock database;dblock_verifyfound every database folder unchanged afterwards. Shovill’s and AMRFinderPlus’s outputs were identical between the two runs (exceptshovill.log), though SKESA is not always so (see the volatile table); mlst’s JSON was not. GTDB’s mock database now comes throughdblock_fetchtoo (gtdbtk-r232-mockup, since GTDB fixed its MD5).replay.shre-ran 22 commands and all 53 outputs matched (run). Added on 2026-11-12: Shovill with SPAdes 3.15.5 and its default read correction, stitching and Pilon (30x) gave 2,803,881 bp in 77 s and mlst ST22 again, but a differentcontigs.fain the second identical run (hence volatile); mlst’s record held 177 inputs (the assembly,VERSION.txt2025-12-29, the scheme map, 12 BLAST files and 162 profile tables), found throughmlst --helpbehind the workflow’s wrapper script;dblock_verifywithdeepre-hashed every file of the four databases, including the 162 of the AMRFinderPlus folder with dblock’s indexes, and all matched (run). The workflow now also runscoverm_genomeon the S. aureus SKESA assembly,kleborateon K. pneumoniae HS11286’s RefSeq genome (expected: ST11, KPC-2) with M. genitalium as an assembly Kleborate gives no row, andassembly_statson M. genitalium (one 580,076 bp contig); not yet run. - Stand-ins for the paper-redo gaps (2026-11-14): Shovill →
assembly_stats(N50, L50, N90, L90 of a known assembly, andmin_contig) →coverm_genome(Shovill logged 61×, mapping 20.5×: the warning) →kleboratethrough a wrapper script thatexecs it, with stand-in bundled data inlib/python3.12/site-packages(hashed into the record) → isotable withdepthandkleboraterequired, then replay. - Stand-ins for several samples (2026-11-14):
coverm_contig(depth for one sample, a cached BAM for the other) →semibin2with a pretrained model and with the BAM →checkm2over all bins →galah(refusing a report that misses genomes and two genomes with one name; run again over the same outdir) →coverm_abundancefrom galah’s list over two samples → replay from a clean folder. The stand-in BAM’s header changes every run, as CoverM’s does; the replay says the next call read a BAM that differs and still passes. - Stand-ins for multi-sample binning (2026-11-15):
semibin2_concatenate(refusing a missing, repeated or dotted name and a file given twice) of two assemblies both calledfinal.contigs.fa→coverm_contigof both samples to the concatenated contigs withbam_cache_dir→semibin2multi(refusing a file without sample names, an environment and one BAM) →checkm2andgalahon its one bins folder → replay from a clean folder, the links remade. - With the real programs on the laptop (2026-11-15, 8 GB cap): the multi-sample route on the
two-genome mock and on three Crystal Geyser samples, with MetaBAT2 and SemiBin2
globalon the same assemblies, CheckM2 and isotable (numbers in Multi-sample binning). Not replayed (the run took about 2 hours); the stand-in test replays the route. - With the real programs on the laptop (2026-11-14, each step under an 8 GB cap, the Crystal
Geyser sample): fastp →
coverm_contigwithbam_cache_dir(depth table identical to the earlier run’s) →semibin2trained on the BAM (killed at the cap, twice) →galah→coverm_abundance→semibin2global; thenreplay.shfrom a folder without their outputs: “5 commands re-run, 62 outputs match”, 414 s, 4.46 GiB peak. Numbers insemibin2,galahandcoverm_abundance. The real-tools workflow now also installs SemiBin2 and galah and runscoverm_contigwithbam_cache_dir,semibin2(trained, on the two-genome mock),galahover the MetaBAT2 and SemiBin2 bins andcoverm_abundance; not yet run. - By hand: a session with sheetgen → leanqc → isotable → dblock_catalog replayed with all 7 outputs
matching; dblock_add, plan, verify, env and check against a local project. On 2026-11-14, the
real CoverM 0.8.0 and Kleborate 3.2.4 on BfR-EC-20867 from the paper redo:
assembly_stats,coverm_genome,kleborateand isotable through irit-mcp, thenreplay.shfrom a folder with their outputs deleted (“4 commands re-run, 5 outputs match”); andkleborateon HS11286 (ST11, KPC-2, QC warningambiguous_bases) with M. genitalium (no row, and a warning naming it).
Known gaps
Section titled “Known gaps”dblock_fetchhas not been run through the server against the real servers (dblock’s own tests cover fetching).- An unknown parameter is refused by the MCP SDK before the server sees the call, so that refusal isn’t in the run record (refusals of known parameters are).
- Inputs are hashed in full before each call, so a call on large FASTQ folders reads them twice.
replay.shwrites to the original paths; there is no option to replay into another folder.- The root check runs before the tool starts; a symlink swapped in between could still redirect a write (the server doesn’t sandbox the tools).
- Calls with overlapping outputs wait for each other, but a call may still read files another call is writing.
- The RO-Crate does not include the data, and has no
agent(who ran it) yet. - No streamable HTTP transport.
- The real programs are checked by the opt-in workflow on small genomes and GTDB’s mock database.
With R232 data, GTDB-Tk has run through irit-mcp only on a laptop by hand, for a genome the ANI
screen assigns (
gtdbprep_ani, thendata_path: <work>/gtdbtk_data; see the laptop run); tree placement through irit-mcp has not. - Bakta: the AMRFinderPlus data inside the Bakta v6 databases (
amrfinderplus-db/) may be older than theamrfinderBioconda installs with Bakta 1.12.2, and Bakta then fails with “amrfinder error”. Give Bakta dblock’samrfinderplus-db-4.2-2026-10-29.1asamrfinderplus-db/latestthrough a folder of links (dblock); runningamrfinder_updateinto the dblock Bakta folder also works, butdblock_verifythen reports that folder as changed. - Shovill 1.4.2 runs
spades.py --versioneven when SKESA assembles; SPAdes 3.15.5’s script fails on the newest Python a Bioconda solve can pick, and Shovill then stops (“Can’t parse spades version”). Install it withpython=3.11(shovill=1.4.2 python=3.11), as the workflow does. - CheckM2 1.1.0 from Bioconda can fail to load TensorFlow on newer glibc (“cannot enable
executable stack”). Setting
GLIBC_TUNABLES=glibc.rtld.execstack=2for CheckM2 works around it (the workflow does this in a wrapper script). - Kleborate from pip needs
pandasand Kaptive 3.2.x besides what pip installs (seekleborate); Bioconda’s package works without that but downloads about 900 MB for ECTyper when installed. assembly_statshas not been compared with a QUAST run (QUAST isn’t installed on the laptop); it follows QUAST 5’sbasic_stats.pyand matches hand counts and Kleborate’s contig statistics.- SemiBin2: single-sample self-supervised training did not fit in 8 GB on a real sample; the pretrained models and multi-sample binning of three 0.5 Gb samples did (see Multi-sample binning). Its training settings are not offered.
- galah takes one CheckM2 report; bins checked in several CheckM2 batches need their reports joined by hand first.
- A long Bakta or GTDB-Tk call blocks until it ends; there is no progress reporting or cancellation beyond the client closing the connection.