phasepred 0.9.0__py3-none-any.whl

phasepred/data/models/PdPS/manifest.json

@@ -0,0 +1,25 @@
+{
+  "task": "PdPS",
+  "feature_columns": [
+    "Hydropathy",
+    "FCR",
+    "IDR",
+    "LCR",
+    "PScore",
+    "PLAAC",
+    "catGRANULE",
+    "DeepCoil"
+  ],
+  "feature_definitions_version": "v2022",
+  "protocol": "paper-default",
+  "n_models": 10,
+  "n_neg_ratio": 2,
+  "n_folds": 5,
+  "seed": 42,
+  "train_sheet": "PdPS",
+  "trained_at": "2026-09-07T07:34:28Z",
+  "xgboost_version": "3.2.0",
+  "auc_cv": 0.7378839637531593,
+  "auc_cv_ensemble": 0.7653199192061899,
+  "auc_test_s3": 0.717539200076712
+}

phasepred/data/models/SaPS/manifest.json

@@ -0,0 +1,25 @@
+{
+  "task": "SaPS",
+  "feature_columns": [
+    "Hydropathy",
+    "FCR",
+    "IDR",
+    "LCR",
+    "PScore",
+    "PLAAC",
+    "catGRANULE",
+    "DeepCoil"
+  ],
+  "feature_definitions_version": "v2022",
+  "protocol": "paper-default",
+  "n_models": 10,
+  "n_neg_ratio": 2,
+  "n_folds": 5,
+  "seed": 42,
+  "train_sheet": "SaPS",
+  "trained_at": "2026-09-07T07:34:28Z",
+  "xgboost_version": "3.2.0",
+  "auc_cv": 0.8607288284023668,
+  "auc_cv_ensemble": 0.8826724260355029,
+  "auc_test_s3": 0.8147863025163637
+}

phasepred/data/models/hPdPS/manifest.json

@@ -0,0 +1,27 @@
+{
+  "task": "hPdPS",
+  "feature_columns": [
+    "Hydropathy",
+    "FCR",
+    "IDR",
+    "LCR",
+    "PScore",
+    "PLAAC",
+    "catGRANULE",
+    "DeepCoil",
+    "Phos freq",
+    "DeepPhase"
+  ],
+  "feature_definitions_version": "v2022",
+  "protocol": "paper-default",
+  "n_models": 10,
+  "n_neg_ratio": 2,
+  "n_folds": 5,
+  "seed": 42,
+  "train_sheet": "hPdPS",
+  "trained_at": "2026-09-07T07:34:28Z",
+  "xgboost_version": "3.2.0",
+  "auc_cv": 0.8161708448753462,
+  "auc_cv_ensemble": 0.8406024930747922,
+  "auc_test_s3": 0.7988882803943045
+}

phasepred/data/models/hSaPS/manifest.json

@@ -0,0 +1,27 @@
+{
+  "task": "hSaPS",
+  "feature_columns": [
+    "Hydropathy",
+    "FCR",
+    "IDR",
+    "LCR",
+    "PScore",
+    "PLAAC",
+    "catGRANULE",
+    "DeepCoil",
+    "Phos freq",
+    "DeepPhase"
+  ],
+  "feature_definitions_version": "v2022",
+  "protocol": "paper-default",
+  "n_models": 10,
+  "n_neg_ratio": 2,
+  "n_folds": 5,
+  "seed": 42,
+  "train_sheet": "hSaPS",
+  "trained_at": "2026-09-07T07:34:28Z",
+  "xgboost_version": "3.2.0",
+  "auc_cv": 0.9175152089072544,
+  "auc_cv_ensemble": 0.9333333333333332,
+  "auc_test_s3": 0.8157655502392344
+}

phasepred/data.py

@@ -0,0 +1,65 @@
+"""Canonical root / data-file resolution for the phasepred package.
+
+Every repo-local or shipped data path used by the package goes through the
+helpers here so that the CLI and API work from any working directory:
+
+- ``PHASEPRED_DATA_ROOT`` overrides where repo-local data lives
+  (``data/``, ``tools/``, ``products/``, ``.external_envs/``). When the
+  package is pip-installed without a checkout, point this at a directory
+  laid out like the repository root.
+- Without an override, the repository root is inferred from this module's
+  location (package is installed from ``src/phasepred/`` inside a checkout,
+  so ``parents[2]`` is the repo root).
+- Package-bundled resources (JSON calibration constants, etc.) are resolved
+  relative to the module itself.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def repo_root() -> Path:
+    """The repository root, inferred from the module location."""
+    return Path(__file__).resolve().parents[2]
+
+
+def data_root() -> Path:
+    """The directory that holds repo-local data (override-able).
+
+    Preference: ``PHASEPRED_DATA_ROOT`` env var > inferred repository root.
+    """
+    override = os.environ.get("PHASEPRED_DATA_ROOT")
+    if override:
+        return Path(override).expanduser().resolve()
+    return repo_root()
+
+
+def data_path(*parts: str) -> Path:
+    """Resolve a path under the data root (e.g. ``data_path("data", "raw", ...)``)."""
+    return data_root().joinpath(*parts)
+
+
+def bundled_path(*parts: str) -> Path:
+    """Resolve a package-bundled resource (inside ``src/phasepred/``)."""
+    return Path(__file__).parent.joinpath(*parts)
+
+
+def models_root() -> Path:
+    """Default Product A artifacts root.
+
+    Preference: ``PHASEPRED_DATA_ROOT`` override (external data root laid out
+    like the repo) > package-bundled models (``src/phasepred/data/models``,
+    shipped in the wheel) > inferred repository ``products/`` layout (dev
+    checkout fallback).
+    """
+    override = os.environ.get("PHASEPRED_DATA_ROOT")
+    if override:
+        return Path(override).expanduser().resolve().joinpath(
+            "products", "A_paper_split_recomputed", "models"
+        )
+    bundled = bundled_path("data", "models")
+    if bundled.is_dir():
+        return bundled
+    return data_path("products", "A_paper_split_recomputed", "models")

phasepred/espritz.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from collections.abc import Iterable
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+ESPRITZ_RUNNER = Path(__file__).resolve().parents[2] / "tools" / "ESpritz" / "run"
+
+
+@dataclass(frozen=True)
+class ESpritzFeature:
+    accession: str
+    espritz_idr: float
+    mean_score: float
+    max_score: float
+    disorder_threshold: float
+    residues: int
+    model: str
+    sw: int
+
+    def to_json(self) -> dict[str, object]:
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> ESpritzFeature:
+        return cls(
+            accession=str(payload["accession"]),
+            espritz_idr=float(payload["espritz_idr"]),
+            mean_score=float(payload["mean_score"]),
+            max_score=float(payload["max_score"]),
+            disorder_threshold=float(payload["disorder_threshold"]),
+            residues=int(payload["residues"]),
+            model=str(payload["model"]),
+            sw=int(payload["sw"]),
+        )
+
+
+class ESpritzFeatureCache:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+
+    def _read_all(self) -> dict[str, ESpritzFeature]:
+        if not self.path.exists():
+            return {}
+        features: dict[str, ESpritzFeature] = {}
+        with self.path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                stripped = line.strip()
+                if not stripped:
+                    continue
+                feature = ESpritzFeature.from_json(json.loads(stripped))
+                features[feature.accession] = feature
+        return features
+
+    def append_new(self, feature: ESpritzFeature) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(feature.to_json(), sort_keys=True) + "\n")
+
+
+def resolve_espritz_features(
+    sequence_rows: Iterable[dict[str, object]],
+    *,
+    cache_path: str | Path,
+    model: str = "D",
+    sw: int = 0,
+    chunk_size: int = 250,
+    workers: int = 1,
+) -> list[ESpritzFeature]:
+    cache = ESpritzFeatureCache(cache_path)
+    cached_features = cache._read_all()
+    rows = list(sequence_rows)
+    features: list[ESpritzFeature] = []
+    pending_rows: list[dict[str, object]] = []
+    for row in rows:
+        accession = str(row["UniprotEntry"]).strip()
+        cached = cached_features.get(accession)
+        if cached is not None and cached.model == model and cached.sw == sw:
+            features.append(cached)
+            continue
+        pending_rows.append(row)
+
+    chunks = [
+        pending_rows[start : start + chunk_size]
+        for start in range(0, len(pending_rows), chunk_size)
+    ]
+    if workers <= 1:
+        for chunk in chunks:
+            for feature in compute_espritz_features(chunk, model=model, sw=sw):
+                cache.append_new(feature)
+                cached_features[feature.accession] = feature
+                features.append(feature)
+    else:
+        with ProcessPoolExecutor(max_workers=workers) as executor:
+            futures = [
+                executor.submit(compute_espritz_features, chunk, model=model, sw=sw)
+                for chunk in chunks
+            ]
+            for future in as_completed(futures):
+                for feature in future.result():
+                    cache.append_new(feature)
+                    cached_features[feature.accession] = feature
+                    features.append(feature)
+
+    by_accession = {feature.accession: feature for feature in features}
+    return [
+        by_accession[str(row["UniprotEntry"]).strip()]
+        for row in rows
+        if str(row["UniprotEntry"]).strip() in by_accession
+    ]
+
+
+def compute_espritz_features(
+    sequence_rows: Iterable[dict[str, object]],
+    *,
+    model: str = "D",
+    sw: int = 0,
+) -> list[ESpritzFeature]:
+    if not ESPRITZ_RUNNER.exists():
+        raise FileNotFoundError(f"ESpritz runner not found: {ESPRITZ_RUNNER}")
+    rows = list(sequence_rows)
+    with tempfile.TemporaryDirectory(prefix="phasepred_espritz_") as tmp:
+        workdir = Path(tmp)
+        accessions: list[str] = []
+        for row in rows:
+            accession = str(row["UniprotEntry"]).strip()
+            sequence = "".join(str(row["sequence"]).split()).upper()
+            if not accession or not sequence:
+                continue
+            accessions.append(accession)
+            (workdir / f"{_safe_stem(accession)}.fasta").write_text(
+                f">{accession}\n{sequence}\n",
+                encoding="utf-8",
+            )
+        if not accessions:
+            return []
+        subprocess.run(
+            [str(ESPRITZ_RUNNER), str(workdir), model, str(sw)],
+            check=True,
+            cwd=str(ESPRITZ_RUNNER.parents[2]),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+        features = []
+        for accession in accessions:
+            output = workdir / f"{_safe_stem(accession)}.espritz"
+            if output.exists():
+                features.append(parse_espritz_output(output, accession, model=model, sw=sw))
+        return features
+
+
+def parse_espritz_output(
+    path: str | Path,
+    accession: str,
+    *,
+    model: str = "D",
+    sw: int = 0,
+) -> ESpritzFeature:
+    states: list[str] = []
+    scores: list[float] = []
+    for line in Path(path).read_text(encoding="utf-8", errors="replace").splitlines():
+        parts = line.strip().split()
+        if len(parts) != 2 or parts[0] not in {"D", "O"}:
+            continue
+        try:
+            score = float(parts[1])
+        except ValueError:
+            continue
+        states.append(parts[0])
+        scores.append(score)
+    if not scores:
+        raise ValueError(f"No ESpritz residue scores parsed from {path}")
+    return ESpritzFeature(
+        accession=accession,
+        espritz_idr=sum(state == "D" for state in states) / len(states),
+        mean_score=sum(scores) / len(scores),
+        max_score=max(scores),
+        disorder_threshold=0.5072 if model == "D" and sw == 0 else float("nan"),
+        residues=len(scores),
+        model=model,
+        sw=sw,
+    )
+
+
+def _safe_stem(accession: str) -> str:
+    return "".join(char if char.isalnum() or char in "._-" else "_" for char in accession)

phasepred/features.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import pandas as pd
+from localcider.sequenceParameters import SequenceParameters
+
+BASE_FEATURE_COLUMNS = [
+    "Hydropathy",
+    "FCR",
+    "IDR",
+    "LCR",
+    "PScore",
+    "PLAAC",
+    "catGRANULE",
+    "DeepCoil",
+]
+
+HUMAN_FEATURE_COLUMNS = BASE_FEATURE_COLUMNS + ["Phos freq", "DeepPhase"]
+
+# DeepCoil v2022 definition (FEATURES.md §8): binary indicator with
+# threshold 0.82 on the raw coiled-coil probability.
+DEEPCOIL_THRESHOLD = 0.82
+
+# catGRANULE residue profile window (CATGRANULE_SPEC §5 / FEATURES.md §7):
+# a 51-residue centered window, covering the interior positions
+# 25..L-26 (1-indexed) → length L-50, offset 24.
+CATGRANULE_RESIDUE_WINDOW = 51
+CATGRANULE_RESIDUE_OFFSET = 24
+
+KYTE_DOOLITTLE = {
+    "A": 1.8,
+    "C": 2.5,
+    "D": -3.5,
+    "E": -3.5,
+    "F": 2.8,
+    "G": -0.4,
+    "H": -3.2,
+    "I": 4.5,
+    "K": -3.9,
+    "L": 3.8,
+    "M": 1.9,
+    "N": -3.5,
+    "P": -1.6,
+    "Q": -3.5,
+    "R": -4.5,
+    "S": -0.8,
+    "T": -0.7,
+    "V": 4.2,
+    "W": -0.9,
+    "Y": -1.3,
+}
+
+CHARGED_RESIDUES = frozenset({"D", "E", "K", "R"})
+
+
+class FeatureSchemaError(ValueError):
+    """Raised when feature inputs do not satisfy a model schema."""
+
+
+def compute_native_features(sequence: str) -> dict[str, float]:
+    normalized = sequence.upper()
+    if not normalized:
+        raise FeatureSchemaError("Cannot compute features for an empty sequence")
+    unknown = sorted({residue for residue in normalized if residue not in KYTE_DOOLITTLE})
+    if unknown:
+        raise FeatureSchemaError(f"Unsupported residues in sequence: {', '.join(unknown)}")
+    length = len(normalized)
+    return {
+        "length": float(length),
+        "Hydropathy": SequenceParameters(normalized).get_uversky_hydropathy(),
+        "FCR": sum(1 for residue in normalized if residue in CHARGED_RESIDUES) / length,
+    }
+
+
+def build_feature_matrix(
+    sequence_records: pd.DataFrame,
+    imported_features: pd.DataFrame | None = None,
+    *,
+    feature_columns: Sequence[str] = BASE_FEATURE_COLUMNS,
+) -> pd.DataFrame:
+    _require_columns(sequence_records, {"UniprotEntry", "sequence"}, "sequence records")
+    native_rows = []
+    for row in sequence_records.itertuples(index=False):
+        features = compute_native_features(str(row.sequence))
+        native_rows.append({"UniprotEntry": str(row.UniprotEntry), **features})
+    native = pd.DataFrame(native_rows)
+
+    if imported_features is None:
+        matrix = native
+    else:
+        _require_columns(imported_features, {"UniprotEntry"}, "imported features")
+        matrix = native.merge(
+            imported_features,
+            on="UniprotEntry",
+            how="left",
+            suffixes=("", "_imported"),
+        )
+        for column in ["Hydropathy", "FCR", "length"]:
+            imported_column = f"{column}_imported"
+            if imported_column in matrix.columns:
+                matrix = matrix.drop(columns=[imported_column])
+
+    missing = [column for column in feature_columns if column not in matrix.columns]
+    if missing:
+        raise FeatureSchemaError(f"Missing required feature columns: {', '.join(missing)}")
+    return matrix
+
+
+def validate_feature_columns(frame: pd.DataFrame, feature_columns: Sequence[str]) -> None:
+    missing = [column for column in feature_columns if column not in frame.columns]
+    if missing:
+        raise FeatureSchemaError(f"Missing required feature columns: {', '.join(missing)}")
+
+
+def _require_columns(frame: pd.DataFrame, columns: set[str], name: str) -> None:
+    missing = sorted(columns - set(frame.columns))
+    if missing:
+        raise FeatureSchemaError(f"{name} missing columns: {', '.join(missing)}")
+
+
+# ---------------------------------------------------------------------------
+# Residue-level alignment utilities (v2022 definitions)
+# ---------------------------------------------------------------------------
+
+
+def catgranule_profile_alignment(sequence_length: int) -> range:
+    """Position range (0-indexed) covered by a catGRANULE residue profile.
+
+    The profile is a 51-residue sliding-window mean (radius 25) over the
+    interior span: 0-indexed ``24 .. L-27`` (i.e. offset 24, length ``L-50``;
+    FEATURES.md §7 / CATGRANULE_SPEC §5). Empty range when the sequence is
+    too short for the window.
+    """
+    radius = (CATGRANULE_RESIDUE_WINDOW - 1) // 2
+    start = radius - 1
+    stop = sequence_length - radius - 1
+    if stop <= start:
+        return range(0, 0)
+    return range(start, stop)
+
+
+def pscore_alignment(sequence_length: int, residue_length: int) -> range:
+    """Position range (0-indexed) covered by a PScore residue array.
+
+    PScore omits a sequence-dependent number of head residues (empirically
+    1..L-delta; FEATURES.md §5): align the shorter array to the *suffix* of
+    the full sequence. Returns an empty range when the residue array is
+    longer than the sequence.
+    """
+    if residue_length < 0 or residue_length > sequence_length:
+        return range(0, 0)
+    return range(sequence_length - residue_length, sequence_length)
+
+
+def binary_deepcoil(raw_cc: Sequence[float]) -> float:
+    """v2022 DeepCoil feature value: ``1.0 if max(raw_cc) >= 0.82 else 0.0``."""
+    return 1.0 if max(raw_cc) >= DEEPCOIL_THRESHOLD else 0.0