Python API and extension guide

CodonAnalyzer is the primary analysis interface. Individual calculators in codonadaptpy.metrics can also be used independently. Inputs and outputs are standard-library dataclasses that can be serialized without a framework-specific schema library and remain available regardless of which optional dependencies are installed.

CDSAggregator uses a configured CodonAnalyzer to generate per-gene results, boundary-aware genome-wide results for each isolate, and results for any requested focus genes. Records identify their isolate and gene through metadata; no gene name is hard-coded.

Add a metric by implementing a focused calculation class and invoking it from CodonAnalyzer.analyze. Add a new input format in SequenceParser.parse. Add reference sources by constructing ReferenceProfile objects and registering them with ReferenceManager. Biological tables should always include database/release provenance, selection criteria, taxonomy, and checksums when available.

ComparativeAnalyzer.automatic_test(left, right, paired=False, alpha=0.05) records its normality diagnostic and selects Welch’s t test or Mann–Whitney U for independent samples, and a paired t test or Wilcoxon signed-rank test for paired samples. Normality is assessed on within-pair differences for paired designs. The returned dictionary includes the selected test, sample sizes, statistic, p value, effect-size name and value, and the documented selection policy.

ComparativeAnalyzer accepts mappings containing numeric metrics and grouping metadata. SciPy is used for inferential tests and clustering, while NumPy and scikit-learn support multivariate analyses. It exposes Welch and Mann-Whitney tests, Hedges’ g, FDR correction, PCA, correspondence analysis, stratified LDA with a reproducible train/test split, hierarchical clustering, correlations, and distances.

PlotManager provides optional self-contained interactive HTML for hover and zoom workflows. It uses Plotly only when requested and does not use Kaleido or browser automation. PublicationPlotManager returns browser-independent static Matplotlib figures with the Okabe-Ito palette, redundant markers, sample sizes, standard errors, outward-offset axes, and vector-compatible output. Its methods cover grouped PCA and LDA, an automatic RSCU PCA biplot, held-out confusion matrices, exact 59-codon RSCU profiles and group-similarity heatmaps, UpSet-style exact preferred-codon intersections, composition summaries, metric correlations, ENC-GC3s/neutrality/PR2 diagnostics, all 16 dinucleotide O/E profiles and heatmaps, scalar metric panels, sliding-window CAI, and multi-host CAI/RCDI/SiD landscapes. save exports PNG, TIFF, PDF, or SVG.

Phylogenetic and temporal API

PhylogeneticAnalyzer writes FASTA, aligns with MAFFT, trims with trimAL, and infers an ML tree using IQ-TREE/ModelFinder with ultrafast bootstrap or FastTree. External command arguments and result paths are returned in a serializable PhylogenyResult. Setting trim_required=True is recommended for publication workflows because it prevents silent use of an untrimmed alignment.

TemporalAnalyzer.temporal_signal performs a root-to-tip regression and can search candidate roots in the style of a rapid TempEst diagnostic. The result contains rate, fitted root date, R², p value, residuals, and the selected outgroup. date_tree applies that deterministic strict-clock mapping while anchoring observed tips to their collection dates. lineage_through_time counts dated branches across a calendar grid. These methods do not implement a relaxed clock, Bayesian posterior sampling, effective population size, or HPD intervals and therefore must not be labeled as Bayesian skyline results.

PhylogeneticComparator.robinson_foulds prunes two trees to shared accessions and reports raw and normalized unrooted Robinson-Foulds distance. This is useful for quantifying whole-genome versus focus-gene topology discordance.

ETE3TreePlotter uses ETE3 for topology parsing, rooting, traversal, pruning, and node metadata, then renders headlessly with Matplotlib. It provides ML tree, time-tree, temporal-signal, and deterministic LTT figures as 600 dpi raster or vector output without ETE3’s optional Qt interface.

High-level analysis API

class codonadaptpy.analyzer.AnalysisConfig(validation=<factory>, sliding_window=30, sliding_step=1, simulate_cai=0, random_seed=1, strict=True)

Configure validation, windows, simulation, and reproducibility settings.

Parameters:

• validation (ValidationConfig)

• sliding_window (int)

• sliding_step (int)

• simulate_cai (int)

• random_seed (int)

• strict (bool)

class codonadaptpy.analyzer.CodonAnalyzer(config=None, *, reference=None, hosts=None)

Coordinate codon-usage and adaptation analyses through one interface.

Initialize an analyzer with optional target and host references.

Parameters:

• config (AnalysisConfig | None)

• reference (ReferenceProfile | None)

• hosts (dict[str, ReferenceProfile] | None)

analyze(record)

Analyze one sequence and return a structured result.

Parameters:

record (SequenceRecord)

Return type:

AnalysisResult

analyze_many(records)

Analyze records in deterministic input order.

Parameters:

records (list[SequenceRecord])

Return type:

list[AnalysisResult]

analyze_cds_collection(identifier, records, *, metadata=None)

Analyze pooled coding regions while preserving every CDS boundary.

Each member is validated and framed independently. Terminal stops are excluded from pooled codon and composition metrics, and sequence-word plus codon-pair calculations never span adjacent CDSs.

Parameters:

• identifier (str)

• records (list[SequenceRecord])

• metadata (dict[str, Any] | None)

Return type:

AnalysisResult

analyze_file(source, *, fmt=None)

Parse and analyze every record in a supported input file.

Parameters:

• source (str | Path)

• fmt (str | None)

Return type:

list[AnalysisResult]

codonadaptpy.analyzer.analyzer_from_reference_files(reference_path=None, host_paths=None, *, config=None)

Build an analyzer by loading reference profiles from disk.

Parameters:

• reference_path (str | Path | None)

• host_paths (list[str | Path] | None)

• config (AnalysisConfig | None)

Return type:

CodonAnalyzer

Sequence models and validation

class codonadaptpy.models.SequenceRecord(identifier, sequence, description='', metadata=<factory>)

Store a named nucleotide sequence and arbitrary sample metadata.

Parameters:

• identifier (str)

• sequence (str)

• description (str)

• metadata (dict[str, Any])

to_dict()

Return a JSON-compatible representation of the record.

Return type:

dict[str, Any]

class codonadaptpy.models.ValidationConfig(reading_frame=0, genetic_code=1, require_start=True, require_stop=True, ambiguous_policy='reject', allow_partial=False, convert_rna=True)

Control normalization and coding-sequence quality checks.

Reading frames use zero-based offsets 0, 1, or 2. Ambiguous codons may be rejected, skipped by downstream analyses, or retained with warnings. Partial sequences relax start, stop, and divisible-by-three requirements while preserving all other diagnostics.

Parameters:

• reading_frame (Literal[0, 1, 2])

• genetic_code (int)

• require_start (bool)

• require_stop (bool)

• ambiguous_policy (Literal['reject', 'skip', 'allow'])

• allow_partial (bool)

• convert_rna (bool)

class codonadaptpy.models.ValidationReport(identifier, normalized_sequence, issues=<factory>, genetic_code=1, reading_frame=0)

Collect normalized sequence data and structured validation findings.

Parameters:

• identifier (str)

• normalized_sequence (str)

• issues (list[ValidationIssue])

• genetic_code (int)

• reading_frame (int)

property is_valid: bool

Return True when the report contains no error-level issues.

property errors: list[ValidationIssue]

Return only error-level findings.

property warnings: list[ValidationIssue]

Return only warning-level findings.

to_dict()

Return a JSON-compatible representation of the report.

Return type:

dict[str, Any]

class codonadaptpy.validation.SequenceValidator(config=None)

Validate and normalize coding sequences under a fixed policy.

Initialize the validator and resolve its selected genetic code.

Parameters:

config (ValidationConfig | None)

validate(record, *, raise_on_error=False)

Validate one sequence record and return every detected issue.

Parameters:

• record (SequenceRecord) – Input record containing an identifier and nucleotide sequence.

• raise_on_error (bool) – Raise SequenceValidationError after collecting errors. The default returns an invalid report for batch-friendly behavior.

Return type:

ValidationReport

class codonadaptpy.parsers.SequenceParser

Read supported sequence inputs into consistent sequence records.

parse(source, *, fmt=None)

Parse a path, text stream, or direct nucleotide sequence.

Format is inferred from file extensions when omitted. Plain strings that do not identify existing paths are treated as pasted sequences unless they begin with > and therefore represent FASTA text.

Parameters:

• source (str | Path | TextIO)

• fmt (str | None)

Return type:

list[SequenceRecord]

parse_fasta(handle)

Yield records from FASTA-formatted text with duplicate checks.

Parameters:

handle (Iterable[str])

Return type:

Iterator[SequenceRecord]

parse_table(path)

Yield records from CSV/TSV containing identifier and sequence columns.

Parameters:

path (str | Path)

Return type:

Iterator[SequenceRecord]

parse_genbank(path)

Yield CDS features, or whole records without CDS, from GenBank input.

Parameters:

path (str | Path)

Return type:

Iterator[SequenceRecord]

attach_metadata(records, path, *, identifier_column='identifier')

Attach CSV/TSV metadata rows to records by unique identifier.

Parameters:

• records (list[SequenceRecord])

• path (str | Path)

• identifier_column (str)

Return type:

list[SequenceRecord]

parse_zip(path)

Yield FASTA and delimited records directly from a ZIP archive.

Parameters:

path (str | Path)

Return type:

Iterator[SequenceRecord]

References and aggregation

class codonadaptpy.references.ReferenceProfile(name, counts, genetic_code=1, version='1', source='user-supplied', description='', metadata=<factory>)

Represent versioned codon counts and their scientific provenance.

Parameters:

• name (str)

• counts (dict[str, float])

• genetic_code (int)

• version (str)

• source (str)

• description (str)

• metadata (dict[str, Any])

to_dict()

Return profile content in JSON-compatible form.

Return type:

dict[str, Any]

class codonadaptpy.references.ReferenceManager

Manage named codon profiles and reproducible reference persistence.

Initialize a registry containing an explicitly synthetic baseline.

register(profile, *, replace=False)

Validate and register a profile under its unique name.

Parameters:

• profile (ReferenceProfile)

• replace (bool)

Return type:

None

from_sequences(name, records, *, genetic_code=1, version='1', source='user CDS set')

Build a reference by pooling strictly validated coding sequences.

Parameters:

• name (str)

• records (list[SequenceRecord])

• genetic_code (int)

• version (str)

• source (str)

Return type:

ReferenceProfile

get(name)

Return a registered profile or raise a domain-specific error.

Parameters:

name (str)

Return type:

ReferenceProfile

list()

Return catalog metadata without duplicating full count tables.

Return type:

list[dict[str, Any]]

save(name, path)

Serialize a registered profile to deterministic JSON.

Parameters:

• name (str)

• path (str | Path)

Return type:

Path

load(path, *, replace=False)

Load JSON or two-column CSV/TSV reference data and register it.

Parameters:

• path (str | Path)

• replace (bool)

Return type:

ReferenceProfile

class codonadaptpy.aggregation.CDSAggregator(analyzer)

Group CDS records and calculate gene-wise plus genome-wide results.

Initialize aggregation around an existing configured analyzer.

Parameters:

analyzer (CodonAnalyzer)

analyze(records, *, isolate_key='isolate', gene_key='gene', focus_genes=())

Analyze CDSs grouped by metadata-defined biological isolate.

Parameters:

• records (list[SequenceRecord])

• isolate_key (str)

• gene_key (str)

• focus_genes (tuple[str, ...])

Return type:

list[IsolateAnalysis]

class codonadaptpy.aggregation.IsolateAnalysis(isolate_id, genome_result, gene_results, focus_gene_results=<factory>)

Store all analysis scopes generated for one biological isolate.

Parameters:

• isolate_id (str)

• genome_result (AnalysisResult)

• gene_results (list[AnalysisResult])

• focus_gene_results (dict[str, list[AnalysisResult]])

to_dict()

Return nested isolate output in JSON-compatible form.

Return type:

dict[str, Any]

Comparative analysis and visualization

class codonadaptpy.comparative.ComparativeAnalyzer

Provide group-level statistical and multivariate analysis helpers.

summarize(values)

Return count, mean, median, standard deviation, minimum, and maximum.

Parameters:

values (Sequence[float])

Return type:

dict[str, float]

group_summaries(records, *, group_key, metric_keys)

Summarize selected numeric metrics for each metadata group.

Parameters:

• records (Sequence[Mapping[str, Any]])

• group_key (str)

• metric_keys (Sequence[str])

Return type:

dict[str, dict[str, dict[str, float]]]

compare_two_groups(left, right, *, test='welch')

Run Welch or Mann-Whitney testing and calculate Hedges’ g.

Parameters:

• left (Sequence[float])

• right (Sequence[float])

• test (str)

Return type:

dict[str, float]

automatic_test(left, right, *, paired=False, alpha=0.05, estimand='mean', confidence=0.95, bootstrap_replicates=2000, random_seed=1)

Run an estimand-first paired or independent two-sample analysis.

estimand="mean" tests a mean difference using a paired t test or Welch’s unequal-variance t test. estimand="distribution" tests a paired shift with Wilcoxon’s signed-rank test or an independent stochastic-ordering difference with the Mann–Whitney U test. This choice is made from the scientific estimand and sampling design, not from a preliminary normality-test decision.

Normality diagnostics remain available as model checks. The result also includes a percentile-bootstrap confidence interval for the corresponding location contrast and an effect size appropriate to the selected design. Missing and non-finite observations are removed; in paired mode, pairs are removed together to preserve correspondence.

Parameters:

• left (Sequence[float])

• right (Sequence[float])

• paired (bool)

• alpha (float)

• estimand (str)

• confidence (float)

• bootstrap_replicates (int)

• random_seed (int)

Return type:

dict[str, Any]

static adjust_bh(p_values)

Apply Benjamini-Hochberg false-discovery-rate correction.

Parameters:

p_values (Sequence[float])

Return type:

list[float]

multivariate(matrix, *, components=2)

Return standardized PCA scores, loadings, variance, and distances.

Parameters:

• matrix (Sequence[Sequence[float]])

• components (int)

Return type:

dict[str, Any]

hierarchical_clustering(matrix, *, method='average', metric='euclidean')

Return SciPy linkage and leaf order for reproducible clustering.

Parameters:

• matrix (Sequence[Sequence[float]])

• method (str)

• metric (str)

Return type:

dict[str, Any]

linear_discriminant(matrix, labels, *, test_size=0.3, random_seed=1)

Train and evaluate stratified linear discriminant classification.

The returned projection contains every input observation, while the confusion matrix and classification report are calculated only from the held-out test subset. The split indices and random seed are retained to make reported accuracy exactly reproducible.

Parameters:

• matrix (Sequence[Sequence[float]])

• labels (Sequence[str])

• test_size (float)

• random_seed (int)

Return type:

dict[str, Any]

repeated_grouped_discriminant(matrix, labels, groups, *, folds=5, repeats=20, random_seed=1, shrinkage=True)

Evaluate LDA with repeated stratified, group-exclusive folds.

All observations sharing a group are kept in the same fold, preventing exact duplicates, isolates, or sequence clusters from appearing in both training and test data. Metrics are reported per fold and as mean, standard deviation, and percentile intervals across all held-out predictions. Shrinkage LDA is used by default for high-dimensional codon-feature matrices.

Parameters:

• matrix (Sequence[Sequence[float]])

• labels (Sequence[str])

• groups (Sequence[str | int])

• folds (int)

• repeats (int)

• random_seed (int)

• shrinkage (bool)

Return type:

dict[str, Any]

correspondence_analysis(matrix, *, components=2)

Perform correspondence analysis on a non-negative count/RSCU matrix.

Parameters:

• matrix (Sequence[Sequence[float]])

• components (int)

Return type:

dict[str, Any]

class codonadaptpy.visualization.PlotManager

Build optional interactive Plotly figures for self-contained HTML.

rscu_heatmap(results)

Create an interactive sequence-by-codon RSCU heatmap.

Parameters:

results (list[AnalysisResult])

Return type:

Any

enc_gc3(results)

Create interactive observed ENC versus GC3 and expectation traces.

Parameters:

results (list[AnalysisResult])

Return type:

Any

sliding_cai(result)

Create an interactive sliding-window CAI line profile.

Parameters:

result (AnalysisResult)

Return type:

Any

neutrality(results)

Create an interactive GC12-versus-GC3 neutrality scatter.

Parameters:

results (list[AnalysisResult])

Return type:

Any

parity_rule_2(results)

Create an interactive PR2 plot with equal-bias references.

Parameters:

results (list[AnalysisResult])

Return type:

Any

save(figure, path)

Write a self-contained HTML figure without Kaleido or Chrome.

Parameters:

• figure (Any)

• path (str | Path)

Return type:

Path

class codonadaptpy.visualization.PublicationPlotManager

Create journal-ready static figures from CodonAdaptPy outputs.

The manager uses the Okabe-Ito colorblind-safe palette, redundant marker shapes, outward-offset axes, visible individual observations, and vector- compatible Matplotlib artists. Matplotlib is imported lazily so sequence analysis remains dependency-free.

ordination(scores, labels, groups, *, x_label='Axis 1', y_label='Axis 2', title='Ordination')

Plot grouped two-dimensional scores with centroid standard errors.

Individual samples are shown with color and shape encoding. Larger black-edged points show group centroids, and error bars represent the standard error independently along both axes.

Parameters:

• scores (list[list[float]])

• labels (list[str])

• groups (list[str])

• x_label (str)

• y_label (str)

• title (str)

Return type:

Any

metric_panels(rows, *, metrics, group, title='Metric distributions', columns=2)

Create box-and-point panels for numeric metrics grouped by metadata.

Boxes show the median and interquartile range; whiskers follow the conventional 1.5-IQR rule. Every observation is overlaid using deterministic horizontal jitter, and each category label includes its sample size.

Parameters:

• rows (list[dict[str, Any]])

• metrics (list[str])

• group (str)

• title (str)

• columns (int)

Return type:

Any

codon_preference_intersections(results, *, group_key, threshold=1.6)

Return exact overlaps of preferred codons across metadata groups.

A codon belongs to a group’s preferred set when its group-mean RSCU is greater than or equal to threshold. Each intersection is exact: a codon assigned to groups A and B is absent from every other displayed group. The structured result supports auditable tables as well as the UpSet-style visualization.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• threshold (float)

Return type:

dict[str, Any]

codon_preference_upset(results, *, group_key, threshold=1.6, max_intersections=20, title='Shared preferred-codon signatures')

Plot exact preferred-codon intersections in an UpSet-style layout.

The upper bars report the number of codons in each exact intersection, the matrix identifies participating metadata groups, and the left bars report each group’s total preferred-codon set size. This avoids the area-comparison problems of multi-set Venn diagrams.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• threshold (float)

• max_intersections (int)

• title (str)

Return type:

Any

rscu_similarity_heatmap(results, *, group_key, title='RSCU signature similarity')

Plot cosine similarity among group-mean 59-codon RSCU profiles.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

rscu_pca_biplot(results, *, group_key, max_loadings=10, title='RSCU principal-component biplot')

Plot standardized 59-codon RSCU scores and influential codons.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• max_loadings (int)

• title (str)

Return type:

Any

sliding_cai(result, *, title=None)

Plot a reference-dependent sliding-window CAI profile.

Parameters:

• result (AnalysisResult)

• title (str | None)

Return type:

Any

metric_correlation_heatmap(results, *, metrics=None, title='Codon-analysis metric correlations')

Plot Pearson correlations among variable scalar analysis metrics.

Parameters:

• results (list[AnalysisResult])

• metrics (list[str] | None)

• title (str)

Return type:

Any

host_adaptation_landscape(results, *, group_key, title='Multi-host codon-adaptation landscape')

Plot CAI against RCDI for every host, with SiD encoded by area.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

dinucleotide_heatmap(results, *, group_key, title='Mean dinucleotide observed/expected ratios')

Plot mean O/E ratios for all 16 dinucleotides by metadata group.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

rscu_heatmap(results, *, group_key, title='Mean relative synonymous codon usage')

Plot group-mean RSCU values for all available sense codons.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

evolutionary_diagnostics(results, *, group_key, title='Evolutionary codon-usage diagnostics')

Create ENC-GC3, neutrality, and PR2 panels by metadata group.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

rscu_profiles(results, *, group_key, title='Relative synonymous codon usage profiles')

Plot group-mean 59-codon RSCU profiles with standard errors.

Codons are arranged by amino-acid family and colored by their third nucleotide. Horizontal reference lines identify the conventional underrepresentation (0.6) and preference (1.6) thresholds.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

dinucleotide_profiles(results, *, group_key, title='Dinucleotide observed/expected profiles')

Plot all 16 group-mean dinucleotide O/E ratios with SEM bars.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

composition_overview(results, *, group_key, title='Nucleotide composition and codon bias')

Create four panels summarizing composition, positional bias, and ENC.

Parameters:

• results (list[AnalysisResult])

• group_key (str)

• title (str)

Return type:

Any

lda_evaluation(analysis, groups, *, title='Linear discriminant analysis')

Plot an LDA projection beside its held-out confusion matrix.

Parameters:

• analysis (dict[str, Any])

• groups (list[str])

• title (str)

Return type:

Any

host_adaptation(rows, *, metrics, group_key, host_key, title='Host adaptation')

Plot host metrics by genotype with observations, means, and SEM.

Parameters:

• rows (list[dict[str, Any]])

• metrics (list[str])

• group_key (str)

• host_key (str)

• title (str)

Return type:

Any

bland_altman_validation(panels, *, title='Method Validation: Bland-Altman and Residual Agreement')

Create multi-panel Bland-Altman and residual agreement plots.

Each dictionary in panels must supply: - metric: str metric label (e.g. ‘CAI’, ‘ENC’, ‘RSCU’, ‘GC3s’) - reference: list[float] reference or benchmark values - tool: list[float] CodonAdaptPy calculated values

Parameters:

• panels (list[dict[str, Any]])

• title (str)

Return type:

Any

repeated_cv_distribution(lda_output, *, title='Repeated Grouped Cross-Validation Distributions')

Plot fold-level accuracy distributions across repeated CV iterations.

Parameters:

• lda_output (dict[str, Any])

• title (str)

Return type:

Any

save(figure, path, *, dpi=600)

Save a publication figure as PNG, TIFF, PDF, or SVG.

Parameters:

• figure (Any)

• path (str | Path)

• dpi (int)

Return type:

Path

Phylogenetics and temporal analysis

class codonadaptpy.phylogenetics.PhylogeneticAnalyzer(*, mafft='mafft', iqtree=None, fasttree=None, trimal='trimal')

Run alignment and maximum-likelihood phylogenetic inference.

Parameters:

• mafft (str) – MAFFT executable name or path.

• iqtree (str | None) – IQ-TREE 2 executable name or path. Both iqtree2 and the frequently packaged iqtree name are discovered automatically.

• fasttree (str | None) – FastTree executable name or path.

• trimal (str) – Optional trimAL executable name or path.

Notes

External tools remain optional package dependencies. Methods raise an informative RuntimeError when the selected executable is not available. IQ-TREE ultrafast bootstrap values should generally use at least 1,000 replicates for a publication analysis.

static write_fasta(records, destination)

Write unique, non-empty sequence records as wrapped FASTA.

Parameters:

• records (Iterable[SequenceRecord])

• destination (str | Path)

Return type:

Path

align(input_fasta, output_fasta, *, method='auto', threads=1)

Align sequences with MAFFT and return the output path and command.

Parameters:

• input_fasta (str | Path)

• output_fasta (str | Path)

• method (Literal['auto', 'linsi', 'einsi', 'fftnsi', 'fftns'])

• threads (int)

Return type:

tuple[Path, list[str]]

trim(alignment, destination, *, mode='automated1', required=False)

Trim an alignment with trimAL, or retain it when trimming is optional.

Parameters:

• alignment (str | Path)

• destination (str | Path)

• mode (Literal['automated1', 'gappyout', 'strict'])

• required (bool)

Return type:

tuple[Path, list[str] | None]

infer_tree(alignment, output_prefix, *, method='iqtree', sequence_type='nt', model='MFP', bootstrap=1000, threads=1)

Infer an ML tree with IQ-TREE ModelFinder or approximate FastTree.

Parameters:

• alignment (str | Path)

• output_prefix (str | Path)

• method (Literal['iqtree', 'fasttree'])

• sequence_type (Literal['nt', 'aa'])

• model (str)

• bootstrap (int)

• threads (int)

Return type:

tuple[Path, str | None, list[str]]

run(records, output_directory, *, name='phylogeny', align_method='auto', tree_method='iqtree', trim=True, trim_required=False, model='MFP', bootstrap=1000, threads=1)

Run FASTA export, alignment, optional trimming, and tree inference.

Parameters:

• records (Iterable[SequenceRecord])

• output_directory (str | Path)

• name (str)

• align_method (Literal['auto', 'linsi', 'einsi', 'fftnsi', 'fftns'])

• tree_method (Literal['iqtree', 'fasttree'])

• trim (bool)

• trim_required (bool)

• model (str)

• bootstrap (int)

• threads (int)

Return type:

PhylogenyResult

class codonadaptpy.phylogenetics.TemporalAnalyzer

Estimate temporal signal and deterministic dated-tree summaries.

ETE3 is imported lazily so codon-only workflows remain dependency free. The input tree should contain branch lengths in substitutions per site. Sampling dates are decimal calendar years keyed by exact leaf names.

classmethod load_tree(tree, *, midpoint_root=True)

Load or copy an ETE3 tree and optionally apply midpoint rooting.

Parameters:

• tree (str | Path | Any)

• midpoint_root (bool)

Return type:

Any

temporal_signal(tree, sample_dates, *, strata=None, midpoint_root=True, optimize_root=False, permutations=0, random_seed=1)

Regress root-to-tip divergence on sampling date.

A positive slope is interpreted as an exploratory strict-clock rate. When permutations is positive, sampling dates are randomized and the complete root-selection procedure is repeated for every replicate. When strata is provided, dates are permuted strictly within each stratum (e.g. genotype or lineage) to avoid confounding between group membership and sampling date. The resulting empirical p value therefore accounts for optimization over candidate roots. At least three dated tips and two distinct sampling years are required.

Parameters:

• tree (str | Path | Any)

• sample_dates (Mapping[str, float | int])

• strata (Mapping[str, Any] | None)

• midpoint_root (bool)

• optimize_root (bool)

• permutations (int)

• random_seed (int)

Return type:

TemporalSignalResult

date_tree(tree, signal, *, midpoint_root=True)

Attach deterministic calendar dates to every ETE3 node.

Internal dates follow the fitted strict-clock transform of root distance. Tips retain an additional observed_date feature when a sampling date is available. The returned topology is suitable for exploratory time-tree plotting and lineage-through-time summaries.

Parameters:

• tree (str | Path | Any)

• signal (TemporalSignalResult)

• midpoint_root (bool)

Return type:

Any

static lineage_through_time(tree, *, points=200)

Count branches crossing an evenly spaced calendar-time grid.

Parameters:

• tree (Any)

• points (int)

Return type:

dict[str, list[float]]

class codonadaptpy.phylogenetics.PhylogeneticComparator

Compare whole-genome and gene-tree topologies on their shared tips.

robinson_foulds(first, second)

Calculate unrooted Robinson-Foulds distance after shared-tip pruning.

The normalized distance is zero for identical shared-tip bipartitions and approaches one as topologies become maximally discordant. At least four shared tips are required for an informative unrooted comparison.

Parameters:

• first (str | Path | Any)

• second (str | Path | Any)

Return type:

dict[str, Any]

class codonadaptpy.phylo_visualization.ETE3TreePlotter

Render ETE3 phylogenies with consistent publication styling.

tree(tree, *, groups=None, title='Maximum-likelihood phylogeny', show_support=True, minimum_support=70.0, time_scaled=False, label_tips=True, align_tip_labels=True, tip_font_size=7.0, support_font_size=6.5)

Plot a branch-length or calendar-time rectangular phylogeny.

Parameters:

• tree (str | Path | Any) – Newick path/string or ETE3 tree.

• groups (Mapping[str, str] | None) – Optional mapping from leaf name to genotype/group.

• show_support (bool) – Label internal support at or above minimum_support.

• time_scaled (bool) – Use each node’s calendar_date feature for x.

• label_tips (bool) – Show leaf names; disable for dense overview trees.

• align_tip_labels (bool) – Place names in one right-hand column connected to their terminal nodes by dotted leader lines.

• tip_font_size (float) – Tip-label size in points. The default remains legible when a dense tree is reproduced at journal width.

• support_font_size (float) – Internal branch-support label size in points.

• title (str)

• minimum_support (float)

Return type:

Any

temporal_signal(analysis, *, groups=None, title='Root-to-tip temporal signal')

Plot root-to-tip regression with sample identities and group encoding.

Parameters:

• analysis (Any)

• groups (Mapping[str, str] | None)

• title (str)

Return type:

Any

lineage_through_time(trajectories, *, title='Lineage-through-time trajectories', normalize=True)

Plot deterministic dated-tree lineage trajectories.

This figure is an exploratory demographic proxy. It does not estimate effective population size and its lines are not Bayesian posterior medians or highest-posterior-density intervals.

Parameters:

• trajectories (Mapping[str, Mapping[str, Sequence[float]]])

• title (str)

• normalize (bool)

Return type:

Any

static save(figure, destination, *, dpi=600)

Save a figure with a transparent vector or high-resolution raster backend.

Parameters:

• figure (Any)

• destination (str | Path)

• dpi (int)

Return type:

Path

Sequence design and reporting

class codonadaptpy.optimizer.OptimizationConfig(direction='optimize', candidates=5, iterations=5000, seed=1, target_gc=None, gc_tolerance=0.05, avoid_motifs=(), preserve_motifs=(), remove_restriction_sites=(), add_restriction_sites=(), max_homopolymer=6, target_cpg=None, target_upa=None, cai_weight=1.0, gc_weight=1.0, motif_penalty=10.0, pair_weight=0.0)

Configure candidate search objectives and hard/soft constraints.

Parameters:

• direction (Literal['optimize', 'deoptimize', 'match'])

• candidates (int)

• iterations (int)

• seed (int)

• target_gc (float | None)

• gc_tolerance (float)

• avoid_motifs (tuple[str, ...])

• preserve_motifs (tuple[str, ...])

• remove_restriction_sites (tuple[str, ...])

• add_restriction_sites (tuple[str, ...])

• max_homopolymer (int)

• target_cpg (float | None)

• target_upa (float | None)

• cai_weight (float)

• gc_weight (float)

• motif_penalty (float)

• pair_weight (float)

class codonadaptpy.optimizer.CodonOptimizer(reference_counts, *, genetic_code=1, pair_scores=None)

Generate and rank synonymous sequences using seeded stochastic search.

Initialize optimizer with a target reference profile.

Parameters:

• reference_counts (dict[str, float])

• genetic_code (int)

• pair_scores (dict[str, float] | None)

optimize(sequence, config=None)

Generate several ranked synonymous candidate coding sequences.

Parameters:

• sequence (str)

• config (OptimizationConfig | None)

Return type:

OptimizationResult

class codonadaptpy.reporting.ReportGenerator

Export package results to machine-readable and publication-friendly files.

write_json(results, path)

Write nested analysis results as indented JSON.

Parameters:

• results (list[AnalysisResult])

• path (str | Path)

Return type:

Path

write_table(results, path, *, delimiter=None)

Write one flattened scalar-metric row per sequence as CSV or TSV.

Parameters:

• results (list[AnalysisResult])

• path (str | Path)

• delimiter (str | None)

Return type:

Path

write_html(results, path)

Write a self-contained HTML summary without a template dependency.

Parameters:

• results (list[AnalysisResult])

• path (str | Path)

Return type:

Path

write_excel(results, path)

Write summary, codon counts, RSCU, validation, and host sheets.

Parameters:

• results (list[AnalysisResult])

• path (str | Path)

Return type:

Path

write_pdf(results, path)

Render the HTML report to PDF using the optional report extra.

Parameters:

• results (list[AnalysisResult])

• path (str | Path)

Return type:

Path

write_optimized_fasta(result, path)

Write ranked optimization candidates in FASTA format.

Parameters:

• result (OptimizationResult)

• path (str | Path)

Return type:

Path