Custom tools import

samovar tools import

Register an executable in the install config (tools.<name>) so prepare / exec / resolve_executable find it without a full ./install.sh.

samovar tools import \
  --name kaiju \
  --env "" \
  --exec kaiju \
  --exec-path /usr/bin/kaiju \
  --type annotator

Flag	Alias	Meaning
--name	-n	Config key. Also the prepare token (--kaiju-test "kaiju /db").
--env		"" (host) or conda (path is a sidecar prefix). Default "".
--exec		Binary name (default: --name). Used as prefix/bin/<exec> when --exec-path is a conda env directory.
--exec-path		File, conda prefix, or a name on PATH. If omitted, PATH is searched for --exec then --name.
--type	-t	Stage / tool_group.

--type values: annotator (a), reads_generator (reads), metagenome_generator (meta), table_reads_generator (table), scoring (score), workflow, runtime, compiler.

Stored row:

"name": ["env", "workflow", "path", "tool_group"]

workflow is conda when --env conda, otherwise bash. path is the resolved file, or the conda prefix.

# Native classifier already on PATH
samovar tools import -n kaiju --exec kaiju --type annotator

# Conda sidecar (prefix, not the file)
samovar tools import -n nanosim --env conda --exec simulator.py \
  --exec-path "$SAMOVAR_ROOT/.cache/samovar/envs/nanosim" --type meta

# Your own annotator script
samovar tools import -n myclf --exec-path /scratch/myclf.py --type annotator
chmod +x /scratch/myclf.py

Then:

samovar prepare --output_dir RUN --myclf-test "myclf /path/to/db"

./install.sh rediscovers PATH tools and keeps existing tools.* values.

---

How a tool must look (by --type)

annotator

Input (SamovaR always passes these flags):

Flag	Value
-i	R1 FASTQ (.fastq or .fastq.gz)
-I	R2 FASTQ (may be empty; still passed)
-d	Database path from prepare (--name-test "name DB")
-o	Output file path (create/overwrite)
-t	Thread count

Do not require -p unless you are a custom.sh router tool (centrifuge, metauto, assembly_hybrid). Imported annotators are invoked directly.

Output file (-o): tab-separated, no header, two columns:

<read_id>	<ncbi_taxid>

• One row per classified read (skip unclassified / taxid 0 if you want).
• read_id is the FASTQ header token without @, without /1 /2.
• Empty -o is allowed (zero reads).
• Snakemake names the file {sample}_{run}.custom_{name}.out. Downstream parsers only care about the two columns.

Processing: classify reads → write that TSV. Do not write logs into -o. Put temp files next to -o or under $TMPDIR and delete them.

Exit 0 on success even if every read is unclassified (empty file). Non-zero abort the annotators Snakemake rule.

Native names (kraken2, kaiju, metaphlan, …) keep their own CLIs; import only records the binary path. Do not import those under a new --name if you still pass --kaiju-test "kaiju …" — the type is taken from the command basename.

reads_generator / metagenome_generator

ISS/ART/wgsim/CAMISIM/NanoSim are wired inside generate, not via this flag set. Import still records path + type so samovar tools --status and PATH prefixes work. Their native CLIs are unchanged.

table_reads_generator

Optional R / table→ISS helpers. Path should be a runnable script. Annotation-table regeneration is documented in samovar_regenerate.md.

scoring

OPAL / MultiQC: executable on PATH or absolute --exec-path. No FASTQ contract.

workflow / runtime / compiler

Snakemake, Nextflow, python, g++: path only.

---

Built-in custom.sh tools

centrifuge, metauto, assembly_hybrid, and the dummy constant-taxID classifier still go through src/annotators/custom.sh (-p <name>). Importing centrifuge only updates the binary location used inside that router, not the SamovaR -i/-I/-d/-o contract.