whisper-ppi 0.1.0__tar.gz

whisper_ppi-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: whisper-ppi
+Version: 0.1.0
+Summary: Weak Heuristic Inference for Supervisory Protein intERaction mapping for PDB and AP-MS datasets
+Home-page: https://github.com/camlab-bioml/whisper
+Author: Vesal Kasmaeifar
+Author-email: vesal.kasmaeifar@mail.utoronto.com
+License: MIT
+Project-URL: Documentation, https://whisper.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/camlab-bioml/whisper
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+
+# whisper
+
+`whisper` is a Python package for scoring protein–protein interactions from proximity labeling and affinity purification mass spectrometry datasets. It uses interpretable features, programmatic weak supervision, and decoy-based false discovery rate (FDR) estimation to identify high-confidence interactors.
+
+## Installation
+
+```bash
+git clone https://github.com/camlab-bioml/whisper
+cd whisper
+pip install .
+```
+
+## Input Format
+
+- A CSV file with:
+  - One column named `Protein`
+  - Other columns representing bait replicate intensities, named as `BAIT_1`, `BAIT_2`, etc.
+- Control samples must be identifiable via substrings in their column names (e.g., `"EGFP"` or `"Empty"`).
+
+## Usage
+
+```python
+#protein-level
+from whisper.protein_features import feature_engineering_protein
+from whisper.protein_train import train_and_score_protein
+import pandas as pd
+
+
+# Load intensity table
+intensity_df = pd.read_csv("input_intensity_dataset.tsv", sep="\t")
+
+controls = ['EGFP', 'Empty', 'NminiTurbo']
+
+# Run feature engineering
+features_df = feature_engineering_protein(intensity_df, controls)
+
+# You can save the features to use in the next step with different settings without generating them again.
+features_df = pd.read_csv("features.csv")
+
+
+# Run scoring and FDR estimation
+scored_df = train_and_score_protein(features_df, initial_positives=15, initial_negatives=200)
+
+
+#peptide-level
+from whisper.peptide_features import feature_engineering_peptide
+from whisper.peptide_train import train_and_score_peptide
+import pandas as pd
+
+
+# Load intensity table
+intensity_df = pd.read_csv("input_intensity_dataset.tsv", sep="\t")
+
+controls = ['EGFP', 'Empty', 'NminiTurbo']
+
+# Run feature engineering
+features_df = feature_engineering_peptide(intensity_df, controls)
+
+# features_df = pd.read_csv("features.csv")
+
+
+# Run scoring and FDR estimation
+scored_df = train_and_score_peptide(features_df, initial_positives=15, initial_negatives=200)
+
+
+#fragment-level
+from whisper.fragment_features import feature_engineering_fragment
+from whisper.fragment_train import train_and_score_fragment
+import pandas as pd
+
+
+# Load intensity table
+intensity_df = pd.read_csv("input_intensity_dataset.tsv", sep="\t")
+
+controls = ['EGFP', 'Empty', 'NminiTurbo']
+
+# Run feature engineering
+features_df = feature_engineering_fragment(intensity_df, controls)
+
+# features_df = pd.read_csv("features.csv")
+
+
+# Run scoring and FDR estimation
+scored_df = train_and_score_fragment(features_df, initial_positives=15, initial_negatives=200)
+```
+
+## Output
+
+The final output includes:
+- `predicted_probability`: Probability of each bait–prey interaction being real
+- `FDR`: Estimated false discovery rate
+- `global_cv_flag`: Flag for likely background preys based on variability across all samples
+
+## Tutorial
+
+[Read the full documentation](https://whisper.readthedocs.io/en/latest/)
+
+
+## Citation
+
+This software is authored by: Vesal Kasmaeifar, Kieran R Campbell
+
+Lunenfeld-Tanenbaum Research Institute & University of Toronto

whisper_ppi-0.1.0/README.md

@@ -0,0 +1,103 @@
+# whisper
+
+`whisper` is a Python package for scoring protein–protein interactions from proximity labeling and affinity purification mass spectrometry datasets. It uses interpretable features, programmatic weak supervision, and decoy-based false discovery rate (FDR) estimation to identify high-confidence interactors.
+
+## Installation
+
+```bash
+git clone https://github.com/camlab-bioml/whisper
+cd whisper
+pip install .
+```
+
+## Input Format
+
+- A CSV file with:
+  - One column named `Protein`
+  - Other columns representing bait replicate intensities, named as `BAIT_1`, `BAIT_2`, etc.
+- Control samples must be identifiable via substrings in their column names (e.g., `"EGFP"` or `"Empty"`).
+
+## Usage
+
+```python
+#protein-level
+from whisper.protein_features import feature_engineering_protein
+from whisper.protein_train import train_and_score_protein
+import pandas as pd
+
+
+# Load intensity table
+intensity_df = pd.read_csv("input_intensity_dataset.tsv", sep="\t")
+
+controls = ['EGFP', 'Empty', 'NminiTurbo']
+
+# Run feature engineering
+features_df = feature_engineering_protein(intensity_df, controls)
+
+# You can save the features to use in the next step with different settings without generating them again.
+features_df = pd.read_csv("features.csv")
+
+
+# Run scoring and FDR estimation
+scored_df = train_and_score_protein(features_df, initial_positives=15, initial_negatives=200)
+
+
+#peptide-level
+from whisper.peptide_features import feature_engineering_peptide
+from whisper.peptide_train import train_and_score_peptide
+import pandas as pd
+
+
+# Load intensity table
+intensity_df = pd.read_csv("input_intensity_dataset.tsv", sep="\t")
+
+controls = ['EGFP', 'Empty', 'NminiTurbo']
+
+# Run feature engineering
+features_df = feature_engineering_peptide(intensity_df, controls)
+
+# features_df = pd.read_csv("features.csv")
+
+
+# Run scoring and FDR estimation
+scored_df = train_and_score_peptide(features_df, initial_positives=15, initial_negatives=200)
+
+
+#fragment-level
+from whisper.fragment_features import feature_engineering_fragment
+from whisper.fragment_train import train_and_score_fragment
+import pandas as pd
+
+
+# Load intensity table
+intensity_df = pd.read_csv("input_intensity_dataset.tsv", sep="\t")
+
+controls = ['EGFP', 'Empty', 'NminiTurbo']
+
+# Run feature engineering
+features_df = feature_engineering_fragment(intensity_df, controls)
+
+# features_df = pd.read_csv("features.csv")
+
+
+# Run scoring and FDR estimation
+scored_df = train_and_score_fragment(features_df, initial_positives=15, initial_negatives=200)
+```
+
+## Output
+
+The final output includes:
+- `predicted_probability`: Probability of each bait–prey interaction being real
+- `FDR`: Estimated false discovery rate
+- `global_cv_flag`: Flag for likely background preys based on variability across all samples
+
+## Tutorial
+
+[Read the full documentation](https://whisper.readthedocs.io/en/latest/)
+
+
+## Citation
+
+This software is authored by: Vesal Kasmaeifar, Kieran R Campbell
+
+Lunenfeld-Tanenbaum Research Institute & University of Toronto

whisper_ppi-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"

whisper_ppi-0.1.0/setup.cfg

@@ -0,0 +1,40 @@
+[metadata]
+name = whisper-ppi
+version = 0.1.0
+author = Vesal Kasmaeifar
+author_email = vesal.kasmaeifar@mail.utoronto.com
+description = Weak Heuristic Inference for Supervisory Protein intERaction mapping for PDB and AP-MS datasets
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/camlab-bioml/whisper
+project_urls = 
+	Documentation = https://whisper.readthedocs.io/en/latest/
+	Source = https://github.com/camlab-bioml/whisper
+license = MIT
+license_files = LICENSE
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+	Intended Audience :: Science/Research
+	Topic :: Scientific/Engineering :: Bio-Informatics
+
+[options]
+package_dir = 
+	= .
+packages = find:
+python_requires = >=3.10
+include_package_data = True
+install_requires = 
+	numpy
+	pandas
+	scikit-learn
+	scipy
+
+[options.packages.find]
+where = .
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

whisper_ppi-0.1.0/setup.py

@@ -0,0 +1,2 @@
+from setuptools import setup
+setup()

whisper_ppi-0.1.0/whisper/__init__.py

@@ -0,0 +1,14 @@
+from .protein_features import feature_engineering_protein as feature_engineering_protein
+from .protein_train import train_and_score_protein as train_and_score_protein
+
+from .peptide_features import feature_engineering_peptide
+from .peptide_train import train_and_score_peptide
+
+from .fragment_features import feature_engineering_fragment
+from .fragment_train import train_and_score_fragment
+
+__all__ = [
+    "feature_engineering_protein", "train_and_score_protein",
+    "feature_engineering_peptide", "train_and_score_peptide",
+    "feature_engineering_fragment", "train_and_score_fragment",
+]

whisper_ppi-0.1.0/whisper/fragment_features.py

@@ -0,0 +1,143 @@
+# whisper/fragment_features.py
+
+import pandas as pd
+import numpy as np
+import re
+from sklearn.preprocessing import StandardScaler
+import warnings
+warnings.filterwarnings("ignore")
+
+
+def feature_engineering_fragment(intensity_df: pd.DataFrame, controls: list) -> pd.DataFrame:
+    """
+    Compute fragment-level features.
+    Mirrors protein/peptide feature engineering but operates on (Protein, Peptide, Fragment).
+
+    Parameters
+    ----------
+    intensity_df : pd.DataFrame
+        Fragment-level intensity matrix with columns:
+        ['Protein', 'Peptide', 'Fragment', <bait/replicate and control columns>]
+    controls : list
+        List of control identifiers (e.g., ["EGFP", "Empty", "NminiTurbo"])
+
+    Returns
+    -------
+    pd.DataFrame
+        Aggregated feature table per bait–(protein, peptide, fragment) with computed metrics.
+    """
+
+    # --- Identify columns ---
+    id_cols = ["Protein", "Peptide", "Fragment"]
+    control_columns = [c for c in intensity_df.columns if any(ctrl in c for ctrl in controls)]
+    sample_columns = [c for c in intensity_df.columns if c not in id_cols]
+    bait_like_columns = [c for c in sample_columns if c not in control_columns]
+    baits = sorted(list(set(col.split("_")[0] for col in bait_like_columns)))
+    intensity_columns = control_columns + [c for c in bait_like_columns if any(b in c for b in baits)]
+
+    # --- Global CV across ALL samples for each fragment (exclude BirA and bait proteins for map) ---
+    global_cv = {}
+    for _, row in intensity_df.iterrows():
+        prot = row["Protein"]
+        vals = row[intensity_columns].astype(float).values
+        mean_all = np.mean(vals)
+        sd_all = np.std(vals)
+        global_cv[(row["Protein"], row["Peptide"], row["Fragment"])] = sd_all / mean_all if mean_all > 0 else 0
+
+    all_bait_features = []
+
+    for bait in baits:
+        bait_columns = [c for c in intensity_df.columns if re.fullmatch(fr"{bait}_\d+", c)]
+        if len(bait_columns) == 0:
+            # skip baits without replicate columns that match the "<bait>_#" pattern
+            continue
+
+        # Exclude the bait's own protein & BirA
+        filtered_df = intensity_df[~intensity_df["Protein"].isin([bait, "birA"])].copy()
+
+        # --- Control summary stats ---
+        ctrl_vals = filtered_df[control_columns].astype(float).values
+        ctrl_means = np.mean(ctrl_vals, axis=1)
+        ctrl_sds = np.std(ctrl_vals, axis=1)
+
+        min_mean_ctrl = np.min(ctrl_means[ctrl_means > 0]) if np.any(ctrl_means > 0) else 1.0
+        min_sd_ctrl = np.min(ctrl_sds[ctrl_sds > 0]) if np.any(ctrl_sds > 0) else 1.0
+
+        features = []
+        for _, row in filtered_df.iterrows():
+            prey_prot = row["Protein"]
+            prey_pep = row["Peptide"]
+            prey_frag = row["Fragment"]
+
+            bait_int = row[bait_columns].astype(float).values
+            ctrl_int = row[control_columns].astype(float).values
+
+            mean_bait = np.mean(bait_int)
+            median_bait = np.median(bait_int)
+            sd_bait = np.std(bait_int)
+
+            mean_ctrl = np.mean(ctrl_int)
+            sd_ctrl = np.std(ctrl_int)
+            mean_ctrl = mean_ctrl if mean_ctrl > 0 else min_mean_ctrl
+            sd_ctrl = sd_ctrl if sd_ctrl > 0 else min_sd_ctrl
+
+            zero_count = np.sum(bait_int == 0)
+            fold_change = mean_bait / mean_ctrl
+            log_fc = np.log2(fold_change + 1e-5)
+            penalized_log_fc = log_fc / max(1, zero_count)
+            snr = mean_bait / sd_ctrl
+            penalized_snr = snr / max(1, zero_count)
+
+            replicate_fc_sd = np.std(bait_int / mean_ctrl)
+            bait_cv = sd_bait / mean_bait if mean_bait != 0 else 0
+            bait_ctrl_sd_ratio = sd_bait / sd_ctrl
+
+            nonzero_reps = int(np.sum(bait_int > 0))
+            reps_above_ctrl_med = int(np.sum(bait_int > np.median(ctrl_int)))
+            single_rep_flag = 1 if nonzero_reps == 1 else 0
+
+            features.append({
+                "Bait": bait,
+                "Protein": prey_prot,
+                "Peptide": prey_pep,
+                "Fragment": prey_frag,
+                "log_fold_change": penalized_log_fc,
+                "snr": penalized_snr,
+                "mean_diff": mean_bait - mean_ctrl,
+                "median_diff": median_bait - np.median(ctrl_int),
+                "replicate_fold_change_sd": replicate_fc_sd,
+                "bait_cv": bait_cv,
+                "bait_control_sd_ratio": bait_ctrl_sd_ratio,
+                "zero_or_neg_fc": 0 if penalized_log_fc <= 0 else 1,
+                "nonzero_reps": nonzero_reps,
+                "reps_above_ctrl_med": reps_above_ctrl_med,
+                "single_rep_flag": single_rep_flag,
+            })
+
+        bait_features = pd.DataFrame(features)
+
+        # --- Scale and composite score (consistent with protein/peptide) ---
+        scale_cols = [
+            "log_fold_change", "snr", "mean_diff", "median_diff",
+            "replicate_fold_change_sd", "bait_cv", "bait_control_sd_ratio",
+            "zero_or_neg_fc",
+        ]
+        scaler = StandardScaler()
+        scaled_df = pd.DataFrame(
+            scaler.fit_transform(bait_features[scale_cols]),
+            columns=scale_cols, index=bait_features.index,
+        )
+
+        bait_features["composite_score"] = scaled_df[
+            ["log_fold_change", "snr", "mean_diff", "median_diff"]
+        ].mean(axis=1)
+
+        bait_features["global_cv"] = bait_features.apply(
+            lambda r: global_cv.get((r["Protein"], r["Peptide"], r["Fragment"]), np.nan), axis=1
+        )
+
+        all_bait_features.append(bait_features.sort_values("composite_score", ascending=False))
+
+    aggregated_features_df = pd.concat(all_bait_features, ignore_index=True)
+    aggregated_features_df.to_csv("features_fragment.csv", index=False)
+    return aggregated_features_df

whisper_ppi-0.1.0/whisper/fragment_train.py

@@ -0,0 +1,175 @@
+# whsiper/fragment_train.py
+
+import os
+import pandas as pd
+import numpy as np
+from sklearn.ensemble import RandomForestClassifier, BaggingClassifier
+from sklearn.preprocessing import StandardScaler
+from scipy.cluster.hierarchy import linkage, fcluster
+import warnings
+warnings.filterwarnings("ignore")
+
+
+def train_and_score_fragment(
+    features_df: pd.DataFrame,
+    initial_positives: int = 15,
+    initial_negatives: int = 200,
+    random_state: int = 42,
+    save_dir: str = ".",
+    fragment_out: str = "whisper_fragment_scores.csv",
+    protein_out: str = "whisper_protein_scores_from_fragments.csv",
+    aggregate_strategy: str = "max",   # "max" or "mean" for fragment->protein prob aggregation
+):
+    """
+    Train a model on FRAGMENT-level features, compute bait-specific decoy FDR,
+    and aggregate to PROTEIN-level scores per bait.
+
+    Expected columns in `features_df`:
+      - Bait, Protein, Peptide, Fragment
+      - composite_score, global_cv (optional), single_rep_flag (optional)
+      - Feature columns:
+          ['log_fold_change','snr','mean_diff','median_diff',
+           'replicate_fold_change_sd','bait_cv','bait_control_sd_ratio','zero_or_neg_fc']
+
+    Saves:
+      - <save_dir>/<fragment_out>: fragment-level scores with FDR
+      - <save_dir>/<protein_out>: protein-level aggregation per bait
+
+    Returns:
+      (fragment_df, protein_df)
+    """
+    rng = np.random.RandomState(random_state)
+
+    # Stable order
+    df = (
+        features_df.copy()
+        .sort_values(["Bait", "Protein", "Peptide", "Fragment"])
+        .reset_index(drop=True)
+    )
+
+    feature_columns = [
+        "log_fold_change", "snr", "mean_diff", "median_diff",
+        "replicate_fold_change_sd", "bait_cv", "bait_control_sd_ratio",
+        "zero_or_neg_fc",
+    ]
+    X = df[feature_columns].values
+
+    # ---------- Cluster baits to identify "strong" set ----------
+    bait_top50_stds = {
+        b: df[df["Bait"] == b]["composite_score"].nlargest(50).std()
+        for b in df["Bait"].unique()
+    }
+    bait_names = np.array(list(bait_top50_stds.keys()))
+    bait_scores = np.array(list(bait_top50_stds.values()), dtype=float).reshape(-1, 1)
+
+    if len(bait_names) > 2:
+        Z = linkage(bait_scores, method="ward")
+        clusters = fcluster(Z, t=2, criterion="maxclust")
+    else:
+        clusters = np.ones(len(bait_names), dtype=int)
+
+    cluster_sizes = {c: int(np.sum(clusters == c)) for c in np.unique(clusters)}
+    cluster_means = {c: float(bait_scores[clusters == c].mean()) for c in np.unique(clusters)}
+    max_size = max(cluster_sizes.values())
+    cands = [c for c, n in cluster_sizes.items() if n == max_size]
+    strong_cluster_id = cands[0] if len(cands) == 1 else max(cands, key=lambda c: cluster_means[c])
+    strong_baits = [b for b, c in zip(bait_names, clusters) if c == strong_cluster_id]
+
+    # ---------- Pseudo-labels ----------
+    y = pd.Series(0, index=df.index)  # 0=unlabeled, 1=pos, -1=neg
+    bait_pos_quota = {b: (initial_positives if b in strong_baits else 0) for b in df["Bait"].unique()}
+
+    for bait in df["Bait"].unique():
+        sub = df[df["Bait"] == bait].copy()
+        n_pos = bait_pos_quota[bait]
+        if n_pos > 0:
+            ranked = sub.sort_values("composite_score", ascending=False)
+            elig = ranked[ranked.get("single_rep_flag", 0) != 1]  # exclude single-rep spikes if present
+            pos_idx = elig.index[:n_pos]
+            y.loc[pos_idx] = 1
+
+            remaining = sub.drop(index=pos_idx, errors="ignore")
+            neg_idx = remaining["composite_score"].nsmallest(initial_negatives).index
+            y.loc[neg_idx] = -1
+
+    labeled_idx = y[y != 0].index
+    X_tr = X[labeled_idx]
+    y_tr = y.loc[labeled_idx].values
+
+    # ---------- Train bagged RF ----------
+    scaler = StandardScaler().fit(X_tr)
+    X_tr_std = scaler.transform(X_tr)
+
+    base = RandomForestClassifier(n_estimators=100, random_state=random_state)
+    clf = BaggingClassifier(estimator=base, n_estimators=100, random_state=random_state)
+    clf.fit(X_tr_std, y_tr)
+
+    X_std = scaler.transform(X)
+    df["predicted_probability"] = clf.predict_proba(X_std)[:, 1]
+
+    # ---------- Bait-specific decoy shuffles for FDR ----------
+    decoys = []
+    for i, bait in enumerate(df["Bait"].unique()):
+        rng_i = np.random.RandomState(random_state + i)
+        sub = df[df["Bait"] == bait].copy()
+        dec = sub[feature_columns].apply(lambda col: rng_i.permutation(col.values))
+        X_dec = scaler.transform(dec.values)
+        decoys.append(clf.predict_proba(X_dec)[:, 1])
+    decoy_probs = np.concatenate(decoys) if len(decoys) else np.array([])
+
+    real_probs = df["predicted_probability"].values
+    unique_p = np.unique(real_probs)
+
+    # raw FDR
+    raw_fdr = {}
+    for p in unique_p:
+        n_real = np.sum(real_probs >= p)
+        n_dec = np.sum(decoy_probs >= p) if decoy_probs.size else 0
+        raw_fdr[p] = min(n_dec / n_real if n_real > 0 else 1.0, 1.0)
+
+    # monotone FDR (non-increasing with prob)
+    sorted_p = np.sort(unique_p)
+    mono_fdr = {sorted_p[0]: raw_fdr[sorted_p[0]]}
+    for i in range(1, len(sorted_p)):
+        p = sorted_p[i]
+        prev = sorted_p[i - 1]
+        mono_fdr[p] = min(raw_fdr[p], mono_fdr[prev])
+
+    df["FDR"] = df["predicted_probability"].map(mono_fdr)
+
+    # ---------- Background flag by global CV (optional) ----------
+    if "global_cv" in df.columns:
+        cv_thresh = np.nanpercentile(df["global_cv"], 25)
+        df["global_cv_flag"] = df["global_cv"].apply(
+            lambda v: "likely background" if pd.notna(v) and v <= cv_thresh else ""
+        )
+    else:
+        df["global_cv_flag"] = ""
+
+    # ===== AGGREGATE TO PROTEIN-LEVEL (per bait) =====
+    prob_agg = "max" if aggregate_strategy.lower() == "max" else "mean"
+
+    grp = df.groupby(["Bait", "Protein"])
+    protein_df = grp.agg(
+        predicted_probability=("predicted_probability", prob_agg),
+        FDR=("FDR", "min"),
+        n_fragments=("Fragment", "count"),
+        n_background=("global_cv_flag", lambda x: (x == "likely background").sum()),
+        mean_cv=("global_cv", "mean"),
+    ).reset_index()
+
+    protein_df["background_flag_protein"] = np.where(
+        protein_df["n_background"] >= 0.5 * protein_df["n_fragments"],
+        "likely background",
+        "",
+    )
+
+    # ----- Save both -----
+    os.makedirs(save_dir, exist_ok=True)
+    fragment_path = os.path.join(save_dir, fragment_out)
+    protein_path = os.path.join(save_dir, protein_out)
+
+    df.to_csv(fragment_path, index=False)
+    protein_df.to_csv(protein_path, index=False)
+
+    return protein_df