Input and validation guide

FASTA identifiers must be unique. CSV/TSV input requires identifier (or id/name) and sequence (or seq) columns; other columns become metadata. GenBank input yields individual CDS features and uses a whole record only when it contains no CDS features. ZIP parsing reads FASTA members without extracting them.

Metadata

Per-isolate aggregation requires an isolate field and a gene field. These can be columns in the sequence table, key/value tokens in FASTA descriptions, GenBank CDS annotations, or a separate CSV/TSV joined with --metadata. A typical metadata table contains identifier,isolate,gene,genotype,host,collection_date,country,accession.

CodonAdaptPy does not infer genotype, host, isolate, collection date, country, or accession from the sequence. These values must be supplied by the user or obtained from a curated source. Genotype metadata can be used for grouping and tree-tip colors, but the label remains an annotation rather than an automatic genotype call.

For separate FASTA and metadata files, use matching identifiers:

>sample01_F
ATGGCT...TAA
>sample02_F
ATGGCC...TAA

identifier,isolate,gene,genotype,host,collection_date,country,accession
sample01_F,sample01,F,A,chicken,2023-05-10,USA,ABC00001
sample02_F,sample02,F,B,turkey,2024-02-17,Canada,ABC00002

codonadaptpy analyze sequences.fasta \
  --metadata metadata.csv \
  --aggregate-by isolate \
  --gene-key gene \
  --focus-gene F \
  --plots \
  --output results

The metadata identifier column must contain unique values. By default it is named identifier; use --metadata-id-column when the table uses another name. Identifiers are matched exactly, including capitalization. Duplicate metadata identifiers or sequences without matching metadata are reported as errors so that annotations cannot be silently assigned to the wrong record.

Metadata can instead be embedded in FASTA descriptions as whitespace-separated key=value tokens:

>sample01_F isolate=sample01 gene=F genotype=A host=chicken
ATGGCT...TAA
>sample02_F isolate=sample02 gene=F genotype=B host=turkey
ATGGCC...TAA

Genome-wide codon analysis pools annotated CDSs; it does not analyze a raw multi-ORF genome as one reading frame. Each CDS must be oriented 5′→3′ in its coding direction. Reading frames restart independently, terminal stops are removed, and nucleotide-word and codon-pair calculations respect gene boundaries.

RNA U is converted to DNA T by default and recorded as a warning. IUPAC ambiguous nucleotides are recognized and handled according to reject, skip, or allow. Unsupported symbols are errors. The reading frame is a zero-based offset. In partial mode, missing start or stop codons and trailing incomplete codons may be downgraded from errors; internal stops remain errors.

Strict mode raises on invalid sequences. Lenient mode returns a ValidationReport so a batch workflow can inspect problems. Metrics exclude ambiguous codons because assigning them probabilistically would introduce an undocumented model assumption.