`pathotypr match`¶

Find the best-matching reference genome for a set of FASTQ reads using k-mer containment.

pathotypr match counts the k-mers in your sequencing reads and scores them against a database of candidate reference genomes packed into a single multi-FASTA. It reports the single reference that shares the largest fraction of your reads' k-mers, together with a weighted containment fraction. Use it for quick reference selection or species/strain sanity checks before running a full classification.

One query set, one best match

match pools all the FASTQ files you provide (whether via --input or every row of an --input-list) into a single query k-mer set and reports one best-matching reference. It does not produce per-sample rows. To keep samples separate, run match once per sample.

Synopsis¶

pathotypr match -r <references.fasta> (-i <reads.fq> ... | -l <list.tsv>) [-o <report.tsv>] [OPTIONS]

You must supply exactly one input source (-i/--input or -l/--input-list) and a reference database (-r/--references).

Inputs¶

What	Flag	Format
Reference database	`-r, --references`	Multi-record FASTA: one record per candidate genome
Reads	`-i, --input` or `-l, --input-list`	FASTQ, plain or gzipped

match pools everything into a single query

This is the one place where a sample list does not mean one result per row. match reads every FASTQ from every row, merges them into one k-mer set, and reports one best-matching reference. The sample-name column is read but ignored for grouping.

List only the reads belonging to the single query you want matched. To match several samples, run match once per sample.

Requirements¶

[x] The reference FASTA is multi-record, the opposite of what classify and split-fastq want. Each record is one candidate genome, and its header is what gets reported.
[x] -k between 1 and 31.
[x] Every FASTQ path exists, checked before counting starts.

No markers and no reference coordinates

match compares raw k-mer content, so it needs no marker panel, no GFF and no shared coordinate system. That is what lets it answer "which of these genomes is my sample closest to" for an unknown organism, before you have a panel to type it with.

How it works¶

Count k-mers across every input FASTQ file in parallel, tallying occurrence counts.
Filter likely sequencing noise by dropping low-count k-mers (see --min-kmer-count).
Stream the reference multi-FASTA in batches, extracting the unique k-mers of each reference.
Score each reference by the weighted fraction of query k-mer occurrences it contains.
Report the highest-scoring reference and its Shared_Kmer_Fraction.

Bounded memory

References are streamed and scored one batch at a time — only a single batch is resident at once. Peak memory is governed by the query k-mer set plus one batch of references, not by the total number of reference genomes in the database. Batch size adapts to the number of CPU threads.

Options¶

Option	Default	Required	Description
`-i, --input <FILE>...`	—	this or `--input-list`	One or more query FASTQ files (gzip supported).
`-l, --input-list <FILE>`	—	this or `--input`	TSV listing FASTQ files: `sample_name\treads1.fastq[\treads2.fastq]`.
`--paired`	`false`	no	Force paired-end mode.
`--no-auto-paired`	`false`	no	Disable auto paired-end detection.
`-r, --references <FILE>`	—	yes	Single multi-FASTA containing all reference genomes.
`-o, --output <FILE>`	stdout	no	Output TSV report. Prints to the console if omitted.
`-k, --kmer-size <N>`	`31`	no	k-mer size for comparison (1–31).
`-t, --threads <N>`	all cores	no	Number of CPU threads.
`--early-stop-confidence <FLOAT>`	`0.0`	no	Reserved; accepted but not read in the current release (no effect).
`--early-stop-min-kmers <N>`	`1000000`	no	Reserved; accepted but not read in the current release (no effect).
`--strict-percentages`	`true`	no	Legacy flag retained for backward compatibility (default on); it does not change current results.
`--min-kmer-count <N>`	`2`	no	Minimum k-mer count to keep (singleton filtering as noise). Set `1` to keep all. Only applied when there are more than 100k unique k-mers and this value is greater than `1`.
`--excel`	`false`	no	Also write an Excel (`.xlsx`) file.

Global flags¶

Available on every subcommand:

Flag	Description
`-v, --verbose`	Increase log verbosity. Repeatable: `-v` = debug, `-vv` = trace.
`-h, --help`	Print help.

Paired-end handling

When you pass more than one file to --input, match auto-detects paired-end files from common naming conventions (_1/_2, _R1/_R2). Because match pools all reads into one query set, this grouping does not change the reported result. Use --paired to force pairing (it requires an even number of files) or --no-auto-paired to switch detection off.

Examples¶

Paired readsSample listExcel + tuning

pathotypr match \
  -r references.fasta \
  -i reads_R1.fastq.gz reads_R2.fastq.gz \
  -o report.tsv

Counts k-mers from both mates, scores them against every genome in references.fasta, and writes the best match to report.tsv.

pathotypr match \
  -r references.fasta \
  -l samples.tsv \
  -o report.tsv

Reads every FASTQ path listed in samples.tsv (sample_name\treads1.fastq[\treads2.fastq]) and pools them into a single query. See Input formats for the TSV layout.

pathotypr match \
  -r references.fasta \
  -i reads_R1.fastq.gz reads_R2.fastq.gz \
  -o report.tsv \
  -k 27 -t 8 --excel

Uses a k-mer size of 27 on 8 threads and additionally writes report.xlsx beside the TSV.

--excel needs -o

The Excel file is written only when an output path is given with -o/--output; its name is derived from the TSV path (report.tsv → report.xlsx). If output goes to the console (no -o), --excel has no effect.

Output¶

TSV report¶

The report has a header row followed by exactly one data row. Columns are tab-separated:

Query_Files Best_Match_Reference    Shared_Kmer_Fraction

Column	Description
`Query_Files`	Comma-separated list of the input FASTQ file paths that were pooled into the query.
`Best_Match_Reference`	FASTA header line of the highest-scoring reference, including any description after the first space.
`Shared_Kmer_Fraction`	Weighted k-mer containment score between `0` and `1`, printed to four decimal places. Higher means more of the query's k-mer content is present in the matched reference.

Example:

Query_Files Best_Match_Reference    Shared_Kmer_Fraction
reads_R1.fastq.gz,reads_R2.fastq.gz NC_000962.3 0.9873

If no reference shares any k-mers with the query, the first reference is still reported with a Shared_Kmer_Fraction of 0.0000 — read a near-zero score as "no usable match". Only an empty reference FASTA yields a header-only report.

Excel report (optional)¶

With --excel and -o, match also writes an .xlsx workbook whose name is the TSV path with .tsv replaced by .xlsx (otherwise .xlsx is appended). It contains the same three columns as the TSV, with a frozen, styled header row and an autofilter.

pathotypr match¶