factorforge-cds 3.0.0__py3-none-any.whl

factorforge/ml/metrics.py

@@ -0,0 +1,295 @@
+"""Shared sequence metrics for v3-alpha evaluation and validation."""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from typing import Any
+
+
+STANDARD_GENETIC_CODE: dict[str, str] = {
+    "TTT": "F",
+    "TTC": "F",
+    "TTA": "L",
+    "TTG": "L",
+    "TCT": "S",
+    "TCC": "S",
+    "TCA": "S",
+    "TCG": "S",
+    "TAT": "Y",
+    "TAC": "Y",
+    "TAA": "*",
+    "TAG": "*",
+    "TGT": "C",
+    "TGC": "C",
+    "TGA": "*",
+    "TGG": "W",
+    "CTT": "L",
+    "CTC": "L",
+    "CTA": "L",
+    "CTG": "L",
+    "CCT": "P",
+    "CCC": "P",
+    "CCA": "P",
+    "CCG": "P",
+    "CAT": "H",
+    "CAC": "H",
+    "CAA": "Q",
+    "CAG": "Q",
+    "CGT": "R",
+    "CGC": "R",
+    "CGA": "R",
+    "CGG": "R",
+    "ATT": "I",
+    "ATC": "I",
+    "ATA": "I",
+    "ATG": "M",
+    "ACT": "T",
+    "ACC": "T",
+    "ACA": "T",
+    "ACG": "T",
+    "AAT": "N",
+    "AAC": "N",
+    "AAA": "K",
+    "AAG": "K",
+    "AGT": "S",
+    "AGC": "S",
+    "AGA": "R",
+    "AGG": "R",
+    "GTT": "V",
+    "GTC": "V",
+    "GTA": "V",
+    "GTG": "V",
+    "GCT": "A",
+    "GCC": "A",
+    "GCA": "A",
+    "GCG": "A",
+    "GAT": "D",
+    "GAC": "D",
+    "GAA": "E",
+    "GAG": "E",
+    "GGT": "G",
+    "GGC": "G",
+    "GGA": "G",
+    "GGG": "G",
+}
+
+STOP_CODONS = {codon for codon, aa in STANDARD_GENETIC_CODE.items() if aa == "*"}
+VALID_BASES = set("ATGC")
+
+
+def _normalize_dna(sequence: str) -> str:
+    return "".join(sequence.upper().replace("U", "T").split())
+
+
+def _codons(sequence: str, include_partial: bool = False) -> list[str]:
+    seq = _normalize_dna(sequence)
+    end = len(seq) if include_partial else len(seq) - len(seq) % 3
+    return [seq[index : index + 3] for index in range(0, end, 3)]
+
+
+def calculate_gc(sequence: str) -> float:
+    """Calculate GC content as a percentage in the range 0-100."""
+    seq = _normalize_dna(sequence)
+    if not seq:
+        return 0.0
+    return ((seq.count("G") + seq.count("C")) / len(seq)) * 100.0
+
+
+def calculate_gc_windows(
+    sequence: str,
+    window_size: int = 60,
+    step: int = 30,
+) -> list[dict[str, float | int]]:
+    """Calculate sliding-window GC percentages."""
+    if window_size <= 0:
+        raise ValueError("window_size must be > 0")
+    if step <= 0:
+        raise ValueError("step must be > 0")
+
+    seq = _normalize_dna(sequence)
+    if not seq:
+        return []
+    if len(seq) <= window_size:
+        return [{"start": 0, "end": len(seq), "gc": calculate_gc(seq)}]
+
+    windows: list[dict[str, float | int]] = []
+    for start in range(0, len(seq) - window_size + 1, step):
+        end = start + window_size
+        windows.append({"start": start, "end": end, "gc": calculate_gc(seq[start:end])})
+    if windows and int(windows[-1]["end"]) < len(seq):
+        start = len(seq) - window_size
+        if start != int(windows[-1]["start"]):
+            windows.append({"start": start, "end": len(seq), "gc": calculate_gc(seq[start:])})
+    return windows
+
+
+def calculate_first_region_gc(
+    sequence: str,
+    region_sizes: list[int] | None = None,
+) -> dict[str, float]:
+    """Calculate GC for configured 5-prime regions."""
+    seq = _normalize_dna(sequence)
+    sizes = region_sizes or [30, 60, 90]
+    result: dict[str, float] = {}
+    for size in sizes:
+        if size <= 0:
+            raise ValueError("region sizes must be > 0")
+        region = seq[: min(size, len(seq))]
+        result[f"first_{size}nt_gc"] = calculate_gc(region)
+    return result
+
+
+def translate_dna(sequence: str) -> str:
+    """Translate DNA to amino acids, using X for invalid codons."""
+    translated: list[str] = []
+    for codon in _codons(sequence):
+        translated.append(STANDARD_GENETIC_CODE.get(codon, "X"))
+    return "".join(translated)
+
+
+def amino_acid_identity(input_protein: str, dna_sequence: str) -> float:
+    """Return exact-position amino acid identity from translated DNA."""
+    expected = "".join(input_protein.upper().split())
+    observed = translate_dna(dna_sequence)
+    if observed.endswith("*") and not expected.endswith("*"):
+        observed = observed[:-1]
+    if not expected:
+        return 0.0
+    matches = sum(1 for exp, obs in zip(expected, observed) if exp == obs)
+    return matches / len(expected) if len(observed) == len(expected) else matches / len(expected)
+
+
+def count_internal_stops(dna_sequence: str) -> int:
+    """Count stop codons before the final codon."""
+    codons = _codons(dna_sequence)
+    return sum(1 for codon in codons[:-1] if codon in STOP_CODONS)
+
+
+def calculate_cai(sequence: str, codon_weights: dict[str, float]) -> float:
+    """Calculate CAI as a geometric mean of supplied codon weights."""
+    seq = _normalize_dna(sequence)
+    if not seq or len(seq) % 3 != 0:
+        return 0.0
+
+    log_sum = 0.0
+    count = 0
+    for codon in _codons(seq):
+        if codon in STOP_CODONS:
+            continue
+        weight = codon_weights.get(codon)
+        if weight is None or weight <= 0:
+            return 0.0
+        log_sum += math.log(weight)
+        count += 1
+    return math.exp(log_sum / count) if count else 0.0
+
+
+def codon_usage_profile(sequence: str) -> dict[str, dict[str, float | int | str]]:
+    """Return codon counts and frequencies for a DNA sequence."""
+    codons = _codons(sequence)
+    counts = Counter(codons)
+    total = sum(counts.values())
+    profile: dict[str, dict[str, float | int | str]] = {}
+    for codon in sorted(counts):
+        profile[codon] = {
+            "count": counts[codon],
+            "frequency": counts[codon] / total if total else 0.0,
+            "aa": STANDARD_GENETIC_CODE.get(codon, "X"),
+        }
+    return profile
+
+
+def detect_homopolymers(sequence: str, max_run: int = 6) -> list[dict[str, Any]]:
+    """Detect runs whose length is greater than or equal to max_run."""
+    if max_run <= 1:
+        raise ValueError("max_run must be > 1")
+
+    seq = _normalize_dna(sequence)
+    findings: list[dict[str, Any]] = []
+    if not seq:
+        return findings
+
+    run_base = seq[0]
+    run_start = 0
+    for index, base in enumerate(seq[1:], start=1):
+        if base == run_base:
+            continue
+        run_length = index - run_start
+        if run_length >= max_run:
+            findings.append(
+                {"start": run_start, "end": index, "base": run_base, "length": run_length}
+            )
+        run_base = base
+        run_start = index
+
+    run_length = len(seq) - run_start
+    if run_length >= max_run:
+        findings.append(
+            {"start": run_start, "end": len(seq), "base": run_base, "length": run_length}
+        )
+    return findings
+
+
+def detect_repeats(sequence: str) -> list[dict[str, Any]]:
+    """Detect simple tandem repeats with motif length 2-6 repeated at least 3 times."""
+    seq = _normalize_dna(sequence)
+    findings: list[dict[str, Any]] = []
+    occupied: set[tuple[int, int]] = set()
+
+    for motif_len in range(2, 7):
+        index = 0
+        while index <= len(seq) - motif_len * 3:
+            motif = seq[index : index + motif_len]
+            repeats = 1
+            cursor = index + motif_len
+            while seq[cursor : cursor + motif_len] == motif:
+                repeats += 1
+                cursor += motif_len
+            if repeats >= 3:
+                span = (index, cursor)
+                if span not in occupied:
+                    findings.append(
+                        {
+                            "start": index,
+                            "end": cursor,
+                            "motif": motif,
+                            "repeat_count": repeats,
+                        }
+                    )
+                    occupied.add(span)
+                index = cursor
+            else:
+                index += 1
+    return findings
+
+
+def detect_forbidden_motifs(sequence: str, motifs: list[str]) -> list[dict[str, Any]]:
+    """Find all exact forbidden motif occurrences."""
+    seq = _normalize_dna(sequence)
+    findings: list[dict[str, Any]] = []
+    for motif in motifs:
+        normalized = _normalize_dna(motif)
+        if not normalized:
+            continue
+        start = seq.find(normalized)
+        while start != -1:
+            findings.append({"start": start, "end": start + len(normalized), "motif": normalized})
+            start = seq.find(normalized, start + 1)
+    return findings
+
+
+def detect_invalid_codons(sequence: str) -> list[dict[str, Any]]:
+    """Detect invalid, partial, or non-ATGC codons."""
+    seq = _normalize_dna(sequence)
+    findings: list[dict[str, Any]] = []
+    for index, codon in enumerate(_codons(seq, include_partial=True)):
+        start = index * 3
+        if len(codon) != 3:
+            findings.append({"start": start, "end": len(seq), "codon": codon, "reason": "partial"})
+        elif set(codon) - VALID_BASES:
+            findings.append({"start": start, "end": start + 3, "codon": codon, "reason": "invalid_base"})
+        elif codon not in STANDARD_GENETIC_CODE:
+            findings.append({"start": start, "end": start + 3, "codon": codon, "reason": "unknown"})
+    return findings
+

factorforge/utils/__init__.py

@@ -0,0 +1,31 @@
+"""Utility helpers for FactorForge."""
+
+from .exceptions import (
+    FactorForgeError,
+    CodonTableError,
+    EmptyCandidateError,
+    FileFormatError,
+    OptimizationError,
+    SequenceValidationError,
+)
+from .sequence_validator import (
+    detect_sequence_type,
+    validate_cds_output,
+    validate_and_normalize,
+    validate_dna_sequence,
+    validate_protein_sequence,
+)
+
+__all__ = [
+    "FactorForgeError",
+    "SequenceValidationError",
+    "OptimizationError",
+    "EmptyCandidateError",
+    "FileFormatError",
+    "CodonTableError",
+    "detect_sequence_type",
+    "validate_cds_output",
+    "validate_and_normalize",
+    "validate_dna_sequence",
+    "validate_protein_sequence",
+]

factorforge/utils/construct_id.py

@@ -0,0 +1,8 @@
+"""construct_id 생성 유틸리티."""
+from datetime import datetime
+
+
+def generate_construct_id() -> str:
+    """CF-YYYYMMDD-HHMMSS 형식의 고유 construct ID 생성."""
+    now = datetime.now()
+    return f"CF-{now.strftime('%Y%m%d-%H%M%S')}"

factorforge/utils/exceptions.py

@@ -0,0 +1,32 @@
+"""Custom exceptions for FactorForge."""
+
+
+class FactorForgeError(Exception):
+    """Base exception for FactorForge."""
+
+
+class SequenceValidationError(FactorForgeError):
+    """Raised when sequence validation fails."""
+
+
+class OptimizationError(FactorForgeError):
+    """Raised when optimization fails."""
+
+
+class EmptyCandidateError(OptimizationError):
+    """Raised when no valid codon candidates are generated."""
+
+    def __init__(self, amino_acid: str, reason: str = "") -> None:
+        self.amino_acid = amino_acid
+        message = f"No valid codon candidates for amino acid '{amino_acid}'"
+        if reason:
+            message = f"{message}: {reason}"
+        super().__init__(message)
+
+
+class FileFormatError(FactorForgeError):
+    """Raised when file format is invalid."""
+
+
+class CodonTableError(FactorForgeError):
+    """Raised when codon table is invalid or missing."""

factorforge/utils/sequence_validator.py

@@ -0,0 +1,189 @@
+"""Sequence validation and type detection utilities."""
+
+from typing import Literal, Tuple
+
+from factorforge.ml.metrics import detect_invalid_codons, translate_dna
+
+from .exceptions import SequenceValidationError
+
+DNA_CHARS = set("ATGCN")
+AMBIGUOUS_DNA_CHARS = set("ATGCM")
+PROTEIN_ONLY_CHARS = set("DEFHIKLPQRSVWY")
+VALID_CHARS = set("ACDEFGHIKLMNPQRSTVWY*")
+MIN_DNA_LEN = 6
+
+
+def _clean_sequence(seq: str) -> str:
+    return "".join(seq.upper().split())
+
+
+def detect_sequence_type(seq: str) -> Literal["dna", "protein", "ambiguous"]:
+    """
+    Detect if input sequence is DNA or protein.
+
+    Args:
+        seq: Input sequence string
+
+    Returns:
+        "dna": Valid DNA (only ATGCN)
+        "protein": Valid protein (contains non-DNA amino acids)
+        "ambiguous": Could be either (only contains A/T/G/C/M)
+
+    Examples:
+        >>> detect_sequence_type("ATGGCC")
+        'dna'
+        >>> detect_sequence_type("MKKGEL")
+        'protein'
+        >>> detect_sequence_type("MA")
+        'ambiguous'
+    """
+    seq_upper = _clean_sequence(seq)
+    if not seq_upper:
+        return "ambiguous"
+
+    seq_chars = set(seq_upper)
+
+    # Protein-only letters present.
+    if seq_chars & PROTEIN_ONLY_CHARS:
+        return "protein"
+
+    # DNA-only letters present.
+    if seq_chars <= DNA_CHARS:
+        if len(seq_upper) >= MIN_DNA_LEN and len(seq_upper) % 3 == 0:
+            return "dna"
+        return "ambiguous"
+
+    # Ambiguous DNA (IUPAC M code).
+    if seq_chars <= AMBIGUOUS_DNA_CHARS:
+        return "ambiguous"
+
+    # Default to protein for other amino-acid characters.
+    return "protein"
+
+
+def validate_and_normalize(
+    seq: str,
+    expected_type: Literal["dna", "protein", "auto"] = "auto",
+) -> Tuple[str, Literal["dna", "protein"]]:
+    """
+    Validate and normalize sequence with type detection.
+
+    Args:
+        seq: Input sequence
+        expected_type: Expected type or "auto" for auto-detection
+
+    Returns:
+        (normalized_sequence, detected_type)
+
+    Raises:
+        SequenceValidationError: If sequence is invalid or type mismatch
+
+    Examples:
+        >>> validate_and_normalize("atggcc", "auto")
+        ('ATGGCC', 'dna')
+        >>> validate_and_normalize("MKKGEL", "protein")
+        ('MKKGEL', 'protein')
+    """
+    seq_clean = _clean_sequence(seq)
+
+    if not seq_clean:
+        raise SequenceValidationError("Empty sequence provided")
+
+    invalid_chars = set(seq_clean) - VALID_CHARS
+    if invalid_chars:
+        raise SequenceValidationError(
+            f"Invalid characters in sequence: {', '.join(sorted(invalid_chars))}"
+        )
+
+    detected = detect_sequence_type(seq_clean)
+
+    if expected_type == "auto":
+        if detected == "ambiguous":
+            if len(seq_clean) >= MIN_DNA_LEN and len(seq_clean) % 3 == 0:
+                return seq_clean, "dna"
+            return seq_clean, "protein"
+        return seq_clean, detected
+
+    if expected_type != detected and detected != "ambiguous":
+        raise SequenceValidationError(
+            f"Expected {expected_type} sequence but detected {detected}. "
+            f"Sequence: {seq_clean[:20]}{'...' if len(seq_clean) > 20 else ''}"
+        )
+
+    return seq_clean, expected_type
+
+
+def validate_dna_sequence(seq: str) -> str:
+    """
+    Validate DNA sequence.
+
+    Args:
+        seq: DNA sequence
+
+    Returns:
+        Normalized DNA sequence
+
+    Raises:
+        SequenceValidationError: If not valid DNA
+    """
+    seq_clean = _clean_sequence(seq)
+    invalid = set(seq_clean) - DNA_CHARS
+    if invalid:
+        raise SequenceValidationError(f"Invalid DNA characters: {', '.join(sorted(invalid))}")
+
+    return seq_clean
+
+
+def validate_protein_sequence(seq: str) -> str:
+    """
+    Validate protein sequence.
+
+    Args:
+        seq: Protein sequence
+
+    Returns:
+        Normalized protein sequence
+
+    Raises:
+        SequenceValidationError: If not valid protein
+    """
+    seq_clean = _clean_sequence(seq)
+    aa_chars = set("ACDEFGHIKLMNPQRSTVWY*")
+    invalid = set(seq_clean) - aa_chars
+    if invalid:
+        raise SequenceValidationError(
+            f"Invalid amino acid characters: {', '.join(sorted(invalid))}"
+        )
+
+    return seq_clean
+
+
+def validate_cds_output(input_protein: str, dna_sequence: str) -> dict[str, object]:
+    """Strictly validate generated CDS output against the input protein.
+
+    This validator is intentionally narrow: it returns only hard-fail errors
+    for generated CDS outputs that should not be recommended.
+    """
+    expected = _clean_sequence(input_protein).rstrip("*")
+    seq = _clean_sequence(dna_sequence).replace("U", "T")
+    errors: list[str] = []
+
+    if len(seq) % 3 != 0:
+        errors.append("length_not_divisible_by_3")
+
+    invalid = detect_invalid_codons(seq)
+    if invalid:
+        errors.append(f"invalid_codons: {invalid[:3]}")
+
+    translated = translate_dna(seq)
+    if "*" in translated[:-1]:
+        errors.append("internal_stop_codon")
+
+    observed = translated.rstrip("*")
+    if expected != observed:
+        errors.append(f"aa_mismatch: expected_len={len(expected)} observed_len={len(observed)}")
+
+    return {
+        "passed": not errors,
+        "errors": errors,
+    }

factorforge/utils/validation.py

@@ -0,0 +1,104 @@
+"""Structured candidate DNA validation for v3-alpha."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from factorforge.ml.metrics import (
+    amino_acid_identity,
+    calculate_first_region_gc,
+    calculate_gc,
+    calculate_gc_windows,
+    count_internal_stops,
+    detect_forbidden_motifs,
+    detect_homopolymers,
+    detect_invalid_codons,
+    detect_repeats,
+)
+
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    "gc_window_low": 30.0,
+    "gc_window_high": 70.0,
+    "gc_window_size": 60,
+    "gc_window_step": 30,
+    "forbidden_motifs": [],
+    "fail_forbidden_motifs": False,
+    "homopolymer_max_run": 6,
+}
+
+
+def validate_candidate_sequence(
+    input_protein: str,
+    dna_sequence: str,
+    config: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Validate a candidate CDS and return a machine-readable result."""
+    cfg = {**DEFAULT_CONFIG, **(config or {})}
+    seq = "".join(dna_sequence.upper().replace("U", "T").split())
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if not seq:
+        errors.append("empty sequence")
+    if len(seq) % 3 != 0:
+        errors.append("sequence length is not divisible by 3")
+
+    invalid_codons = detect_invalid_codons(seq)
+    internal_stop_count = count_internal_stops(seq)
+    identity = amino_acid_identity(input_protein, seq) if seq else 0.0
+    gc = calculate_gc(seq)
+    windows = calculate_gc_windows(
+        seq,
+        window_size=int(cfg["gc_window_size"]),
+        step=int(cfg["gc_window_step"]),
+    )
+    window_values = [float(window["gc"]) for window in windows]
+    gc_window_min = min(window_values) if window_values else 0.0
+    gc_window_max = max(window_values) if window_values else 0.0
+    low = float(cfg["gc_window_low"])
+    high = float(cfg["gc_window_high"])
+    gc_window_outlier_count = sum(1 for value in window_values if value < low or value > high)
+
+    first_region = calculate_first_region_gc(seq)
+    forbidden = detect_forbidden_motifs(seq, list(cfg.get("forbidden_motifs", [])))
+    homopolymers = detect_homopolymers(seq, max_run=int(cfg["homopolymer_max_run"]))
+    repeats = detect_repeats(seq)
+
+    if identity < 1.0:
+        errors.append("amino acid identity is below 1.0")
+    if invalid_codons:
+        errors.append("invalid codons detected")
+    if internal_stop_count:
+        errors.append("internal stop codons detected")
+    if forbidden and bool(cfg.get("fail_forbidden_motifs")):
+        errors.append("forbidden motifs detected")
+
+    if gc_window_outlier_count:
+        warnings.append("local GC window outliers detected")
+    if forbidden and not bool(cfg.get("fail_forbidden_motifs")):
+        warnings.append("forbidden motifs detected")
+    if homopolymers:
+        warnings.append("homopolymers detected")
+    if repeats:
+        warnings.append("simple repeats detected")
+
+    return {
+        "passed": not errors,
+        "amino_acid_identity": identity,
+        "gc": gc,
+        "gc_window_min": gc_window_min,
+        "gc_window_max": gc_window_max,
+        "gc_window_outlier_count": gc_window_outlier_count,
+        "first_30nt_gc": first_region["first_30nt_gc"],
+        "first_60nt_gc": first_region["first_60nt_gc"],
+        "first_90nt_gc": first_region["first_90nt_gc"],
+        "internal_stop_count": internal_stop_count,
+        "invalid_codon_count": len(invalid_codons),
+        "forbidden_motif_count": len(forbidden),
+        "homopolymer_count": len(homopolymers),
+        "repeat_count": len(repeats),
+        "warnings": warnings,
+        "errors": errors,
+    }
+