CodonAdaptPy 1.0.0__py3-none-any.whl

codonadaptpy/references.py

@@ -0,0 +1,169 @@
+"""
+CodonAdaptPy Reference-Data Management
+
+This module creates, validates, loads, saves, versions, and catalogs codon
+reference profiles. A reference may be derived from validated CDS records or
+loaded from a JSON/CSV/TSV table. The package intentionally labels its bundled
+uniform profile as synthetic; organism-specific biological profiles must carry
+source and version metadata supplied by the user or distributor.
+
+Classes:
+    - ReferenceProfile: Named codon counts with provenance metadata.
+    - ReferenceManager: Registry and persistence interface for profiles.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import csv
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .exceptions import ReferenceDataError
+from .genetic_code import GeneticCode
+from .models import SequenceRecord, ValidationConfig
+from .validation import SequenceValidator
+
+
+@dataclass(slots=True)
+class ReferenceProfile:
+    """Represent versioned codon counts and their scientific provenance."""
+
+    name: str
+    counts: dict[str, float]
+    genetic_code: int = 1
+    version: str = "1"
+    source: str = "user-supplied"
+    description: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return profile content in JSON-compatible form."""
+
+        return asdict(self)
+
+
+class ReferenceManager:
+    """Manage named codon profiles and reproducible reference persistence."""
+
+    def __init__(self) -> None:
+        """Initialize a registry containing an explicitly synthetic baseline."""
+
+        code = GeneticCode.from_ncbi(1)
+        self._profiles: dict[str, ReferenceProfile] = {
+            "uniform_standard": ReferenceProfile(
+                name="uniform_standard",
+                counts={codon: 1.0 for codon, amino_acid in code.forward_table.items() if amino_acid != "*"},
+                source="CodonAdaptPy synthetic baseline",
+                description="Non-biological equal-count profile for testing and normalization.",
+                metadata={"biological": False},
+            )
+        }
+
+    def register(self, profile: ReferenceProfile, *, replace: bool = False) -> None:
+        """Validate and register a profile under its unique name."""
+
+        if profile.name in self._profiles and not replace:
+            existing = self._profiles[profile.name]
+            if existing.to_dict() == profile.to_dict():
+                return
+            raise ReferenceDataError(f"Reference profile already exists: {profile.name}")
+        code = GeneticCode.from_ncbi(profile.genetic_code)
+        sense = {codon for codon, amino_acid in code.forward_table.items() if amino_acid != "*"}
+        invalid = set(profile.counts) - set(code.forward_table)
+        if invalid:
+            raise ReferenceDataError(f"Reference contains unsupported codons: {', '.join(sorted(invalid))}")
+        if any(float(value) < 0 for value in profile.counts.values()):
+            raise ReferenceDataError("Reference counts must be non-negative.")
+        profile.counts = {codon: float(profile.counts.get(codon, 0.0)) for codon in sorted(sense)}
+        if not sum(profile.counts.values()):
+            raise ReferenceDataError("Reference contains no positive sense-codon counts.")
+        self._profiles[profile.name] = profile
+
+    def from_sequences(
+        self,
+        name: str,
+        records: list[SequenceRecord],
+        *,
+        genetic_code: int = 1,
+        version: str = "1",
+        source: str = "user CDS set",
+    ) -> ReferenceProfile:
+        """Build a reference by pooling strictly validated coding sequences."""
+
+        validator = SequenceValidator(ValidationConfig(genetic_code=genetic_code))
+        code = validator.genetic_code
+        counts = {codon: 0.0 for codon, amino_acid in code.forward_table.items() if amino_acid != "*"}
+        checksums: list[str] = []
+        for record in records:
+            report = validator.validate(record, raise_on_error=True)
+            framed = report.normalized_sequence[validator.config.reading_frame :]
+            for index in range(0, len(framed) - 2, 3):
+                codon = framed[index : index + 3]
+                if codon in counts:
+                    counts[codon] += 1
+            checksums.append(hashlib.sha256(report.normalized_sequence.encode()).hexdigest())
+        profile = ReferenceProfile(
+            name,
+            counts,
+            genetic_code,
+            version,
+            source,
+            metadata={"sequence_count": len(records), "sequence_sha256": checksums},
+        )
+        self.register(profile)
+        return profile
+
+    def get(self, name: str) -> ReferenceProfile:
+        """Return a registered profile or raise a domain-specific error."""
+
+        try:
+            return self._profiles[name]
+        except KeyError as exc:
+            raise ReferenceDataError(f"Unknown reference profile: {name}") from exc
+
+    def list(self) -> list[dict[str, Any]]:
+        """Return catalog metadata without duplicating full count tables."""
+
+        return [
+            {
+                "name": profile.name,
+                "version": profile.version,
+                "source": profile.source,
+                "genetic_code": profile.genetic_code,
+                "description": profile.description,
+            }
+            for profile in self._profiles.values()
+        ]
+
+    def save(self, name: str, path: str | Path) -> Path:
+        """Serialize a registered profile to deterministic JSON."""
+
+        destination = Path(path)
+        destination.write_text(json.dumps(self.get(name).to_dict(), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        return destination
+
+    def load(self, path: str | Path, *, replace: bool = False) -> ReferenceProfile:
+        """Load JSON or two-column CSV/TSV reference data and register it."""
+
+        source_path = Path(path)
+        if source_path.suffix.lower() == ".json":
+            payload = json.loads(source_path.read_text(encoding="utf-8"))
+            profile = ReferenceProfile(**payload)
+        else:
+            delimiter = "," if source_path.suffix.lower() == ".csv" else "\t"
+            with source_path.open(encoding="utf-8", newline="") as handle:
+                rows = list(csv.DictReader(handle, delimiter=delimiter))
+            counts = {
+                row["codon"].upper().replace("U", "T"): float(row.get("count", row.get("frequency", 0))) for row in rows
+            }
+            profile = ReferenceProfile(source_path.stem, counts, source=str(source_path))
+        self.register(profile, replace=replace)
+        return profile

codonadaptpy/reporting.py

@@ -0,0 +1,174 @@
+"""
+CodonAdaptPy Reproducible File Reports
+
+This module exports analysis and optimization results to JSON, CSV, TSV, FASTA,
+Excel, HTML, and optional PDF. Reports include software, input checksum,
+genetic-code, reference-version, random-seed, and command provenance already
+captured by the analyzer.
+
+Classes:
+    - ReportGenerator: Write deterministic machine-readable and human reports.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import csv
+import html
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from .exceptions import OptionalDependencyError
+from .models import AnalysisResult
+from .optimizer import OptimizationResult
+
+
+class ReportGenerator:
+    """Export package results to machine-readable and publication-friendly files."""
+
+    def write_json(self, results: list[AnalysisResult], path: str | Path) -> Path:
+        """Write complete nested analysis results as indented JSON."""
+
+        destination = Path(path)
+        destination.write_text(
+            json.dumps([result.to_dict() for result in results], indent=2, sort_keys=True) + "\n", encoding="utf-8"
+        )
+        return destination
+
+    def write_table(self, results: list[AnalysisResult], path: str | Path, *, delimiter: str | None = None) -> Path:
+        """Write one flattened scalar-metric row per sequence as CSV or TSV."""
+
+        destination = Path(path)
+        separator = delimiter or ("\t" if destination.suffix.lower() == ".tsv" else ",")
+        rows = [self._summary_row(result) for result in results]
+        fields = sorted({key for row in rows for key in row})
+        with destination.open("w", encoding="utf-8", newline="") as handle:
+            writer = csv.DictWriter(handle, fieldnames=fields, delimiter=separator, lineterminator="\n")
+            writer.writeheader()
+            writer.writerows(rows)
+        return destination
+
+    def write_html(self, results: list[AnalysisResult], path: str | Path) -> Path:
+        """Write a self-contained HTML summary without a template dependency."""
+
+        destination = Path(path)
+        rows = [self._summary_row(result) for result in results]
+        fields = sorted({key for row in rows for key in row})
+        header = "".join(f"<th>{html.escape(field)}</th>" for field in fields)
+        body = "".join(
+            "<tr>" + "".join(f"<td>{html.escape(str(row.get(field, '')))}</td>" for field in fields) + "</tr>"
+            for row in rows
+        )
+        document = f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><title>CodonAdaptPy report</title>
+<style>
+body {{ font-family: system-ui; margin: 2rem; color: #18212b; }}
+table {{ border-collapse: collapse; width: 100%; }}
+th, td {{ border: 1px solid #ccd3da; padding: .45rem; text-align: right; }}
+th {{ background: #edf3f7; }}
+td:first-child, th:first-child {{ text-align: left; }}
+.note {{ padding: 1rem; background: #fff6dc; border-left: 4px solid #d99b00; }}
+</style>
+</head>
+<body>
+<h1>CodonAdaptPy analysis report</h1>
+<p class="note">Codon-usage similarity is descriptive and is not direct proof of expression,
+replication, virulence, host switching, transmission, or fitness.</p>
+<table><thead><tr>{header}</tr></thead><tbody>{body}</tbody></table>
+</body>
+</html>"""
+        destination.write_text(document, encoding="utf-8")
+        return destination
+
+    def write_excel(self, results: list[AnalysisResult], path: str | Path) -> Path:
+        """Write summary, codon counts, RSCU, validation, and host sheets."""
+
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise OptionalDependencyError("Excel reports require CodonAdaptPy[analysis,io].") from exc
+        destination = Path(path)
+        with pd.ExcelWriter(destination) as writer:
+            pd.DataFrame([self._summary_row(result) for result in results]).to_excel(
+                writer, sheet_name="Summary", index=False
+            )
+            pd.DataFrame([{"identifier": result.identifier, **result.codon_counts} for result in results]).to_excel(
+                writer, sheet_name="Codon_counts", index=False
+            )
+            pd.DataFrame([{"identifier": result.identifier, **result.rscu} for result in results]).to_excel(
+                writer, sheet_name="RSCU", index=False
+            )
+            pd.DataFrame(
+                [{"identifier": result.identifier, **result.dinucleotide_odds} for result in results]
+            ).to_excel(writer, sheet_name="Dinucleotide_OE", index=False)
+            pd.DataFrame(
+                [{"identifier": result.identifier, **result.dinucleotide_bias} for result in results]
+            ).to_excel(writer, sheet_name="Dinucleotide_bias", index=False)
+            validation_rows = [
+                {"identifier": result.identifier, **asdict(issue)}
+                for result in results
+                for issue in result.validation.issues
+            ]
+            pd.DataFrame(validation_rows).to_excel(writer, sheet_name="Validation", index=False)
+            host_rows = [
+                {"identifier": result.identifier, "host": host, **metrics}
+                for result in results
+                for host, metrics in result.host_comparisons.items()
+            ]
+            pd.DataFrame(host_rows).to_excel(writer, sheet_name="Hosts", index=False)
+        return destination
+
+    def write_pdf(self, results: list[AnalysisResult], path: str | Path) -> Path:
+        """Render the HTML report to PDF using the optional report extra."""
+
+        try:
+            from weasyprint import HTML
+        except ImportError as exc:
+            raise OptionalDependencyError("PDF reports require CodonAdaptPy[report].") from exc
+        destination = Path(path)
+        html_path = destination.with_suffix(".html")
+        self.write_html(results, html_path)
+        HTML(filename=str(html_path)).write_pdf(str(destination))
+        return destination
+
+    def write_optimized_fasta(self, result: OptimizationResult, path: str | Path) -> Path:
+        """Write ranked optimization candidates in FASTA format."""
+
+        destination = Path(path)
+        lines: list[str] = []
+        for candidate in result.candidates:
+            lines.extend(
+                [
+                    f">candidate_{candidate.rank} score={candidate.score:.6f} "
+                    f"cai={candidate.cai:.6f} gc={candidate.gc:.6f}",
+                    candidate.sequence,
+                ]
+            )
+        destination.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        return destination
+
+    @staticmethod
+    def _summary_row(result: AnalysisResult) -> dict[str, Any]:
+        """Flatten scalar metrics and host metrics for tabular exports."""
+
+        row: dict[str, Any] = {"identifier": result.identifier, "valid": result.validation.is_valid}
+        row.update(
+            {
+                key: value
+                for key, value in result.metrics.items()
+                if isinstance(value, (str, int, float, bool)) or value is None
+            }
+        )
+        row.update({f"dinucleotide_oe.{pair}": value for pair, value in result.dinucleotide_odds.items()})
+        row.update({f"dinucleotide_bias.{pair}": value for pair, value in result.dinucleotide_bias.items()})
+        for host, metrics in result.host_comparisons.items():
+            row.update({f"host.{host}.{key}": value for key, value in metrics.items()})
+        return row

codonadaptpy/validation.py

@@ -0,0 +1,169 @@
+"""
+CodonAdaptPy Coding-Sequence Validation
+
+This module normalizes DNA/RNA input and applies configurable coding-sequence
+quality checks. Validation is non-destructive: every finding is returned in a
+structured report, while strict callers may request an exception for errors.
+
+Checks:
+    - Empty input, whitespace, RNA conversion, and unsupported symbols
+    - Reading-frame offset and triplet divisibility
+    - Required start and terminal stop codons
+    - Internal stops and ambiguous codons
+    - Partial-sequence policy and supported genetic code
+
+Classes:
+    - SequenceValidator: Reusable validator configured for one analysis policy.
+
+:Created: July 20, 2026
+:Updated: July 20, 2026
+:Author: Naveen Duhan
+:Version: 1.0.0
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Literal, cast
+
+from .exceptions import SequenceValidationError
+from .genetic_code import GeneticCode
+from .models import SequenceRecord, ValidationConfig, ValidationIssue, ValidationReport
+
+IUPAC_DNA = frozenset("ACGTRYSWKMBDHVN")
+
+
+class SequenceValidator:
+    """Validate and normalize coding sequences under a fixed policy."""
+
+    def __init__(self, config: ValidationConfig | None = None) -> None:
+        """Initialize the validator and resolve its selected genetic code."""
+
+        self.config = config or ValidationConfig()
+        self.genetic_code = GeneticCode.from_ncbi(self.config.genetic_code)
+
+    def validate(self, record: SequenceRecord, *, raise_on_error: bool = False) -> ValidationReport:
+        """Validate one sequence record and return every detected issue.
+
+        Parameters
+        ----------
+        record:
+            Input record containing an identifier and nucleotide sequence.
+        raise_on_error:
+            Raise :class:`SequenceValidationError` after collecting errors.
+            The default returns an invalid report for batch-friendly behavior.
+        """
+
+        raw = re.sub(r"\s+", "", record.sequence).upper()
+        issues: list[ValidationIssue] = []
+        if not raw:
+            issues.append(ValidationIssue("empty_sequence", "The sequence is empty.", "error"))
+            return self._finish(record.identifier, raw, issues, raise_on_error)
+
+        if "U" in raw:
+            severity = cast(Literal["warning", "error"], "warning" if self.config.convert_rna else "error")
+            issues.append(
+                ValidationIssue(
+                    "rna_input",
+                    "RNA base U was detected." + (" It was converted to T." if self.config.convert_rna else ""),
+                    severity,
+                )
+            )
+            if self.config.convert_rna:
+                raw = raw.replace("U", "T")
+
+        invalid = [(index, base) for index, base in enumerate(raw) if base not in IUPAC_DNA]
+        for index, base in invalid[:25]:
+            issues.append(ValidationIssue("invalid_character", f"Unsupported nucleotide {base!r}.", "error", index))
+        if len(invalid) > 25:
+            issues.append(
+                ValidationIssue(
+                    "invalid_character_limit", f"{len(invalid) - 25} additional invalid symbols were omitted.", "error"
+                )
+            )
+
+        framed = raw[self.config.reading_frame :]
+        if self.config.reading_frame and len(raw) <= self.config.reading_frame:
+            issues.append(
+                ValidationIssue(
+                    "invalid_reading_frame", "The reading-frame offset removes the complete sequence.", "error"
+                )
+            )
+        remainder = len(framed) % 3
+        if remainder:
+            severity = cast(Literal["warning", "error"], "warning" if self.config.allow_partial else "error")
+            issues.append(
+                ValidationIssue(
+                    "incomplete_codon",
+                    f"Sequence length in frame leaves {remainder} trailing nucleotide(s).",
+                    severity,
+                    len(raw) - remainder,
+                )
+            )
+
+        codons = [framed[index : index + 3] for index in range(0, len(framed) - 2, 3)]
+        ambiguous = [(index, codon) for index, codon in enumerate(codons) if set(codon) - set("ACGT")]
+        for index, codon in ambiguous:
+            severity = cast(
+                Literal["warning", "error"], "error" if self.config.ambiguous_policy == "reject" else "warning"
+            )
+            action = {"reject": "rejected", "skip": "skipped", "allow": "retained"}[self.config.ambiguous_policy]
+            issues.append(
+                ValidationIssue(
+                    "ambiguous_codon",
+                    f"Ambiguous codon {codon} will be {action}.",
+                    severity,
+                    self.config.reading_frame + index * 3,
+                )
+            )
+
+        if codons:
+            if (
+                self.config.require_start
+                and not self.config.allow_partial
+                and codons[0] not in self.genetic_code.start_codons
+            ):
+                issues.append(
+                    ValidationIssue(
+                        "missing_start",
+                        f"First codon {codons[0]} is not a start codon for genetic code {self.genetic_code.table_id}.",
+                        "error",
+                        self.config.reading_frame,
+                    )
+                )
+            if (
+                self.config.require_stop
+                and not self.config.allow_partial
+                and codons[-1] not in self.genetic_code.stop_codons
+            ):
+                issues.append(
+                    ValidationIssue(
+                        "missing_stop",
+                        f"Final codon {codons[-1]} is not a stop codon for genetic code {self.genetic_code.table_id}.",
+                        "error",
+                        self.config.reading_frame + (len(codons) - 1) * 3,
+                    )
+                )
+            for index, codon in enumerate(codons[:-1]):
+                if codon in self.genetic_code.stop_codons:
+                    issues.append(
+                        ValidationIssue(
+                            "internal_stop",
+                            f"Internal stop codon {codon} was found.",
+                            "error",
+                            self.config.reading_frame + index * 3,
+                        )
+                    )
+
+        return self._finish(record.identifier, raw, issues, raise_on_error)
+
+    def _finish(
+        self, identifier: str, sequence: str, issues: list[ValidationIssue], raise_on_error: bool
+    ) -> ValidationReport:
+        """Build a report and optionally convert error findings to an exception."""
+
+        report = ValidationReport(identifier, sequence, issues, self.config.genetic_code, self.config.reading_frame)
+        if raise_on_error and not report.is_valid:
+            raise SequenceValidationError("; ".join(issue.message for issue in report.errors))
+        return report
+