Skip to content

docs: state what each command needs as input - #4

Merged
Paururo merged 1 commit into
mainfrom
docs/per-command-inputs
Jul 25, 2026
Merged

docs: state what each command needs as input#4
Paururo merged 1 commit into
mainfrom
docs/per-command-inputs

Conversation

@Paururo

@Paururo Paururo commented Jul 25, 2026

Copy link
Copy Markdown
Member

The reference page is organised by format and the command pages document flags,
so nothing answered the question people actually arrive with: what exactly do
I have to prepare to run this
. Each command page now opens with an Inputs
section covering the files it takes, what makes a run fail, and what is skipped
with a warning instead.

Every constraint is read out of the code, not out of existing prose.

What the sections cover

Page Anchor
train Inputs
predict Inputs
classify Inputs
split-fastq Inputs
match Inputs

input-formats.md gains a pointer to them, since it is the by-format view of
the same material.

The four that were worth writing down

These all produce output that looks perfectly reasonable when you get them
wrong, which is why they belong in the docs rather than in a validation error:

  • classify with -i or --input-files yields one row per FASTA record. A
    200-contig draft assembly is therefore reported as 200 genomes, each typed on
    whichever markers happen to land on that contig, and none of them representing
    the isolate. --input-list aggregates a sample's contigs under one name.
  • match pools its whole sample list into a single query. It merges every
    FASTQ from every row into one k-mer set and reports one best reference. It is
    the only command where a sample list does not mean one result per row.
  • split-fastq calls a marker only above --min-alt-percent, 95 by
    default, so intermediate frequencies never reach the output. That is why mixed
    infections surface as fixed markers on incompatible lineage branches rather
    than as intermediate allele fractions.
  • predict has no unknown class. A query from a lineage absent from the
    training set still receives the closest label the forest can find; only a low
    confidence and margin reveal it.

One code change

The split-fastq help text claimed -k "must be odd, between 11 and 31". It is
not enforced:

k=10  accepted
k=12  accepted
k=21  accepted
k=33  Error: k-mer size must be between 1 and 31, got 33

The text now describes what the code does and keeps the odd value as the
recommendation it always was. If the intent was to enforce odd values with a
lower bound of 11, that is a validation change and a separate decision.

Documentation builds clean under --strict; cargo test --workspace passes
74/74.

…text

The reference page is organised by format, and the command pages document
flags, so nothing answered the question people actually arrive with: what
exactly do I have to prepare to run this. Each command page now opens with an
Inputs section listing the files it takes, what makes a run fail, and what is
skipped with a warning instead.

Every constraint is taken from the code rather than from prose. The ones worth
naming, because getting them wrong produces results that look fine:

- classify with -i or --input-files yields one row per FASTA record, so a
  200-contig draft is reported as 200 genomes, each typed on whichever markers
  happen to land on that contig. --input-list aggregates contigs per sample.
- match pools every FASTQ from every row of its sample list into one query and
  reports one best reference. It is the only command where a sample list does
  not mean one result per row.
- split-fastq calls a marker only above --min-alt-percent, 95 by default, so
  intermediate frequencies never reach the output and mixed infections show up
  as fixed markers on incompatible branches.
- predict has no unknown class; a lineage absent from training still gets a
  label, and only a low confidence and margin reveal it.

The split-fastq help claimed -k 'must be odd, between 11 and 31'. It is not
enforced: k=10 and k=12 are both accepted, and only k>31 is rejected. The text
now describes what the code does and keeps the odd value as the recommendation
it always was.
@Paururo
Paururo merged commit ef6b99e into main Jul 25, 2026
1 check passed
@Paururo
Paururo deleted the docs/per-command-inputs branch July 25, 2026 12:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant