pytransdecoder 0.2.1__py3-none-any.whl

pytransdecoder/core/models.py

@@ -0,0 +1,123 @@
+"""
+Data models for PyTransDecoder
+
+Minimal ORF representation - replaces the 5,588-line Gene_obj.pm
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Tuple, List
+
+
+@dataclass
+class ORF:
+    """
+    Open Reading Frame representation.
+    
+    This replaces Gene_obj.pm with only the essential functionality
+    that TransDecoder actually uses.
+    """
+    # Identifiers
+    transcript_id: str      # asmbl_id in Gene_obj
+    gene_id: str           # TU_feat_name
+    model_id: str          # Model_feat_name
+    
+    # Coordinates (1-based, as in original TransDecoder)
+    start: int
+    end: int
+    strand: str            # '+' or '-'
+    
+    # Sequences
+    sequence: str          # CDS nucleotide sequence
+    protein: str           # Translated protein
+    
+    # Metadata
+    orf_type: str         # complete, 5prime_partial, 3prime_partial, internal
+    length: int           # Length in nucleotides
+    frame: int = 0        # Reading frame (0, 1, 2)
+    phase: int = 0        # CDS phase for GFF3 output
+    description: str = "" # com_name in Gene_obj
+    
+    # For selection/ranking (populated in Predict phase)
+    markov_scores: Optional[List[float]] = None
+    blast_hits: List[str] = field(default_factory=list)
+    pfam_hits: List[str] = field(default_factory=list)
+    
+    def __post_init__(self):
+        """Set defaults after initialization"""
+        if not self.description:
+            orient = '+' if self.strand == '+' else '-'
+            self.description = f"ORF type:{self.orf_type} ({orient})"
+    
+    def get_cds_length(self) -> int:
+        """Get CDS length in nucleotides (replaces Gene_obj::get_CDS_length)"""
+        return self.length
+    
+    def get_model_span(self) -> Tuple[int, int]:
+        """Get (min, max) coordinates (replaces Gene_obj::get_model_span)"""
+        return (min(self.start, self.end), max(self.start, self.end))
+    
+    def to_gff3(self, source: str = "transdecoder") -> str:
+        """
+        Generate GFF3 representation (replaces Gene_obj::to_GFF3_format).
+        
+        Returns multi-line string with gene, mRNA, and CDS features.
+        """
+        lend, rend = self.get_model_span()
+        
+        # Attributes for each feature type
+        gene_attrs = f"ID={self.gene_id};Name=ORF_{self.gene_id}"
+        mrna_attrs = f"ID={self.model_id};Parent={self.gene_id};Name={self.model_id}"
+        cds_attrs = f"ID=cds.{self.model_id};Parent={self.model_id}"
+        
+        lines = []
+        
+        # Gene feature
+        lines.append("\t".join([
+            self.transcript_id,
+            source,
+            "gene",
+            str(lend),
+            str(rend),
+            ".",
+            self.strand,
+            ".",
+            gene_attrs
+        ]))
+        
+        # mRNA feature
+        lines.append("\t".join([
+            self.transcript_id,
+            source,
+            "mRNA",
+            str(lend),
+            str(rend),
+            ".",
+            self.strand,
+            ".",
+            mrna_attrs
+        ]))
+        
+        # CDS feature (with phase)
+        lines.append("\t".join([
+            self.transcript_id,
+            source,
+            "CDS",
+            str(lend),
+            str(rend),
+            ".",
+            self.strand,
+            str(self.phase),
+            cds_attrs
+        ]))
+        
+        return "\n".join(lines)
+    
+    def to_fasta_cds(self) -> str:
+        """Generate FASTA format for CDS sequence"""
+        header = f">{self.model_id} type:{self.orf_type} {self.transcript_id}:{self.start}-{self.end}({self.strand})"
+        return f"{header}\n{self.sequence}"
+    
+    def to_fasta_protein(self, genetic_code: str = "universal") -> str:
+        """Generate FASTA format for protein sequence"""
+        header = f">{self.model_id} type:{self.orf_type} gc:{genetic_code} {self.transcript_id}:{self.start}-{self.end}({self.strand})"
+        return f"{header}\n{self.protein}"

pytransdecoder/core/orf_finder.py

@@ -0,0 +1,317 @@
+"""
+ORF (Open Reading Frame) finder
+
+Replicates the core algorithm from Longest_orf.pm
+"""
+
+from typing import List, Dict, Tuple
+from .models import ORF
+from .translator import Translator
+from .sequence import reverse_complement
+
+
+class ORFFinder:
+    """
+    Find all Open Reading Frames in nucleotide sequences.
+    
+    Replicates the functionality of Longest_orf.pm
+    """
+    
+    def __init__(
+        self,
+        min_protein_length: int = 100,
+        allow_5prime_partial: bool = True,
+        allow_3prime_partial: bool = True,
+        allow_non_met_starts: bool = False,
+        forward_strand: bool = True,
+        reverse_strand: bool = True,
+        genetic_code: str = "universal",
+        complete_orfs_only: bool = False
+    ):
+        """
+        Initialize ORF finder.
+        
+        Args:
+            min_protein_length: Minimum protein length in amino acids
+            allow_5prime_partial: Allow ORFs without start codon
+            allow_3prime_partial: Allow ORFs without stop codon
+            allow_non_met_starts: Allow non-Met start codons
+            forward_strand: Analyze forward strand
+            reverse_strand: Analyze reverse strand
+            genetic_code: Genetic code name
+            complete_orfs_only: Only return complete ORFs (has start and stop)
+        """
+        self.min_protein_length = min_protein_length
+        self.min_nt_length = min_protein_length * 3
+        self.allow_5prime_partial = allow_5prime_partial
+        self.allow_3prime_partial = allow_3prime_partial
+        self.allow_non_met_starts = allow_non_met_starts
+        self.forward_strand = forward_strand
+        self.reverse_strand = reverse_strand
+        self.genetic_code = genetic_code
+        self.complete_orfs_only = complete_orfs_only
+        
+        self.translator = Translator(genetic_code)
+        self.stop_codons = set(self.translator.get_stop_codons())
+        self.start_codons = set(self.translator.get_start_codons(allow_non_met_starts))
+    
+    def find_all_orfs(self, sequence: str, seq_id: str) -> List[ORF]:
+        """
+        Find all ORFs in a sequence.
+        
+        Args:
+            sequence: Nucleotide sequence
+            seq_id: Sequence identifier
+        
+        Returns:
+            List of ORF objects, sorted by length (longest first)
+        """
+        orfs = []
+        original_length = len(sequence)
+        
+        # Forward strand
+        if self.forward_strand:
+            orfs.extend(self._find_orfs_strand(sequence, seq_id, '+', original_length))
+        
+        # Reverse strand
+        if self.reverse_strand:
+            rev_seq = reverse_complement(sequence)
+            orfs.extend(self._find_orfs_strand(rev_seq, seq_id, '-', original_length))
+        
+        # Longest first, as LongOrfs orders them (and hence numbers them .p1, .p2, ...).
+        # Perl generates ORFs per strand (+ then -) in order of start position and then
+        # applies two stable 'reverse sort's by length, so ties keep generation order.
+        strand_rank = {'+': 0, '-': 1}
+        orfs.sort(key=lambda x: (-x._perl_sort_len, strand_rank[x.strand], x._strand_start))
+        
+        return orfs
+    
+    def _find_orfs_strand(self, sequence: str, seq_id: str, strand: str, original_length: int) -> List[ORF]:
+        """Find all ORFs on one strand"""
+        sequence = sequence.upper()
+        orfs = []
+        
+        # Find stops and starts for each frame
+        for frame in range(3):
+            # Find all stop codons in this frame
+            stops, real_stops = self._find_stops_in_frame(sequence, frame)
+            
+            # Find all start codons in this frame (passing real_stops to avoid starts at stop positions)
+            starts = self._find_starts_in_frame(sequence, frame, real_stops)
+            
+            # Build ORFs from start-stop pairs
+            orfs.extend(
+                self._build_orfs_from_coords(
+                    starts, stops, real_stops, sequence, seq_id, strand, frame, original_length
+                )
+            )
+        
+        return orfs
+    
+    def _find_stops_in_frame(self, sequence: str, frame: int) -> Tuple[List[int], set]:
+        """
+        Find all stop codon positions in a specific frame.
+        
+        Returns:
+            Tuple of (all_stops, real_stop_set) where:
+                - all_stops: List of all stop positions (real + implicit)
+                - real_stop_set: Set of positions that are actual stop codons
+        """
+        stops = []
+        real_stops = set()
+        
+        for i in range(frame, len(sequence) - 2, 3):
+            codon = sequence[i:i+3]
+            if codon in self.stop_codons:
+                stops.append(i)
+                real_stops.add(i)
+        
+        # Add implicit stops at end for 3' partials (NOT real stop codons)
+        # Perl adds seq_length, seq_length-1, seq_length-2 as implicit stops
+        if self.allow_3prime_partial:
+            seq_len = len(sequence)
+            for offset in [0, -1, -2]:
+                pos = seq_len + offset
+                if pos >= 0 and pos not in real_stops:
+                    stops.append(pos)
+        
+        return stops, real_stops
+    
+    def _find_starts_in_frame(self, sequence: str, frame: int, real_stops: set) -> List[int]:
+        """
+        Find all start codon positions in a specific frame.
+        
+        Args:
+            sequence: DNA/RNA sequence
+            frame: Reading frame (0, 1, or 2)
+            real_stops: Set of positions that are actual stop codons (to avoid adding stops as starts)
+            
+        Returns:
+            List of start positions
+        """
+        starts = []
+        
+        # Add implicit start at beginning for 5' partials
+        # But don't add it if it's already a stop codon (Perl's logic)
+        if self.allow_5prime_partial and frame not in real_stops:
+            starts.append(frame)
+        
+        # Find explicit start codons
+        for i in range(frame, len(sequence) - 2, 3):
+            codon = sequence[i:i+3]
+            if codon in self.start_codons:
+                starts.append(i)
+        
+        return starts
+    
+    def _build_orfs_from_coords(
+        self,
+        starts: List[int],
+        stops: List[int],
+        real_stops: set,
+        sequence: str,
+        seq_id: str,
+        strand: str,
+        frame: int,
+        original_length: int
+    ) -> List[ORF]:
+        """
+        Build ORF objects from start and stop coordinate lists.
+        
+        Important: Replicates Perl's algorithm where:
+        - Each stop codon is used only once
+        - Each start codon is paired with only its first valid stop
+        This prevents generating overlapping ORFs.
+        
+        Args:
+            real_stops: Set of positions that are actual stop codons
+                       (vs implicit end-of-sequence stops)
+        """
+        orfs = []
+        last_used_stop = -1  # Track the last stop position used in this frame
+        
+        # Iterate through starts in order
+        for start_pos in starts:
+            # Skip starts that come before or at the last used stop
+            # This prevents reusing the same stop codon
+            if start_pos <= last_used_stop:
+                continue
+            
+            # Find the first valid stop after this start (Perl's algorithm)
+            valid_stop = None
+            for stop_pos in stops:
+                if (stop_pos > start_pos and 
+                    (stop_pos - start_pos) % 3 == 0):
+                    valid_stop = stop_pos
+                    break  # Take first valid stop (replicates Perl's 'last')
+            
+            if valid_stop is None:
+                continue
+            
+            # Mark this stop as used
+            last_used_stop = valid_stop
+            
+            # Check if this is a real stop codon or implicit end-of-sequence
+            is_real_stop = valid_stop in real_stops
+            
+            # Extract ORF sequence
+            # For real stops: include the 3 bases of the stop codon
+            # For implicit stops (3' partial): extract up to end of sequence
+            if is_real_stop:
+                # Real stop codon - include it (valid_stop points to start of stop codon)
+                orf_end = valid_stop + 3
+            else:
+                # Implicit stop (3' partial) - extract to end of sequence
+                orf_end = len(sequence)
+            
+            orf_seq = sequence[start_pos:orf_end]
+            
+            # Ensure CDS length is a multiple of 3 (trim partial codons)
+            remainder = len(orf_seq) % 3
+            if remainder != 0:
+                orf_seq = orf_seq[:-remainder]
+                orf_end = start_pos + len(orf_seq)
+            
+            # Length check. As in TransDecoder.LongOrfs, length is counted in codons up to
+            # and including the stop; for 3' partials the implicit stop just past the
+            # sequence end counts as that final codon, so both complete and 3'-partial
+            # ORFs must encode at least (min_protein_length - 1) amino acids.
+            min_len = self.min_nt_length if is_real_stop else self.min_nt_length - 3
+            if len(orf_seq) < min_len:
+                continue
+            
+            # Translate
+            protein = self.translator.translate(orf_seq)
+            
+            # Verify no internal stops (sanity check from Perl code)
+            stop_count = protein.count('*')
+            if stop_count > 1:
+                # Should not happen if algorithm is correct
+                continue
+            
+            # Determine ORF type
+            has_start = sequence[start_pos:start_pos+3] in self.start_codons
+            has_stop = is_real_stop  # Only real stop codons count
+            
+            is_5prime_partial = not has_start
+            is_3prime_partial = not has_stop
+            
+            # Determine ORF type string
+            if not is_5prime_partial and not is_3prime_partial:
+                orf_type = "complete"
+            elif not is_5prime_partial:
+                orf_type = "3prime_partial"
+            elif not is_3prime_partial:
+                orf_type = "5prime_partial"
+            else:
+                orf_type = "internal"
+            
+            # Skip if complete_orfs_only and not complete
+            if self.complete_orfs_only and orf_type != "complete":
+                continue
+            
+            # Calculate coordinates
+            # For reverse strand, transform back to original sequence coordinates
+            # Perl uses: revcomp_coord($pos, $seq_length) = $seq_length - $pos + 1
+            # Perl: start_pos_adj = start_pos + 1, stop_pos_adj = stop_pos + 1 + 2
+            # Perl ALWAYS adds +3 to stop position, even for implicit stops
+            # This affects both coordinate reporting and length calculations
+            if strand == '-':
+                # Transform coordinates back to original sequence. For 3' partial
+                # ORFs, use the trimmed sequence end rather than the implicit stop
+                # position so the reported span matches the extracted CDS.
+                start_adj = start_pos + 1  # 1-based position of start
+                end_adj = orf_end
+
+                # Transform to original sequence coordinates
+                orf_start = original_length - start_adj + 1
+                orf_end_coord = original_length - end_adj + 1
+            else:
+                # Forward strand: convert to 1-based. For 3' partial ORFs, use the
+                # trimmed CDS endpoint rather than valid_stop + 3.
+                orf_start = start_pos + 1  # 1-based position of start
+                orf_end_coord = orf_end
+            
+            # Create ORF object
+            orf = ORF(
+                transcript_id=seq_id,
+                gene_id="",  # Will be set later
+                model_id="",  # Will be set later
+                start=orf_start,
+                end=orf_end_coord,
+                strand=strand,
+                sequence=orf_seq,
+                protein=protein,
+                orf_type=orf_type,
+                length=len(orf_seq),
+                frame=frame
+            )
+            # Ordering used by LongOrfs (see find_all_orfs): Perl sorts on the untrimmed
+            # length (through the end of the sequence for 3' partials) and generates
+            # ORFs in order of start position within a strand, across frames.
+            orf._perl_sort_len = (orf_end if is_real_stop else len(sequence)) - start_pos
+            orf._strand_start = start_pos
+
+            orfs.append(orf)
+        
+        return orfs

pytransdecoder/core/presets.py

@@ -0,0 +1,152 @@
+"""
+Presets: models and ORF acceptance thresholds learned from a large reference transcriptome, for inputs
+too small (or too partial) to learn from (TransDecoderPaper evidence E21).
+
+A preset directory holds
+  preset.json            name, source, genetic code, GC %, long-ORF auto-accept length (nt or null),
+                         decoy strata, q levels
+  hexamer.scores.gz      the reference run's Markov coding model
+  training_orfs.cds.gz   the reference run's training ORFs (fix the median per-base coding contrast
+                         used by start refinement)
+  kozak.tsv              the reference run's start-context model (optional)
+  thresholds.tsv.gz      per decoy stratum and q level, the smallest frame contrast accepted in the
+                         reference run's target-decoy q-values (decoy_qvalues.tsv)
+(uncompressed files are read too). Bundled presets live in pytransdecoder/presets/<name>; the same
+files ship with TransDecoder (Perl) in PerlLib/presets.
+With a preset, Predict scores the input with the preset model and keeps a candidate ORF (in-frame score
+> 0, frame contrast > 0) when its contrast reaches the preset threshold of its stratum at the chosen q.
+"""
+import gzip
+import json
+import shutil
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+Q_LEVELS = (0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.3, 0.5)
+BUNDLED_DIR = Path(__file__).resolve().parent.parent / "presets"
+
+
+def bundled_presets() -> List[str]:
+    if not BUNDLED_DIR.is_dir():
+        return []
+    return sorted(d.name for d in BUNDLED_DIR.iterdir() if (d / "preset.json").exists())
+
+
+def resolve(name_or_dir: str) -> Path:
+    """A bundled preset name or a preset directory."""
+    p = Path(name_or_dir)
+    if (p / "preset.json").exists():
+        return p
+    if (BUNDLED_DIR / name_or_dir / "preset.json").exists():
+        return BUNDLED_DIR / name_or_dir
+    raise FileNotFoundError(f"no preset '{name_or_dir}': not a preset directory or a bundled preset "
+                            f"({', '.join(bundled_presets()) or 'none installed'})")
+
+
+def _find(path: Path, name: str) -> Optional[Path]:
+    for f in (path / (name + ".gz"), path / name):
+        if f.exists():
+            return f
+    return None
+
+
+def _open(path: Path):
+    return gzip.open(path, "rt") if path.suffix == ".gz" else open(path)
+
+
+def copy_plain(src: Path, dest: Path) -> None:
+    """Copy a preset file, decompressing .gz."""
+    with _open(src) as fin, open(dest, "w") as fout:
+        shutil.copyfileobj(fin, fout)
+
+
+def _gzip_copy(src: Path, dest: Path) -> None:
+    # mtime 0: identical bytes for identical content (reproducible bundled files)
+    with open(src, "rb") as fin, open(dest, "wb") as raw, gzip.GzipFile(fileobj=raw, mode="wb", mtime=0) as fout:
+        shutil.copyfileobj(fin, fout)
+
+
+def build_preset(run_workdir: Path, out_dir: Path, name: str, gc_pct: float,
+                 auto_accept_nt: Optional[float], genetic_code: str, strata: str, source: str = "") -> Path:
+    """Write a preset from a finished decoy-rule Predict run (its <input>.transdecoder_dir)."""
+    run_workdir, out_dir = Path(run_workdir), Path(out_dir)
+    qfile = run_workdir / "decoy_qvalues.tsv"
+    if not qfile.exists():
+        raise FileNotFoundError(f"{qfile} not found: build presets from a finished Predict run")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    _gzip_copy(run_workdir / "hexamer.scores", out_dir / "hexamer.scores.gz")
+    _gzip_copy(run_workdir / "__checkpoints_TDpredict" / "top_training_orfs.cds", out_dir / "training_orfs.cds.gz")
+    kozak = run_workdir / "start_refinement.kozak.tsv"
+    if kozak.exists():
+        shutil.copy(kozak, out_dir / "kozak.tsv")
+    by_stratum = defaultdict(list)
+    with open(qfile) as fh:
+        for line in fh:
+            if line.startswith("#"):
+                continue
+            _, stratum, contrast, q = line.rstrip("\n").split("\t")
+            by_stratum[stratum].append((float(q), float(contrast)))
+    lines = ["#stratum\tq\tmin_contrast\tn_targets\n"]
+    for stratum in sorted(by_stratum, key=lambda s: tuple(_key(s))):
+        rows = by_stratum[stratum]
+        for level in Q_LEVELS:
+            ok = [c for q, c in rows if q <= level]
+            lines.append(f"{stratum}\t{level:g}\t{min(ok) if ok else 'inf'}\t{len(rows)}\n")
+    with gzip.GzipFile(out_dir / "thresholds.tsv.gz", "wb", mtime=0) as fh:
+        fh.write("".join(lines).encode())
+    meta = {"name": name, "source": source, "genetic_code": genetic_code, "gc_pct": round(gc_pct, 2),
+            "auto_accept_nt": None if auto_accept_nt in (None, float("inf")) else auto_accept_nt,
+            "strata": strata, "q_levels": list(Q_LEVELS)}
+    (out_dir / "preset.json").write_text(json.dumps(meta, indent=1) + "\n")
+    return out_dir
+
+
+def _key(stratum: str) -> Tuple:
+    out = []
+    for x in stratum.split(","):
+        out.append(x == "True" if x in ("True", "False") else int(x))
+    return tuple(out)
+
+
+class Preset:
+    def __init__(self, path):
+        self.path = Path(path)
+        self.meta = json.loads((self.path / "preset.json").read_text())
+        self.hexamer_scores = _find(self.path, "hexamer.scores")
+        self.training_orfs = _find(self.path, "training_orfs.cds")
+        self.kozak = self.path / "kozak.tsv" if (self.path / "kozak.tsv").exists() else None
+        self.strata = self.meta["strata"]
+        self._thr: Dict[float, Dict[Tuple, float]] = defaultdict(dict)
+        with _open(_find(self.path, "thresholds.tsv")) as fh:
+            for line in fh:
+                if line.startswith("#"):
+                    continue
+                stratum, q, c, _ = line.rstrip("\n").split("\t")
+                self._thr[float(q)][_key(stratum)] = float(c)
+
+    @property
+    def auto_accept_nt(self) -> float:
+        a = self.meta.get("auto_accept_nt")
+        return float("inf") if a is None else float(a)
+
+    def level(self, q: float) -> float:
+        """Largest stored q level <= q (the smallest level if q is below all of them)."""
+        levels = sorted(self._thr)
+        ok = [x for x in levels if x <= q + 1e-12]
+        return ok[-1] if ok else levels[0]
+
+    def threshold(self, stratum: Tuple, q: float) -> float:
+        """Minimum frame contrast at q for a stratum; strata absent from the reference use the nearest
+        ORF-length bin with the same remaining keys, then any transcript-length bin of the same type."""
+        table = self._thr[self.level(q)]
+        if stratum in table:
+            return table[stratum]
+        rest = stratum[1:]
+        same = [k for k in table if k[1:] == rest]
+        if not same and len(stratum) == 3:
+            same = [k for k in table if k[2] == stratum[2]]
+        if not same:
+            same = list(table)
+        best = min(same, key=lambda k: (abs(k[0] - stratum[0]), abs(k[1] - stratum[1]) if len(k) > 1 else 0))
+        return table[best]

pytransdecoder/core/prng.py

@@ -0,0 +1,54 @@
+"""
+Portable pseudo-random numbers for decoy shuffles, identical in PyTransDecoder and TransDecoder (Perl).
+
+xoshiro128** (Blackman & Vigna 2018) on 32-bit words, seeded from FNV-1a hashes of a seed string.
+All arithmetic stays below 2^53, so the Perl implementation (PerlLib/Decoys.pm) gives the same stream.
+"""
+from typing import List
+
+M32 = 0xFFFFFFFF
+
+
+def fnv1a32(text: str) -> int:
+    h = 0x811C9DC5
+    for b in text.encode():
+        h = ((h ^ b) * 0x01000193) & M32
+    return h
+
+
+def _rotl(x: int, k: int) -> int:
+    return ((x << k) | (x >> (32 - k))) & M32
+
+
+class Xoshiro128ss:
+    def __init__(self, seed: str):
+        s = [fnv1a32(f"{seed}#{i}") for i in range(4)]
+        if not any(s):
+            s[0] = 1
+        self.s: List[int] = s
+
+    def next32(self) -> int:
+        s = self.s
+        result = (_rotl((s[1] * 5) & M32, 7) * 9) & M32
+        t = (s[1] << 9) & M32
+        s[2] ^= s[0]
+        s[3] ^= s[1]
+        s[1] ^= s[2]
+        s[0] ^= s[3]
+        s[2] ^= t
+        s[3] = _rotl(s[3], 11)
+        return result
+
+    def below(self, n: int) -> int:
+        """Uniform integer in [0, n) by rejection (n >= 1)."""
+        limit = (2 ** 32 // n) * n
+        while True:
+            r = self.next32()
+            if r < limit:
+                return r % n
+
+    def shuffle(self, items: list) -> None:
+        """Fisher-Yates, in place."""
+        for i in range(len(items) - 1, 0, -1):
+            j = self.below(i + 1)
+            items[i], items[j] = items[j], items[i]