CodonAdaptPy 1.0.0__py3-none-any.whl

codonadaptpy/genetic_code.py

@@ -0,0 +1,115 @@
+"""
+CodonAdaptPy Genetic-Code Models
+
+This module provides immutable genetic-code objects and codon-family lookup
+tables. NCBI genetic code 1 is bundled so the core package has no mandatory
+dependencies; other NCBI tables are loaded through Biopython when installed.
+
+Features:
+    - DNA-normalized codon translation
+    - Synonymous-codon family construction
+    - Start- and stop-codon classification
+    - Optional access to all NCBI genetic codes through Biopython
+
+Classes:
+    - GeneticCode: Immutable translation table used throughout the package.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+
+from .exceptions import ReferenceDataError
+
+_BASES = "TCAG"
+_AMINO_ACIDS = "FFLLSSSSYY**CC*WLLLLPPPPHHQQRRRRIIIMTTTTNNKKSSRRVVVVAAAADDEEGGGG"
+STANDARD_FORWARD_TABLE = {
+    a + b + c: amino_acid
+    for (a, b, c), amino_acid in zip(
+        ((a, b, c) for a in _BASES for b in _BASES for c in _BASES),
+        _AMINO_ACIDS,
+        strict=True,
+    )
+}
+
+
+@dataclass(frozen=True)
+class GeneticCode:
+    """Represent a DNA codon translation table.
+
+    Parameters
+    ----------
+    table_id:
+        NCBI genetic-code identifier.
+    name:
+        Human-readable genetic-code name.
+    forward_table:
+        Mapping from each unambiguous DNA codon to a one-letter amino acid or
+        ``"*"`` for termination.
+    start_codons:
+        Codons accepted as translation starts by this genetic code.
+    stop_codons:
+        Codons interpreted as termination signals.
+    """
+
+    table_id: int
+    name: str
+    forward_table: dict[str, str]
+    start_codons: frozenset[str]
+    stop_codons: frozenset[str]
+
+    @classmethod
+    def from_ncbi(cls, table_id: int = 1) -> GeneticCode:
+        """Create a genetic code from a numeric NCBI table identifier.
+
+        Standard code 1 is always available. Other tables require the
+        ``CodonAdaptPy[io]`` extra because their definitions are obtained from
+        Biopython's maintained NCBI codon-table registry.
+        """
+
+        if table_id == 1:
+            stops = frozenset(codon for codon, aa in STANDARD_FORWARD_TABLE.items() if aa == "*")
+            return cls(
+                table_id=1,
+                name="Standard",
+                forward_table=dict(STANDARD_FORWARD_TABLE),
+                start_codons=frozenset({"ATG", "TTG", "CTG"}),
+                stop_codons=stops,
+            )
+        try:
+            from Bio.Data import CodonTable
+        except ImportError as exc:
+            raise ReferenceDataError(f"Genetic code {table_id} requires Biopython; install CodonAdaptPy[io].") from exc
+        try:
+            source = CodonTable.unambiguous_dna_by_id[table_id]
+        except KeyError as exc:
+            raise ReferenceDataError(f"Unsupported NCBI genetic code: {table_id}") from exc
+        table = dict(source.forward_table)
+        table.update({codon: "*" for codon in source.stop_codons})
+        return cls(
+            table_id=table_id,
+            name=source.names[0],
+            forward_table=table,
+            start_codons=frozenset(source.start_codons),
+            stop_codons=frozenset(source.stop_codons),
+        )
+
+    @cached_property
+    def synonymous_codons(self) -> dict[str, tuple[str, ...]]:
+        """Return sorted synonymous codon families keyed by amino acid."""
+
+        families: dict[str, list[str]] = {}
+        for codon, amino_acid in self.forward_table.items():
+            families.setdefault(amino_acid, []).append(codon)
+        return {amino_acid: tuple(sorted(codons)) for amino_acid, codons in families.items()}
+
+    def translate(self, codon: str) -> str | None:
+        """Translate one DNA or RNA codon, returning ``None`` if ambiguous."""
+
+        return self.forward_table.get(codon.upper().replace("U", "T"))

codonadaptpy/metrics/__init__.py

@@ -0,0 +1,28 @@
+"""
+CodonAdaptPy Metric Implementations
+
+This package groups independent, testable calculation classes for adaptation,
+codon usage, nucleotide composition, oligonucleotide representation, codon
+pairs, host comparison, and evolutionary diagnostics.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from .adaptation import AdaptationMetrics
+from .composition import CompositionMetrics
+from .evolutionary import EvolutionaryMetrics
+from .host import HostComparator
+from .pairs import PairMetrics
+from .usage import CodonUsageMetrics
+
+__all__ = [
+    "AdaptationMetrics",
+    "CodonUsageMetrics",
+    "CompositionMetrics",
+    "EvolutionaryMetrics",
+    "HostComparator",
+    "PairMetrics",
+]

codonadaptpy/metrics/adaptation.py

@@ -0,0 +1,133 @@
+"""
+CodonAdaptPy Adaptation Metrics
+
+This module calculates CAI, expected/simulated CAI, confidence intervals,
+sliding-window profiles, RCDI, and tRNA adaptation index in logarithmic space.
+Zero-frequency reference codons receive an explicit configurable floor rather
+than triggering numerical underflow or silently disappearing.
+
+Classes:
+    - AdaptationMetrics: Reference-aware adaptation calculations.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections import Counter
+from collections.abc import Iterable, Mapping
+
+from ..exceptions import AnalysisError, ReferenceDataError
+from ..genetic_code import GeneticCode
+
+
+class AdaptationMetrics:
+    """Calculate reference-dependent codon adaptation statistics."""
+
+    def __init__(self, genetic_code: GeneticCode | None = None, *, zero_floor: float = 0.01) -> None:
+        """Initialize metrics for a genetic code and positive zero-count floor."""
+
+        if not 0 < zero_floor <= 1:
+            raise ValueError("zero_floor must be in (0, 1].")
+        self.genetic_code = genetic_code or GeneticCode.from_ncbi(1)
+        self.zero_floor = zero_floor
+
+    def weights_from_counts(self, counts: Mapping[str, int | float]) -> dict[str, float]:
+        """Derive relative adaptiveness weights within synonymous families."""
+
+        weights: dict[str, float] = {}
+        for amino_acid, family in self.genetic_code.synonymous_codons.items():
+            if amino_acid == "*":
+                continue
+            maximum = max(float(counts.get(codon, 0.0)) for codon in family)
+            if maximum <= 0:
+                weights.update({codon: self.zero_floor for codon in family})
+            else:
+                weights.update(
+                    {codon: max(float(counts.get(codon, 0.0)) / maximum, self.zero_floor) for codon in family}
+                )
+        return weights
+
+    def cai(self, codons: Iterable[str], weights: Mapping[str, float]) -> float:
+        """Calculate classical CAI as a geometric mean in logarithmic space.
+
+        Methionine and tryptophan are included with weight 1 when present in a
+        complete table. Stop and ambiguous codons are excluded. Missing sense
+        codons are excluded, while explicitly non-positive weights are errors.
+        """
+
+        values: list[float] = []
+        for raw_codon in codons:
+            codon = raw_codon.upper().replace("U", "T")
+            if codon in self.genetic_code.stop_codons or set(codon) - set("ACGT"):
+                continue
+            if codon not in weights:
+                continue
+            weight = float(weights[codon])
+            if weight <= 0:
+                raise ReferenceDataError(f"Codon {codon} has a non-positive reference weight.")
+            values.append(math.log(weight))
+        if not values:
+            raise AnalysisError("No eligible sense codons were available for CAI calculation.")
+        return math.exp(sum(values) / len(values))
+
+    def sliding_cai(
+        self, codons: list[str], weights: Mapping[str, float], *, window: int = 30, step: int = 1
+    ) -> list[dict[str, float]]:
+        """Return CAI values for overlapping codon windows."""
+
+        if window < 1 or step < 1:
+            raise ValueError("window and step must be positive integers.")
+        if len(codons) < window:
+            return [{"start_codon": 1.0, "end_codon": float(len(codons)), "cai": self.cai(codons, weights)}]
+        return [
+            {
+                "start_codon": float(start + 1),
+                "end_codon": float(start + window),
+                "cai": self.cai(codons[start : start + window], weights),
+            }
+            for start in range(0, len(codons) - window + 1, step)
+        ]
+
+    def simulated_cai(
+        self, codons: list[str], weights: Mapping[str, float], *, simulations: int = 1000, seed: int = 1
+    ) -> dict[str, float | list[float]]:
+        """Simulate synonymous sequences preserving amino-acid composition."""
+
+        if simulations < 1:
+            raise ValueError("simulations must be positive.")
+        rng = random.Random(seed)
+        translated = [self.genetic_code.translate(codon) for codon in codons]
+        amino_acids = [aa for aa in translated if aa is not None and aa != "*"]
+        values = [
+            self.cai([rng.choice(self.genetic_code.synonymous_codons[aa]) for aa in amino_acids], weights)
+            for _ in range(simulations)
+        ]
+        ordered = sorted(values)
+        low = ordered[max(0, int(0.025 * simulations) - 1)]
+        high = ordered[min(simulations - 1, int(0.975 * simulations))]
+        return {"mean": sum(values) / len(values), "ci_low": low, "ci_high": high, "values": values}
+
+    def rcdi(self, codons: Iterable[str], reference_frequencies: Mapping[str, float]) -> float:
+        """Calculate Relative Codon Deoptimization Index; 1 indicates a close match."""
+
+        counts = Counter(codon for codon in codons if self.genetic_code.translate(codon) not in {None, "*"})
+        total = sum(counts.values())
+        if not total:
+            raise AnalysisError("RCDI requires at least one unambiguous sense codon.")
+        score = 0.0
+        for codon, count in counts.items():
+            observed = count / total
+            expected = float(reference_frequencies.get(codon, 0.0))
+            score += observed / max(expected, self.zero_floor / 64.0)
+        return score / len(counts)
+
+    def tai(self, codons: Iterable[str], trna_weights: Mapping[str, float]) -> float:
+        """Calculate tRNA Adaptation Index from user-supplied codon weights."""
+
+        return self.cai(codons, trna_weights)

codonadaptpy/metrics/composition.py

@@ -0,0 +1,173 @@
+"""
+CodonAdaptPy Composition and Oligonucleotide Metrics
+
+This module calculates whole-sequence and codon-position nucleotide metrics,
+GC content at synonymous third positions (GC3s), overlapping di-/trinucleotide
+frequencies, and observed/expected representation ratios for all 16
+dinucleotides. Pooled calculations preserve CDS boundaries.
+
+Classes:
+    - CompositionMetrics: Dependency-free nucleotide composition calculations.
+
+: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
+
+from ..genetic_code import GeneticCode
+
+DINUCLEOTIDES = tuple(left + right for left in "ACGT" for right in "ACGT")
+
+
+class CompositionMetrics:
+    """Calculate sequence composition and short-word statistics."""
+
+    @staticmethod
+    def _clean(sequence: str) -> str:
+        """Normalize RNA to DNA and retain unambiguous nucleotides only."""
+
+        return "".join(base for base in sequence.upper().replace("U", "T") if base in "ACGT")
+
+    def gc_metrics(
+        self,
+        sequence: str,
+        *,
+        frame: int = 0,
+        genetic_code: GeneticCode | None = None,
+    ) -> dict[str, float]:
+        """Return whole, positional, and synonymous-third composition.
+
+        ``GC3s`` uses third positions of unambiguous sense codons belonging to
+        amino acids with more than one synonymous codon. Methionine,
+        tryptophan, stops, and ambiguous codons are therefore excluded.
+        """
+
+        clean = self._clean(sequence)
+        framed = clean[frame:]
+        positions = [framed[index::3] for index in range(3)]
+        code = genetic_code or GeneticCode.from_ncbi(1)
+        codons = [framed[index : index + 3] for index in range(0, len(framed) - 2, 3)]
+        synonymous_thirds = "".join(
+            codon[2]
+            for codon in codons
+            if (amino_acid := code.translate(codon)) not in {None, "*"} and len(code.synonymous_codons[amino_acid]) > 1
+        )
+
+        def fraction(text: str, accepted: set[str]) -> float:
+            return sum(base in accepted for base in text) / len(text) if text else 0.0
+
+        third = positions[2]
+        return {
+            "a": fraction(clean, {"A"}),
+            "t": fraction(clean, {"T"}),
+            "g": fraction(clean, {"G"}),
+            "c": fraction(clean, {"C"}),
+            "at": fraction(clean, {"A", "T"}),
+            "gc": fraction(clean, {"G", "C"}),
+            "at1": fraction(positions[0], {"A", "T"}),
+            "at2": fraction(positions[1], {"A", "T"}),
+            "at3": fraction(third, {"A", "T"}),
+            "gc1": fraction(positions[0], {"G", "C"}),
+            "gc2": fraction(positions[1], {"G", "C"}),
+            "gc3": fraction(third, {"G", "C"}),
+            "gc3s": fraction(synonymous_thirds, {"G", "C"}),
+            "a3": fraction(third, {"A"}),
+            "t3": fraction(third, {"T"}),
+            "g3": fraction(third, {"G"}),
+            "c3": fraction(third, {"C"}),
+        }
+
+    def oligonucleotide_frequencies(self, sequence: str, size: int) -> dict[str, float]:
+        """Return overlapping frequencies for observed words of requested size."""
+
+        return self.oligonucleotide_frequencies_many([sequence], size)
+
+    def oligonucleotide_frequencies_many(self, sequences: Iterable[str], size: int) -> dict[str, float]:
+        """Return pooled word frequencies without crossing sequence boundaries."""
+
+        if size < 1:
+            raise ValueError("Oligonucleotide size must be positive.")
+        counts: Counter[str] = Counter()
+        for sequence in sequences:
+            clean = self._clean(sequence)
+            counts.update(clean[index : index + size] for index in range(max(0, len(clean) - size + 1)))
+        total = sum(counts.values())
+        return {word: count / total for word, count in sorted(counts.items())} if total else {}
+
+    def representation(self, sequence: str, dinucleotide: str) -> float:
+        """Calculate a dinucleotide observed/expected representation ratio."""
+
+        clean = self._clean(sequence)
+        pair = dinucleotide.upper().replace("U", "T")
+        if len(pair) != 2 or set(pair) - set("ACGT"):
+            raise ValueError("dinucleotide must contain exactly two A/C/G/T bases.")
+        if len(clean) < 2:
+            return 0.0
+        observed = sum(clean[index : index + 2] == pair for index in range(len(clean) - 1)) / (len(clean) - 1)
+        first = clean.count(pair[0]) / len(clean)
+        second = clean.count(pair[1]) / len(clean)
+        return observed / (first * second) if first and second else 0.0
+
+    def dinucleotide_odds(self, sequence: str) -> dict[str, float | None]:
+        """Return observed/expected ratios for all 16 DNA dinucleotides."""
+
+        clean = self._clean(sequence)
+        return self.dinucleotide_odds_many([clean])
+
+    def dinucleotide_odds_many(self, sequences: Iterable[str]) -> dict[str, float | None]:
+        """Return boundary-safe pooled O/E ratios across multiple CDSs.
+
+        Adjacent bases from different CDSs are never counted as a biological
+        dinucleotide. Mononucleotide and within-CDS pair counts are pooled
+        before observed and expected frequencies are calculated.
+        """
+
+        mono_counts: Counter[str] = Counter()
+        pair_counts: Counter[str] = Counter()
+        nucleotide_total = 0
+        pair_total = 0
+        for sequence in sequences:
+            clean = self._clean(sequence)
+            mono_counts.update(clean)
+            pairs = [clean[index : index + 2] for index in range(max(0, len(clean) - 1))]
+            pair_counts.update(pairs)
+            nucleotide_total += len(clean)
+            pair_total += len(pairs)
+        if nucleotide_total == 0 or pair_total == 0:
+            return {pair: None for pair in DINUCLEOTIDES}
+        result: dict[str, float | None] = {}
+        for pair in DINUCLEOTIDES:
+            observed = pair_counts[pair] / pair_total
+            expected = (mono_counts[pair[0]] / nucleotide_total) * (mono_counts[pair[1]] / nucleotide_total)
+            result[pair] = observed / expected if expected else None
+        return result
+
+    @staticmethod
+    def classify_dinucleotide_odds(
+        odds: dict[str, float | None],
+        *,
+        overrepresented: float = 1.25,
+        underrepresented: float = 0.78,
+    ) -> dict[str, str]:
+        """Classify O/E ratios using configurable literature thresholds."""
+
+        if underrepresented >= overrepresented:
+            raise ValueError("underrepresented threshold must be below overrepresented threshold.")
+        return {
+            pair: (
+                "undefined"
+                if value is None
+                else "overrepresented"
+                if value > overrepresented
+                else "underrepresented"
+                if value < underrepresented
+                else "neutral"
+            )
+            for pair, value in odds.items()
+        }

codonadaptpy/metrics/evolutionary.py

@@ -0,0 +1,60 @@
+"""
+CodonAdaptPy Evolutionary Codon-Usage Diagnostics
+
+This module supplies data for ENC-GC3, neutrality, and Parity Rule 2 analyses.
+The methods return numeric summaries suitable for plotting and group analysis
+without coupling the scientific calculations to a plotting backend.
+
+Classes:
+    - EvolutionaryMetrics: Mutation/selection-oriented codon diagnostics.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+class EvolutionaryMetrics:
+    """Calculate expected ENC and compositional evolutionary summaries."""
+
+    @staticmethod
+    def expected_enc(gc3: float) -> float:
+        """Return Wright's mutation-only expected ENC for a GC3 fraction."""
+
+        gc3 = max(0.0, min(1.0, gc3))
+        denominator = gc3**2 + (1 - gc3) ** 2
+        return 2 + gc3 + 29 / denominator
+
+    @staticmethod
+    def neutrality(gc1: Sequence[float], gc2: Sequence[float], gc3: Sequence[float]) -> dict[str, float]:
+        """Fit GC12 against GC3 and report slope, intercept, and R-squared."""
+
+        if not (len(gc1) == len(gc2) == len(gc3)) or not gc3:
+            raise ValueError("GC1, GC2, and GC3 must have equal non-zero lengths.")
+        y = [(a + b) / 2 for a, b in zip(gc1, gc2, strict=True)]
+        x_mean, y_mean = sum(gc3) / len(gc3), sum(y) / len(y)
+        denominator = sum((value - x_mean) ** 2 for value in gc3)
+        slope = (
+            sum((x - x_mean) * (target - y_mean) for x, target in zip(gc3, y, strict=True)) / denominator
+            if denominator
+            else 0.0
+        )
+        intercept = y_mean - slope * x_mean
+        fitted = [intercept + slope * x for x in gc3]
+        total = sum((target - y_mean) ** 2 for target in y)
+        residual = sum((target - estimate) ** 2 for target, estimate in zip(y, fitted, strict=True))
+        return {"slope": slope, "intercept": intercept, "r_squared": 1 - residual / total if total else 0.0}
+
+    @staticmethod
+    def parity_rule_2(a3: float, t3: float, g3: float, c3: float) -> dict[str, float]:
+        """Return PR2 coordinates A3/(A3+T3) and G3/(G3+C3)."""
+
+        return {
+            "at_bias": a3 / (a3 + t3) if a3 + t3 else 0.5,
+            "gc_bias": g3 / (g3 + c3) if g3 + c3 else 0.5,
+        }

codonadaptpy/metrics/host.py

@@ -0,0 +1,145 @@
+"""
+CodonAdaptPy Multi-Host Comparison Metrics
+
+This module compares sequence codon usage with one or more host reference
+profiles using RSCU similarity, cosine similarity, Euclidean distance,
+Jensen-Shannon divergence, rank/linear correlation, dinucleotide compatibility,
+RCDI, CAI, and a transparent bounded composite score.
+
+Classes:
+    - HostComparator: Compare query codons with named reference profiles.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+from ..genetic_code import GeneticCode
+from .adaptation import AdaptationMetrics
+from .usage import CodonUsageMetrics
+
+
+def _pearson(left: Sequence[float], right: Sequence[float]) -> float:
+    """Calculate Pearson correlation without requiring SciPy."""
+
+    if len(left) != len(right) or not left:
+        return 0.0
+    left_mean, right_mean = sum(left) / len(left), sum(right) / len(right)
+    numerator = sum((a - left_mean) * (b - right_mean) for a, b in zip(left, right, strict=True))
+    denominator = math.sqrt(sum((a - left_mean) ** 2 for a in left) * sum((b - right_mean) ** 2 for b in right))
+    return numerator / denominator if denominator else 0.0
+
+
+def _ranks(values: Sequence[float]) -> list[float]:
+    """Assign average ranks, including tied values."""
+
+    ordered = sorted(range(len(values)), key=lambda index: values[index])
+    ranks = [0.0] * len(values)
+    start = 0
+    while start < len(ordered):
+        end = start + 1
+        while end < len(ordered) and values[ordered[end]] == values[ordered[start]]:
+            end += 1
+        rank = (start + end - 1) / 2 + 1
+        for index in ordered[start:end]:
+            ranks[index] = rank
+        start = end
+    return ranks
+
+
+class HostComparator:
+    """Compare sequence usage against codon-count or frequency references."""
+
+    def __init__(self, genetic_code: GeneticCode | None = None) -> None:
+        """Initialize shared codon-usage and adaptation calculators."""
+
+        self.genetic_code = genetic_code or GeneticCode.from_ncbi(1)
+        self.usage = CodonUsageMetrics(self.genetic_code)
+        self.adaptation = AdaptationMetrics(self.genetic_code)
+
+    def compare(self, codons: list[str], reference: Mapping[str, float]) -> dict[str, float]:
+        """Calculate a complete host-comparison result for one reference."""
+
+        keys = sorted(codon for codon, aa in self.genetic_code.forward_table.items() if aa != "*")
+        query_frequency = self.usage.frequencies(codons)
+        reference_total = sum(max(0.0, float(reference.get(key, 0.0))) for key in keys)
+        ref_frequency = {
+            key: max(0.0, float(reference.get(key, 0.0))) / reference_total if reference_total else 0.0 for key in keys
+        }
+        query = [query_frequency.get(key, 0.0) for key in keys]
+        target = [ref_frequency[key] for key in keys]
+        dot = sum(a * b for a, b in zip(query, target, strict=True))
+        norm = math.sqrt(sum(a * a for a in query) * sum(b * b for b in target))
+        cosine = dot / norm if norm else 0.0
+        euclidean = math.sqrt(sum((a - b) ** 2 for a, b in zip(query, target, strict=True)))
+        midpoint = [(a + b) / 2 for a, b in zip(query, target, strict=True)]
+
+        def kl(values: Sequence[float], mean: Sequence[float]) -> float:
+            return sum(
+                value * math.log(value / average, 2)
+                for value, average in zip(values, mean, strict=True)
+                if value > 0 and average > 0
+            )
+
+        jsd = (kl(query, midpoint) + kl(target, midpoint)) / 2
+        weights = self.adaptation.weights_from_counts(reference)
+        query_rscu = self.usage.rscu(codons)
+        reference_rscu = self.usage.rscu_from_counts(reference)
+        rscu_distance = math.sqrt(sum((query_rscu.get(key, 0.0) - reference_rscu.get(key, 0.0)) ** 2 for key in keys))
+        sid_similarity, sid_distance = self.sid(query_rscu, reference_rscu)
+        pearson = _pearson(query, target)
+        spearman = _pearson(_ranks(query), _ranks(target))
+        cai = self.adaptation.cai(codons, weights)
+        rcdi = self.adaptation.rcdi(codons, ref_frequency)
+        composite = max(0.0, min(1.0, (cai + cosine + (pearson + 1) / 2 + (1 - min(1.0, jsd))) / 4))
+        return {
+            "cai": cai,
+            "rcdi": rcdi,
+            "rscu_distance": rscu_distance,
+            "sid_similarity": sid_similarity,
+            "sid_distance": sid_distance,
+            "cosine_similarity": cosine,
+            "euclidean_distance": euclidean,
+            "jensen_shannon_divergence": jsd,
+            "pearson_correlation": pearson,
+            "spearman_correlation": spearman,
+            "composite_adaptation_score": composite,
+        }
+
+    def sid(
+        self,
+        query_rscu: Mapping[str, float],
+        reference_rscu: Mapping[str, float],
+    ) -> tuple[float, float]:
+        """Calculate the exact 59-codon RSCU similarity and distance.
+
+        The calculation excludes stop codons and the single-codon methionine
+        and tryptophan families. It returns cosine similarity ``R`` followed
+        by the published distance ``D(A,B) = (1 - R) / 2``.
+        """
+
+        codons = sorted(
+            codon
+            for amino_acid, family in self.genetic_code.synonymous_codons.items()
+            if amino_acid != "*" and len(family) > 1
+            for codon in family
+        )
+        query = [float(query_rscu.get(codon, 0.0)) for codon in codons]
+        target = [float(reference_rscu.get(codon, 0.0)) for codon in codons]
+        numerator = sum(left * right for left, right in zip(query, target, strict=True))
+        denominator = math.sqrt(sum(value * value for value in query) * sum(value * value for value in target))
+        similarity = numerator / denominator if denominator else 0.0
+        return similarity, (1 - similarity) / 2
+
+    def compare_many(
+        self, codons: list[str], references: Mapping[str, Mapping[str, float]]
+    ) -> dict[str, dict[str, float]]:
+        """Compare one query sequence with every named host profile."""
+
+        return {name: self.compare(codons, reference) for name, reference in references.items()}