factorforge-cds 3.0.0__py3-none-any.whl

factorforge/engines/v2/scoring.py

@@ -0,0 +1,232 @@
+"""
+Multidimensional Scoring for FactorForge v2.
+Composite scoring function with optional ViennaRNA MFE integration.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Optimal GC range for N. benthamiana
+GC_OPT_MIN = 41.0
+GC_OPT_MAX = 44.0
+GC_OPT_MID = 42.5
+
+# ViennaRNA availability cache
+_vienna_available: bool | None = None
+
+
+@dataclass
+class ScoringConfig:
+    """Scoring weight configuration for composite optimization score."""
+
+    w_cai: float = 0.5
+    w_gc: float = 0.3
+    w_mfe: float = 0.2
+    w_dinuc: float = 0.0  # CpG/TpA dinucleotide penalty (opt-in, default off)
+    gc_opt: float = GC_OPT_MID
+    use_mfe: bool = True
+
+    def __post_init__(self) -> None:
+        """Normalize weights to sum to 1.0."""
+        self._normalize()
+
+    def _normalize(self) -> None:
+        """Ensure active weights sum to 1.0."""
+        total = (
+            self.w_cai
+            + self.w_gc
+            + (self.w_mfe if self.use_mfe else 0.0)
+            + self.w_dinuc
+        )
+        if total > 0:
+            self.w_cai /= total
+            self.w_gc /= total
+            if self.use_mfe:
+                self.w_mfe /= total
+            else:
+                self.w_mfe = 0.0
+            self.w_dinuc /= total
+
+
+# Pre-defined scoring configs per optimization profile
+PROFILE_SCORING_CONFIGS: dict[str, ScoringConfig] = {
+    "balanced": ScoringConfig(w_cai=0.5, w_gc=0.3, w_mfe=0.2, gc_opt=GC_OPT_MID),
+    "high_cai": ScoringConfig(w_cai=0.8, w_gc=0.1, w_mfe=0.1, gc_opt=GC_OPT_MID),
+    "gc_target": ScoringConfig(w_cai=0.1, w_gc=0.7, w_mfe=0.2, gc_opt=GC_OPT_MID),
+    "assembly_friendly": ScoringConfig(w_cai=0.5, w_gc=0.3, w_mfe=0.2, gc_opt=GC_OPT_MID),
+    "ramp": ScoringConfig(w_cai=0.4, w_gc=0.3, w_mfe=0.3, gc_opt=GC_OPT_MID),
+    # TRV viral-delivery profile — Li et al. (2026): prioritize MFE and viral-context GC target.
+    "viral_delivery": ScoringConfig(w_cai=0.35, w_gc=0.25, w_mfe=0.40, gc_opt=47.5, use_mfe=True),
+}
+
+
+def _check_vienna_available() -> bool:
+    """Check if ViennaRNA Python bindings are available."""
+    global _vienna_available
+    if _vienna_available is None:
+        try:
+            import RNA  # noqa: F401
+
+            _vienna_available = True
+            logger.debug("ViennaRNA Python bindings available")
+        except ImportError:
+            _vienna_available = False
+            logger.debug("ViennaRNA not available; MFE scoring disabled")
+    return _vienna_available
+
+
+def calculate_mfe(sequence: str) -> float | None:
+    """
+    Calculate minimum free energy (MFE) using ViennaRNA.
+
+    Args:
+        sequence: DNA or RNA sequence.
+
+    Returns:
+        MFE in kcal/mol, or None if ViennaRNA is not available.
+    """
+    if not _check_vienna_available():
+        return None
+
+    try:
+        import RNA
+
+        # Convert DNA to RNA (T → U)
+        rna_seq = sequence.upper().replace("T", "U")
+        _, mfe = RNA.fold(rna_seq)
+        return float(mfe)
+    except Exception as exc:
+        logger.debug(f"MFE calculation failed: {exc}")
+        return None
+
+
+def normalize_mfe(mfe: float, seq_length: int) -> float:
+    """
+    Normalize MFE to 0-1 range where 1 = no structure (favorable).
+
+    Uses empirical scaling: MFE per nucleotide typically ranges from
+    -0.5 to 0.0 kcal/mol/nt for mRNA coding sequences.
+
+    Args:
+        mfe: Minimum free energy in kcal/mol.
+        seq_length: Sequence length in nucleotides.
+
+    Returns:
+        Normalized MFE score (0-1, higher = less structured = better for translation).
+    """
+    if seq_length == 0:
+        return 0.5
+
+    mfe_per_nt = mfe / seq_length
+    # Clamp to expected range [-0.5, 0.0]
+    clamped = max(-0.5, min(0.0, mfe_per_nt))
+    # Map to [0, 1] where 0.0 kcal/mol/nt → 1.0 and -0.5 → 0.0
+    return 1.0 + (clamped / 0.5)
+
+
+def calculate_dinucleotide_score(sequence: str) -> float:
+    """Calculate a dinucleotide avoidance score (0-1, higher = fewer CpG/TpA).
+
+    Combines CpG and TpA observed/expected ratios. A sequence with no CpG
+    and no TpA scores 1.0; high density scores toward 0.0.
+
+    Args:
+        sequence: DNA sequence.
+
+    Returns:
+        Dinucleotide avoidance score (0-1).
+    """
+    from factorforge.engines.v2.utils import calculate_dinucleotide_ratio
+
+    if len(sequence) < 6:
+        return 1.0
+
+    cpg_ratio = calculate_dinucleotide_ratio(sequence, "CG")
+    tpa_ratio = calculate_dinucleotide_ratio(sequence, "TA")
+
+    # Score: 1.0 when ratio=0, 0.0 when ratio>=2.0
+    cpg_score = max(0.0, 1.0 - cpg_ratio / 2.0)
+    tpa_score = max(0.0, 1.0 - tpa_ratio / 2.0)
+
+    return (cpg_score + tpa_score) / 2.0
+
+
+def calculate_composite_score(
+    cai: float,
+    gc: float,
+    sequence: str | None = None,
+    config: ScoringConfig | None = None,
+    profile: str | None = None,
+    **kwargs: Any,
+) -> float:
+    """
+    Calculate multidimensional composite score.
+
+    S = w1*CAI + w2*(1 - |GC - GC_opt|/50) + w3*MFE_norm + w4*dinuc_score
+
+    Args:
+        cai: Codon Adaptation Index (0-1).
+        gc: GC content percentage (0-100).
+        sequence: DNA sequence for optional MFE calculation.
+        config: Explicit ScoringConfig. Overrides profile.
+        profile: Profile name for preset config lookup.
+        **kwargs: Additional parameters (e.g., target_gc for gc_target profile).
+
+    Returns:
+        Composite score (0-1).
+    """
+    # Resolve config
+    if config is None:
+        profile_name = (profile or "balanced").lower()
+        config = PROFILE_SCORING_CONFIGS.get(profile_name)
+        if config is None:
+            config = PROFILE_SCORING_CONFIGS["balanced"]
+
+    # Allow target_gc override for gc_target profile
+    gc_opt = float(kwargs.get("target_gc", config.gc_opt))
+
+    # Component 1: CAI (already 0-1)
+    cai_score = max(0.0, min(1.0, cai))
+
+    # Component 2: GC proximity to optimum
+    gc_score = max(0.0, 1.0 - abs(gc - gc_opt) / 50.0)
+
+    # Component 3: MFE (optional)
+    mfe_score = 0.5  # neutral default
+    actual_w_mfe = config.w_mfe
+
+    if config.use_mfe and sequence is not None and _check_vienna_available():
+        mfe = calculate_mfe(sequence)
+        if mfe is not None:
+            mfe_score = normalize_mfe(mfe, len(sequence))
+        else:
+            actual_w_mfe = 0.0
+    else:
+        actual_w_mfe = 0.0
+
+    # Component 4: Dinucleotide avoidance (opt-in, default weight 0.0)
+    dinuc_score = 0.5  # neutral default
+    actual_w_dinuc = config.w_dinuc
+    if actual_w_dinuc > 0 and sequence is not None:
+        dinuc_score = calculate_dinucleotide_score(sequence)
+    elif actual_w_dinuc > 0:
+        actual_w_dinuc = 0.0  # Cannot compute without sequence
+
+    # Compute weighted score (re-normalize if MFE/dinuc disabled)
+    w_total = config.w_cai + config.w_gc + actual_w_mfe + actual_w_dinuc
+    if w_total == 0:
+        return 0.0
+
+    score = (
+        (config.w_cai / w_total) * cai_score
+        + (config.w_gc / w_total) * gc_score
+        + (actual_w_mfe / w_total) * mfe_score
+        + (actual_w_dinuc / w_total) * dinuc_score
+    )
+
+    return round(score, 3)

factorforge/engines/v2/utils.py

@@ -0,0 +1,231 @@
+"""
+Utility helpers for FactorForge v2 engines.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+import os
+from pathlib import Path
+from typing import Any, cast
+
+
+def get_data_path() -> Path:
+    """Get data directory path from environment or package resources.
+
+    Checks FACTORFORGE_DATA_DIR environment variable first, then falls back to
+    the bundled package data directory (works with pip-installed packages).
+
+    Returns:
+        Path to data directory.
+
+    Examples:
+        >>> data_dir = get_data_path()
+        >>> isinstance(data_dir, Path)
+        True
+    """
+    data_dir = os.getenv("FACTORFORGE_DATA_DIR")
+    if data_dir:
+        return Path(data_dir)
+
+    # Use importlib.resources to locate bundled package data
+    # This works correctly whether the package is installed via pip or run from source
+    try:
+        ref = importlib.resources.files("factorforge") / "data"
+        return Path(str(ref))
+    except (TypeError, ModuleNotFoundError):
+        # Fallback for development: go up from v2/utils.py to src/factorforge/data
+        return Path(__file__).resolve().parents[2] / "data"
+
+
+def calculate_gc(sequence: str) -> float:
+    """Calculate GC content percentage.
+
+    Args:
+        sequence: DNA sequence string.
+
+    Returns:
+        GC content as percentage (0-100).
+
+    Examples:
+        >>> calculate_gc("ATGC")
+        50.0
+    """
+    if not sequence:
+        return 0.0
+
+    seq = sequence.upper()
+    gc_count = seq.count("G") + seq.count("C")
+    return (gc_count / len(sequence)) * 100
+
+
+def count_dinucleotides(sequence: str, dinucleotide: str = "CG") -> int:
+    """Count occurrences of a dinucleotide in a DNA sequence.
+
+    Args:
+        sequence: DNA sequence string (case-insensitive).
+        dinucleotide: Two-character dinucleotide to count (e.g., "CG", "TA").
+
+    Returns:
+        Count of dinucleotide occurrences.
+
+    Examples:
+        >>> count_dinucleotides("ACGACG", "CG")
+        2
+    """
+    seq = sequence.upper()
+    dn = dinucleotide.upper()
+    return sum(1 for i in range(len(seq) - 1) if seq[i : i + 2] == dn)
+
+
+def calculate_dinucleotide_ratio(sequence: str, dinucleotide: str = "CG") -> float:
+    """Calculate observed/expected ratio of a dinucleotide.
+
+    Compares actual dinucleotide frequency to what would be expected
+    from mononucleotide composition. Ratio < 1.0 means suppressed,
+    > 1.0 means enriched.
+
+    Args:
+        sequence: DNA sequence string (case-insensitive).
+        dinucleotide: Two-character dinucleotide (e.g., "CG", "TA").
+
+    Returns:
+        Observed/expected ratio (0.0 if sequence too short or denominator zero).
+
+    Examples:
+        >>> calculate_dinucleotide_ratio("ACGTACGT", "CG")  # doctest: +SKIP
+        1.0
+    """
+    seq = sequence.upper()
+    if len(seq) < 2:
+        return 0.0
+
+    dn = dinucleotide.upper()
+    observed = sum(1 for i in range(len(seq) - 1) if seq[i : i + 2] == dn)
+
+    n1 = seq.count(dn[0])
+    n2 = seq.count(dn[1])
+    n = len(seq)
+
+    expected = (n1 * n2) / n if n > 0 else 0.0
+    if expected == 0.0:
+        return 0.0
+
+    return observed / expected
+
+
+def load_codon_table(organism: str, codon_tables_dir: Path) -> dict[str, Any]:
+    """Load codon usage table for organism.
+
+    Args:
+        organism: Organism name (e.g., "human", "ecoli").
+        codon_tables_dir: Directory containing codon table files.
+
+    Returns:
+        Codon table payload parsed from JSON.
+
+    Raises:
+        FileNotFoundError: If codon table file not found.
+    """
+    filename = organism if organism.endswith(".json") else f"{organism}_codons.json"
+    codon_table_path = codon_tables_dir / filename
+
+    with open(codon_table_path, "r", encoding="utf-8") as handle:
+        return cast(dict[str, Any], json.load(handle))
+
+
+def build_aa_to_codons_map(codon_table: dict[str, Any]) -> dict[str, list[str]]:
+    """Build amino-acid-to-codons map from a codon table payload."""
+    amino_acids = codon_table.get("amino_acids", {})
+    if not isinstance(amino_acids, dict):
+        return {}
+    return {aa: list(info.get("codons", [])) for aa, info in amino_acids.items()}
+
+
+def load_golden_set(data_dir: Path | None = None) -> dict[str, Any]:
+    """Load golden set codon table for CAI reference weights.
+
+    Falls back to the standard codon table if golden set file is not found.
+
+    Args:
+        data_dir: Data directory path. Defaults to get_data_path().
+
+    Returns:
+        Golden set codon table dict.
+    """
+    if data_dir is None:
+        data_dir = get_data_path()
+    golden_path = data_dir / "nbenthamiana_golden_set.json"
+    if golden_path.exists():
+        with open(golden_path, "r", encoding="utf-8") as f:
+            return cast(dict[str, Any], json.load(f))
+    # Fallback to standard table
+    standard_path = data_dir / "nbenthamiana_codons.json"
+    with open(standard_path, "r", encoding="utf-8") as f:
+        return cast(dict[str, Any], json.load(f))
+
+
+def translate_codon(codon: str, codon_table: dict[str, str]) -> str:
+    """Translate DNA codon to amino acid.
+
+    Args:
+        codon: 3-letter DNA codon.
+        codon_table: Codon to amino acid mapping.
+
+    Returns:
+        Single letter amino acid code.
+
+    Raises:
+        KeyError: If codon not in table.
+    """
+    return codon_table[codon.upper()]
+
+
+def parse_fasta_records(content: str) -> list[tuple[str, str]]:
+    """Parse FASTA content into (record_id, sequence) tuples.
+
+    Args:
+        content: FASTA text content.
+
+    Returns:
+        List of (record_id, sequence) tuples.
+
+    Raises:
+        ValueError: If content is not valid FASTA.
+    """
+    records: list[tuple[str, str]] = []
+    seq_id: str | None = None
+    seq_lines: list[str] = []
+
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        if line.startswith(">"):
+            if seq_id is not None:
+                sequence = "".join(seq_lines).upper()
+                if not sequence:
+                    raise ValueError(f"Empty FASTA record: {seq_id}")
+                records.append((seq_id, sequence))
+
+            header = line[1:].strip()
+            seq_id = header.split()[0] if header else f"seq{len(records) + 1}"
+            seq_lines = []
+            continue
+
+        if seq_id is None:
+            raise ValueError("Invalid FASTA: sequence data found before header")
+        seq_lines.append(line)
+
+    if seq_id is not None:
+        sequence = "".join(seq_lines).upper()
+        if not sequence:
+            raise ValueError(f"Empty FASTA record: {seq_id}")
+        records.append((seq_id, sequence))
+
+    if not records:
+        raise ValueError("No FASTA records found")
+
+    return records