Command-line interface

The codonadaptpy command is installed with the package. Display the available subcommands with:

codonadaptpy --help
codonadaptpy --version

Analyze coding sequences

codonadaptpy analyze coding_sequences.fasta \
  --reference host_reference.json \
  --formats json,csv,html \
  --plots \
  --output results

With --plots, CodonAdaptPy writes browser-independent 600-DPI PNG figures by default. Figures include RSCU heatmaps and profiles, evolutionary diagnostics, nucleotide-composition summaries, and dinucleotide profiles and heatmaps. Select formats explicitly when needed:

codonadaptpy analyze coding_sequences.fasta \
  --plots \
  --plot-formats png,pdf,svg,tiff \
  --plot-group-key genotype \
  --output results

PNG, PDF, SVG and TIFF figures use Matplotlib only and are the default. Install the plotting dependency with python -m pip install "CodonAdaptPy[plot]".

Interactive HTML is optional and useful for hovering, zooming and inspecting large datasets. Install it with python -m pip install "CodonAdaptPy[interactive]", then request --plot-formats html or --plot-formats png,html. Plotly JavaScript is embedded in each output file, so viewing does not require internet access. Kaleido and Chrome automation are not required.

The static collection includes codon_preference_upset, an UpSet-style view of exact preferred-codon overlaps across the field selected by --plot-group-key. A codon is preferred when its group-mean RSCU is at least 1.6 by default. CodonAdaptPy also writes codon_preference_intersections.tsv, which lists the groups and codons behind every intersection. Configure the analysis with:

codonadaptpy analyze coding_sequences.csv \
  --plots \
  --plot-group-key genotype \
  --rscu-preference-threshold 1.6 \
  --upset-max-intersections 20 \
  --output results

The intersections are descriptive codon-usage signatures. They should not be interpreted as evidence of selection, host adaptation, or phenotype without appropriate evolutionary or experimental analysis.

Additional data-aware publication figures include:

rscu_similarity_heatmap: cosine similarity among group-mean 59-codon RSCU profiles;
rscu_pca_biplot: standardized sample ordination with influential codon loadings;
metric_correlation_heatmap: relationships among variable scalar codon metrics;
host_adaptation_landscape: CAI versus RCDI by host, with SiD represented by marker area.

The PCA and correlation figures require at least three informative sequences, and the host landscape requires one or more --host references. These conditions do not stop the analysis. Instead, plot_manifest.json lists the figures generated and gives an explicit reason for each skipped figure.

For a table containing isolate and gene metadata, run per-gene analysis and boundary-aware pooling together:

codonadaptpy analyze isolate_cds.csv \
  --aggregate-by isolate \
  --gene-key gene \
  --focus-gene F \
  --output results

The input table may contain identifier, sequence, isolate, gene, genotype, host, collection_date, country and accession columns. Additional columns are retained as metadata.

For sequences and annotations stored separately, the FASTA identifiers must match the metadata identifier column exactly:

identifier,isolate,gene,genotype,host,collection_date
sample01_F,sample01,F,A,chicken,2023-05-10
sample02_F,sample02,F,B,turkey,2024-02-17

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

CodonAdaptPy uses the supplied genotype value for groups; it does not assign genotype A, B, or another label from sequence alone. See the input and validation guide for supported metadata layouts and identifier validation.

Compare host references

codonadaptpy compare coding_sequences.fasta \
  --host chicken_reference.json \
  --host turkey_reference.json \
  --host human_reference.json \
  --output host_comparison

Build a reference

codonadaptpy reference build highly_expressed_cds.fasta \
  --name chicken_high_expression \
  --version 1 \
  --source "curated CDS collection" \
  --output chicken_reference.json

References should document their sequence-selection criteria, organism or cell type, database release, genetic code and provenance.

Infer a phylogeny

codonadaptpy phylogeny coding_sequences.fasta \
  --metadata metadata.csv \
  --group-key genotype \
  --tree-method iqtree \
  --bootstrap 1000 \
  --output phylogeny_results

Here, --group-key genotype colors or groups tree tips using the genotype column in metadata.csv. Records without that field are displayed as Unknown; tree clustering by itself does not create genotype labels.

Publication mode requires trimAL unless --no-trim is explicitly selected. CodonAdaptPy reports missing executables and does not silently substitute an alternative method.

Optimize a coding sequence

codonadaptpy optimize input.fasta \
  --reference host_reference.json \
  --candidates 20 \
  --seed 12345 \
  --output optimized

Optimized candidates require downstream review for RNA structure, splicing, regulatory elements and experimental performance not represented by the selected constraints.