phasepred 0.9.0__py3-none-any.whl

phasepred/legacy_features.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import gzip
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from phasepred.data import data_path
+from phasepred.features import compute_native_features
+from phasepred.tool_paths import (
+    PhaSePredToolNotFound,
+    find_tool_entry,
+)
+
+
+class LegacyFeatureError(RuntimeError):
+    """Raised when a legacy feature adapter cannot compute a value."""
+
+
+@dataclass(frozen=True)
+class ScalarFeature:
+    accession: str
+    value: float
+    source: str
+
+    def to_json(self) -> dict[str, object]:
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, payload: dict[str, Any]) -> ScalarFeature:
+        return cls(
+            accession=str(payload["accession"]),
+            value=float(payload["value"]),
+            source=str(payload["source"]),
+        )
+
+
+def compute_lcr_features(sequence_rows: list[dict[str, object]]) -> list[ScalarFeature]:
+    try:
+        seg_entry = find_tool_entry("seg")
+    except PhaSePredToolNotFound as e:
+        raise LegacyFeatureError(str(e)) from e
+    fasta = _write_temp_fasta(sequence_rows)
+    try:
+        result = subprocess.run(
+            [str(seg_entry), str(fasta), "12", "2.2", "2.5", "-x"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    finally:
+        fasta.unlink(missing_ok=True)
+    masked = _parse_fasta_text(result.stdout)
+    features = []
+    for row in sequence_rows:
+        accession = str(row["UniprotEntry"])
+        sequence = masked.get(accession, "")
+        if not sequence:
+            continue
+        low_complexity = sum(1 for residue in sequence if residue == "x" or residue.islower())
+        features.append(
+            ScalarFeature(
+                accession=accession,
+                value=low_complexity / len(sequence),
+                source="seg_12_2.2_2.5_x",
+            )
+        )
+    return features
+
+
+def compute_pscore_features(sequence_rows: list[dict[str, object]]) -> list[ScalarFeature]:
+    try:
+        pscore_entry = find_tool_entry("pscore")
+    except PhaSePredToolNotFound as e:
+        raise LegacyFeatureError(str(e)) from e
+    with tempfile.TemporaryDirectory(prefix="phasepred_pscore_") as tmp:
+        workdir = Path(tmp)
+        fasta = workdir / "input.fasta"
+        output = workdir / "pscore.tsv"
+        fasta.write_text(_fasta_text(sequence_rows), encoding="utf-8")
+        subprocess.run(
+            [
+                str(pscore_entry),
+                str(fasta),
+                "-output",
+                str(output),
+                "-overwrite",
+                "-mute",
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return parse_pscore_output(output)
+
+
+def parse_pscore_output(path: str | Path) -> list[ScalarFeature]:
+    rows = []
+    for line in Path(path).read_text(encoding="utf-8", errors="replace").splitlines():
+        parts = line.split()
+        if len(parts) >= 3 and parts[0].startswith("PScore"):
+            accession = parts[-1].lstrip(">")
+            rows.append(ScalarFeature(accession, float(parts[1]), "pscore_elife_sourcecode2"))
+    return rows
+
+
+def compute_plaac_features(sequence_rows: list[dict[str, object]]) -> list[ScalarFeature]:
+    try:
+        plaac_runner = find_tool_entry("plaac")
+    except PhaSePredToolNotFound as e:
+        raise LegacyFeatureError(str(e)) from e
+    with tempfile.TemporaryDirectory(prefix="phasepred_plaac_") as tmp:
+        fasta = Path(tmp) / "input.fasta"
+        fasta.write_text(_fasta_text(sequence_rows), encoding="utf-8")
+        result = subprocess.run(
+            [str(plaac_runner), "-i", str(fasta)],
+            cwd=str(data_path()),
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    return parse_plaac_output(result.stdout)
+
+
+def parse_plaac_output(text: str) -> list[ScalarFeature]:
+    lines = [line for line in text.splitlines() if line.strip()]
+    header = None
+    rows = []
+    for line in lines:
+        if line.startswith("SEQid\t"):
+            header = line.split("\t")
+            continue
+        if header is None or line.startswith("#"):
+            continue
+        parts = line.split("\t")
+        if len(parts) != len(header):
+            continue
+        record = dict(zip(header, parts, strict=False))
+        if "SEQid" in record and "NLLR" in record:
+            rows.append(ScalarFeature(record["SEQid"], float(record["NLLR"]), "plaac_nllr"))
+    return rows
+
+
+def compute_phosphosite_frequencies(
+    sequence_rows: list[dict[str, object]],
+    phosphosite_path: str | Path,
+) -> list[ScalarFeature]:
+    lengths = {str(row["UniprotEntry"]): len(str(row["sequence"])) for row in sequence_rows}
+    counts = dict.fromkeys(lengths, 0)
+    with gzip.open(phosphosite_path, "rt", encoding="utf-8", errors="replace") as handle:
+        header = None
+        for line in handle:
+            if line.startswith("GENE\t"):
+                header = line.rstrip("\n").split("\t")
+                continue
+            if header is None or not line.strip() or line.startswith("PhosphoSitePlus"):
+                continue
+            record = dict(zip(header, line.rstrip("\n").split("\t"), strict=False))
+            accession = record.get("ACC_ID", "")
+            if accession in counts and record.get("ORGANISM", "").lower() == "human":
+                counts[accession] += 1
+    return [
+        ScalarFeature(accession, count / lengths[accession], "phosphositeplus_sites_per_residue")
+        for accession, count in counts.items()
+        if lengths[accession] > 0
+    ]
+
+
+def load_deepphase_scores(path: str | Path) -> pd.DataFrame:
+    frame = pd.read_excel(path, sheet_name="tableS3")
+    required = {"Swiss-Prot ID", "DeepPhase_score"}
+    missing = required - set(frame.columns)
+    if missing:
+        raise LegacyFeatureError(f"DeepPhase table missing columns: {', '.join(sorted(missing))}")
+    return frame[["Swiss-Prot ID", "DeepPhase_score"]].rename(
+        columns={"Swiss-Prot ID": "UniprotEntry", "DeepPhase_score": "DeepPhase"}
+    )
+
+
+def native_feature_frame(sequence_rows: list[dict[str, object]]) -> pd.DataFrame:
+    rows = []
+    errors = []
+    for row in sequence_rows:
+        accession = str(row["UniprotEntry"])
+        try:
+            features = compute_native_features(str(row["sequence"]))
+        except ValueError as exc:
+            errors.append({"UniprotEntry": accession, "error": str(exc)})
+            features = {}
+        rows.append({"UniprotEntry": accession, **features})
+    frame = pd.DataFrame(rows)
+    if errors:
+        frame.attrs["errors"] = errors
+    return frame
+
+
+def _write_temp_fasta(sequence_rows: list[dict[str, object]]) -> Path:
+    handle = tempfile.NamedTemporaryFile("w", suffix=".fasta", delete=False, encoding="utf-8")
+    with handle:
+        handle.write(_fasta_text(sequence_rows))
+    return Path(handle.name)
+
+
+def _fasta_text(sequence_rows: list[dict[str, object]]) -> str:
+    return "".join(
+        f">{str(row['UniprotEntry']).strip()}\n{''.join(str(row['sequence']).split()).upper()}\n"
+        for row in sequence_rows
+    )
+
+
+def _parse_fasta_text(text: str) -> dict[str, str]:
+    records: dict[str, list[str]] = {}
+    current = None
+    for line in text.splitlines():
+        if line.startswith(">"):
+            current = line[1:].split()[0]
+            records[current] = []
+        elif current is not None:
+            records[current].append(line.strip())
+    return {accession: "".join(parts) for accession, parts in records.items()}

phasepred/models.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import joblib
+import pandas as pd
+from sklearn.impute import SimpleImputer
+from sklearn.linear_model import LogisticRegression
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+from phasepred.features import (
+    BASE_FEATURE_COLUMNS,
+    HUMAN_FEATURE_COLUMNS,
+    validate_feature_columns,
+)
+
+FEATURES_BY_TASK = {
+    "SaPS": BASE_FEATURE_COLUMNS,
+    "PdPS": BASE_FEATURE_COLUMNS,
+    "hSaPS": HUMAN_FEATURE_COLUMNS,
+    "hPdPS": HUMAN_FEATURE_COLUMNS,
+}
+
+# The v2022 feature-definitions version that the code implements
+# (docs/FEATURES.md). Model artifacts tag their training definitions with
+# this value; mismatches trigger the stale warning in `predict`.
+FEATURE_DEFINITIONS_VERSION = "v2022"
+
+MANIFEST_FILENAME = "manifest.json"
+
+
+class ModelManifestError(RuntimeError):
+    """Raised when a model directory manifest is unreadable."""
+
+
+@dataclass(frozen=True)
+class ModelManifest:
+    feature_definitions_version: str
+    raw: dict[str, Any]
+
+
+def load_model_manifest(model_dir: Path) -> ModelManifest | None:
+    """Read ``manifest.json`` from a model directory, if present.
+
+    Returns ``None`` for pre-0.9.0 artifacts that carry no manifest. A
+    malformed manifest raises :class:`ModelManifestError`.
+    """
+    manifest_path = model_dir / MANIFEST_FILENAME
+    if not manifest_path.is_file():
+        return None
+    try:
+        import json
+
+        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise ModelManifestError(f"Unreadable model manifest at {manifest_path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise ModelManifestError(f"Model manifest at {manifest_path} is not a JSON object")
+    version = raw.get("feature_definitions_version")
+    if not isinstance(version, str) or not version:
+        raise ModelManifestError(
+            f"Model manifest at {manifest_path} is missing string "
+            "feature_definitions_version"
+        )
+    return ModelManifest(feature_definitions_version=version, raw=raw)
+
+
+def model_dir_is_stale(model_dir: Path) -> tuple[bool, str]:
+    """Check whether a model directory binds an out-of-date feature set.
+
+    Returns ``(is_stale, reason)``. Legacy artifacts without a manifest, and
+    artifacts whose ``feature_definitions_version`` differs from the current
+    ``FEATURE_DEFINITIONS_VERSION``, are stale.
+    """
+    manifest = load_model_manifest(model_dir)
+    if manifest is None:
+        return True, (
+            f"model directory {model_dir} has no {MANIFEST_FILENAME} "
+            "(pre-0.9.0 artifact trained before feature_definitions_version "
+            f"tagging; current version {FEATURE_DEFINITIONS_VERSION})"
+        )
+    if manifest.feature_definitions_version != FEATURE_DEFINITIONS_VERSION:
+        return True, (
+            f"model directory {model_dir} binds feature_definitions_version "
+            f"{manifest.feature_definitions_version!r} but the code implements "
+            f"{FEATURE_DEFINITIONS_VERSION!r}"
+        )
+    return False, ""
+
+
+@dataclass
+class ModelArtifact:
+    task: str
+    feature_columns: list[str]
+    estimator: Pipeline
+
+    def dump(self, path: str | Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        joblib.dump(self, path)
+
+
+def train_model_artifact(
+    frame: pd.DataFrame,
+    *,
+    label_column: str,
+    task: str,
+    feature_columns: list[str] | None = None,
+) -> ModelArtifact:
+    if label_column not in frame.columns:
+        raise ValueError(f"Label column not found: {label_column}")
+    columns = feature_columns or list(FEATURES_BY_TASK[task])
+    validate_feature_columns(frame, columns)
+    estimator = Pipeline(
+        steps=[
+            ("impute", SimpleImputer(strategy="median")),
+            ("scale", StandardScaler()),
+            ("classifier", LogisticRegression(max_iter=2000, random_state=42)),
+        ]
+    )
+    estimator.fit(frame[columns], frame[label_column].astype(int))
+    return ModelArtifact(task=task, feature_columns=columns, estimator=estimator)
+
+
+def load_model_artifact(path: str | Path) -> ModelArtifact:
+    artifact = joblib.load(path)
+    if not isinstance(artifact, ModelArtifact):
+        raise TypeError(f"Unexpected model artifact type: {type(artifact)!r}")
+    return artifact
+
+
+def predict_with_artifact(artifact: ModelArtifact, frame: pd.DataFrame) -> pd.DataFrame:
+    validate_feature_columns(frame, artifact.feature_columns)
+    scores = artifact.estimator.predict_proba(frame[artifact.feature_columns])[:, 1]
+    output = pd.DataFrame({"score": scores})
+    if "UniprotEntry" in frame.columns:
+        output.insert(0, "UniprotEntry", frame["UniprotEntry"].to_numpy())
+    return output

phasepred/paper.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import pandas as pd
+
+
+class PaperSplitError(ValueError):
+    """Raised when paper supplemental split tables cannot be parsed."""
+
+
+@dataclass(frozen=True)
+class PaperSplit:
+    train: pd.DataFrame
+    test: pd.DataFrame
+
+    @property
+    def all_rows(self) -> pd.DataFrame:
+        return pd.concat([self.train, self.test], ignore_index=True)
+
+
+@dataclass(frozen=True)
+class PaperFeatures:
+    train: pd.DataFrame
+    test: pd.DataFrame
+
+    @property
+    def all_rows(self) -> pd.DataFrame:
+        return pd.concat([self.train, self.test], ignore_index=True)
+
+
+TRAIN_SHEETS: dict[str, tuple[str, str]] = {
+    "SaPS": ("SaPS", "NoPS"),
+    "PdPS": ("PdPS", "NoPS"),
+    "hSaPS": ("hSaPS", "hNoPS"),
+    "hPdPS": ("hPdPS", "hNoPS"),
+}
+
+TEST_SHEETS: dict[str, tuple[tuple[str, ...], str]] = {
+    "SaPS": (("SaPS-test", "PS-test"), "NoPS-test"),
+    "PdPS": (("PdPS-test", "PS-test"), "NoPS-test"),
+    "hSaPS": (("hSaPS-test", "hPS-test"), "hNoPS-test"),
+    "hPdPS": (("hPdPS-test", "hPS-test"), "hNoPS-test"),
+}
+
+
+def load_paper_split(s2_path: str | Path, s3_path: str | Path) -> PaperSplit:
+    s2 = Path(s2_path)
+    s3 = Path(s3_path)
+    if not s2.exists():
+        raise PaperSplitError(f"Dataset S2 workbook not found: {s2}")
+    if not s3.exists():
+        raise PaperSplitError(f"Dataset S3 workbook not found: {s3}")
+
+    train_rows: list[dict[str, object]] = []
+    for task, (positive_sheet, negative_sheet) in TRAIN_SHEETS.items():
+        train_rows.extend(_rows_for_sheet(s2, positive_sheet, task, "train", 1))
+        train_rows.extend(_rows_for_sheet(s2, negative_sheet, task, "train", 0))
+
+    test_rows: list[dict[str, object]] = []
+    for task, (positive_sheets, negative_sheet) in TEST_SHEETS.items():
+        for positive_sheet in positive_sheets:
+            test_rows.extend(_rows_for_sheet(s3, positive_sheet, task, "test", 1))
+        test_rows.extend(_rows_for_sheet(s3, negative_sheet, task, "test", 0))
+
+    return PaperSplit(
+        train=pd.DataFrame(train_rows, columns=_split_columns()),
+        test=pd.DataFrame(test_rows, columns=_split_columns()),
+    )
+
+
+def load_paper_features(s2_path: str | Path, s3_path: str | Path) -> PaperFeatures:
+    s2 = Path(s2_path)
+    s3 = Path(s3_path)
+    if not s2.exists():
+        raise PaperSplitError(f"Dataset S2 workbook not found: {s2}")
+    if not s3.exists():
+        raise PaperSplitError(f"Dataset S3 workbook not found: {s3}")
+
+    train_rows: list[dict[str, object]] = []
+    for task, (positive_sheet, negative_sheet) in TRAIN_SHEETS.items():
+        train_rows.extend(_feature_rows_for_sheet(s2, positive_sheet, task, "train", 1))
+        train_rows.extend(_feature_rows_for_sheet(s2, negative_sheet, task, "train", 0))
+
+    test_rows: list[dict[str, object]] = []
+    for task, (positive_sheets, negative_sheet) in TEST_SHEETS.items():
+        for positive_sheet in positive_sheets:
+            test_rows.extend(_feature_rows_for_sheet(s3, positive_sheet, task, "test", 1))
+        test_rows.extend(_feature_rows_for_sheet(s3, negative_sheet, task, "test", 0))
+
+    return PaperFeatures(
+        train=pd.DataFrame(train_rows),
+        test=pd.DataFrame(test_rows),
+    )
+
+
+def _split_columns() -> list[str]:
+    return ["task", "split", "label", "UniprotEntry", "source_sheet"]
+
+
+def _rows_for_sheet(
+    workbook: Path,
+    sheet_name: str,
+    task: str,
+    split: str,
+    label: int,
+) -> list[dict[str, object]]:
+    frame = _read_sheet(workbook, sheet_name)
+    return [
+        {
+            "task": task,
+            "split": split,
+            "label": label,
+            "UniprotEntry": accession,
+            "source_sheet": sheet_name,
+        }
+        for accession in (frame["UniprotEntry"].dropna().astype(str).str.strip().tolist())
+        if accession
+    ]
+
+
+def _feature_rows_for_sheet(
+    workbook: Path,
+    sheet_name: str,
+    task: str,
+    split: str,
+    label: int,
+) -> list[dict[str, object]]:
+    frame = _read_sheet(workbook, sheet_name)
+    records = frame.to_dict(orient="records")
+    rows: list[dict[str, object]] = []
+    for record in records:
+        accession = str(record.get("UniprotEntry") or "").strip()
+        if not accession:
+            continue
+        row = dict(record)
+        row.update(
+            {
+                "task": task,
+                "split": split,
+                "label": label,
+                "UniprotEntry": accession,
+                "source_sheet": sheet_name,
+            }
+        )
+        rows.append(row)
+    return rows
+
+
+def _read_sheet(workbook: Path, sheet_name: str) -> pd.DataFrame:
+    try:
+        frame = pd.read_excel(workbook, sheet_name=sheet_name)
+    except ValueError as exc:
+        raise PaperSplitError(f"Required sheet {sheet_name!r} not found in {workbook}") from exc
+    if "UniprotEntry" not in frame.columns:
+        frame = pd.read_excel(workbook, sheet_name=sheet_name, header=1)
+    if "UniprotEntry" not in frame.columns:
+        raise PaperSplitError(f"Sheet {sheet_name!r} in {workbook} lacks UniprotEntry column")
+    return frame