FlavoTyper Results Dictionary

This document describes every column in typing_results.tsv, all possible special values, and the internal reason codes recorded in typing_results.jsonl.

---

TSV columns (23 total)

Identification

Column	Type	Description
Sample_name	string	Sample ID derived from the input filename (FASTA extension stripped)
Typed	bool	True if typing was executed; False if the QC gate blocked typing

Typing result

Column	Type	Description
O_type	string	O-type label (e.g. O:1) or a special state (see below)
R_type	string	R-type label (e.g. R1V1, R2, R0) or a special state (see below)
S_type	string	S-type label (S0 or S1), or NotTyped
Serotype	string	Combined call as O_type-S_type-R_type (e.g. O:1-S0-R1V1, O:0-S0-R0)
Call_state	string	Resolved, Partial, Ambiguous, Undefined, or NotTyped (see below)
Alternative_serotypes	string	Semicolon-separated alternative calls when evidence is ambiguous; empty when resolved

Species verification

Column	Type	Description
Species_check	string	Enabled if fastANI was run; Disabled if --no-species-check was used
Species_passed	string	True or False when species check was run; empty when disabled
Calculated_ANI	float	Best ANI value found by fastANI (empty if check was disabled or no hits)
ANI_reference	string	Filename of the reference genome that gave the best ANI (empty if unavailable)

Assembly QC

Column	Type	Description
N_contigs	int	Number of contigs in the genome assembly
Genome_size_bp	int	Total assembly length in base pairs
GC_percent	float	Assembly GC content (%)
QC_passed	bool	True if all blocking QC checks passed; False if typing was blocked
QC_warnings	string	All QC messages separated by ; — includes blocking failures and advisory warnings

Marker evidence

Column	Type	Description
Present_markers	string	Semicolon-separated marker gene names that passed identity + coverage thresholds
Present_markers_ranges	string	Genomic coordinates of accepted marker hits: gene:start-end separated by ;
Present_markers_contig_names	string	Contig names of accepted marker hits: gene:contig separated by ;

Warnings and diagnostics

Column	Type	Description
Typing_warnings	string	Typing-stage warnings separated by ; (e.g. cross-contig markers, unsatisfied distance rules, novel-combination flag when no reference strain exists)
Serotype_reference	string	Human-readable provenance sentence for resolved calls with a known reference strain (e.g. This serotype was observed in F. psychrophilum strain DK001; GenBank: GCA_900186405; PMID: 29467746.). Empty when the serotype has no reference strain in data/reference_loci.fasta, or for ambiguous/not-typed calls.
Raw_hits	string	All BLASTN hits including those below thresholds, separated by ;. Format: gene\|identity=X\|coverage=X\|contig=X\|coords=start-end

---

Special values for O_type and R_type

O_type

Value	Meaning
O:0 – O:7	Uniquely assigned O-type
Undefined	No O-marker was detected above thresholds
Ambiguous	More than one O-marker was detected; a unique O-type cannot be determined
NotTyped	QC gate failed; typing was not attempted

R_type

Value	Meaning
R1V1, R1V2, R1V3	Specific R1 variant assigned by variant rules
R1	R1 base group detected but no variant rule matched
R2, R3, R4	R2/R3/R4 base group detected (S-type is reported separately)
R0	Default assigned to O-types (e.g. O:0) that declare no R-markers and none are detected
Undefined	No valid R base group could be assigned from detected markers
Ambiguous	Multiple valid R interpretations matched (multiple base groups or variants)
NotTyped	QC gate failed; typing was not attempted

S_type

Value	Meaning
S0	S1 marker genes not detected — default S-type
S1	All S1 marker genes detected
NotTyped	QC gate failed; typing was not attempted

---

Call states

Call_state	Meaning
Resolved	Both O-type and R-type are uniquely assigned
Partial	Exactly one of O-type or R-type is Undefined (the other is typed)
Ambiguous	One of O-type or R-type is Ambiguous
Undefined	Nothing was typed: O-type and R-type are both Undefined and no S1 markers were detected (S0)
NotTyped	QC gate failed; typing was not attempted

---

Reason codes

Reason codes are recorded in typing_results.jsonl (field reason_codes). They provide machine-readable transparency about the decision path.

O-type reasons

Code	Meaning
O_UNIQUE_MARKER	Exactly one O-marker detected → unique O-type assigned
O_MULTIPLE_MARKERS	Multiple O-markers detected → Ambiguous
O_NO_MARKER	No O-marker detected → Undefined

R-type reasons

Code	Meaning
R_BASE_GROUP_DETECTED	Exactly one R base group satisfied
R_VARIANT_RULE_MATCH	A specific variant rule matched
R_BASE_ONLY	Base group detected but no variant matched; base label returned
R_MULTIPLE_BASE_GROUPS	More than one base group satisfied → Ambiguous
R_MULTIPLE_VARIANTS	More than one variant rule matched → Ambiguous
R_NO_BASE_GROUP	No base group satisfied → Undefined
R_DEFAULTED_TO_R0	O-type declared as not requiring R-markers and none detected → R0

QC reason

Code	Meaning
QC_GATE_FAILED	Sample was not typed because QC checks failed