Skip to content

api.md

Latest commit

 

History

History
128 lines (89 loc) · 6.01 KB

api.md

File metadata and controls

128 lines (89 loc) · 6.01 KB
Raw

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

.. autoclass:: codonadaptpy.analyzer.AnalysisConfig
   :members:

.. autoclass:: codonadaptpy.analyzer.CodonAnalyzer
   :members:

.. autofunction:: codonadaptpy.analyzer.analyzer_from_reference_files

Sequence models and validation

.. autoclass:: codonadaptpy.models.SequenceRecord
   :members:

.. autoclass:: codonadaptpy.models.ValidationConfig
   :members:

.. autoclass:: codonadaptpy.models.ValidationReport
   :members:

.. autoclass:: codonadaptpy.validation.SequenceValidator
   :members:

.. autoclass:: codonadaptpy.parsers.SequenceParser
   :members:

References and aggregation

.. autoclass:: codonadaptpy.references.ReferenceProfile
   :members:

.. autoclass:: codonadaptpy.references.ReferenceManager
   :members:

.. autoclass:: codonadaptpy.aggregation.CDSAggregator
   :members:

.. autoclass:: codonadaptpy.aggregation.IsolateAnalysis
   :members:

Comparative analysis and visualization

.. autoclass:: codonadaptpy.comparative.ComparativeAnalyzer
   :members:

.. autoclass:: codonadaptpy.visualization.PlotManager
   :members:

.. autoclass:: codonadaptpy.visualization.PublicationPlotManager
   :members:

Phylogenetics and temporal analysis

.. autoclass:: codonadaptpy.phylogenetics.PhylogeneticAnalyzer
   :members:

.. autoclass:: codonadaptpy.phylogenetics.TemporalAnalyzer
   :members:

.. autoclass:: codonadaptpy.phylogenetics.PhylogeneticComparator
   :members:

.. autoclass:: codonadaptpy.phylo_visualization.ETE3TreePlotter
   :members:

Sequence design and reporting

.. autoclass:: codonadaptpy.optimizer.OptimizationConfig
   :members:

.. autoclass:: codonadaptpy.optimizer.CodonOptimizer
   :members:

.. autoclass:: codonadaptpy.reporting.ReportGenerator
   :members: