CodonAdaptPy 1.0.0__py3-none-any.whl

codonadaptpy/metrics/pairs.py

@@ -0,0 +1,107 @@
+"""
+CodonAdaptPy Codon-Pair Metrics
+
+This module calculates observed codon-pair frequencies, expected pair usage
+under independent codon sampling, log-odds codon-pair scores, and a sequence
+codon-pair bias summary. Ambiguous and stop-containing pairs are excluded.
+
+Classes:
+    - PairMetrics: Codon-pair counting and scoring utilities.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from collections.abc import Iterable, Mapping
+
+from ..genetic_code import GeneticCode
+
+
+class PairMetrics:
+    """Calculate codon-pair frequencies, scores, and compatibility."""
+
+    def __init__(self, genetic_code: GeneticCode | None = None) -> None:
+        """Initialize pair filtering for a selected genetic code."""
+
+        self.genetic_code = genetic_code or GeneticCode.from_ncbi(1)
+
+    def frequencies(self, codons: Iterable[str]) -> dict[str, float]:
+        """Return adjacent sense-codon pair frequencies keyed ``CODON-CODON``."""
+
+        return self.frequencies_many([codons])
+
+    def frequencies_many(self, codon_segments: Iterable[Iterable[str]]) -> dict[str, float]:
+        """Return pooled pair frequencies without creating cross-CDS pairs."""
+
+        counts: Counter[str] = Counter()
+        for codons in codon_segments:
+            values = [codon for codon in codons if self.genetic_code.translate(codon) not in {None, "*"}]
+            counts.update(f"{left}-{right}" for left, right in zip(values, values[1:], strict=False))
+        total = sum(counts.values())
+        return {pair: count / total for pair, count in sorted(counts.items())} if total else {}
+
+    def scores(self, codons: Iterable[str], *, pseudocount: float = 1e-9) -> dict[str, float]:
+        """Return log observed/expected scores for codon pairs in one sequence."""
+
+        return self.scores_many([codons], pseudocount=pseudocount)
+
+    def scores_many(
+        self,
+        codon_segments: Iterable[Iterable[str]],
+        *,
+        pseudocount: float = 1e-9,
+    ) -> dict[str, float]:
+        """Return pooled pair log-odds while respecting CDS boundaries."""
+
+        segments = [
+            [codon for codon in segment if self.genetic_code.translate(codon) not in {None, "*"}]
+            for segment in codon_segments
+        ]
+        values = [codon for segment in segments for codon in segment]
+        singles = Counter(values)
+        pairs = self.frequencies_many(segments)
+        total = len(values)
+        return (
+            {
+                pair: math.log(
+                    (observed + pseudocount) / ((singles[left] / total) * (singles[right] / total) + pseudocount)
+                )
+                for pair, observed in pairs.items()
+                for left, right in [pair.split("-")]
+            }
+            if total
+            else {}
+        )
+
+    def bias(self, codons: Iterable[str], reference_scores: Mapping[str, float] | None = None) -> float:
+        """Return mean codon-pair score using sequence or reference pair scores."""
+
+        values = list(codons)
+        scores = dict(reference_scores) if reference_scores is not None else self.scores(values)
+        pairs = [
+            f"{left}-{right}" for left, right in zip(values, values[1:], strict=False) if f"{left}-{right}" in scores
+        ]
+        return sum(scores[pair] for pair in pairs) / len(pairs) if pairs else 0.0
+
+    def bias_many(
+        self,
+        codon_segments: Iterable[Iterable[str]],
+        reference_scores: Mapping[str, float] | None = None,
+    ) -> float:
+        """Return mean pair score across CDSs without boundary artifacts."""
+
+        segments = [list(segment) for segment in codon_segments]
+        scores = dict(reference_scores) if reference_scores is not None else self.scores_many(segments)
+        pairs = [
+            f"{left}-{right}"
+            for segment in segments
+            for left, right in zip(segment, segment[1:], strict=False)
+            if f"{left}-{right}" in scores
+        ]
+        return sum(scores[pair] for pair in pairs) / len(pairs) if pairs else 0.0

codonadaptpy/metrics/usage.py

@@ -0,0 +1,155 @@
+"""
+CodonAdaptPy Codon-Usage Metrics
+
+This module calculates codon counts, RSCU, ENC, FOP, CBI, intrinsic codon
+deviation, amino-acid composition, and reference frequencies. Implementations
+operate on codon iterables and explicitly exclude termination and ambiguous
+codons unless a metric documents otherwise.
+
+Classes:
+    - CodonUsageMetrics: Genetic-code-aware codon-bias statistics.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Iterable, Mapping
+
+from ..genetic_code import GeneticCode
+
+
+class CodonUsageMetrics:
+    """Calculate intrinsic and reference-aware codon-usage statistics."""
+
+    def __init__(self, genetic_code: GeneticCode | None = None) -> None:
+        """Initialize calculations for a selected genetic code."""
+
+        self.genetic_code = genetic_code or GeneticCode.from_ncbi(1)
+
+    def counts(self, codons: Iterable[str], *, include_stops: bool = False) -> dict[str, int]:
+        """Count unambiguous recognized codons and return a complete 64-codon map."""
+
+        observed = Counter(codon.upper().replace("U", "T") for codon in codons)
+        return {
+            codon: observed.get(codon, 0)
+            for codon, amino_acid in sorted(self.genetic_code.forward_table.items())
+            if include_stops or amino_acid != "*"
+        }
+
+    def frequencies(self, codons: Iterable[str]) -> dict[str, float]:
+        """Return global sense-codon relative frequencies summing to one."""
+
+        counts = self.counts(codons)
+        total = sum(counts.values())
+        return {codon: count / total if total else 0.0 for codon, count in counts.items()}
+
+    def rscu(self, codons: Iterable[str]) -> dict[str, float]:
+        """Calculate Relative Synonymous Codon Usage for every sense codon."""
+
+        return self.rscu_from_counts(self.counts(codons))
+
+    def rscu_from_counts(self, counts: Mapping[str, int | float]) -> dict[str, float]:
+        """Calculate RSCU directly from an existing codon-count mapping."""
+
+        result: dict[str, float] = {}
+        for amino_acid, family in self.genetic_code.synonymous_codons.items():
+            if amino_acid == "*":
+                continue
+            total = sum(float(counts.get(codon, 0.0)) for codon in family)
+            result.update(
+                {codon: (float(counts.get(codon, 0.0)) * len(family) / total if total else 0.0) for codon in family}
+            )
+        return dict(sorted(result.items()))
+
+    def amino_acid_composition(self, codons: Iterable[str]) -> dict[str, float]:
+        """Return fractional one-letter amino-acid composition."""
+
+        amino_acids = [self.genetic_code.translate(codon) for codon in codons]
+        counts = Counter(aa for aa in amino_acids if aa and aa != "*")
+        total = sum(counts.values())
+        return {
+            aa: counts.get(aa, 0) / total if total else 0.0
+            for aa in sorted(self.genetic_code.synonymous_codons)
+            if aa != "*"
+        }
+
+    def enc(self, codons: Iterable[str]) -> float:
+        """Estimate effective number of codons using homozygosity by family.
+
+        The estimator follows Wright's family-degeneracy formulation with an
+        unbiased within-family homozygosity correction. Missing degeneracy
+        classes contribute their neutral expectation, keeping ENC within the
+        conventional 20 (maximal bias) to 61 (minimal bias) range.
+        """
+
+        counts = self.counts(codons)
+        family_f: dict[int, list[float]] = {2: [], 3: [], 4: [], 6: []}
+        for amino_acid, family in self.genetic_code.synonymous_codons.items():
+            if amino_acid == "*" or len(family) == 1:
+                continue
+            values = [counts[codon] for codon in family]
+            n = sum(values)
+            if n > 1:
+                f_value = (sum(value * value for value in values) - n) / (n * (n - 1))
+                family_f.setdefault(len(family), []).append(max(f_value, 1 / len(family)))
+        means = {size: (sum(values) / len(values) if values else 1 / size) for size, values in family_f.items()}
+        value = 2 + 9 / means[2] + 1 / means[3] + 5 / means[4] + 3 / means[6]
+        return min(61.0, max(20.0, value))
+
+    def optimal_codons(self, reference_counts: Mapping[str, int | float]) -> set[str]:
+        """Select the most frequent codon(s) in each synonymous family."""
+
+        optimal: set[str] = set()
+        for amino_acid, family in self.genetic_code.synonymous_codons.items():
+            if amino_acid == "*" or len(family) == 1:
+                continue
+            maximum = max(float(reference_counts.get(codon, 0.0)) for codon in family)
+            optimal.update(codon for codon in family if float(reference_counts.get(codon, 0.0)) == maximum)
+        return optimal
+
+    def fop(self, codons: Iterable[str], optimal_codons: set[str]) -> float:
+        """Calculate frequency of optimal codons among synonymous sense codons."""
+
+        eligible = [
+            codon
+            for codon in codons
+            if len(self.genetic_code.synonymous_codons.get(self.genetic_code.translate(codon) or "", ())) > 1
+        ]
+        return sum(codon in optimal_codons for codon in eligible) / len(eligible) if eligible else 0.0
+
+    def cbi(self, codons: Iterable[str], optimal_codons: set[str]) -> float:
+        """Calculate Codon Bias Index relative to a selected optimal-codon set."""
+
+        codon_list = list(codons)
+        counts = self.counts(codon_list)
+        observed = sum(counts.get(codon, 0) for codon in optimal_codons)
+        expected = 0.0
+        maximum = 0
+        for amino_acid, family in self.genetic_code.synonymous_codons.items():
+            if amino_acid == "*" or len(family) == 1:
+                continue
+            family_total = sum(counts[codon] for codon in family)
+            family_optimal = len(set(family) & optimal_codons)
+            expected += family_total * family_optimal / len(family)
+            maximum += family_total
+        denominator = maximum - expected
+        return (observed - expected) / denominator if denominator else 0.0
+
+    def icdi(self, codons: Iterable[str]) -> float:
+        """Calculate intrinsic codon deviation from equal synonymous usage."""
+
+        counts = self.counts(codons)
+        deviations: list[float] = []
+        for amino_acid, family in self.genetic_code.synonymous_codons.items():
+            if amino_acid == "*" or len(family) == 1:
+                continue
+            total = sum(counts[codon] for codon in family)
+            if total:
+                equal = 1 / len(family)
+                deviations.append(sum(abs(counts[codon] / total - equal) for codon in family) / (2 * (1 - equal)))
+        return sum(deviations) / len(deviations) if deviations else 0.0

codonadaptpy/models.py

@@ -0,0 +1,128 @@
+"""
+CodonAdaptPy Data Models
+
+This module contains dependency-free dataclasses shared by parsing,
+validation, analysis, optimization, reporting, and command-line workflows.
+Models expose ``to_dict`` methods so results can be serialized without a
+framework-specific schema library.
+
+Classes:
+    - SequenceRecord: One coding sequence and its metadata.
+    - ValidationConfig: User-selected validation policy.
+    - ValidationIssue: One structured validation observation.
+    - ValidationReport: Validation outcome and normalized sequence.
+    - AnalysisResult: Complete metrics for a single sequence.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+
+@dataclass(slots=True)
+class SequenceRecord:
+    """Store a named nucleotide sequence and arbitrary sample metadata."""
+
+    identifier: str
+    sequence: str
+    description: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-compatible representation of the record."""
+
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class ValidationConfig:
+    """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.
+    """
+
+    reading_frame: Literal[0, 1, 2] = 0
+    genetic_code: int = 1
+    require_start: bool = True
+    require_stop: bool = True
+    ambiguous_policy: Literal["reject", "skip", "allow"] = "reject"
+    allow_partial: bool = False
+    convert_rna: bool = True
+
+
+@dataclass(slots=True)
+class ValidationIssue:
+    """Describe one validation warning or error with optional sequence locus."""
+
+    code: str
+    message: str
+    severity: Literal["warning", "error"]
+    position: int | None = None
+
+
+@dataclass(slots=True)
+class ValidationReport:
+    """Collect normalized sequence data and structured validation findings."""
+
+    identifier: str
+    normalized_sequence: str
+    issues: list[ValidationIssue] = field(default_factory=list)
+    genetic_code: int = 1
+    reading_frame: int = 0
+
+    @property
+    def is_valid(self) -> bool:
+        """Return ``True`` when the report contains no error-level issues."""
+
+        return not any(issue.severity == "error" for issue in self.issues)
+
+    @property
+    def errors(self) -> list[ValidationIssue]:
+        """Return only error-level findings."""
+
+        return [issue for issue in self.issues if issue.severity == "error"]
+
+    @property
+    def warnings(self) -> list[ValidationIssue]:
+        """Return only warning-level findings."""
+
+        return [issue for issue in self.issues if issue.severity == "warning"]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-compatible representation of the report."""
+
+        return asdict(self) | {"is_valid": self.is_valid}
+
+
+@dataclass(slots=True)
+class AnalysisResult:
+    """Store validation, scalar metrics, profiles, and count tables."""
+
+    identifier: str
+    validation: ValidationReport
+    metrics: dict[str, Any]
+    codon_counts: dict[str, int]
+    rscu: dict[str, float]
+    amino_acid_composition: dict[str, float]
+    dinucleotide_frequencies: dict[str, float]
+    dinucleotide_odds: dict[str, float | None]
+    dinucleotide_bias: dict[str, str]
+    trinucleotide_frequencies: dict[str, float]
+    codon_pair_scores: dict[str, float] = field(default_factory=dict)
+    sliding_windows: dict[str, list[dict[str, float]]] = field(default_factory=dict)
+    host_comparisons: dict[str, dict[str, float]] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return all nested result fields in JSON-compatible form."""
+
+        return asdict(self)

codonadaptpy/optimizer.py

@@ -0,0 +1,194 @@
+"""
+CodonAdaptPy Constrained Sequence Optimization
+
+This module designs multiple synonymous coding sequences while preserving the
+translated amino-acid sequence. Candidate ranking can increase or decrease
+reference CAI, approach a target GC fraction, control CpG/UpA, avoid or require
+motifs and restriction sites, limit homopolymers, and account for codon-pair
+scores. Results expose each trade-off rather than hiding it in one sequence.
+
+Classes:
+    - OptimizationConfig: Objectives, constraints, and reproducibility options.
+    - OptimizationCandidate: One designed sequence and its diagnostics.
+    - OptimizationResult: Ranked candidates and source metadata.
+    - CodonOptimizer: Reproducible stochastic constrained optimizer.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import random
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+from .exceptions import AnalysisError
+from .genetic_code import GeneticCode
+from .metrics.adaptation import AdaptationMetrics
+from .metrics.composition import CompositionMetrics
+from .metrics.pairs import PairMetrics
+
+
+@dataclass(slots=True)
+class OptimizationConfig:
+    """Configure candidate search objectives and hard/soft constraints."""
+
+    direction: Literal["optimize", "deoptimize", "match"] = "optimize"
+    candidates: int = 5
+    iterations: int = 5000
+    seed: int = 1
+    target_gc: float | None = None
+    gc_tolerance: float = 0.05
+    avoid_motifs: tuple[str, ...] = ()
+    preserve_motifs: tuple[str, ...] = ()
+    remove_restriction_sites: tuple[str, ...] = ()
+    add_restriction_sites: tuple[str, ...] = ()
+    max_homopolymer: int = 6
+    target_cpg: float | None = None
+    target_upa: float | None = None
+    cai_weight: float = 1.0
+    gc_weight: float = 1.0
+    motif_penalty: float = 10.0
+    pair_weight: float = 0.0
+
+
+@dataclass(slots=True)
+class OptimizationCandidate:
+    """Store one synonymous candidate and transparent objective diagnostics."""
+
+    rank: int
+    sequence: str
+    score: float
+    cai: float
+    gc: float
+    cpg_representation: float
+    upa_representation: float
+    constraint_violations: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class OptimizationResult:
+    """Collect source sequence, configuration, and ranked candidate designs."""
+
+    source_sequence: str
+    amino_acid_sequence: str
+    candidates: list[OptimizationCandidate]
+    config: OptimizationConfig
+    genetic_code: int
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return nested optimization output in JSON-compatible form."""
+
+        return asdict(self)
+
+
+class CodonOptimizer:
+    """Generate and rank synonymous sequences using seeded stochastic search."""
+
+    def __init__(
+        self, reference_counts: dict[str, float], *, genetic_code: int = 1, pair_scores: dict[str, float] | None = None
+    ) -> None:
+        """Initialize optimizer with a target reference profile."""
+
+        self.code = GeneticCode.from_ncbi(genetic_code)
+        self.adaptation = AdaptationMetrics(self.code)
+        self.composition = CompositionMetrics()
+        self.pairs = PairMetrics(self.code)
+        self.weights = self.adaptation.weights_from_counts(reference_counts)
+        self.reference_counts = reference_counts
+        self.pair_scores = pair_scores or {}
+
+    def optimize(self, sequence: str, config: OptimizationConfig | None = None) -> OptimizationResult:
+        """Generate several ranked synonymous candidate coding sequences."""
+
+        config = config or OptimizationConfig()
+        normalized = "".join(sequence.upper().replace("U", "T").split())
+        if len(normalized) % 3:
+            raise AnalysisError("Optimization requires a sequence divisible by three.")
+        codons = [normalized[index : index + 3] for index in range(0, len(normalized), 3)]
+        amino_acids = [self.code.translate(codon) for codon in codons]
+        if any(amino_acid is None for amino_acid in amino_acids):
+            raise AnalysisError("Optimization does not accept ambiguous or invalid codons.")
+        terminal_stop = bool(amino_acids and amino_acids[-1] == "*")
+        if "*" in amino_acids[:-1]:
+            raise AnalysisError("Optimization does not accept internal stop codons.")
+        design_amino_acids = [aa for aa in amino_acids if aa is not None and aa != "*"]
+        stop = codons[-1] if terminal_stop else ""
+        rng = random.Random(config.seed)
+        designs: dict[str, tuple[float, dict[str, float], list[str]]] = {}
+        initial = "".join(codons[:-1] if terminal_stop else codons) + stop
+        for _ in range(max(config.iterations, config.candidates)):
+            candidate_codons = [self._choose_codon(aa, config.direction, rng) for aa in design_amino_acids]
+            candidate = "".join(candidate_codons) + stop
+            score, diagnostics, violations = self._score(candidate, candidate_codons, config)
+            previous = designs.get(candidate)
+            if previous is None or score > previous[0]:
+                designs[candidate] = (score, diagnostics, violations)
+        if initial not in designs:
+            initial_codons = codons[:-1] if terminal_stop else codons
+            designs[initial] = self._score(initial, initial_codons, config)
+        ordered = sorted(designs.items(), key=lambda item: item[1][0], reverse=True)[: config.candidates]
+        candidates = [
+            OptimizationCandidate(
+                rank,
+                candidate,
+                score,
+                diagnostics["cai"],
+                diagnostics["gc"],
+                diagnostics["cpg"],
+                diagnostics["upa"],
+                violations,
+            )
+            for rank, (candidate, (score, diagnostics, violations)) in enumerate(ordered, start=1)
+        ]
+        return OptimizationResult(normalized, "".join(design_amino_acids), candidates, config, self.code.table_id)
+
+    def _choose_codon(self, amino_acid: str, direction: str, rng: random.Random) -> str:
+        """Sample a synonymous codon according to the requested direction."""
+
+        family = self.code.synonymous_codons[amino_acid]
+        weights = [self.weights[codon] for codon in family]
+        if direction == "deoptimize":
+            weights = [1 / max(weight, 1e-9) for weight in weights]
+        elif direction == "match":
+            weights = [max(float(self.reference_counts.get(codon, 0.0)), 1e-9) for codon in family]
+        return rng.choices(family, weights=weights, k=1)[0]
+
+    def _score(
+        self, sequence: str, codons: list[str], config: OptimizationConfig
+    ) -> tuple[float, dict[str, float], list[str]]:
+        """Evaluate objectives and report every constraint violation."""
+
+        cai = self.adaptation.cai(codons, self.weights)
+        composition = self.composition.gc_metrics(sequence)
+        cpg = self.composition.representation(sequence, "CG")
+        upa = self.composition.representation(sequence, "TA")
+        cai_term = -cai if config.direction == "deoptimize" else cai
+        score = config.cai_weight * cai_term
+        if config.target_gc is not None:
+            score -= config.gc_weight * abs(composition["gc"] - config.target_gc)
+        if config.target_cpg is not None:
+            score -= abs(cpg - config.target_cpg)
+        if config.target_upa is not None:
+            score -= abs(upa - config.target_upa)
+        if self.pair_scores and config.pair_weight:
+            score += config.pair_weight * self.pairs.bias(codons, self.pair_scores)
+        violations: list[str] = []
+        forbidden = tuple(
+            item.upper().replace("U", "T") for item in config.avoid_motifs + config.remove_restriction_sites
+        )
+        required = tuple(
+            item.upper().replace("U", "T") for item in config.preserve_motifs + config.add_restriction_sites
+        )
+        violations.extend(f"forbidden motif present: {motif}" for motif in forbidden if motif and motif in sequence)
+        violations.extend(f"required motif absent: {motif}" for motif in required if motif and motif not in sequence)
+        if config.target_gc is not None and abs(composition["gc"] - config.target_gc) > config.gc_tolerance:
+            violations.append("GC content outside tolerance")
+        if config.max_homopolymer > 0 and re.search(rf"([ACGT])\1{{{config.max_homopolymer},}}", sequence):
+            violations.append(f"homopolymer longer than {config.max_homopolymer}")
+        score -= config.motif_penalty * len(violations)
+        return score, {"cai": cai, "gc": composition["gc"], "cpg": cpg, "upa": upa}, violations