Getting started

Choose an installation

The core package has no mandatory third-party Python dependencies. Install the stable release from PyPI:

python -m pip install CodonAdaptPy

Install all optional Python dependencies with:

python -m pip install "CodonAdaptPy[all]"

From a cloned repository, install an editable development environment with:

python -m pip install --editable ".[dev,all]"

For alignment and phylogenetic inference, use the supplied Conda environment so MAFFT, trimAL, IQ-TREE and FastTree are available on the command line:

conda env create -f environment.yml
conda activate codonadaptpy

Analyze one coding sequence

from codonadaptpy import CodonAnalyzer, SequenceRecord, ValidationConfig
from codonadaptpy.analyzer import AnalysisConfig
from codonadaptpy.references import ReferenceManager

reference = ReferenceManager().get("uniform_standard")
analyzer = CodonAnalyzer(
    AnalysisConfig(validation=ValidationConfig()),
    reference=reference,
)

record = SequenceRecord("example_cds", "ATGGCTGCCGACTAA")
result = analyzer.analyze(record)

print(result.metrics["gc3s"])
print(result.metrics["cai"])
print(result.rscu)

The bundled uniform_standard reference is an explicitly synthetic equal-count profile intended for testing and normalization. Biological host-adaptation claims require a curated, versioned reference created from an appropriate CDS collection.

Analyze a file

from codonadaptpy import CodonAnalyzer

results = CodonAnalyzer().analyze_file("coding_sequences.fasta")
for result in results:
    print(result.identifier, result.metrics["enc"], result.metrics["gc3s"])

Supported inputs include pasted DNA or RNA, FASTA, GenBank, CSV, TSV and ZIP archives of FASTA files. See the input and validation guide before analyzing genome-scale or partial-CDS data.

Boundary-aware per-isolate analysis

Genome-wide codon analysis should pool counts from validated CDSs within each isolate. A raw genome sequence should not be treated as one continuous CDS, and adjacent genes should not create artificial codons or codon pairs.

from codonadaptpy import CDSAggregator, CodonAnalyzer
from codonadaptpy.parsers import SequenceParser

aggregator = CDSAggregator(CodonAnalyzer())
records = SequenceParser().parse("isolate_cds.csv")
analyses = aggregator.analyze(records, isolate_key="isolate", gene_key="gene")

Save reproducible outputs

Use ReportGenerator to export structured results rather than copying values manually:

from codonadaptpy.reporting import ReportGenerator

reporter = ReportGenerator()
reporter.write_json(results, "results/analysis.json")
reporter.write_table(results, "results/analysis.csv")

Every analysis result includes validation details and metadata describing the package version, platform, configuration, input checksum and reference where applicable.