ptmreloc 0.1.0__py3-none-any.whl

ptmreloc/__init__.py

@@ -0,0 +1,50 @@
+"""ptmreloc — prior-knowledge guided relocalization of low-confidence PTM sites.
+
+Quick start. The human reference database (PhosphoSitePlus, Gold Standard, Functional
+Landscape, UniProt FASTA) is downloaded once on first use, unless you pass your own tables::
+
+    import ptmreloc as pr
+
+    out = pr.reassign(peptides)                          # default weights, default PSP
+    res = pr.optimize(peptides, out_dir="opt/")          # optimize against default GS/FUN
+    out = pr.reassign(peptides, weights=res)             # or weights="opt/weights.json"
+    rep = pr.evaluate(peptides, weights=res); print(rep.summary())
+
+    # own data: any of psp= / gold= / fun= / fasta= (DataFrame or file path)
+    out = pr.reassign(peptides, psp="my_psp.tsv")
+
+The lower-level building blocks (``build_candidate_table``, ``choose``,
+``evaluate_selection``, ``optimize_weights``, ``Reassigner``) are exported too.
+"""
+from .api import EvaluationReport, compare_weights, evaluate, load_reference, optimize, reassign, resolve_weights
+from .database import (DATABASE_FILES, annotate_residues, cache_dir, database_dir, database_file,
+                       database_info, default_proteome, default_reference, download_database, read_fasta)
+from .defaults import DEFAULT_THRESHOLD, DEFAULT_WEIGHTS, WEIGHT_PRESETS
+from .engine import choose, site_scores
+from .features import FEATURE_NAMES, WEIGHT_NAMES, CandidateTable, FeatureConfig, build_candidate_table
+from .metrics import composite_score, evaluate_by_ascore, trial_relative_composite
+from .metrics import evaluate as evaluate_selection
+from .optimize import OptimizationResult, normalize_weights, optimize_weights
+from .peptide import format_residue, parse_peptide, parse_residue, relabel
+from .reassign import Reassigner, apply_selection, load_weights
+from .reference import ReferenceDB, read_table, write_table
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # high-level API
+    "optimize", "reassign", "evaluate", "compare_weights", "load_reference", "resolve_weights",
+    "EvaluationReport", "OptimizationResult",
+    # reference database
+    "DATABASE_FILES", "download_database", "cache_dir", "database_dir", "database_file", "database_info",
+    "default_reference",
+    "default_proteome", "read_fasta", "annotate_residues",
+    # defaults
+    "DEFAULT_WEIGHTS", "DEFAULT_THRESHOLD", "WEIGHT_PRESETS",
+    # building blocks
+    "ReferenceDB", "read_table", "write_table", "FeatureConfig", "CandidateTable", "build_candidate_table",
+    "FEATURE_NAMES", "WEIGHT_NAMES", "choose", "site_scores", "evaluate_selection", "evaluate_by_ascore",
+    "composite_score", "trial_relative_composite", "optimize_weights", "normalize_weights",
+    "Reassigner", "apply_selection", "load_weights", "parse_peptide", "parse_residue", "format_residue",
+    "relabel",
+]

ptmreloc/api.py

@@ -0,0 +1,268 @@
+"""High-level library API: one call each for optimize / reassign / evaluate.
+
+Reference data defaults to the human reference database (PhosphoSitePlus,
+Gold Standard, Functional Landscape, UniProt FASTA), downloaded once on first use. To use your own data, pass
+DataFrames or file paths (pkl/csv/tsv/parquet/xlsx) as ``psp=``, ``gold=``, ``fun=``,
+``fasta=``. Anything left as ``None`` falls back to the default file; ``False``
+disables an optional table. A prebuilt :class:`ReferenceDB` can be passed as ``psp``
+(its own GS/FUN sites are used unless ``gold``/``fun`` are given explicitly).
+
+If the peptide table has no residue column, residues are annotated from the
+protein sequences (``fasta=``, the default human proteome).
+
+Weights (``weights=``) may be any of:
+
+* ``None`` – the package defaults (:data:`ptmreloc.DEFAULT_WEIGHTS`)
+* a preset name – ``"medians"``, ``"fun_medians"``, ``"gs_medians"``, ``"htp_only"``
+* a path to a ``weights.json`` written by :func:`optimize` (its threshold and
+  feature settings are used too, unless overridden)
+* an :class:`OptimizationResult`
+* a mapping ``{"w_H": ..., "w_L": ..., "w_D": ...}`` or a sequence ``(w_H, w_L, w_D)``
+"""
+from __future__ import annotations
+
+import copy
+import os
+from dataclasses import dataclass, field
+from typing import Dict, Mapping, Optional, Sequence, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+from .database import annotate_residues, database_dir, database_file, default_reference
+from .defaults import DEFAULT_THRESHOLD, DEFAULT_WEIGHTS, WEIGHT_PRESETS
+from .engine import as_weight_vector, choose
+from .features import DEFAULT_COLUMNS, WEIGHT_NAMES, FeatureConfig, build_candidate_table
+from .metrics import DEFAULT_ASCORE_BINS, evaluate as _evaluate_selection, evaluate_by_ascore
+from .optimize import OptimizationResult, optimize_weights
+from .reassign import Reassigner, load_weights
+from .reference import ReferenceDB, TableLike, read_table, write_table
+
+RefSpec = Union[None, TableLike, ReferenceDB]
+OptTable = Union[None, bool, TableLike]
+WeightsSpec = Union[None, str, os.PathLike, OptimizationResult, Mapping[str, float], Sequence[float], np.ndarray]
+
+
+# ------------------------------------------------------------------ helpers
+def resolve_weights(weights: WeightsSpec = None) -> Tuple[Dict[str, float], Optional[float], Optional[FeatureConfig]]:
+    """Turn any accepted weights spec into ``(weights, threshold or None, FeatureConfig or None)``."""
+    if weights is None:
+        return dict(DEFAULT_WEIGHTS), None, None
+    if isinstance(weights, OptimizationResult):
+        return dict(weights.weights), weights.threshold, weights.config
+    if isinstance(weights, (str, os.PathLike)):
+        key = os.fspath(weights)
+        if key.lower() in WEIGHT_PRESETS:
+            return dict(WEIGHT_PRESETS[key.lower()]), None, None
+        if os.path.isfile(key):
+            payload = load_weights(key)
+            cfg = payload.get("feature_config")
+            return dict(payload["weights"]), payload.get("threshold"), FeatureConfig(**cfg) if cfg else None
+        raise ValueError(f"{key!r} is neither a weights file nor a preset {sorted(WEIGHT_PRESETS)}")
+    w = as_weight_vector(weights)
+    return dict(zip(WEIGHT_NAMES, map(float, w))), None, None
+
+
+def load_reference(
+    psp: RefSpec = None,
+    gold: OptTable = None,
+    fun: OptTable = None,
+    organism: Optional[str] = None,
+    database: Optional[Union[str, os.PathLike]] = None,
+) -> ReferenceDB:
+    """Build the reference used for scoring (PSP) and for evaluation (GS, FUN).
+
+    Each argument may be a DataFrame or file path (your own data), ``None`` (the
+    default dataset from ``database`` / the default database folder) or ``False``
+    (``gold``/``fun`` only: do not load). If ``psp`` is a :class:`ReferenceDB`, it is
+    returned as is, or as a copy extended with explicitly given ``gold``/``fun`` tables.
+
+    >>> ref = load_reference()                          # all default
+    >>> ref = load_reference(psp="my_psp.tsv")          # own PSP, default GS/FUN
+    >>> ref = load_reference(gold=False, fun=False)     # default PSP only
+    """
+    if isinstance(psp, ReferenceDB):
+        if gold is None and fun is None or gold is False and fun is False:
+            return psp
+        ref = copy.copy(psp)
+        if gold is not None and gold is not False:
+            ref.gold = set(psp.gold)
+            ref.load_gold(read_table(gold))
+        if fun is not None and fun is not False:
+            ref.fun = dict(psp.fun)
+            ref.load_fun(read_table(fun))
+        return ref
+
+    if psp is None and (gold is None or gold is False) and (fun is None or fun is False):
+        return default_reference(gold=gold is None, fun=fun is None, organism=organism, path=database)
+
+    def pick(x, name):
+        if x is False:
+            return None
+        return database_file(name, database) if x is None else x
+
+    return ReferenceDB.from_sources(pick(psp, "psp"), pick(gold, "gold"), pick(fun, "fun"), organism=organism)
+
+
+def _settings(weights, threshold, config):
+    w, thr_w, cfg_w = resolve_weights(weights)
+    thr = threshold if threshold is not None else (thr_w if thr_w is not None else DEFAULT_THRESHOLD)
+    cfg = config if config is not None else (cfg_w if cfg_w is not None else FeatureConfig())
+    return w, float(thr), cfg
+
+
+def _peptides(peptides: TableLike, columns=None, fasta=None, config: Optional[FeatureConfig] = None) -> pd.DataFrame:
+    df = read_table(peptides)
+    res_col = {**DEFAULT_COLUMNS, **(columns or {})}["residue"]
+    if res_col not in df.columns:
+        label = config.ptm_label if config is not None else "*"
+        df = annotate_residues(df, fasta, columns, label)
+    return df
+
+
+# ------------------------------------------------------------------ optimize
+def optimize(
+    peptides: TableLike,
+    psp: RefSpec = None,
+    gold: OptTable = None,
+    fun: OptTable = None,
+    threshold: float = DEFAULT_THRESHOLD,
+    n_samples: int = 2000,
+    config: Optional[FeatureConfig] = None,
+    columns: Optional[Mapping[str, str]] = None,
+    out_dir: Optional[str] = None,
+    organism: Optional[str] = None,
+    fasta: Optional[Union[TableLike, Mapping[str, str]]] = None,
+    **kwargs,
+) -> OptimizationResult:
+    """Optimize (w_H, w_L, w_D) against Gold Standard / Functional Landscape sites.
+
+    Extra keyword arguments go to :func:`ptmreloc.optimize_weights` (``refine``,
+    ``holdout_frac``, ``top_frac``, ``gs_weight``, ``log10_bounds``, ``seed``, ``verbose`` ...).
+    If ``out_dir`` is given, ``weights.json`` and the trial/evaluation tables are written there.
+
+    >>> res = ptmreloc.optimize("peptides.tsv")                      # default reference data
+    >>> res = ptmreloc.optimize(df, psp="my_psp.tsv", gold="my_gs.tsv")  # own data (FUN default)
+    >>> res.weights, res.summary()
+    """
+    ref = load_reference(psp, gold, fun, organism)
+    if not ref.has_targets:
+        raise ValueError("optimize needs Gold Standard and/or Functional Landscape sites (gold=, fun=)")
+    cfg = config or FeatureConfig()
+    table = build_candidate_table(_peptides(peptides, columns, fasta, cfg), ref, cfg, columns)
+    res = optimize_weights(table, threshold=threshold, n_samples=n_samples, **kwargs)
+    if out_dir:
+        res.save(out_dir)
+    return res
+
+
+# ------------------------------------------------------------------ reassign
+def reassign(
+    peptides: TableLike,
+    psp: RefSpec = None,
+    weights: WeightsSpec = None,
+    threshold: Optional[float] = None,
+    config: Optional[FeatureConfig] = None,
+    columns: Optional[Mapping[str, str]] = None,
+    include_candidates: bool = True,
+    output: Optional[str] = None,
+    organism: Optional[str] = None,
+    fasta: Optional[Union[TableLike, Mapping[str, str]]] = None,
+) -> pd.DataFrame:
+    """Relocalize sites of peptides with AScore <= threshold. Only PSP is required.
+
+    Without ``weights`` the package defaults are used (threshold 30); without
+    ``psp`` the default PhosphoSitePlus table is used.
+    Returns the input table plus ``NewPeptide``, ``NewResidue``, ``Reassigned``,
+    ``ReassignStatus``, ``OriginalSiteProb``, ``NewSiteProb`` (and ``CandidateSiteProbs``).
+
+    >>> out = ptmreloc.reassign(df)                                    # default PSP, default weights
+    >>> out = ptmreloc.reassign(df, psp="my_psp.tsv", weights="opt/weights.json")
+    """
+    w, thr, cfg = _settings(weights, threshold, config)
+    ref = load_reference(psp, gold=False, fun=False, organism=organism)
+    df = _peptides(peptides, columns, fasta, cfg)
+    out = Reassigner(ref, w, thr, cfg, columns).reassign(df, include_candidates)
+    if output:
+        write_table(out, output)
+    return out
+
+
+# ------------------------------------------------------------------ evaluate
+@dataclass
+class EvaluationReport:
+    weights: Dict[str, float]
+    threshold: float
+    overall: Dict[str, float]  # metrics on rows with AScore <= threshold
+    by_ascore: pd.DataFrame  # metrics per AScore bin (selection applied to every bin)
+    config: FeatureConfig = field(default_factory=FeatureConfig)
+
+    def summary(self) -> str:
+        keys = ["n_rows", "n_rows_changed", "delta_gs", "random_delta_gs", "oracle_delta_gs", "delta_fun",
+                "random_delta_fun", "oracle_delta_fun", "gs_gain", "fun_gain", "composite"]
+        head = "\n".join(f"  {k:<18}{self.overall[k]:.4g}" for k in keys)
+        cols = ["ascore_bin", "n_rows", "frac_rows_changed", "delta_gs", "random_delta_gs", "delta_fun",
+                "random_delta_fun", "gs_gain", "fun_gain", "composite"]
+        with pd.option_context("display.width", 200, "display.max_columns", 20, "display.precision", 4):
+            return (f"weights {self.weights}, AScore <= {self.threshold:g}\n{head}\n\n"
+                    f"{self.by_ascore[cols].to_string(index=False)}")
+
+
+def evaluate(
+    peptides: TableLike,
+    psp: RefSpec = None,
+    gold: OptTable = None,
+    fun: OptTable = None,
+    weights: WeightsSpec = None,
+    threshold: Optional[float] = None,
+    bins: Sequence[float] = DEFAULT_ASCORE_BINS,
+    config: Optional[FeatureConfig] = None,
+    columns: Optional[Mapping[str, str]] = None,
+    gs_weight: float = 0.5,
+    organism: Optional[str] = None,
+    fasta: Optional[Union[TableLike, Mapping[str, str]]] = None,
+) -> EvaluationReport:
+    """Score a weight set against GS/FUN sites, overall and per AScore bin.
+
+    >>> rep = ptmreloc.evaluate(df)                                    # default data, default weights
+    >>> print(rep.summary())
+    """
+    w, thr, cfg = _settings(weights, threshold, config)
+    ref = load_reference(psp, gold, fun, organism)
+    if not ref.has_targets:
+        raise ValueError("evaluate needs Gold Standard and/or Functional Landscape sites (gold=, fun=)")
+    table = build_candidate_table(_peptides(peptides, columns, fasta, cfg), ref, cfg, columns)
+    sel = choose(table, w)
+    overall = _evaluate_selection(table, sel, table.r_ascore <= thr, gs_weight)
+    by_bin = evaluate_by_ascore(table, sel, bins=bins, gs_weight=gs_weight)
+    return EvaluationReport(w, thr, overall, by_bin, cfg)
+
+
+def compare_weights(
+    peptides: TableLike,
+    psp: RefSpec = None,
+    gold: OptTable = None,
+    fun: OptTable = None,
+    weight_sets: Optional[Mapping[str, WeightsSpec]] = None,
+    threshold: float = DEFAULT_THRESHOLD,
+    config: Optional[FeatureConfig] = None,
+    columns: Optional[Mapping[str, str]] = None,
+    gs_weight: float = 0.5,
+    organism: Optional[str] = None,
+    fasta: Optional[Union[TableLike, Mapping[str, str]]] = None,
+) -> pd.DataFrame:
+    """Evaluate several weight sets on the same data (features built once).
+
+    ``weight_sets`` defaults to all presets. Returns one row per weight set.
+    All sets share ``threshold`` and ``config``.
+    """
+    weight_sets = weight_sets if weight_sets is not None else {k: k for k in WEIGHT_PRESETS}
+    ref = load_reference(psp, gold, fun, organism)
+    cfg = config or FeatureConfig()
+    table = build_candidate_table(_peptides(peptides, columns, fasta, cfg), ref, cfg, columns)
+    mask = table.r_ascore <= threshold
+    recs = []
+    for name, spec in weight_sets.items():
+        w, _, _ = resolve_weights(spec)
+        recs.append({"weights": name, **w, **_evaluate_selection(table, choose(table, w), mask, gs_weight)})
+    return pd.DataFrame(recs)

ptmreloc/cli.py

@@ -0,0 +1,199 @@
+"""Command-line interface: ``ptmreloc optimize | reassign | evaluate``."""
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+import numpy as np
+
+from . import api
+from .defaults import DEFAULT_THRESHOLD, DEFAULT_WEIGHTS, WEIGHT_PRESETS
+from .features import FeatureConfig
+from .reference import read_table, write_table
+
+
+def _add_common(p: argparse.ArgumentParser, targets: bool) -> None:
+    p.add_argument("-i", "--input", required=True, help="peptide table (pkl/csv/tsv/parquet/xlsx)")
+    g = p.add_argument_group("reference data (default: human reference database, downloaded on first use)")
+    g.add_argument("--psp", default=None, help="own PhosphoSitePlus site table")
+    if targets:
+        g.add_argument("--gold", default=None, help="own Gold Standard site table ('none' to disable)")
+        g.add_argument("--fun", default=None, help="own Functional Landscape site table ('none' to disable)")
+    g.add_argument("--fasta", default=None,
+                   help="own protein FASTA, used only when the input has no residue column")
+    g.add_argument("--database", default=None, help="folder with reference files (same names) to use instead")
+    g.add_argument("--organism", default=None, help="filter own PSP by ORGANISM (e.g. human)")
+    p.add_argument("--sheet", default=None, help="Excel sheet name for --input")
+    g = p.add_argument_group("input columns")
+    g.add_argument("--col-uniprot", default="UniProt")
+    g.add_argument("--col-peptide", default="Peptide")
+    g.add_argument("--col-residue", default="Residue")
+    g.add_argument("--col-ascore", default="AScore")
+
+
+def _add_features(p: argparse.ArgumentParser, inherit: bool) -> None:
+    g = p.add_argument_group("features" + (" (default: from --weights file, else legacy)" if inherit else ""))
+    d = None if inherit else argparse.SUPPRESS
+    g.add_argument("--ptm-label", default=d)
+    g.add_argument("--candidate-residues", default=d)
+    g.add_argument("--evidence-transform", choices=["legacy", "log", "raw"], default=d)
+    g.add_argument("--distance-mode", choices=["legacy", "inverse"], default=d)
+
+
+def _config(a, base: FeatureConfig = FeatureConfig()):
+    """Explicit feature flags override ``base``; returns None when nothing was given and base is None."""
+    over = {k: getattr(a, k, None) for k in ("ptm_label", "candidate_residues", "evidence_transform", "distance_mode")}
+    over = {k: v for k, v in over.items() if v is not None}
+    return FeatureConfig(**{**base.to_dict(), **over})
+
+
+def _opt_table(x):
+    return False if isinstance(x, str) and x.lower() == "none" else x
+
+
+def _ref(a, targets: bool):
+    gold = _opt_table(a.gold) if targets else False
+    fun = _opt_table(a.fun) if targets else False
+    return api.load_reference(a.psp, gold, fun, organism=a.organism, database=a.database)
+
+
+def _columns(a):
+    return {"uniprot": a.col_uniprot, "peptide": a.col_peptide, "residue": a.col_residue, "ascore": a.col_ascore}
+
+
+def _read_input(a):
+    kw = {"sheet_name": a.sheet} if a.sheet else {}
+    return read_table(a.input, **kw)
+
+
+def _weights_spec(a):
+    if a.w is not None:
+        return list(a.w)
+    return a.weights  # file, preset name, or None -> defaults
+
+
+def _resolved(a):
+    w, thr, cfg = api.resolve_weights(_weights_spec(a))
+    thr = a.threshold if a.threshold is not None else (thr if thr is not None else DEFAULT_THRESHOLD)
+    return w, thr, _config(a, cfg or FeatureConfig())
+
+
+def cmd_optimize(a) -> int:
+    t0 = time.time()
+    res = api.optimize(
+        _read_input(a), _ref(a, True), fasta=a.fasta, threshold=a.threshold, n_samples=a.n_samples,
+        config=_config(a), columns=_columns(a), out_dir=a.out, organism=a.organism,
+        log10_bounds=(a.log10_low, a.log10_high), refine=not a.no_refine, refine_maxiter=a.refine_maxiter,
+        top_frac=a.top_frac, holdout_frac=a.holdout, gs_weight=a.gs_weight, seed=a.seed, verbose=True,
+    )
+    print(res.summary())
+    print(f"\nwrote {a.out}/weights.json, trials.csv, evaluation.csv, metrics_by_ascore.csv "
+          f"({time.time() - t0:.1f}s)")
+    return 0
+
+
+def cmd_reassign(a) -> int:
+    w, thr, cfg = _resolved(a)
+    out = api.reassign(_read_input(a), _ref(a, False), fasta=a.fasta, weights=w, threshold=thr, config=cfg, columns=_columns(a),
+                       include_candidates=not a.no_candidates, organism=a.organism)
+    write_table(out, a.output)
+    n_elig = int((out["ReassignStatus"] == "eligible").sum())
+    print(f"weights {w}, AScore <= {thr:g}")
+    print(f"{len(out)} rows; {n_elig} eligible; {int(out['Reassigned'].sum())} relocalized; "
+          f"{int((out['ReassignStatus'] == 'unparsed').sum())} unparsed -> {a.output}")
+    return 0
+
+
+def cmd_evaluate(a) -> int:
+    w, thr, cfg = _resolved(a)
+    bins = [-np.inf] + [float(x) for x in a.bins.split(",")]
+    rep = api.evaluate(_read_input(a), _ref(a, True), fasta=a.fasta, weights=w, threshold=thr, bins=bins,
+                       config=cfg, columns=_columns(a), organism=a.organism)
+    print(rep.summary())
+    if a.output:
+        write_table(rep.by_ascore, a.output)
+    return 0
+
+
+def cmd_info(a) -> int:
+    from .database import _database_url, cache_dir, database_info
+
+    with __import__("pandas").option_context("display.width", 200, "display.max_colwidth", 120):
+        print(database_info(a.database).to_string(index=False))
+    print(f"\ndownload cache: {cache_dir()}\ndownload URL:   {_database_url() or '(not configured)'}")
+    print(f"\ndefault weights: {DEFAULT_WEIGHTS}, AScore threshold {DEFAULT_THRESHOLD:g}")
+    print(f"presets: {', '.join(WEIGHT_PRESETS)}")
+    return 0
+
+
+def cmd_download(a) -> int:
+    from .database import download_database
+
+    dest = download_database(url=a.url, dest=a.dest, force=a.force, verify=not a.no_verify)
+    print(f"reference data ready in {dest}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="ptmreloc", description="Prior-knowledge guided PTM site relocalization")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("info", help="show the reference data files in use and the default weights")
+    p.add_argument("--database", default=None)
+    p.set_defaults(func=cmd_info)
+
+    p = sub.add_parser("download", help="download the reference data (otherwise fetched on first use)")
+    p.add_argument("--url", default=None, help="base URL of the data files (default: the package's)")
+    p.add_argument("--dest", default=None, help="target folder (default: the per-user cache)")
+    p.add_argument("--force", action="store_true", help="download again even if present")
+    p.add_argument("--no-verify", action="store_true", help="skip checksum verification")
+    p.set_defaults(func=cmd_download)
+
+    p = sub.add_parser("optimize", help="optimize weights against Gold Standard / Functional sites")
+    _add_common(p, targets=True)
+    _add_features(p, inherit=True)
+    p.add_argument("-o", "--out", required=True, help="output directory")
+    p.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD,
+                   help="AScore cutoff (reassign AScore <= cutoff)")
+    p.add_argument("--n-samples", type=int, default=2000)
+    p.add_argument("--log10-low", type=float, default=-3.0)
+    p.add_argument("--log10-high", type=float, default=0.0)
+    p.add_argument("--no-refine", action="store_true")
+    p.add_argument("--refine-maxiter", type=int, default=30)
+    p.add_argument("--top-frac", type=float, default=0.05)
+    p.add_argument("--holdout", type=float, default=0.2, help="fraction of proteins held out")
+    p.add_argument("--gs-weight", type=float, default=0.5, help="GS weight in the composite score")
+    p.add_argument("--seed", type=int, default=0)
+    p.set_defaults(func=cmd_optimize)
+
+    wh = (f"weights.json from `ptmreloc optimize`, or a preset ({', '.join(WEIGHT_PRESETS)}). "
+          f"Default: {DEFAULT_WEIGHTS}")
+    for name, func, targets, help_ in [
+        ("reassign", cmd_reassign, False, "relocalize sites (default weights unless --weights/--w)"),
+        ("evaluate", cmd_evaluate, True, "score weights against GS/FUN, per AScore bin"),
+    ]:
+        p = sub.add_parser(name, help=help_)
+        _add_common(p, targets=targets)
+        _add_features(p, inherit=True)
+        p.add_argument("--weights", default=None, help=wh)
+        p.add_argument("--w", nargs=3, type=float, metavar=("W_H", "W_L", "W_D"), help="explicit weights")
+        p.add_argument("--threshold", type=float, default=None,
+                       help=f"AScore cutoff (default: from weights file, else {DEFAULT_THRESHOLD:g})")
+        if name == "reassign":
+            p.add_argument("-o", "--output", required=True, help="output table (.tsv/.csv/.pkl/.parquet/.xlsx)")
+            p.add_argument("--no-candidates", action="store_true", help="omit CandidateSiteProbs column")
+        else:
+            p.add_argument("--bins", default="0,10,20,30,50,100,inf", help="AScore bin edges")
+            p.add_argument("-o", "--output", default=None, help="write per-bin metrics table")
+        p.set_defaults(func=func)
+    return ap
+
+
+def main(argv=None) -> int:
+    a = build_parser().parse_args(argv)
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())