docs: state what each command needs as input - #4
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
Inputssection 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
trainpredictclassifysplit-fastqmatchinput-formats.mdgains a pointer to them, since it is the by-format view ofthe 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:
classifywith-ior--input-filesyields one row per FASTA record. A200-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-listaggregates a sample's contigs under one name.matchpools its whole sample list into a single query. It merges everyFASTQ 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-fastqcalls a marker only above--min-alt-percent, 95 bydefault, 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.
predicthas no unknown class. A query from a lineage absent from thetraining set still receives the closest label the forest can find; only a low
confidence and margin reveal it.
One code change
The
split-fastqhelp text claimed-k"must be odd, between 11 and 31". It isnot enforced:
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 --workspacepasses74/74.