phasepred 0.9.0__py3-none-any.whl

phasepred/predictor.py

@@ -0,0 +1,215 @@
+"""PhaSePred predictor: compute features and score proteins from FASTA."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from phasepred.data import models_root
+
+# Default artifact (single product): Product A — paper split recomputed.
+DEFAULT_MODELS_DIR = models_root()
+
+
+# ---------------------------------------------------------------------------
+# Feature computation
+# ---------------------------------------------------------------------------
+
+
+def compute_all_features(
+    records: list[dict[str, str]],
+    *,
+    include_human: bool = False,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """Compute all PhaSePred features for a list of FASTA records.
+
+    Each record is {"accession": str, "sequence": str}.
+    Returns a DataFrame with feature columns ready for prediction.
+    """
+    from catgranule import CatGranuleInputError, score_sequence
+
+    from phasepred import tools
+    from phasepred.features import compute_native_features as _native
+
+    t_start = time.time()
+
+    # --- Native features (pure Python, fast) ---
+    native_rows = []
+    for r in records:
+        seq = str(r["sequence"]).upper()
+        try:
+            feats = _native(seq)
+            native_rows.append(
+                {
+                    "UniprotEntry": r["accession"],
+                    "length": feats["length"],
+                    "Hydropathy": feats["Hydropathy"],
+                    "FCR": feats["FCR"],
+                }
+            )
+        except Exception:
+            native_rows.append(
+                {
+                    "UniprotEntry": r["accession"],
+                    "length": float("nan"),
+                    "Hydropathy": float("nan"),
+                    "FCR": float("nan"),
+                }
+            )
+
+    feature_df = pd.DataFrame(native_rows)
+    if verbose:
+        print(f"  Native features: {len(feature_df)} in {time.time() - t_start:.1f}s")
+
+    # --- catGRANULE (via the catgranule package, legacy-unaudited weights) ---
+    t0 = time.time()
+    cat_scores: dict[str, float] = {}
+    for r in records:
+        try:
+            cat_scores[r["accession"]] = float(score_sequence(str(r["sequence"]))["single"])
+        except CatGranuleInputError:
+            cat_scores[r["accession"]] = float("nan")
+    feature_df["catGRANULE"] = feature_df["UniprotEntry"].map(cat_scores)
+    if verbose:
+        n = feature_df["catGRANULE"].notna().sum()
+        print(f"  catGRANULE: {n}/{len(feature_df)} in {time.time() - t0:.1f}s")
+
+    # --- ESpritz IDR ---
+    t0 = time.time()
+    espritz_scores = tools.run_espritz(records)
+    feature_df["IDR"] = feature_df["UniprotEntry"].map(espritz_scores)
+    if verbose:
+        n = feature_df["IDR"].notna().sum()
+        print(f"  ESpritz IDR: {n}/{len(feature_df)} in {time.time() - t0:.1f}s")
+
+    # --- SEG LCR ---
+    t0 = time.time()
+    seg_scores = tools.run_seg(records)
+    feature_df["LCR"] = feature_df["UniprotEntry"].map(seg_scores)
+    if verbose:
+        n = feature_df["LCR"].notna().sum()
+        print(f"  SEG LCR: {n}/{len(feature_df)} in {time.time() - t0:.1f}s")
+
+    # --- PScore (parallel) ---
+    t0 = time.time()
+    pscore_scores = tools.run_pscore(records)
+    feature_df["PScore"] = feature_df["UniprotEntry"].map(pscore_scores)
+    if verbose:
+        n = feature_df["PScore"].notna().sum()
+        print(f"  PScore: {n}/{len(feature_df)} in {time.time() - t0:.1f}s")
+
+    # --- PLAAC (parallel) ---
+    t0 = time.time()
+    plaac_scores = tools.run_plaac(records)
+    feature_df["PLAAC"] = feature_df["UniprotEntry"].map(plaac_scores)
+    if verbose:
+        n = feature_df["PLAAC"].notna().sum()
+        print(f"  PLAAC: {n}/{len(feature_df)} in {time.time() - t0:.1f}s")
+
+    # --- DeepCoil (on-demand subprocess into isolated conda env; binary 0/1) ---
+    t0 = time.time()
+    dc_scores = tools.run_deepcoil(records)
+    feature_df["DeepCoil"] = feature_df["UniprotEntry"].map(dc_scores)
+    if verbose:
+        n = feature_df["DeepCoil"].notna().sum()
+        print(f"  DeepCoil: {n}/{len(feature_df)} in {time.time() - t0:.1f}s")
+
+    # --- Human-specific features ---
+    if include_human:
+        t0 = time.time()
+        phos_scores = tools.compute_phos_freq(records)
+        feature_df["Phos freq"] = feature_df["UniprotEntry"].map(phos_scores)
+        dp_scores = tools.lookup_deepphase([r["accession"] for r in records])
+        feature_df["DeepPhase"] = feature_df["UniprotEntry"].map(dp_scores)
+        if verbose:
+            n_p = feature_df["Phos freq"].notna().sum()
+            n_d = feature_df["DeepPhase"].notna().sum()
+            print(f"  Phos freq + DeepPhase: {n_p}, {n_d} in {time.time() - t0:.1f}s")
+
+    if verbose:
+        total_t = time.time() - t_start
+        print(f"  Total feature computation: {total_t:.0f}s")
+
+    return feature_df
+
+
+# ---------------------------------------------------------------------------
+# Model loading and prediction
+# ---------------------------------------------------------------------------
+
+
+def load_ensemble(model_dir: Path) -> list:
+    """Load a 10-model XGBoost ensemble from a directory of joblib files."""
+    import joblib
+
+    model_files = sorted(model_dir.glob("8f_model_*.joblib"))
+    if not model_files:
+        raise FileNotFoundError(f"No 8f_model_*.joblib files found in {model_dir}")
+    return [joblib.load(str(f)) for f in model_files]
+
+
+def load_single_model(model_path: Path):
+    """Load a single model artifact (joblib file)."""
+    import joblib
+
+    if not model_path.exists():
+        raise FileNotFoundError(f"Model not found: {model_path}")
+    return joblib.load(str(model_path))
+
+
+def predict_scores(
+    models: list,
+    features: pd.DataFrame,
+    feature_columns: list[str],
+) -> pd.DataFrame:
+    """Predict scores using a loaded ensemble (or single model).
+
+    If the model was trained on a subset of columns (e.g. paper baseline
+    with only 3 features), use only those columns from the feature table.
+
+    Returns DataFrame with columns: UniprotEntry, score
+    """
+    # Check if the model artifact specifies its own feature columns
+    model_columns = None
+    if isinstance(models, list) and models:
+        first = models[0]
+        if hasattr(first, "feature_columns"):
+            model_columns = list(first.feature_columns)
+    elif hasattr(models, "feature_columns"):
+        model_columns = list(models.feature_columns)
+
+    effective_columns = model_columns or feature_columns
+    avail_cols = [c for c in effective_columns if c in features.columns]
+    missing = set(effective_columns) - set(avail_cols)
+    if missing:
+        for col in missing:
+            features[col] = float("nan")
+
+    X = features[avail_cols]
+
+    # models may be a single object or a list
+    model_list = models if isinstance(models, list) else [models]
+
+    if len(model_list) > 1:
+        scores = np.zeros(len(X))
+        for model in model_list:
+            scores += _model_predict_proba(model, X)[:, 1]
+        scores /= len(model_list)
+    else:
+        scores = _model_predict_proba(model_list[0], X)[:, 1]
+
+    result = features[["UniprotEntry"]].copy()
+    result["score"] = scores
+    return result
+
+
+def _model_predict_proba(model, X: pd.DataFrame) -> np.ndarray:
+    """Call predict_proba, handling both sklearn Pipeline and ModelArtifact."""
+    if hasattr(model, "estimator"):
+        # ModelArtifact wrapper
+        return model.estimator.predict_proba(X)
+    return model.predict_proba(X)

phasepred/sequences.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol
+
+import pandas as pd
+import requests
+from Bio import SeqIO
+
+UNIPROT_FASTA_BASE_URL = "https://rest.uniprot.org/uniprotkb"
+
+
+@dataclass(frozen=True)
+class ProteinSequence:
+    accession: str
+    sequence: str
+    source: str
+    header: str
+    retrieved_at: str | None = None
+    endpoint: str | None = None
+    sequence_hash: str = field(init=False)
+    length: int = field(init=False)
+
+    def __post_init__(self) -> None:
+        normalized = self.sequence.replace(" ", "").replace("\n", "").upper()
+        if not normalized:
+            raise ValueError(f"Protein sequence for {self.accession!r} is empty")
+        object.__setattr__(self, "sequence", normalized)
+        object.__setattr__(self, "length", len(normalized))
+        object.__setattr__(
+            self,
+            "sequence_hash",
+            hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
+        )
+
+    def to_json(self) -> dict[str, object]:
+        payload = asdict(self)
+        payload.pop("sequence_hash", None)
+        payload.pop("length", None)
+        payload["sequence_hash"] = self.sequence_hash
+        payload["length"] = self.length
+        return payload
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> ProteinSequence:
+        retrieved_at = payload.get("retrieved_at")
+        endpoint = payload.get("endpoint")
+        return cls(
+            accession=str(payload["accession"]),
+            sequence=str(payload["sequence"]),
+            source=str(payload["source"]),
+            header=str(payload.get("header") or ""),
+            retrieved_at=str(retrieved_at) if retrieved_at else None,
+            endpoint=str(endpoint) if endpoint else None,
+        )
+
+
+class SequenceFetcher(Protocol):
+    def fetch_fasta(self, accession: str) -> ProteinSequence: ...
+
+
+class SequenceCache:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+
+    def get(self, accession: str) -> ProteinSequence | None:
+        accession = accession.strip()
+        for record in self._read_all().values():
+            if record.accession == accession:
+                return record
+        return None
+
+    def put(self, record: ProteinSequence) -> None:
+        records = self._read_all()
+        records[record.accession] = record
+        self.write_all(records)
+
+    def write_all(self, records: dict[str, ProteinSequence]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("w", encoding="utf-8") as handle:
+            for item in records.values():
+                handle.write(json.dumps(item.to_json(), sort_keys=True) + "\n")
+
+    def _read_all(self) -> dict[str, ProteinSequence]:
+        if not self.path.exists():
+            return {}
+        records: dict[str, ProteinSequence] = {}
+        with self.path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                record = ProteinSequence.from_json(json.loads(stripped))
+                records[record.accession] = record
+        return records
+
+
+class UniProtClient:
+    def __init__(
+        self,
+        *,
+        base_url: str = UNIPROT_FASTA_BASE_URL,
+        session: requests.Session | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.session = session or requests.Session()
+        self.timeout = timeout
+
+    def fetch_fasta(self, accession: str) -> ProteinSequence:
+        accession = accession.strip()
+        endpoint = f"{self.base_url}/{accession}.fasta"
+        response = self.session.get(
+            endpoint,
+            headers={"Accept": "text/x-fasta"},
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        records = _records_from_fasta_text(response.text, source="uniprot", endpoint=endpoint)
+        if not records:
+            raise ValueError(f"UniProt returned no FASTA record for {accession}")
+        record = records[0]
+        return ProteinSequence(
+            accession=accession,
+            sequence=record.sequence,
+            source="uniprot",
+            header=record.header,
+            retrieved_at=datetime.now(UTC).isoformat(),
+            endpoint=endpoint,
+        )
+
+
+def read_fasta_records(path: str | Path) -> list[ProteinSequence]:
+    text = Path(path).read_text(encoding="utf-8")
+    return _records_from_fasta_text(text, source="fasta", endpoint=None)
+
+
+def resolve_accessions(
+    accessions: list[str],
+    *,
+    cache_path: str | Path,
+    client: SequenceFetcher | None = None,
+    allow_network: bool = True,
+) -> list[ProteinSequence]:
+    cache = SequenceCache(cache_path)
+    fetcher = client or UniProtClient()
+    records: list[ProteinSequence] = []
+    for accession in accessions:
+        normalized = accession.strip()
+        if not normalized:
+            continue
+        cached = cache.get(normalized)
+        if cached is not None:
+            records.append(cached)
+            continue
+        if not allow_network:
+            raise ValueError(f"Sequence for {normalized} is not cached and network is disabled")
+        fetched = fetcher.fetch_fasta(normalized)
+        cache.put(fetched)
+        records.append(fetched)
+    return records
+
+
+def sequence_records_to_frame(records: list[ProteinSequence]) -> pd.DataFrame:
+    return pd.DataFrame(
+        [
+            {
+                "UniprotEntry": record.accession,
+                "sequence": record.sequence,
+                "source": record.source,
+                "header": record.header,
+                "retrieved_at": record.retrieved_at,
+                "endpoint": record.endpoint,
+                "length": record.length,
+                "sequence_hash": record.sequence_hash,
+            }
+            for record in records
+        ]
+    )
+
+
+def _records_from_fasta_text(
+    text: str,
+    *,
+    source: str,
+    endpoint: str | None,
+) -> list[ProteinSequence]:
+    from io import StringIO
+
+    records: list[ProteinSequence] = []
+    for seq_record in SeqIO.parse(StringIO(text), "fasta"):
+        header = f">{seq_record.description}"
+        accession = _accession_from_header(seq_record.id)
+        records.append(
+            ProteinSequence(
+                accession=accession,
+                sequence=str(seq_record.seq),
+                source=source,
+                header=header,
+                endpoint=endpoint,
+            )
+        )
+    if not records:
+        raise ValueError("No FASTA records found")
+    return records
+
+
+def _accession_from_header(identifier: str) -> str:
+    parts = identifier.split("|")
+    if len(parts) >= 2 and parts[0] in {"sp", "tr"}:
+        return parts[1]
+    match = re.match(r"([A-Za-z0-9_.-]+)", identifier)
+    if not match:
+        raise ValueError(f"Cannot parse FASTA accession from header {identifier!r}")
+    return match.group(1)

phasepred/tool_features.py

@@ -0,0 +1,218 @@
+"""Per-tool feature decomposition (the ``tool-features`` CLI surface).
+
+Each PhaSePred feature is produced by an upstream tool (or a native/table
+computation). This module computes them *individually* so a caller can
+decompose a protein's PS-related profile tool-by-tool, matching the web
+``tools.<x>`` payloads:
+
+* summary value per tool (the ``single``/``NLLR``/``FCR`` column),
+* optional per-residue arrays (``--residue-json``), for the tools whose local
+  contracts expose them.
+
+Tool name vocabulary is aligned with the web API (PLAN §6-S7): ``espritz,
+seg, pscore, plaac, catgranule, deepcoil, deepphase, phos, hydropathy,
+charge``. A single tool failing degrades to ``NaN`` for that tool only — the
+whole run never aborts (same degrade semantics as ``predict``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+import pandas as pd
+
+from phasepred import tools
+from phasepred.features import CHARGED_RESIDUES, compute_native_features
+
+# Tool vocabulary (web API order).
+TOOL_NAMES = [
+    "espritz",
+    "seg",
+    "pscore",
+    "plaac",
+    "catgranule",
+    "deepcoil",
+    "deepphase",
+    "phos",
+    "hydropathy",
+    "charge",
+]
+
+# Tools whose local contract exposes per-residue arrays for --residue-json.
+_RESIDUE_TOOLS = {"espritz", "seg", "catgranule", "deepcoil", "charge"}
+
+
+def _catgranule(records: list[dict[str, str]]) -> tuple[dict[str, float], dict[str, dict]]:
+    from catgranule import score_sequence
+
+    singles: dict[str, float] = {}
+    residues: dict[str, dict] = {}
+    for r in records:
+        seq = str(r["sequence"]).upper()
+        try:
+            scored = score_sequence(seq)
+            singles[r["accession"]] = float(scored["single"])
+            residues[r["accession"]] = {"residue": [float(x) for x in scored["residue"]]}
+        except Exception:
+            singles[r["accession"]] = float("nan")
+            residues[r["accession"]] = {"residue": []}
+    return singles, residues
+
+
+def _charge_residues(records: list[dict[str, str]]) -> dict[str, dict]:
+    out: dict[str, dict] = {}
+    for r in records:
+        seq = str(r["sequence"]).upper()
+        label = [1.0 if c in CHARGED_RESIDUES else 0.0 for c in seq]
+        pos_pos = [i for i, c in enumerate(seq) if c in {"K", "R"}]
+        pos_neg = [i for i, c in enumerate(seq) if c in {"D", "E"}]
+        out[r["accession"]] = {"label": label, "POS_pos": pos_pos, "POS_neg": pos_neg}
+    return out
+
+
+def compute_tool_features(
+    records: list[dict[str, str]],
+    tool_names: list[str],
+    *,
+    residue: bool = False,
+) -> tuple[pd.DataFrame, dict[str, dict[str, dict]]]:
+    """Compute per-tool summary values (and optional residue arrays).
+
+    Returns ``(summary_df, residue_map)``. ``summary_df`` has ``UniprotEntry``
+    plus one column per requested tool (NaN on degrade). ``residue_map`` maps
+    ``accession -> tool -> field -> list`` (empty when ``residue`` is False).
+    """
+    requested = [t for t in tool_names if t in TOOL_NAMES]
+    accs = [r["accession"] for r in records]
+    summary: dict[str, list[object]] = {t: [float("nan")] * len(accs) for t in requested}
+    residue_map: dict[str, dict[str, dict]] = {a: {} for a in accs}
+
+    # Native (hydropathy, charge) — pure Python, no tools.
+    native: dict[str, dict[str, float]] = {a: {} for a in accs}
+    for r in records:
+        try:
+            native[r["accession"]] = compute_native_features(str(r["sequence"]).upper())
+        except Exception:
+            native[r["accession"]] = {}
+
+    if "hydropathy" in requested:
+        for i, r in enumerate(records):
+            summary["hydropathy"][i] = native[r["accession"]].get("Hydropathy", float("nan"))
+    if "charge" in requested:
+        for i, r in enumerate(records):
+            summary["charge"][i] = native[r["accession"]].get("FCR", float("nan"))
+        if residue:
+            for a, ch_payload in _charge_residues(records).items():
+                residue_map[a]["charge"] = ch_payload
+
+    # catgranule (package) — pure Python.
+    if "catgranule" in requested:
+        singles, residues = _catgranule(records)
+        for i, r in enumerate(records):
+            summary["catgranule"][i] = singles[r["accession"]]
+        if residue:
+            for a, cg_payload in residues.items():
+                residue_map[a]["catgranule"] = cg_payload
+
+    # ESpritz (IDR) — perl tool; residue arrays derivable.
+    if "espritz" in requested:
+        esp_resid: dict[str, dict[str, object]] = (
+            tools.espritz_residues(records) if residue else {}
+        )
+        if not residue:
+            for i, acc in enumerate(accs):
+                summary["espritz"][i] = tools.run_espritz(records).get(acc, float("nan"))
+        else:
+            for i, r in enumerate(records):
+                esp_payload = esp_resid.get(r["accession"])
+                if esp_payload is None:
+                    summary["espritz"][i] = float("nan")
+                    continue
+                esp_label = cast(list[str], esp_payload["label"])
+                summary["espritz"][i] = (
+                    sum(1 for s in esp_label if s == "D") / len(esp_label)
+                    if esp_label
+                    else float("nan")
+                )
+                residue_map[r["accession"]]["espritz"] = {
+                    "label": esp_label,
+                    "residue": cast(list[float], esp_payload["residue"]),
+                }
+
+    # SEG (LCR) — native binary; residue mask derivable.
+    if "seg" in requested:
+        seg_resid: dict[str, dict[str, object]] = tools.seg_residues(records) if residue else {}
+        if not residue:
+            for i, acc in enumerate(accs):
+                summary["seg"][i] = tools.run_seg(records).get(acc, float("nan"))
+        else:
+            for i, r in enumerate(records):
+                seg_payload = seg_resid.get(r["accession"])
+                if seg_payload is None:
+                    summary["seg"][i] = float("nan")
+                    continue
+                seg_label = cast(list[float], seg_payload["label"])
+                summary["seg"][i] = sum(seg_label) / len(seg_label) if seg_label else float("nan")
+                residue_map[r["accession"]]["seg"] = {"label": seg_label}
+
+    # DeepCoil (v2022 binary) — external env; residue arrays derivable.
+    if "deepcoil" in requested:
+        dc_resid: dict[str, dict[str, object]] = (
+            tools.deepcoil_residues(records) if residue else {}
+        )
+        if not residue:
+            for i, acc in enumerate(accs):
+                summary["deepcoil"][i] = tools.run_deepcoil(records).get(acc, float("nan"))
+        else:
+            for i, r in enumerate(records):
+                dc_payload = dc_resid.get(r["accession"])
+                if dc_payload is None:
+                    summary["deepcoil"][i] = float("nan")
+                    continue
+                raw_cc = cast(list[float], dc_payload["coiled-coil"])
+                summary["deepcoil"][i] = (
+                    float(1.0 if raw_cc and max(raw_cc) >= tools.DEEPCOIL_THRESHOLD else 0.0)
+                    if raw_cc
+                    else float("nan")
+                )
+                residue_map[r["accession"]]["deepcoil"] = {
+                    "coiled-coil": raw_cc,
+                    "sharpen": cast(list[float], dc_payload["sharpen"]),
+                }
+
+    # PScore / PLAAC — single only (residue not exposed by local contract).
+    if "pscore" in requested:
+        vals = tools.run_pscore(records)
+        for i, r in enumerate(records):
+            summary["pscore"][i] = vals.get(r["accession"], float("nan"))
+    if "plaac" in requested:
+        vals = tools.run_plaac(records)
+        for i, r in enumerate(records):
+            summary["plaac"][i] = vals.get(r["accession"], float("nan"))
+
+    # Lookups (DeepPhase, PhosphoSitePlus).
+    if "deepphase" in requested:
+        vals = tools.lookup_deepphase(accs)
+        for i, acc in enumerate(accs):
+            summary["deepphase"][i] = vals.get(acc, float("nan"))
+    if "phos" in requested:
+        vals = tools.compute_phos_freq(records)
+        for i, r in enumerate(records):
+            summary["phos"][i] = vals.get(r["accession"], float("nan"))
+
+    frame = pd.DataFrame({"UniprotEntry": accs})
+    for t in requested:
+        frame[t] = summary[t]
+    return frame, residue_map
+
+
+def write_residue_json(residue_map: dict[str, dict[str, dict]], out_dir: Path) -> None:
+    """Write one JSON file per accession: ``{tool: {field: [...]}}``."""
+    import json
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for acc, tools_map in residue_map.items():
+        safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in acc)
+        path = out_dir / f"{safe}.json"
+        path.write_text(json.dumps(tools_map, indent=2), encoding="utf-8")