peplocus 0.5.6__py3-none-any.whl

peplocus/__init__.py

@@ -0,0 +1,11 @@
+"""PepLocus: peptide coordinates directly from genome assemblies."""
+__version__ = "0.5.6"
+
+
+def map_peptides(assembly=None, peptides=None, out=None, **options):
+    """Map peptide-file paths with CLI-equivalent options; return summary dict."""
+    from .api import map_peptides as run
+    return run(assembly, peptides, out, **options)
+
+
+__all__ = ["__version__", "map_peptides"]

peplocus/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

peplocus/annotation.py

@@ -0,0 +1,103 @@
+"""Read transcript exon structures from GTF and GFF3-style Helixer annotations."""
+from collections import Counter, defaultdict
+import gzip
+import re
+from urllib.parse import unquote
+
+from .junctions import Junction, motif
+
+
+_ATTRIBUTE = re.compile(
+    r'(?:^|;)\s*([^\s=;]+)\s*(?:=\s*|\s+)'
+    r'("(?:[^"\\]|\\.)*"|\'(?:[^\'\\]|\\.)*\'|[^;]*)'
+)
+
+
+def annotation_parents(attributes):
+    """Read GTF/GFF2/GFF3 relationships without grouping separate isoforms by gene.
+
+    Split GFF3 Parent lists before URL decoding: an encoded comma is part of an ID.
+    Protein-only and bare transcript labels support older predictor output.
+    """
+    attrs = {}
+    for match in _ATTRIBUTE.finditer(attributes):
+        key, value = match.groups()
+        value = value.strip()
+        quoted = len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}
+        if quoted:
+            value = re.sub(r'\\([\\"\'])', r'\1', value[1:-1])
+        attrs[key.lower()] = value
+    for key in ('transcript_id', 'parent', 'protein_id'):
+        value = attrs.get(key)
+        if value and value != '.':
+            parts = value.split(',') if key == 'parent' else [value]
+            return [unquote(part.strip()) for part in parts if part.strip()]
+    bare = attributes.strip().rstrip(';').strip()
+    if re.fullmatch(r'[\w.:%+|/-]+', bare) and bare != '.':
+        return [unquote(bare)]
+    return []
+
+
+def read_annotation(path, fasta, lengths):
+    """Return exon-adjacency junctions, without pretending annotation is read support.
+
+    Exons are preferred per transcript; CDS intervals are a fallback when exons
+    are absent. CDS phase is not trimmed: every junction is searched in all frames,
+    preserving codons split across introns. Annotated introns are not BAM-filtered.
+    """
+    transcripts = defaultdict(lambda: {"exon": set(), "CDS": set()})
+    identities = {}
+    stats = Counter()
+    opener = gzip.open if str(path).endswith('.gz') else open
+    with opener(path, 'rt') as handle:
+        for number, line in enumerate(handle, 1):
+            if line.startswith('##FASTA'):
+                break
+            if not line.strip() or line.startswith('#'):
+                continue
+            fields = line.rstrip('\n').split('\t')
+            if len(fields) != 9:
+                raise ValueError(f"annotation line {number}: expected 9 GTF/GFF columns")
+            chrom, _, feature, start, end, _, strand, _, attributes = fields
+            feature = feature.lower()
+            if feature not in {'exon', 'cds'}:
+                continue
+            feature = 'CDS' if feature == 'cds' else 'exon'
+            stats['feature_rows'] += 1
+            if chrom not in lengths:
+                stats['feature_rows_unknown_contig'] += 1
+                continue
+            start, end = int(start)-1, int(end)
+            if not 0 <= start < end <= lengths[chrom]:
+                raise ValueError(f"annotation line {number}: interval outside assembly")
+            if strand not in {'+', '-'}:
+                raise ValueError(f"annotation line {number}: exon/CDS requires + or - strand")
+            parents = annotation_parents(attributes)
+            if not parents:
+                raise ValueError(f"annotation line {number}: exon/CDS lacks transcript_id or Parent (or protein_id/bare transcript label); gene-only features cannot resolve isoforms")
+            for parent in parents:
+                identity = (chrom, strand)
+                if parent in identities and identities[parent] != identity:
+                    raise ValueError(f"annotation transcript {parent!r} appears on conflicting contigs/strands")
+                identities[parent] = identity
+                transcripts[(chrom, strand, parent)][feature].add((start, end))
+    if not transcripts:
+        raise ValueError('annotation contains no usable exon/CDS transcripts on assembly contigs')
+    junctions = {}
+    for (chrom, strand, parent), features in transcripts.items():
+        exons = sorted(features['exon'] or features['CDS'])
+        stats['transcripts'] += 1
+        stats['transcripts_exon' if features['exon'] else 'transcripts_cds_fallback'] += 1
+        # Merge touching/overlapping segments; they do not define an intron.
+        merged = []
+        for a,b in exons:
+            if merged and a <= merged[-1][1]:
+                merged[-1] = (merged[-1][0], max(b, merged[-1][1]))
+            else:
+                merged.append((a,b))
+        for left, right in zip(merged, merged[1:]):
+            start, end = left[1], right[0]
+            key = (chrom, start, end, strand)
+            junctions[key] = Junction(chrom, start, end, strand, 0, 'annotation', motif(fasta, chrom, start, end, strand))
+    stats['junctions_retained'] = len(junctions)
+    return sorted(junctions.values()), dict(stats)

peplocus/api.py

@@ -0,0 +1,43 @@
+"""Python entry point using exactly the same defaults as the command line."""
+import argparse
+
+
+def map_peptides(assembly=None, peptides=None, out=None, *, threads=8, **options):
+    """Map a peptide file; return the run summary dictionary.
+
+    Keyword options use CLI names with underscores, e.g. gtf=..., bam=...,
+    rescue_one_edit=True, min_rescue_length=9, chunk_size=2000000.
+    Invalid options raise ValueError. Inputs are paths, never modified in place.
+    """
+    if "genome" in options:
+        if assembly is not None:
+            raise ValueError("use assembly only; genome is a legacy alias")
+        assembly=options.pop("genome")
+    if assembly is None or peptides is None or out is None:
+        raise ValueError("assembly, peptides and out are required")
+    from .cli import parser, validate_arguments
+    root=parser()
+    def error(message):raise ValueError(message)
+    root.error=error
+    actions={action.dest:action for action in root._actions if action.option_strings}
+    if "min_rescue_length" in options:
+        if "rescue_min_length" in options:
+            raise ValueError("use only min_rescue_length (rescue_min_length is a legacy alias)")
+        options["rescue_min_length"]=options.pop("min_rescue_length")
+    if "il_equivalent" in options and options["il_equivalent"] is not True:
+        raise ValueError("I/L equivalence is always enabled; il_equivalent must be True")
+    values=dict(options,threads=threads)
+    argv=["--assembly",str(assembly),"--peptides",str(peptides),"--out",str(out)]
+    for key,value in values.items():
+        if key not in actions or key in {"help","help_advanced","version","genome","peptides","out"}:
+            raise ValueError("unknown or reserved mapping option: "+key)
+        action=actions[key]
+        flag=action.option_strings[0]
+        if isinstance(action,argparse._StoreTrueAction):
+            if not isinstance(value,bool):raise ValueError(key+" must be boolean")
+            if value:argv.append(flag)
+        elif value is not None:
+            argv.extend([flag,str(value)])
+    args=root.parse_args(argv)
+    validate_arguments(args)
+    return args.func(args)

peplocus/cli.py

@@ -0,0 +1,232 @@
+"""PepLocus command-line interface."""
+import argparse
+import csv
+import json
+import logging
+from pathlib import Path
+import sys
+import tempfile
+
+import pysam
+
+from . import __version__
+from .io import prepare_reference
+from .junctions import extract_bam, write_junctions
+from .annotation import read_annotation
+from .output import EDIT_FIELDS
+from .pipeline import map_peptides
+from .rescue import one_edit
+from .sequence import canonical, join_blocks, translate
+
+
+class _HelpParser(argparse.ArgumentParser):
+    """Keep tuning flags parseable while presenting a small everyday interface."""
+    def _view(self, render):
+        hidden=[] if getattr(self,"_show_advanced",False) else getattr(self,"_advanced_actions",[])
+        saved=[(action,action.help) for action in hidden]
+        try:
+            for action,_ in saved:action.help=argparse.SUPPRESS
+            return render()
+        finally:
+            for action,help_text in saved:action.help=help_text
+
+    def parse_args(self, args=None, namespace=None):
+        args=list(sys.argv[1:] if args is None else args)
+        if args[:1]==["map"]:args=args[1:]  # compatibility with older scripts
+        return super().parse_args(args, namespace)
+
+    def format_help(self):return self._view(super().format_help)
+    def format_usage(self):return self._view(super().format_usage)
+
+
+class _AdvancedHelp(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string=None):
+        parser._show_advanced=True
+        parser.print_help()
+        parser.exit()
+
+
+def positive(text):
+    value = int(text)
+    if value < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return value
+
+
+def nonnegative(text):
+    value = int(text)
+    if value < 0:
+        raise argparse.ArgumentTypeError("must be zero or a positive integer")
+    return value
+
+
+def junction_options(parser):
+    parser.add_argument("--min-mapq", type=nonnegative, default=10, help="minimum BAM mapping quality (default: 10)")
+    parser.add_argument("--min-read-anchor", type=positive, default=8, help="aligned bases on each side of a BAM intron (default: 8)")
+    parser.add_argument("--min-junction-support", type=positive, default=2, help="minimum primary, nonduplicate alignment observations per junction (default: 2)")
+    parser.add_argument("--min-intron", type=positive, default=20, help="minimum BAM/discovery intron length in bp (default: 20)")
+    parser.add_argument("--max-intron", type=positive, default=500000, help="maximum BAM/discovery intron length in bp (default: 500000)")
+
+
+def run_junctions(args):
+    out = Path(args.out)
+    if out.exists():
+        raise ValueError(f"output already exists: {out}")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="peplocus-junctions-") as cache:
+        genome, index, lengths = prepare_reference(args.genome, cache)
+        with pysam.FastaFile(genome, filepath_index=index) as fasta:
+            junctions, stats = [], {}
+            if args.bam:
+                junctions, bam_stats = extract_bam(args.bam, fasta, lengths, args.min_mapq, args.min_read_anchor, args.min_junction_support, args.min_intron, args.max_intron)
+                stats["bam"] = bam_stats
+            if args.gtf:
+                annotation_junctions, annotation_stats = read_annotation(args.gtf, fasta, lengths)
+                junctions.extend(annotation_junctions)
+                stats["annotation"] = annotation_stats
+        write_junctions(out, junctions)
+    print(json.dumps(stats, indent=2))
+
+
+def run_verify(args):
+    count = 0
+    with tempfile.TemporaryDirectory(prefix="peplocus-verify-") as cache:
+        genome, index, lengths = prepare_reference(args.genome, cache)
+        with pysam.FastaFile(genome, filepath_index=index) as fasta, open(args.mappings) as handle:
+            reader = csv.DictReader(handle, delimiter="\t")
+            if not {"peptide", "chrom", "strand", "blocks", "matched_sequence"} <= set(reader.fieldnames or []):
+                raise ValueError("expected a PepLocus mappings.tsv file")
+            for row in reader:
+                if not all(isinstance(row.get(name),str) and row[name] for name in ("peptide","chrom","strand","blocks","matched_sequence")):
+                    raise ValueError("mapping row has empty required fields")
+                blocks = json.loads(row["blocks"])
+                if not isinstance(blocks,list) or not all(isinstance(block,list) and len(block)==2 and
+                        all(type(value) is int for value in block) for block in blocks):
+                    raise ValueError("mapping blocks must be a list of integer coordinate pairs")
+                if row["strand"] not in {"+", "-"} or row["chrom"] not in lengths or not blocks:
+                    raise ValueError(f"invalid mapping: {row}")
+                previous = -1
+                for a,b in blocks:
+                    if not 0 <= a < b <= lengths[row["chrom"]] or a < previous:
+                        raise ValueError(f"invalid genomic blocks: {blocks}")
+                    previous = b
+                if sum(b-a for a,b in blocks) != 3*len(row["matched_sequence"]):
+                    raise ValueError("mapping blocks do not span complete matched codons")
+                if "start" in row and (int(row["start"])!=blocks[0][0] or int(row["end"])!=blocks[-1][1]):
+                    raise ValueError("mapping start/end disagree with blocks")
+                observed = translate(join_blocks(fasta, row["chrom"], row["strand"], blocks), args.genetic_code)
+                if row.get("match_type") == "one_edit":
+                    edit = one_edit(row["peptide"], observed, args.il_equivalent)
+                    valid = (observed == row["matched_sequence"] and edit is not None
+                             and row.get("edit_distance") == "1"
+                             and all(str(edit[key]) == row.get(key) for key in
+                                     EDIT_FIELDS))
+                else:
+                    valid = observed == row["matched_sequence"] and canonical(observed,args.il_equivalent) == canonical(row["peptide"],args.il_equivalent)
+                if not valid:
+                    raise ValueError(f"mapping does not reproduce peptide/alignment: {row['peptide']} at {row['chrom']}:{blocks}")
+                count += 1
+    print(json.dumps({"verified_loci": count, "valid": True}))
+
+
+def parser(command=None):
+    if command in {"junctions", "verify"}:
+        return utility_parser(command)
+    mapping = _HelpParser(prog="peplocus",
+        description=None,
+        epilog="For tuning controls: peplocus --help-advanced",
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    mapping.add_argument("--version", action="version", version=f"PepLocus {__version__}")
+    mapping.add_argument("--help-advanced", action=_AdvancedHelp, nargs=0,
+                         help="show advanced controls and exit")
+    mapping.add_argument("-a", "--assembly", "--genome", dest="genome", metavar="ASSEMBLY", required=True, help="assembly FASTA (plain or gzip)")
+    mapping.add_argument("-p", "--peptides", required=True, help="peptide list, FASTA, CSV or TSV")
+    mapping.add_argument("--peptide-column", help="column name in CSV/TSV input")
+    mapping.add_argument("--out", required=True, help="output directory without existing PepLocus results")
+    mapping.add_argument("-g", "--gtf", "--gff", dest="gtf", help="annotation supplying splice junctions (GTF/GFF)")
+    mapping.add_argument("-b", "--bam", help="optional RNA-seq BAM; no index required")
+    mapping.add_argument("--junctions", help="optional reusable PepLocus junction TSV")
+    mapping.add_argument("--threads", type=positive, default=8, help="worker processes (default: 8)")
+    mapping.add_argument("--chunk-size", type=positive, default=2000000, help="genomic bases per worker task (default: 2000000)")
+    mapping.add_argument("--min-length", type=positive, default=1, help="minimum peptide length; short matches can be highly ambiguous")
+    mapping.add_argument("--il-equivalent", action="store_true", default=True, help=argparse.SUPPRESS)
+    mapping.add_argument("--genetic-code", type=positive, default=1, help="NCBI translation table; applies to every contig (default: 1)")
+    mapping.add_argument("--rescue-one-edit", action="store_true", help="rescue exact-unmapped peptides with one amino-acid edit")
+    mapping.add_argument("--min-rescue-length", dest="rescue_min_length", metavar="MIN_LENGTH", type=positive, default=9, help="minimum query length for one-edit rescue (default: 9)")
+    mapping.add_argument("--igv-display-bed", action="store_true", help="also write a display-only BED with reversed negative-strand labels and GAPMS-style colors")
+    mapping.add_argument("--no-verify", action="store_true", help="skip final extraction/translation verification (enabled by default)")
+    junction_options(mapping)
+    mapping.add_argument("--max-junctions", type=positive, default=3, help="maximum introns crossed by a supported peptide path (default: 3)")
+    mapping.add_argument("--max-paths-per-junction", type=nonnegative, default=1000, help="splice graph path cap per first intron; 0 means unlimited")
+    mapping.add_argument("--discover-junctions", action="store_true", help="discover bounded single-intron alignments without annotation")
+    mapping.add_argument("--discover-all", action="store_true", help="run discovery for mapped peptides too (requires --discover-junctions)")
+    mapping.add_argument("--novel-anchor", type=positive, default=4, help="amino acids required at each terminal discovery anchor (default: 4)")
+    mapping.add_argument("--novel-cache-mb", type=nonnegative, default=256, help="memory budget for caching small contigs during discovery; 0 disables it (default: 256 MiB)")
+    mapping.add_argument("--max-seed-hits", type=nonnegative, default=2000, help="discovery seed-hit cap per contig/strand; 0 means unlimited")
+    mapping.add_argument("--max-novel-pairs", type=nonnegative, default=10000, help="discovery candidate-junction cap per peptide/contig/strand; 0 means unlimited")
+    common={"help","version","help_advanced","genome","peptides","out","gtf","bam","threads",
+            "rescue_min_length","rescue_one_edit","discover_junctions"}
+    mapping._advanced_actions=[action for action in mapping._actions if action.dest not in common]
+    advanced=mapping.add_argument_group("Advanced controls")
+    for action in mapping._advanced_actions:
+        for group in mapping._action_groups:
+            if group is not advanced and action in group._group_actions:group._group_actions.remove(action)
+        advanced._group_actions.append(action)
+    mapping.set_defaults(func=map_peptides, command="map")
+    return mapping
+
+
+def utility_parser(command):
+    """Legacy utilities, kept for existing scripts; mapping needs no subcommand."""
+    junction = argparse.ArgumentParser(prog="peplocus junctions")
+    junction.add_argument("-a", "--assembly", "--genome", dest="genome", metavar="ASSEMBLY", required=True)
+    junction.add_argument("-b", "--bam", help="RNA-seq BAM")
+    junction.add_argument("-g", "--gtf", "--gff", dest="gtf", help="GTF or Helixer GFF3-style annotation")
+    junction.add_argument("--out", required=True, help="new junction TSV path")
+    junction_options(junction)
+    junction.set_defaults(func=run_junctions, command="junctions")
+    verify = argparse.ArgumentParser(prog="peplocus verify")
+    verify.add_argument("-a", "--assembly", "--genome", dest="genome", metavar="ASSEMBLY", required=True)
+    verify.add_argument("--mappings", required=True)
+    verify.add_argument("--il-equivalent", action="store_true", default=True, help=argparse.SUPPRESS)
+    verify.add_argument("--genetic-code", type=positive, default=1)
+    verify.set_defaults(func=run_verify, command="verify")
+    return junction if command == "junctions" else verify
+
+
+def validate_arguments(args):
+    if args.command == "junctions" and not (args.bam or args.gtf):
+        raise ValueError("junctions requires --bam and/or --gtf")
+    if hasattr(args,"min_intron") and args.min_intron > args.max_intron:
+        raise ValueError("--min-intron cannot exceed --max-intron")
+    if getattr(args,"discover_all",False) and not args.discover_junctions:
+        raise ValueError("--discover-all requires --discover-junctions")
+    from Bio.Data import CodonTable
+    if getattr(args,"genetic_code",1) not in CodonTable.unambiguous_dna_by_id:
+        raise ValueError("--genetic-code must be a valid NCBI DNA translation-table number")
+    code=CodonTable.unambiguous_dna_by_id[getattr(args,"genetic_code",1)]
+    if set(code.stop_codons) & set(code.forward_table):
+        raise ValueError("context-dependent stop codons are unsupported for --genetic-code; choose a table with unambiguous stop semantics")
+    if getattr(args,"rescue_min_length",2) < 2:
+        raise ValueError("--min-rescue-length must be at least 2")
+
+
+def main(argv=None):
+    argv=list(sys.argv[1:] if argv is None else argv)
+    command=argv.pop(0) if argv[:1] and argv[0] in {"junctions", "verify"} else None
+    root = parser(command)
+    args = root.parse_args(argv)
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+    try:
+        validate_arguments(args)
+    except ValueError as error:
+        root.error(str(error))
+    try:
+        args.func(args)
+    except (ValueError, OSError, KeyError) as error:
+        logging.getLogger("peplocus").error("%s", error)
+        return 2
+    except KeyboardInterrupt:
+        logging.getLogger("peplocus").error("Interrupted; no completed result summary was published")
+        return 130
+    return 0

peplocus/digestion.py

@@ -0,0 +1,83 @@
+"""Fast cleavage-context checks shared by exact, splice and one-edit searches."""
+from .sequence import reverse_complement, translate
+
+AMINO_ACIDS = frozenset("ACDEFGHIKLMNPQRSTVWY")
+METHIONINE_REMOVAL = frozenset("ACGPSTV")
+NON_PROLINE = AMINO_ACIDS - {"P"}
+C_FOLLOWING = NON_PROLINE | {"*"}
+CONTEXT_FIELDS = ["upstream_aa", "downstream_aa", "query_n_terminal_context", "query_c_terminal_context",
+                  "reference_n_terminal_context", "reference_c_terminal_context", "query_tryptic", "reference_tryptic",
+                  "n_cleavage_change", "c_cleavage_change", "context_evidence"]
+
+
+def cleavage_context(peptide, upstream="", downstream=""):
+    """Check both ends; M-based exceptions establish plausibility, not initiation."""
+    previous = upstream[-1:]  # upstream holds up to two residues, in protein order
+    following = downstream[:1]
+    n = "nontryptic" if previous in AMINO_ACIDS | {"*"} else "unknown"
+    if previous in {"K", "R"} and peptide[:1] in NON_PROLINE:
+        n = "tryptic"
+    elif peptide.startswith("M"):
+        n = "possible_protein_start"
+    elif previous == "M" and peptide[:1] in METHIONINE_REMOVAL:
+        n = "possible_methionine_removal"
+    c = "nontryptic" if following in AMINO_ACIDS | {"*"} else "unknown"
+    if following == "*":
+        c = "translated_stop"
+    elif peptide[-1:] in {"K", "R"} and following in NON_PROLINE:
+        c = "tryptic"
+    return dict(context_evidence="genome", upstream_aa=upstream[-2:], downstream_aa=following,
+                n_terminal_context=n, c_terminal_context=c,
+                enzyme_compatible=n not in {"nontryptic","unknown"} and c not in {"nontryptic","unknown"})
+
+
+def compare_contexts(query, reference, upstream="", downstream=""):
+    q=cleavage_context(query,upstream,downstream)
+    ref=cleavage_context(reference,upstream,downstream)
+    def change(which):
+        flank=upstream[-1:] if which=="n" else downstream[:1]
+        if flank not in AMINO_ACIDS | {"*"}:return "unresolved"
+        if flank=="*":return "no_peptide_bond"
+        before=ref[which+"_terminal_context"]=="tryptic"
+        after=q[which+"_terminal_context"]=="tryptic"
+        return "unchanged" if before==after else "gained" if after else "lost"
+    return dict(upstream_aa=upstream[-2:],downstream_aa=downstream[:1],
+        query_n_terminal_context=q["n_terminal_context"],query_c_terminal_context=q["c_terminal_context"],
+        reference_n_terminal_context=ref["n_terminal_context"],reference_c_terminal_context=ref["c_terminal_context"],
+        query_tryptic=q["enzyme_compatible"],reference_tryptic=ref["enzyme_compatible"],
+        n_cleavage_change=change("n"),c_cleavage_change=change("c"),context_evidence="genome")
+
+
+def protein_context(protein, start, end, query=None):
+    reference=protein[start:end]
+    return compare_contexts(reference if query is None else query,reference,
+                            protein[max(0,start-2):start],protein[end:end+1])
+
+
+def genomic_context(reference, chrom, strand, blocks, peptide, table=1):
+    """Only outer flanks are needed; internal split codons remain in the peptide."""
+    left, right = blocks[0][0], blocks[-1][1]
+    size = reference.get_reference_length(chrom)
+    if strand == "+":
+        upstream = reference.fetch(chrom,max(0,left-6),left)
+        downstream = reference.fetch(chrom,right,min(size,right+3))
+        # At a contig edge use complete codons nearest the peptide.
+        upstream = upstream[len(upstream)%3:]
+    else:
+        upstream = reverse_complement(reference.fetch(chrom,right,min(size,right+6)))
+        downstream = reverse_complement(reference.fetch(chrom,max(0,left-3),left))
+        upstream = upstream[len(upstream)%3:]
+    return compare_contexts(peptide,peptide,translate(upstream,table),translate(downstream,table))
+
+
+def extend_path(path, lengths, upstream_nt=6, downstream_nt=3):
+    """Add flanking codons only to outer path ends, preserving all introns."""
+    chrom,strand,segments,support,motifs,source=path
+    segments=list(segments)
+    if strand=="+":
+        a,b=segments[0];segments[0]=(max(0,a-upstream_nt),b)
+        a,b=segments[-1];segments[-1]=(a,min(lengths[chrom],b+downstream_nt))
+    else:
+        a,b=segments[0];segments[0]=(a,min(lengths[chrom],b+upstream_nt))
+        a,b=segments[-1];segments[-1]=(max(0,a-downstream_nt),b)
+    return chrom,strand,tuple(segments),support,motifs,source

peplocus/discovery.py

@@ -0,0 +1,169 @@
+"""Optional bounded, annotation-free discovery of single-intron peptide mappings."""
+from array import array
+from bisect import bisect_left, bisect_right
+from collections import Counter, defaultdict
+import logging
+
+import ahocorasick
+
+from .sequence import canonical, reverse_complement, translate
+from .digestion import genomic_context
+
+
+LOG = logging.getLogger("peplocus")
+
+
+def discover(fasta, lengths, peptides, peptide_ids, table=1, il_equivalent=True, anchor=4, min_intron=20, max_intron=500000, max_seed_hits=2000, max_pairs=10000, chunk_size=2000000, stats=None, limited=None, cache_mb=256):
+    """Join exact terminal amino-acid seeds and test all nucleotide splice phases.
+
+    Exhaustive only within the configured single-intron, canonical-motif, anchor,
+    intron-length, and repeat/candidate limits. No protein prediction is involved.
+    """
+    stats = stats if stats is not None else Counter()
+    limited = limited if limited is not None else set()
+    targets = [pid for pid in peptide_ids if len(peptides[pid]) >= 2 * anchor]
+    stats["novel_eligible_peptides"] = len(targets)
+    if not targets:
+        return
+    seeds = {}
+    terminal = {}
+    for pid in targets:
+        seq = canonical(peptides[pid], il_equivalent)
+        left, right = seq[:anchor], seq[-anchor:]
+        seeds.setdefault(left, len(seeds))
+        seeds.setdefault(right, len(seeds))
+        terminal[pid] = (seeds[left], seeds[right])
+    automaton = ahocorasick.Automaton()
+    for word, sid in seeds.items():
+        automaton.add_word(word, sid)
+    automaton.make_automaton()
+    for chrom, length in lengths.items():
+        LOG.info("Novel discovery: collecting seed positions on %s (%s bp)", chrom, length)
+        # Small random faidx reads are expensive on shared filesystems. Cache
+        # a contig only when the forward/reverse/transient copies fit the budget;
+        # larger chromosomes retain indexed on-demand access.
+        cached_forward = fasta.fetch(chrom).upper() if length * 3 <= cache_mb * 1024 * 1024 else None
+        if cached_forward is not None:
+            stats["novel_contigs_cached"] += 1
+        positions = defaultdict(lambda: array("Q"))
+        capped = set()
+        overlap = 3 * anchor - 1
+        for start in range(0, length, chunk_size):
+            core_end = min(length, start + chunk_size)
+            end = min(length, core_end + overlap)
+            forward = cached_forward[start:end] if cached_forward is not None else fasta.fetch(chrom, start, end).upper()
+            for strand, dna in (("+", forward), ("-", reverse_complement(forward))):
+                for frame in range(3):
+                    protein = canonical(translate(dna[frame:], table), il_equivalent)
+                    for last, sid in automaton.iter(protein):
+                        local = frame + 3 * (last - anchor + 1)
+                        genomic = start + local if strand == "+" else end - local - 3 * anchor
+                        if not start <= genomic < core_end:
+                            continue
+                        key = (strand, sid)
+                        if max_seed_hits and len(positions[key]) >= max_seed_hits:
+                            capped.add(key)
+                            continue
+                        position = genomic if strand == "+" else length - genomic - 3 * anchor
+                        positions[key].append(position)
+        stats["novel_seed_keys_capped"] += len(capped)
+        LOG.info("Novel discovery: %s retained seed positions on %s; %s capped keys", sum(map(len, positions.values())), chrom, len(capped))
+        for key, values in positions.items():
+            positions[key] = array("Q", sorted(values))
+        for strand in ("+", "-"):
+            oriented = cached_forward if strand == "+" else reverse_complement(cached_forward) if cached_forward is not None else None
+            def fetch(a, b):
+                if oriented is not None:
+                    return oriented[a:b]
+                if strand == "+":
+                    return fasta.fetch(chrom, a, b).upper()
+                return reverse_complement(fasta.fetch(chrom, length - b, length - a).upper())
+            for pid in targets:
+                left_seed, right_seed = terminal[pid]
+                if (strand, left_seed) in capped or (strand, right_seed) in capped:
+                    limited.add(pid)
+                lefts = positions.get((strand, left_seed), ())
+                rights = positions.get((strand, right_seed), ())
+                peptide = peptides[pid]
+                nt_length = len(peptide) * 3
+                expected = canonical(peptide, il_equivalent)
+                # Verify each seed's surrounding peptide context before joining
+                # loci. Most random 4-aa anchors cannot extend to a valid splice
+                # boundary. This avoids the Cartesian product of such anchors.
+                right_groups = defaultdict(list)
+                right_windows = {}
+                for right in rights:
+                    end = right + 3 * anchor
+                    window_start = end - nt_length
+                    if window_start < 0:
+                        continue
+                    window = fetch(window_start, end)
+                    protein = canonical(translate(window, table), il_equivalent)
+                    stats["novel_seed_contexts_checked"] += 1
+                    shared = 0
+                    for observed, wanted in zip(reversed(protein), reversed(expected)):
+                        if observed != wanted:
+                            break
+                        shared += 1
+                    minimum_cut = max(3 * anchor, 3 * (len(peptide) - shared) - 2)
+                    accepted = False
+                    for cut in range(minimum_cut, nt_length - 3 * anchor + 1):
+                        acceptor = window[cut-2:cut]
+                        if acceptor in {"AG", "AC"}:
+                            right_groups[(cut, acceptor)].append(end)
+                            accepted = True
+                    if accepted:
+                        right_windows[end] = window
+                pairs = 0
+                exhausted = False
+                for start in lefts:
+                    if start + nt_length > length:
+                        continue
+                    left_window = fetch(start, start + nt_length)
+                    protein = canonical(translate(left_window, table), il_equivalent)
+                    stats["novel_seed_contexts_checked"] += 1
+                    shared = 0
+                    for observed, wanted in zip(protein, expected):
+                        if observed != wanted:
+                            break
+                        shared += 1
+                    maximum_cut = min(nt_length - 3 * anchor, 3 * shared + 2)
+                    for cut in range(3 * anchor, maximum_cut + 1):
+                        donor_motif = left_window[cut:cut+2]
+                        if donor_motif not in {"GT", "GC", "AT"}:
+                            continue
+                        acceptor_motif = "AC" if donor_motif == "AT" else "AG"
+                        ends = right_groups.get((cut, acceptor_motif), ())
+                        low = start + nt_length + min_intron
+                        high = start + nt_length + max_intron
+                        lo, hi = bisect_left(ends, low), bisect_right(ends, high)
+                        for end in ends[lo:hi]:
+                            if max_pairs and pairs >= max_pairs:
+                                limited.add(pid)
+                                stats["novel_pair_groups_capped"] += 1
+                                exhausted = True
+                                break
+                            pairs += 1
+                            stats["novel_anchor_pairs_tested"] += 1
+                            donor = start + cut
+                            acceptor = end - (nt_length - cut)
+                            right_window = right_windows[end]
+                            matched = translate(left_window[:cut] + right_window[cut:], table)
+                            if canonical(matched, il_equivalent) != expected:
+                                continue
+                            if strand == "+":
+                                blocks = ((start, donor), (acceptor, end))
+                            else:
+                                blocks = ((length - end, length - acceptor), (length - donor, length - start))
+                            context = genomic_context(fasta,chrom,strand,blocks,matched,table)
+                            context["context_evidence"] = "novel"
+                            m = donor_motif + "-" + acceptor_motif
+                            stats["novel_hits_before_deduplication"] += 1
+                            yield (pid, chrom, strand, blocks, matched, "novel", 0, m, context)
+                        if exhausted:
+                            break
+                    if exhausted:
+                        break
+        oriented = None
+        cached_forward = None
+        LOG.info("Novel discovery: finished %s", chrom)