peplocus 0.5.6__tar.gz

peplocus-0.5.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qussai Abbas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

peplocus-0.5.6/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md LICENSE
+recursive-include src/peplocus *.py
+prune tests
+prune docs
+prune scripts
+prune evaluation
+prune benchmarks
+prune test_carrot
+prune build
+prune dist
+prune .venv
+global-exclude __pycache__ *.py[cod]

peplocus-0.5.6/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: peplocus
+Version: 0.5.6
+Summary: Fast peptide-to-genome mapping with splice-junction support and one-edit rescue
+Author: Qussai Abbas
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/qussai96/PepLocus
+Project-URL: Source, https://github.com/qussai96/PepLocus
+Project-URL: Issues, https://github.com/qussai96/PepLocus/issues
+Keywords: proteogenomics,peptides,genome,splicing,BED12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: biopython>=1.80
+Requires-Dist: pyahocorasick>=2.0
+Requires-Dist: pysam>=0.22
+Dynamic: license-file
+
+# PepLocus
+
+Map mass-spectrometry peptides directly to eukaryotic genome assemblies, including splice-junction peptides. PepLocus searches all six reading frames, always treats I/L as equivalent, and can use GTF/GFF annotations or RNA-seq BAM evidence.
+
+![PepLocus overview](https://raw.githubusercontent.com/qussai96/PepLocus/main/PepLocus.png)
+
+## Install
+
+Requires Python 3.9 or newer. Linux and macOS are recommended.
+
+```bash
+python -m pip install "git+https://github.com/qussai96/PepLocus.git"
+```
+
+Once published on PyPI:
+
+```bash
+python -m pip install peplocus
+```
+
+Dependencies are installed automatically; no external aligner is needed.
+
+## Run
+
+Map a peptide list to an assembly:
+
+```bash
+peplocus -a assembly.fa -p peptides.tsv --out results
+```
+
+Add annotation and/or RNA-seq evidence to find splice-junction placements:
+
+```bash
+peplocus -a assembly.fa -p peptides.tsv -g models.gtf -b rnaseq.bam --out results_spliced
+```
+
+`-g` accepts GTF or GFF. Either `-g` or `-b` can be used alone. A BAM index is not required.
+
+Optional one-edit rescue searches peptides with no exact match for one amino-acid substitution, insertion or deletion:
+
+```bash
+peplocus -a assembly.fa -p peptides.tsv -g models.gtf --rescue-one-edit --out results_rescue
+```
+
+The default is **8 workers** (`--threads`). Rescue uses a minimum query length of **9 aa**; short candidates can be highly ambiguous. Use `--min-rescue-length 12` for a more conservative search. `--discover-junctions` optionally searches for bounded canonical single-intron matches without supplied evidence.
+
+Peptides can be a plain list, FASTA, CSV or TSV; FragPipe's `Peptide Sequence` column is recognised automatically. Assembly FASTA may be plain or gzip-compressed. Use a fresh output directory for each run.
+
+```bash
+peplocus -h
+```
+
+## Results
+
+| File | Contents |
+|---|---|
+| `all_mappings.bed` | Exact and I/L-equivalent placements |
+| `tryptic_mappings.bed` | Placements with compatible tryptic or possible protein-terminal contexts |
+| `mappings.tsv` | Coordinates, sequences, evidence, cleavage contexts and mapping counts |
+| `peptides.tsv` | Per-peptide exact and rescue counts and status |
+| `unmapped.tsv` | Peptides with no exact match, including labeled rescue candidates |
+| `summary.json` | Parameters, counts, timings and search limits |
+
+BED files use standard BED12 coordinates, with peptide names in biological N-to-C orientation on both strands. Rescue candidates are kept separately in `rescue/`, with their own all/tryptic BED files and detailed TSV. A reusable `junctions.tsv` is also saved when splice evidence is supplied.
+
+Contiguous matching is exhaustive for the chosen translation table. Splice mapping depends on available junctions and search limits. Placements show sequence compatibility; one-edit candidates are not confirmed variants, and tryptic compatibility alone does not establish biological origin.
+
+[Report an issue](https://github.com/qussai96/PepLocus/issues) · [MIT license](https://github.com/qussai96/PepLocus/blob/main/LICENSE)

peplocus-0.5.6/README.md

@@ -0,0 +1,68 @@
+# PepLocus
+
+Map mass-spectrometry peptides directly to eukaryotic genome assemblies, including splice-junction peptides. PepLocus searches all six reading frames, always treats I/L as equivalent, and can use GTF/GFF annotations or RNA-seq BAM evidence.
+
+![PepLocus overview](https://raw.githubusercontent.com/qussai96/PepLocus/main/PepLocus.png)
+
+## Install
+
+Requires Python 3.9 or newer. Linux and macOS are recommended.
+
+```bash
+python -m pip install "git+https://github.com/qussai96/PepLocus.git"
+```
+
+Once published on PyPI:
+
+```bash
+python -m pip install peplocus
+```
+
+Dependencies are installed automatically; no external aligner is needed.
+
+## Run
+
+Map a peptide list to an assembly:
+
+```bash
+peplocus -a assembly.fa -p peptides.tsv --out results
+```
+
+Add annotation and/or RNA-seq evidence to find splice-junction placements:
+
+```bash
+peplocus -a assembly.fa -p peptides.tsv -g models.gtf -b rnaseq.bam --out results_spliced
+```
+
+`-g` accepts GTF or GFF. Either `-g` or `-b` can be used alone. A BAM index is not required.
+
+Optional one-edit rescue searches peptides with no exact match for one amino-acid substitution, insertion or deletion:
+
+```bash
+peplocus -a assembly.fa -p peptides.tsv -g models.gtf --rescue-one-edit --out results_rescue
+```
+
+The default is **8 workers** (`--threads`). Rescue uses a minimum query length of **9 aa**; short candidates can be highly ambiguous. Use `--min-rescue-length 12` for a more conservative search. `--discover-junctions` optionally searches for bounded canonical single-intron matches without supplied evidence.
+
+Peptides can be a plain list, FASTA, CSV or TSV; FragPipe's `Peptide Sequence` column is recognised automatically. Assembly FASTA may be plain or gzip-compressed. Use a fresh output directory for each run.
+
+```bash
+peplocus -h
+```
+
+## Results
+
+| File | Contents |
+|---|---|
+| `all_mappings.bed` | Exact and I/L-equivalent placements |
+| `tryptic_mappings.bed` | Placements with compatible tryptic or possible protein-terminal contexts |
+| `mappings.tsv` | Coordinates, sequences, evidence, cleavage contexts and mapping counts |
+| `peptides.tsv` | Per-peptide exact and rescue counts and status |
+| `unmapped.tsv` | Peptides with no exact match, including labeled rescue candidates |
+| `summary.json` | Parameters, counts, timings and search limits |
+
+BED files use standard BED12 coordinates, with peptide names in biological N-to-C orientation on both strands. Rescue candidates are kept separately in `rescue/`, with their own all/tryptic BED files and detailed TSV. A reusable `junctions.tsv` is also saved when splice evidence is supplied.
+
+Contiguous matching is exhaustive for the chosen translation table. Splice mapping depends on available junctions and search limits. Placements show sequence compatibility; one-edit candidates are not confirmed variants, and tryptic compatibility alone does not establish biological origin.
+
+[Report an issue](https://github.com/qussai96/PepLocus/issues) · [MIT license](https://github.com/qussai96/PepLocus/blob/main/LICENSE)

peplocus-0.5.6/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "peplocus"
+version = "0.5.6"
+description = "Fast peptide-to-genome mapping with splice-junction support and one-edit rescue"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Qussai Abbas"}]
+keywords = ["proteogenomics", "peptides", "genome", "splicing", "BED12"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = ["numpy>=1.23", "biopython>=1.80", "pyahocorasick>=2.0", "pysam>=0.22"]
+
+[project.urls]
+Homepage = "https://github.com/qussai96/PepLocus"
+Source = "https://github.com/qussai96/PepLocus"
+Issues = "https://github.com/qussai96/PepLocus/issues"
+
+[project.scripts]
+peplocus = "peplocus.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

peplocus-0.5.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

peplocus-0.5.6/src/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-0.5.6/src/peplocus/__main__.py

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

peplocus-0.5.6/src/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-0.5.6/src/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-0.5.6/src/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