pytransdecoder 0.2.1__py3-none-any.whl

pytransdecoder/core/__init__.py

@@ -0,0 +1 @@
+"""Core modules for PyTransDecoder"""

pytransdecoder/core/base_freqs.py

@@ -0,0 +1,71 @@
+"""
+Base frequency calculation
+
+Computes nucleotide frequencies for background model.
+Replaces compute_base_probs.pl
+"""
+
+from typing import Dict
+from .fasta import read_fasta
+
+
+def compute_base_counts(fasta_file: str, top_strand_only: bool = False) -> Dict[str, int]:
+    """
+    Count nucleotides in a FASTA file, as compute_base_probs.pl does.
+
+    Unless top_strand_only, each base also increments its complement so that
+    the counts reflect both strands (A=T, C=G).
+    """
+    complement = {'A': 'T', 'T': 'A', 'G': 'C', 'C': 'G'}
+    counts = {base: 0 for base in 'ACGT'}
+    for record in read_fasta(fasta_file):
+        for base in str(record.seq).upper():
+            if base in counts:
+                counts[base] += 1
+                if not top_strand_only:
+                    counts[complement[base]] += 1
+    return counts
+
+
+def compute_base_frequencies(fasta_file: str, top_strand_only: bool = False) -> Dict[str, float]:
+    """Nucleotide frequencies from a FASTA file (see compute_base_counts)."""
+    counts = compute_base_counts(fasta_file, top_strand_only)
+    total = sum(counts.values())
+    if total == 0:
+        return {base: 0.25 for base in 'ACGT'}
+    return {base: counts[base] / total for base in 'ACGT'}
+
+
+def write_base_frequencies(counts: Dict[str, int], output_file: str):
+    """
+    Write base_freqs.dat in TransDecoder's format: base, count, ratio (3 decimals).
+
+    The rounded ratio is what both implementations read back as the background
+    model, so it is written exactly as compute_base_probs.pl does.
+    """
+    total = sum(counts.values())
+    with open(output_file, 'w') as f:
+        for base in 'ACGT':
+            ratio = counts[base] / total if total else 0.25
+            f.write(f"{base}\t{counts[base]}\t{ratio:.3f}\n")
+
+
+def read_base_frequencies(input_file: str) -> Dict[str, float]:
+    """Read background base frequencies from base_freqs.dat (base, count, ratio)."""
+    frequencies = {}
+    with open(input_file) as f:
+        for line in f:
+            parts = line.split()
+            if len(parts) == 3:
+                frequencies[parts[0]] = float(parts[2])
+            elif len(parts) == 2:  # files written by PyTransDecoder <= 0.1.0
+                frequencies[parts[0]] = float(parts[1])
+    missing = set('ACGT') - set(frequencies)
+    if missing:
+        raise ValueError(f"{input_file}: missing base frequencies for {sorted(missing)}")
+    return frequencies
+
+
+def calculate_gc_content(frequencies: Dict[str, float]) -> float:
+    """Calculate GC content from base frequencies"""
+    return frequencies.get('G', 0) + frequencies.get('C', 0)

pytransdecoder/core/decoys.py

@@ -0,0 +1,113 @@
+"""
+Decoy ORFs from shuffled transcripts, for target-decoy FDR estimates of candidate ORFs (experimental).
+
+Each transcript is shuffled preserving its dinucleotide counts (Altschul & Erickson 1985; the random
+Eulerian path is drawn with Wilson's algorithm for the last-exit tree), so decoys keep the transcript's
+length and base composition. Random numbers come from core/prng.py, so the Perl implementation
+(PerlLib/Decoys.pm) produces the same decoys. Decoy ORFs are found with the same ORF finder, genetic code, minimum
+length and strand setting as LongOrfs and scored with the run's trained Markov model.
+
+Within strata of ORF length (log-spaced bins), transcript length (log2 bins) and ORF type (complete vs
+partial), a target ORF with frame contrast c has
+    FDR(c) = decoys with contrast >= c / (shuffles x targets with contrast >= c)
+and its q-value is the lowest FDR of any cutoff that accepts it. Strata without decoys give q = 0.
+"""
+import bisect
+import math
+from collections import defaultdict
+from typing import Dict, Hashable, Iterable, List, Tuple
+
+from pytransdecoder.core.prng import Xoshiro128ss
+
+LENGTH_BIN_RATIO = 1.1
+LENGTH_BIN_START = 50  # codons
+TX_BIN_START = 500  # nt
+STRATA = ("len", "len_tx", "len_tx_type")
+
+
+def dinucleotide_shuffle(seq: str, rng: Xoshiro128ss) -> str:
+    """Random sequence with the same first base, last base and dinucleotide counts as seq."""
+    n = len(seq)
+    if n < 3:
+        return seq
+    edges = defaultdict(list)
+    for a, b in zip(seq, seq[1:]):
+        edges[a].append(b)
+    end = seq[-1]
+    # random last-exit tree rooted at the final base (Wilson's loop-erased random walks)
+    in_tree, nxt, last = {end}, {}, {}
+    for v in sorted(edges):
+        u = v
+        while u not in in_tree:
+            nxt[u] = edges[u][rng.below(len(edges[u]))]
+            u = nxt[u]
+        u = v
+        while u not in in_tree:
+            in_tree.add(u)
+            last[u] = nxt[u]
+            u = nxt[u]
+    order = {}
+    for v in sorted(edges):
+        out = edges[v][:]
+        if v in last:
+            out.remove(last[v])
+        rng.shuffle(out)
+        if v in last:
+            out.append(last[v])
+        order[v] = out
+    pos = defaultdict(int)
+    res, u = [seq[0]], seq[0]
+    for _ in range(n - 1):
+        w = order[u][pos[u]]
+        pos[u] += 1
+        res.append(w)
+        u = w
+    return "".join(res)
+
+
+def _length_bin(codons: int) -> int:
+    """Largest k with codons >= LENGTH_BIN_START * LENGTH_BIN_RATIO**k (powers by repeated
+    multiplication, so the Perl port bins identically); -1 below LENGTH_BIN_START."""
+    if codons < LENGTH_BIN_START:
+        return -1
+    k, edge = 0, LENGTH_BIN_START * LENGTH_BIN_RATIO
+    while codons >= edge:
+        k += 1
+        edge *= LENGTH_BIN_RATIO
+    return k
+
+
+def stratum(codons: int, tx_len: int, complete: bool, strata: str = "len_tx_type") -> Tuple:
+    """Stratum key: ORF-length bin, then (len_tx) transcript-length bin (floor(log2(tx_len / 500)) + 1,
+    0 below 500 nt), then (len_tx_type) ORF type."""
+    k = (_length_bin(codons),)
+    if strata in ("len_tx", "len_tx_type"):
+        k += ((tx_len // TX_BIN_START).bit_length() if tx_len >= TX_BIN_START else 0,)
+    if strata == "len_tx_type":
+        k += (bool(complete),)
+    return k
+
+
+def qvalues(targets: Dict[str, Tuple[Hashable, float]], decoys: Iterable[Tuple[Hashable, float]],
+            n_shuffles: int) -> Dict[str, float]:
+    """q-value per target ORF id from (stratum, contrast) of targets and decoys (eligible ORFs only)."""
+    tby, dby = defaultdict(list), defaultdict(list)
+    for orf_id, (k, c) in targets.items():
+        tby[k].append(c)
+    for k, c in decoys:
+        dby[k].append(c)
+    q_of = {}
+    for k, tc in tby.items():
+        tc = sorted(tc)
+        dc = sorted(dby.get(k, ()))
+        q, run_min = [], math.inf
+        for i, c in enumerate(tc):
+            fdr = (len(dc) - bisect.bisect_left(dc, c)) / n_shuffles / (len(tc) - i)
+            run_min = min(run_min, fdr)
+            q.append(run_min)
+        q_of[k] = (tc, q)
+    out = {}
+    for orf_id, (k, c) in targets.items():
+        tc, q = q_of[k]
+        out[orf_id] = q[bisect.bisect_left(tc, c)]
+    return out

pytransdecoder/core/fasta.py

@@ -0,0 +1,55 @@
+"""
+FASTA reading shared by all PyTransDecoder steps.
+
+Text before the first '>' header line (e.g. ';' comment lines, as in FAIR Header Reference
+files) is skipped with a warning, as Perl TransDecoder's Fasta_reader does. Biopython's "fasta"
+parser rejects such files, and older Perl versions read the text as an extra sequence.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import IO, Iterator, Union
+
+from Bio.Seq import Seq
+from Bio.SeqRecord import SeqRecord
+
+logger = logging.getLogger(__name__)
+
+
+def read_fasta(source: Union[str, Path, IO[str]]) -> Iterator[SeqRecord]:
+    """Yield SeqRecords (id = first word of the header, description = whole header) from a
+    path or an open text handle. Whitespace inside sequences is removed."""
+    if isinstance(source, (str, Path)):
+        with open(source) as handle:
+            yield from _parse(handle, str(source))
+    else:
+        yield from _parse(source, getattr(source, "name", "FASTA input"))
+
+
+def _parse(handle: IO[str], label: str) -> Iterator[SeqRecord]:
+    header = None
+    chunks = []
+    skipped_text = False
+    for line in handle:
+        if line.startswith(">"):
+            if header is not None:
+                yield _record(header, chunks)
+            elif skipped_text:
+                logger.warning("%s: skipped text before the first '>' header line", label)
+            header, chunks = line[1:].rstrip("\r\n"), []
+        elif header is None:
+            skipped_text = skipped_text or bool(line.strip())
+        else:
+            chunks.append("".join(line.split()))
+    if header is None and skipped_text:
+        logger.warning("%s: no '>' header line found; no sequences read", label)
+    if header is not None:
+        yield _record(header, chunks)
+
+
+def _record(header: str, chunks) -> SeqRecord:
+    words = header.split()
+    seq_id = words[0] if words else ""
+    return SeqRecord(Seq("".join(chunks)), id=seq_id, name=seq_id, description=header)

pytransdecoder/core/gene_model.py

@@ -0,0 +1,143 @@
+"""
+Coding gene models (exons + a CDS range) and their GFF3 / BED representation.
+
+Used for TransDecoder's transcript-level outputs (one exon spanning the transcript) and for
+ORFs propagated to the genome through transcript structures. The GFF3 layout follows Perl
+TransDecoder's Gene_obj::to_GFF3_format: gene, then per isoform mRNA, five_prime_UTR, exon (+
+CDS) in transcription order, three_prime_UTR; a blank line after each gene.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Sequence, Tuple
+
+Segment = Tuple[int, int]
+
+
+@dataclass
+class CodingModel:
+    """One transcript isoform with a CDS. Coordinates are 1-based inclusive on `seqid`;
+    exons are (lend, rend) with lend <= rend; cds_lend/cds_rend bound the CDS (incl. stop)."""
+    seqid: str
+    strand: str
+    exons: List[Segment]
+    cds_lend: int
+    cds_rend: int
+    model_id: str
+    name: str = ""
+    extra_attrs: str = ""          # appended to the mRNA attributes (e.g. "score=...;...")
+
+    def __post_init__(self):
+        if self.strand not in ("+", "-"):
+            raise ValueError(f"strand must be + or -, not {self.strand!r}")
+        self.exons = sorted((min(a, b), max(a, b)) for a, b in self.exons)
+        self.cds_lend, self.cds_rend = sorted((self.cds_lend, self.cds_rend))
+
+    # -- ordering helpers -------------------------------------------------------------
+    def _in_tx_order(self, segments: Sequence[Segment]) -> List[Segment]:
+        segs = sorted(segments)
+        return segs if self.strand == "+" else segs[::-1]
+
+    def exons_tx_order(self) -> List[Segment]:
+        return self._in_tx_order(self.exons)
+
+    def cds_segments(self) -> List[Segment]:
+        """CDS pieces per exon, in transcription order."""
+        segs = [(max(a, self.cds_lend), min(b, self.cds_rend)) for a, b in self.exons
+                if b >= self.cds_lend and a <= self.cds_rend]
+        if not segs:
+            raise ValueError(f"{self.model_id}: CDS {self.cds_lend}-{self.cds_rend} lies outside its exons")
+        return self._in_tx_order(segs)
+
+    def _utr(self, left: bool) -> List[Segment]:
+        if left:
+            segs = [(a, min(b, self.cds_lend - 1)) for a, b in self.exons if a < self.cds_lend]
+        else:
+            segs = [(max(a, self.cds_rend + 1), b) for a, b in self.exons if b > self.cds_rend]
+        return self._in_tx_order(segs)
+
+    def utr5(self) -> List[Segment]:
+        return _min_utr(self._utr(left=(self.strand == "+")))
+
+    def utr3(self) -> List[Segment]:
+        return _min_utr(self._utr(left=(self.strand == "-")))
+
+    def span(self) -> Segment:
+        return self.exons[0][0], self.exons[-1][1]
+
+    # -- output -----------------------------------------------------------------------
+    def gff3_lines(self, gene_id: str, source: str) -> List[str]:
+        lend, rend = self.span()
+        name = _quoted(self.name)
+        attrs = f"ID={self.model_id};Parent={gene_id}" + (f";Name={name}" if name else "") + \
+            (f";{self.extra_attrs}" if self.extra_attrs else "")
+        lines = [_row(self.seqid, source, "mRNA", lend, rend, self.strand, ".", attrs)]
+        for i, (a, b) in enumerate(self.utr5(), 1):
+            lines.append(_row(self.seqid, source, "five_prime_UTR", a, b, self.strand, ".",
+                              f"ID={self.model_id}.utr5p{i};Parent={self.model_id}"))
+        cds = dict()
+        cds_len = 0
+        for a, b in self.cds_segments():
+            # GFF3 phase: bases to skip from this segment's 5' end to reach a codon start
+            cds[(a, b)] = (3 - cds_len % 3) % 3
+            cds_len += b - a + 1
+        for i, (ea, eb) in enumerate(self.exons_tx_order(), 1):
+            lines.append(_row(self.seqid, source, "exon", ea, eb, self.strand, ".",
+                              f"ID={self.model_id}.exon{i};Parent={self.model_id}"))
+            for (a, b), phase in cds.items():
+                if ea <= a and b <= eb:
+                    lines.append(_row(self.seqid, source, "CDS", a, b, self.strand, str(phase),
+                                      f"ID=cds.{self.model_id};Parent={self.model_id}"))
+        for i, (a, b) in enumerate(self.utr3(), 1):
+            lines.append(_row(self.seqid, source, "three_prime_UTR", a, b, self.strand, ".",
+                              f"ID={self.model_id}.utr3p{i};Parent={self.model_id}"))
+        return lines
+
+    def bed12(self, name: str) -> str:
+        """BED12 line (as Perl gff3_file_to_bed.pl: thickStart/End = CDS span)."""
+        lend, rend = self.span()
+        sizes = ",".join(str(b - a + 1) for a, b in self.exons)
+        starts = ",".join(str(a - lend) for a, _ in self.exons)
+        return "\t".join(map(str, [self.seqid, lend - 1, rend, name, 0, self.strand,
+                                   self.cds_lend - 1, self.cds_rend, 0, len(self.exons), sizes, starts]))
+
+
+@dataclass
+class CodingGene:
+    gene_id: str
+    models: List[CodingModel] = field(default_factory=list)
+    name: str = ""
+
+    def gff3_text(self, source: str = "transdecoder") -> str:
+        m0 = self.models[0]
+        lend = min(m.span()[0] for m in self.models)
+        rend = max(m.span()[1] for m in self.models)
+        name = _quoted(self.name if self.name else m0.name)
+        gene_attrs = f"ID={_quote_id(self.gene_id)}" + (f";Name={name}" if name else "")
+        lines = [_row(m0.seqid, source, "gene", lend, rend, m0.strand, ".", gene_attrs)]
+        for m in self.models:
+            lines += m.gff3_lines(_quote_id(self.gene_id), source)
+        return "\n".join(lines) + "\n\n"
+
+
+def _min_utr(segments: List[Segment]) -> List[Segment]:
+    # as Perl Gene_obj::has_5prime_UTR / has_3prime_UTR: a UTR needs more than 2 nt in total,
+    # so the 1-2 nt left by a partial ORF's frame offset is not reported
+    return segments if sum(b - a + 1 for a, b in segments) > 2 else []
+
+
+def _row(seqid, source, ftype, a, b, strand, phase, attrs) -> str:
+    return f"{seqid}\t{source}\t{ftype}\t{a}\t{b}\t.\t{strand}\t{phase}\t{attrs}"
+
+
+def _quoted(name: Optional[str]) -> str:
+    if not name:
+        return ""
+    if name[0] in "'\"" and name[-1] in "'\"":
+        return name
+    return f'"{name}"'
+
+
+def _quote_id(identifier: str) -> str:
+    return f'"{identifier}"' if ";" in identifier else identifier

pytransdecoder/core/gff3_parser.py

@@ -0,0 +1,58 @@
+"""
+Simple GFF3 parser for TransDecoder
+
+Parses GFF3 files generated by LongOrfs phase.
+"""
+
+from typing import Generator, Dict, Any
+
+
+def parse_gff3(gff3_file: str) -> Generator[Dict[str, Any], None, None]:
+    """
+    Parse a GFF3 file
+    
+    Args:
+        gff3_file: Path to GFF3 file
+        
+    Yields:
+        Dictionary for each GFF3 feature with keys:
+        - seqid: sequence ID
+        - source: source
+        - type: feature type
+        - start: start position (1-based)
+        - end: end position (1-based)
+        - score: score
+        - strand: strand
+        - phase: phase
+        - attributes: dict of attributes
+    """
+    with open(gff3_file) as f:
+        for line in f:
+            line = line.strip()
+            
+            # Skip empty lines and comments
+            if not line or line.startswith('#'):
+                continue
+            
+            parts = line.split('\t')
+            if len(parts) != 9:
+                continue
+            
+            # Parse attributes
+            attributes = {}
+            for attr in parts[8].split(';'):
+                if '=' in attr:
+                    key, value = attr.split('=', 1)
+                    attributes[key] = value.split(',')
+            
+            yield {
+                'seqid': parts[0],
+                'source': parts[1],
+                'type': parts[2],
+                'start': int(parts[3]),
+                'end': int(parts[4]),
+                'score': parts[5],
+                'strand': parts[6],
+                'phase': parts[7],
+                'attributes': attributes
+            }

pytransdecoder/core/homology_starts.py

@@ -0,0 +1,54 @@
+"""
+Homology-assisted start refinement (used only when BLASTP and/or Pfam hits are supplied to Predict).
+
+For an ORF that is open at its 5' end and has a first in-frame ATG at peptide position a (1-based
+position in the longest-ORF peptide, whose position 1 is the first whole codon at the open end):
+
+  R2 (BLASTP, trim):  the best hit's subject N-terminus is aligned (sstart <= R2_MAX_SSTART) and maps
+                      to within R2_MAX_OFFSET aa of the ATG: |qstart - (sstart - 1) - a| <= R2_MAX_OFFSET
+  R1 (BLASTP, keep):  the best hit's alignment starts >= R1_MIN_UPSTREAM aa upstream of the ATG
+                      (qstart <= a - R1_MIN_UPSTREAM) and the subject continues further N-terminal
+                      (sstart > 1)
+  R3 (Pfam, keep):    a Pfam domain envelope starts >= R3_MIN_UPSTREAM aa upstream of the ATG
+                      (env_from <= a - R3_MIN_UPSTREAM)
+
+R2 calls trim-to-ATG; R1 or R3 call keep-5'-open. When both a trim and a keep call fire, or none
+fires, the ab initio coding-vs-UTR rule decides. Thresholds: TransDecoderPaper evidence E33 step 3
+(fixed before evaluation on simulated Trinity assemblies and the cross-species benchmark).
+"""
+from typing import List, Optional, Tuple
+
+R2_MAX_SSTART = 3
+R2_MAX_OFFSET = 5
+R1_MIN_UPSTREAM = 5
+R3_MIN_UPSTREAM = 1
+
+
+def homology_start_call(atg_aa: int, blast: Optional[Tuple[int, int]] = None,
+                        pfam_env_from: Optional[int] = None) -> Tuple[List[str], Optional[str]]:
+    """
+    Args:
+        atg_aa: 1-based peptide position of the first in-frame ATG
+        blast: (qstart, sstart) of the ORF's best BLASTP hit, or None (no hit / no BLASTP input)
+        pfam_env_from: smallest envelope start of the ORF's Pfam domains, or None
+    Returns:
+        (rules fired, call) with call 'trim', 'keep', 'conflict' or None (no rule fired)
+    """
+    fired = []
+    if blast is not None:
+        qstart, sstart = blast
+        if sstart <= R2_MAX_SSTART and abs(qstart - (sstart - 1) - atg_aa) <= R2_MAX_OFFSET:
+            fired.append("R2")
+        if qstart <= atg_aa - R1_MIN_UPSTREAM and sstart > 1:
+            fired.append("R1")
+    if pfam_env_from is not None and pfam_env_from <= atg_aa - R3_MIN_UPSTREAM:
+        fired.append("R3")
+    trim = "R2" in fired
+    keep = "R1" in fired or "R3" in fired
+    if trim and keep:
+        return fired, "conflict"
+    if trim:
+        return fired, "trim"
+    if keep:
+        return fired, "keep"
+    return fired, None

pytransdecoder/core/kozak.py

@@ -0,0 +1,180 @@
+"""
+Start-codon (Kozak) context model used by start codon refinement.
+
+Positions -6..-1 and +4..+5 around an ATG (A of ATG = +1; the ATG itself is not scored).
+Log2-odds (bits, +1 pseudocounts) of training ORF start contexts vs in-frame ATGs inside the
+training ORFs: +1 bit = twice as start-like as an average internal ATG. Same model and file formats as Perl TransDecoder (PerlLib/Kozak_model.pm,
+util/train_kozak_model.pl).
+"""
+
+from __future__ import annotations
+
+import math
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence
+
+UPSTREAM = 6
+DOWNSTREAM = 2
+BASES = ("A", "C", "G", "T")
+MIN_TRAINING_STARTS = 50
+
+Counts = List[Dict[str, int]]
+Model = List[Dict[str, float]]
+
+
+def position_labels() -> List[str]:
+    return [str(k) for k in range(-UPSTREAM, 0)] + [f"+{k}" for k in range(4, 4 + DOWNSTREAM)]
+
+
+def window(sequence: str, atg_index: int) -> List[Optional[str]]:
+    """Bases at -6..-1 and +4..+5 around the ATG at atg_index (None outside the sequence)."""
+    positions = list(range(atg_index - UPSTREAM, atg_index)) + \
+        list(range(atg_index + 3, atg_index + 3 + DOWNSTREAM))
+    return [sequence[j] if 0 <= j < len(sequence) and sequence[j] in "ACGT" else None
+            for j in positions]
+
+
+def new_counts() -> Counts:
+    return [dict.fromkeys(BASES, 0) for _ in range(UPSTREAM + DOWNSTREAM)]
+
+
+def add_site(counts: Counts, sequence: str, atg_index: int) -> None:
+    for k, base in enumerate(window(sequence, atg_index)):
+        if base:
+            counts[k][base] += 1
+
+
+def log_odds_model(pos_counts: Counts, neg_counts: Counts) -> Model:
+    model = []
+    for pc, nc in zip(pos_counts, neg_counts):
+        pt, nt = sum(pc.values()) + 4, sum(nc.values()) + 4
+        model.append({b: math.log2(((pc[b] + 1) / pt) / ((nc[b] + 1) / nt)) for b in BASES})
+    return model
+
+
+def score(model: Model, sequence: str, atg_index: int) -> float:
+    return sum(model[k][b] for k, b in enumerate(window(sequence, atg_index)) if b)
+
+
+def write_model(model: Model, num_starts: int, filename: Path) -> None:
+    with open(filename, "w") as out:
+        out.write("#position\tA\tC\tG\tT  (log2-odds in bits, start vs internal in-frame ATG; "
+                  f"{num_starts} training starts)\n")
+        for label, row in zip(position_labels(), model):
+            out.write(label + "\t" + "\t".join(f"{row[b]:.3f}" for b in BASES) + "\n")
+
+
+def read_model(filename: Path) -> Model:
+    model = []
+    with open(filename) as handle:
+        for line in handle:
+            if line.startswith("#"):
+                continue
+            parts = line.rstrip("\n").split("\t")
+            if len(parts) == 5:
+                model.append({b: float(v) for b, v in zip(BASES, parts[1:])})
+    if len(model) != UPSTREAM + DOWNSTREAM:
+        raise ValueError(f"{filename} does not have {UPSTREAM + DOWNSTREAM} positions")
+    return model
+
+
+def write_counts(pos_counts: Counts, neg_counts: Counts, filename: Path) -> None:
+    with open(filename, "w") as out:
+        out.write("\t".join(["#position"] + [f"start_{b}" for b in BASES] +
+                            [f"internal_{b}" for b in BASES]) + "\n")
+        for label, pc, nc in zip(position_labels(), pos_counts, neg_counts):
+            out.write("\t".join([label] + [str(pc[b]) for b in BASES] + [str(nc[b]) for b in BASES]) + "\n")
+
+
+def _nice_ceiling(value: float) -> float:
+    for step in (0.25, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10):
+        if value <= step:
+            return step
+    return int(value) + 1
+
+
+def _fmt(v: float) -> str:
+    return f"{v:g}"
+
+
+def write_logo_svg(pos_counts: Counts, model: Model, num_starts: int, filename: Path) -> None:
+    """
+    Two panels over -6..-1, ATG, +4..+5 (the ATG itself is labeled, not drawn):
+      top:    information content (bits) of the training start contexts
+      bottom: log2-odds vs internal in-frame ATGs, positive above and negative below the axis
+    Both y scales fit the data (at least 0.5 bits / 1 log2 unit).
+    """
+    color = {"A": "#109648", "C": "#255C99", "G": "#F7B32B", "T": "#D62839"}
+    glyph_w = {"A": 72, "C": 72, "G": 78, "T": 61}   # bold Helvetica/Arial at 100px; cap height ~72px
+    labels = position_labels()
+    cols = labels[:UPSTREAM] + ["A", "T", "G"] + labels[UPSTREAM:]
+    colw, left, top_h, bot_h, gap = 40, 56, 150, 220, 56
+
+    ic_stack, up_stack, dn_stack = [], [], []
+    max_ic, max_lo = 0.5, 1.0
+    for k in range(UPSTREAM + DOWNSTREAM):
+        n = sum(pos_counts[k].values())
+        f = {b: (pos_counts[k][b] + 0.5) / (n + 2) for b in BASES}
+        ic = 2 + sum(f[b] * math.log2(f[b]) for b in BASES)
+        ic_stack.append([(b, f[b] * ic) for b in sorted(BASES, key=lambda b: f[b])])
+        max_ic = max(max_ic, ic)
+        lo = model[k]
+        up = [(b, lo[b]) for b in sorted(BASES, key=lambda b: lo[b]) if lo[b] > 0]
+        dn = [(b, -lo[b]) for b in sorted(BASES, key=lambda b: -lo[b]) if lo[b] < 0]
+        up_stack.append(up)
+        dn_stack.append(dn)
+        max_lo = max(max_lo, sum(h for _, h in up), sum(h for _, h in dn))
+    ic_top, lo_top = _nice_ceiling(max_ic), _nice_ceiling(max_lo)
+
+    top_y0 = 40 + top_h
+    bot_axis = top_y0 + gap + bot_h / 2
+    height = top_y0 + gap + bot_h + 40
+    width = left + len(cols) * colw + 20
+    ic_px, lo_px = top_h / ic_top, (bot_h / 2) / lo_top
+
+    svg = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{_fmt(height)}" '
+           'font-family="Helvetica,Arial,sans-serif">',
+           '<rect width="100%" height="100%" fill="white"/>',
+           f'<text x="{left}" y="22" font-size="14">Start-codon context of {num_starts} training ORF starts (bits)</text>',
+           f'<text x="{left}" y="{_fmt(top_y0 + gap - 14)}" font-size="14">Log2-odds vs in-frame ATGs inside the training ORFs</text>']
+
+    def letter(b: str, x: float, y_base: float, h: float) -> None:
+        if h < 0.5:
+            return
+        svg.append(f'<text x="0" y="0" font-size="100" font-weight="bold" fill="{color[b]}" '
+                   f'transform="translate({x + 2:.1f},{y_base:.1f}) scale({(colw - 4) / glyph_w[b]:.4f},{h / 72:.4f})">{b}</text>')
+
+    for c, label in enumerate(cols):
+        x = left + c * colw
+        is_atg = UPSTREAM <= c < UPSTREAM + 3
+        style = ' font-weight="bold" fill="#888888"' if is_atg else ""
+        svg.append(f'<text x="{x + colw / 2:.1f}" y="{height - 14:.1f}" font-size="{16 if is_atg else 12}" '
+                   f'text-anchor="middle"{style}>{label}</text>')
+        if is_atg:
+            continue
+        k = c if c < UPSTREAM else c - 3
+        y = top_y0
+        for b, v in ic_stack[k]:
+            letter(b, x, y, v * ic_px)
+            y -= v * ic_px
+        y = bot_axis
+        for b, v in up_stack[k]:
+            letter(b, x, y, v * lo_px)
+            y -= v * lo_px
+        y = bot_axis
+        for b, v in dn_stack[k]:
+            y += v * lo_px
+            letter(b, x, y, v * lo_px)
+
+    xr = left + len(cols) * colw
+    svg.append(f'<line x1="{left}" y1="{_fmt(top_y0)}" x2="{xr}" y2="{_fmt(top_y0)}" stroke="black"/>')
+    svg.append(f'<line x1="{left}" y1="{_fmt(bot_axis)}" x2="{xr}" y2="{_fmt(bot_axis)}" stroke="black"/>')
+    svg.append(f'<line x1="{left - 4}" y1="{top_y0 - top_h:.1f}" x2="{left - 4}" y2="{top_y0:.1f}" stroke="black"/>')
+    svg.append(f'<line x1="{left - 4}" y1="{bot_axis - bot_h / 2:.1f}" x2="{left - 4}" y2="{bot_axis + bot_h / 2:.1f}" stroke="black"/>')
+    for text, y in [(0, top_y0), (_fmt(ic_top / 2), top_y0 - top_h / 2), (_fmt(ic_top), top_y0 - top_h),
+                    (f"+{_fmt(lo_top)}", bot_axis - bot_h / 2), (0, bot_axis), (f"-{_fmt(lo_top)}", bot_axis + bot_h / 2)]:
+        svg.append(f'<text x="{left - 8}" y="{y + 4:.1f}" font-size="11" text-anchor="end">{text}</text>')
+    svg.append("</svg>")
+
+    with open(filename, "w") as out:
+        out.write("\n".join(svg) + "\n")