represolve 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- represolve/__init__.py +53 -0
- represolve/benchmark.py +119 -0
- represolve/data.py +118 -0
- represolve/density.py +70 -0
- represolve/metrics.py +68 -0
- represolve/models.py +208 -0
- represolve/null.py +75 -0
- represolve/regimes.py +62 -0
- represolve-1.0.0.dist-info/METADATA +136 -0
- represolve-1.0.0.dist-info/RECORD +13 -0
- represolve-1.0.0.dist-info/WHEEL +5 -0
- represolve-1.0.0.dist-info/licenses/LICENSE +21 -0
- represolve-1.0.0.dist-info/top_level.txt +1 -0
represolve/__init__.py
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""represolve: replicate-resolved evaluation for perturbation-response models.
|
|
2
|
+
|
|
3
|
+
Companion framework to the manuscript "represolve: Replicate-resolved
|
|
4
|
+
masked-completion benchmarking reveals regime-dependent model rankings and
|
|
5
|
+
calibrates keloid fibroblast candidates". Provides the fold-frozen masked-completion benchmark,
|
|
6
|
+
nearest-perturbation-centroid and shrinkage baselines, regime-stratified
|
|
7
|
+
ranking, and the permutation/type-I calibration utilities used in the paper.
|
|
8
|
+
"""
|
|
9
|
+
from .metrics import centered_score, neighbour_similarity, pearson, replicate_agreement
|
|
10
|
+
from .models import (
|
|
11
|
+
DAECompletion,
|
|
12
|
+
LinearCompletion,
|
|
13
|
+
MaskedMLPCompletion,
|
|
14
|
+
MoPPCACompletion,
|
|
15
|
+
NearestCentroid,
|
|
16
|
+
SVDCompletion,
|
|
17
|
+
default_models,
|
|
18
|
+
)
|
|
19
|
+
from .density import cosine_knn_density, observed_agreement, route
|
|
20
|
+
from .benchmark import masked_completion_benchmark, summarize
|
|
21
|
+
from .regimes import assign_deciles, bootstrap_ci, decile_ranking
|
|
22
|
+
from .null import bh_qvalues, permutation_null, type1_check
|
|
23
|
+
from .data import DATASETS, HalfDataset, list_datasets, load_halves
|
|
24
|
+
|
|
25
|
+
__version__ = "1.0.0"
|
|
26
|
+
__all__ = [
|
|
27
|
+
"pearson",
|
|
28
|
+
"centered_score",
|
|
29
|
+
"replicate_agreement",
|
|
30
|
+
"neighbour_similarity",
|
|
31
|
+
"SVDCompletion",
|
|
32
|
+
"DAECompletion",
|
|
33
|
+
"MaskedMLPCompletion",
|
|
34
|
+
"LinearCompletion",
|
|
35
|
+
"MoPPCACompletion",
|
|
36
|
+
"NearestCentroid",
|
|
37
|
+
"default_models",
|
|
38
|
+
"masked_completion_benchmark",
|
|
39
|
+
"summarize",
|
|
40
|
+
"assign_deciles",
|
|
41
|
+
"decile_ranking",
|
|
42
|
+
"bootstrap_ci",
|
|
43
|
+
"permutation_null",
|
|
44
|
+
"bh_qvalues",
|
|
45
|
+
"type1_check",
|
|
46
|
+
"DATASETS",
|
|
47
|
+
"HalfDataset",
|
|
48
|
+
"list_datasets",
|
|
49
|
+
"load_halves",
|
|
50
|
+
"cosine_knn_density",
|
|
51
|
+
"observed_agreement",
|
|
52
|
+
"route",
|
|
53
|
+
]
|
represolve/benchmark.py
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""Fold-frozen masked-completion benchmark.
|
|
2
|
+
|
|
3
|
+
The core evaluation loop used in the paper. Given two replicate measurement
|
|
4
|
+
halves of the same perturbations (A and B), perturbations are split into
|
|
5
|
+
K folds; gene selection and all model fitting happen inside each training
|
|
6
|
+
fold, and each held-out perturbation is predicted from a random observed-gene
|
|
7
|
+
mask, then scored against BOTH halves. Comparing the same- half (A) and
|
|
8
|
+
independent-half (B) scores quantifies how much of a benchmark number is
|
|
9
|
+
shared-response recovery versus reproducible target-specific prediction.
|
|
10
|
+
"""
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import numpy as np
|
|
14
|
+
import pandas as pd
|
|
15
|
+
from sklearn.model_selection import KFold
|
|
16
|
+
|
|
17
|
+
from .metrics import pearson, replicate_agreement
|
|
18
|
+
from .models import default_models
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def masked_completion_benchmark(
|
|
22
|
+
half_a: np.ndarray,
|
|
23
|
+
half_b: np.ndarray,
|
|
24
|
+
pert_names: np.ndarray,
|
|
25
|
+
genes: np.ndarray,
|
|
26
|
+
n_folds: int = 5,
|
|
27
|
+
n_genes_selected: int = 5000,
|
|
28
|
+
mask_fraction: float = 0.1,
|
|
29
|
+
mask_seed_base: int = 1000,
|
|
30
|
+
models: list | None = None,
|
|
31
|
+
random_state: int = 0,
|
|
32
|
+
) -> pd.DataFrame:
|
|
33
|
+
"""Run the fold-frozen masked-completion benchmark.
|
|
34
|
+
|
|
35
|
+
Parameters
|
|
36
|
+
----------
|
|
37
|
+
half_a, half_b : (n_perturbations, n_genes) arrays
|
|
38
|
+
Mean expression profiles of the same perturbations measured in two
|
|
39
|
+
independent partitions (e.g. guide halves or cell-pool halves).
|
|
40
|
+
pert_names, genes : (n_perturbations,), (n_genes,) arrays
|
|
41
|
+
n_genes_selected : int
|
|
42
|
+
Number of top-variance genes selected inside each training fold.
|
|
43
|
+
mask_fraction : float
|
|
44
|
+
Fraction of selected genes treated as observed for each test
|
|
45
|
+
perturbation (the paper uses 0.1).
|
|
46
|
+
mask_seed_base : int
|
|
47
|
+
Per-perturbation mask seed = mask_seed_base + perturbation index,
|
|
48
|
+
making masks deterministic and comparable across runs.
|
|
49
|
+
models : list of BaseCompletion, optional
|
|
50
|
+
Defaults to `default_models()` (svd20, lw, moppca5, nn10, nn50).
|
|
51
|
+
|
|
52
|
+
Returns
|
|
53
|
+
-------
|
|
54
|
+
DataFrame with one row per (perturbation, fold): rep_cen plus
|
|
55
|
+
{model}_A_cen and {model}_B_cen centered scores.
|
|
56
|
+
"""
|
|
57
|
+
if models is None:
|
|
58
|
+
models = default_models()
|
|
59
|
+
half_a = np.asarray(half_a, dtype=np.float64)
|
|
60
|
+
half_b = np.asarray(half_b, dtype=np.float64)
|
|
61
|
+
mean_all = (half_a + half_b) / 2.0
|
|
62
|
+
|
|
63
|
+
rows = []
|
|
64
|
+
for fold, (train, test) in enumerate(
|
|
65
|
+
KFold(n_folds, shuffle=True, random_state=random_state).split(pert_names)
|
|
66
|
+
):
|
|
67
|
+
selected = np.argsort(-mean_all[train].var(axis=0), kind="stable")[
|
|
68
|
+
:n_genes_selected
|
|
69
|
+
]
|
|
70
|
+
T = mean_all[np.ix_(train, selected)]
|
|
71
|
+
mu = T.mean(axis=0)
|
|
72
|
+
for m in models:
|
|
73
|
+
m.fit(T)
|
|
74
|
+
|
|
75
|
+
for idx in test:
|
|
76
|
+
observed = (
|
|
77
|
+
np.random.RandomState(mask_seed_base + idx).rand(len(selected))
|
|
78
|
+
< mask_fraction
|
|
79
|
+
)
|
|
80
|
+
hidden = ~observed
|
|
81
|
+
hid_pos = np.flatnonzero(hidden)
|
|
82
|
+
aa = half_a[idx, selected]
|
|
83
|
+
bb = half_b[idx, selected]
|
|
84
|
+
row = {
|
|
85
|
+
"pert": pert_names[idx],
|
|
86
|
+
"fold": fold,
|
|
87
|
+
"n_observed": int(observed.sum()),
|
|
88
|
+
"rep_cen": replicate_agreement(aa[hid_pos], bb[hid_pos], mu[hid_pos]),
|
|
89
|
+
}
|
|
90
|
+
for m in models:
|
|
91
|
+
pred = m.predict(aa, observed)
|
|
92
|
+
row[f"{m.name}_A_cen"] = pearson(
|
|
93
|
+
pred[hid_pos] - mu[hid_pos], aa[hid_pos] - mu[hid_pos]
|
|
94
|
+
)
|
|
95
|
+
row[f"{m.name}_B_cen"] = pearson(
|
|
96
|
+
pred[hid_pos] - mu[hid_pos], bb[hid_pos] - mu[hid_pos]
|
|
97
|
+
)
|
|
98
|
+
rows.append(row)
|
|
99
|
+
return pd.DataFrame(rows)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def summarize(df: pd.DataFrame, models: list | None = None) -> pd.DataFrame:
|
|
103
|
+
"""Per-model mean A-half and B-half centered scores and the A-B gap."""
|
|
104
|
+
model_names = models or [
|
|
105
|
+
c[: -len("_A_cen")] for c in df.columns if c.endswith("_A_cen")
|
|
106
|
+
]
|
|
107
|
+
out = []
|
|
108
|
+
for m in model_names:
|
|
109
|
+
a, b = df[f"{m}_A_cen"], df[f"{m}_B_cen"]
|
|
110
|
+
out.append(
|
|
111
|
+
{
|
|
112
|
+
"model": m,
|
|
113
|
+
"same_half": a.mean(),
|
|
114
|
+
"independent_half": b.mean(),
|
|
115
|
+
"inflation": a.mean() - b.mean(),
|
|
116
|
+
"n": a.notna().sum(),
|
|
117
|
+
}
|
|
118
|
+
)
|
|
119
|
+
return pd.DataFrame(out).sort_values("independent_half", ascending=False)
|
represolve/data.py
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
"""Frozen replicate-half datasets used in the manuscript.
|
|
2
|
+
|
|
3
|
+
Each entry describes one masked-completion benchmark context: two
|
|
4
|
+
independent measurement halves (S[0], S[1]) of the same perturbation
|
|
5
|
+
panel, stored as ``.npz`` with keys ``S`` (2, n_pert, n_genes),
|
|
6
|
+
``N`` (2, n_pert) cell counts, ``perts``, ``genes``.
|
|
7
|
+
|
|
8
|
+
Halves were built by ``j48_build_external_halves.py`` (scPerturb Zenodo
|
|
9
|
+
record 7041849) and the K562 builders described in
|
|
10
|
+
``paper_map/FIGURE_TO_CODE.md``. Checksums are in
|
|
11
|
+
``DATA_MANIFEST.csv`` next to this module.
|
|
12
|
+
"""
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
from dataclasses import dataclass
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
|
|
18
|
+
import numpy as np
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class HalfDataset:
|
|
23
|
+
name: str
|
|
24
|
+
description: str
|
|
25
|
+
split_axis: str # what the two halves separate
|
|
26
|
+
modality: str
|
|
27
|
+
source: str
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
DATASETS = {
|
|
31
|
+
"k562_essential": HalfDataset(
|
|
32
|
+
name="k562_essential",
|
|
33
|
+
description="Replogle Weismann 2022 K562 essential screen, "
|
|
34
|
+
"even/odd gem-group cell-pool halves",
|
|
35
|
+
split_axis="gem_group (cell/lane pools; not donors)",
|
|
36
|
+
modality="CRISPRi",
|
|
37
|
+
source="Replogle et al. 2022, Cell; normalized single-cell h5ad",
|
|
38
|
+
),
|
|
39
|
+
"k562_gwps": HalfDataset(
|
|
40
|
+
name="k562_gwps",
|
|
41
|
+
description="Replogle Weismann 2022 K562 genome-wide "
|
|
42
|
+
"perturb-seq, even/odd gem-group halves",
|
|
43
|
+
split_axis="gem_group (cell/lane pools; not donors)",
|
|
44
|
+
modality="CRISPRi genome-scale",
|
|
45
|
+
source="Replogle et al. 2022, Cell",
|
|
46
|
+
),
|
|
47
|
+
"norman": HalfDataset(
|
|
48
|
+
name="norman",
|
|
49
|
+
description="Norman et al. 2019 combinatorial screen, single-gene "
|
|
50
|
+
"perturbations, odd/even gem-group halves",
|
|
51
|
+
split_axis="gemgroup",
|
|
52
|
+
modality="CRISPRa",
|
|
53
|
+
source="NormanWeissman2019_filtered.h5ad, scPerturb Zenodo 7041849",
|
|
54
|
+
),
|
|
55
|
+
"rpe1": HalfDataset(
|
|
56
|
+
name="rpe1",
|
|
57
|
+
description="Replogle RPE1 screen, odd/even batch halves",
|
|
58
|
+
split_axis="batch (56 batches, odd/even)",
|
|
59
|
+
modality="CRISPRi",
|
|
60
|
+
source="ReplogleWeissman2022_rpe1.h5ad, scPerturb Zenodo 7041849",
|
|
61
|
+
),
|
|
62
|
+
"sciplex3": HalfDataset(
|
|
63
|
+
name="sciplex3",
|
|
64
|
+
description="Srivatsan et al. 2020 sci-Plex3 chemical screen, "
|
|
65
|
+
"rep1/rep2 biological-replicate halves across "
|
|
66
|
+
"drug x dose x cell line",
|
|
67
|
+
split_axis="biological replicate (rep1 vs rep2)",
|
|
68
|
+
modality="chemical perturbation",
|
|
69
|
+
source="SrivatsanTrapnell2020_sciplex3.h5ad, scPerturb Zenodo 7041849",
|
|
70
|
+
),
|
|
71
|
+
"frangieh": HalfDataset(
|
|
72
|
+
name="frangieh",
|
|
73
|
+
description="Frangieh et al. 2021 melanoma CRISPR screen, "
|
|
74
|
+
"guide-level halves",
|
|
75
|
+
split_axis="guide split",
|
|
76
|
+
modality="CRISPR",
|
|
77
|
+
source="Frangieh et al. 2021, Nature Genetics; scPerturb Zenodo 7041849",
|
|
78
|
+
),
|
|
79
|
+
"tian2021i": HalfDataset(
|
|
80
|
+
name="tian2021i",
|
|
81
|
+
description="Tian et al. 2021 CRISPRi screen, odd/even halves",
|
|
82
|
+
split_axis="odd/even split",
|
|
83
|
+
modality="CRISPRi",
|
|
84
|
+
source="Tian et al. 2021; scPerturb Zenodo 7041849",
|
|
85
|
+
),
|
|
86
|
+
"rpe1_e150": HalfDataset(
|
|
87
|
+
name="rpe1_e150",
|
|
88
|
+
description="RPE1 E150 screen, gem-group halves",
|
|
89
|
+
split_axis="gem-group split",
|
|
90
|
+
modality="CRISPRi",
|
|
91
|
+
source="scPerturb Zenodo 7041849",
|
|
92
|
+
),
|
|
93
|
+
"tahoe100m": HalfDataset(
|
|
94
|
+
name="tahoe100m",
|
|
95
|
+
description="Tahoe-100M drug x cell-line context, plate3 "
|
|
96
|
+
"sample-level halves",
|
|
97
|
+
split_axis="sample split",
|
|
98
|
+
modality="chemical perturbation",
|
|
99
|
+
source="Tahoe-100M",
|
|
100
|
+
),
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def load_halves(path: str | Path):
|
|
105
|
+
"""Load a frozen halves npz.
|
|
106
|
+
|
|
107
|
+
Returns (half_a, half_b, perts, genes) with shapes
|
|
108
|
+
(n_pert, n_genes), (n_pert, n_genes), (n_pert,), (n_genes,).
|
|
109
|
+
"""
|
|
110
|
+
z = np.load(path, allow_pickle=True)
|
|
111
|
+
s = np.asarray(z["S"], dtype=np.float64)
|
|
112
|
+
if s.shape[0] != 2:
|
|
113
|
+
raise ValueError(f"expected S with leading axis 2, got {s.shape}")
|
|
114
|
+
return s[0], s[1], np.asarray(z["perts"]), np.asarray(z["genes"])
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def list_datasets() -> list[HalfDataset]:
|
|
118
|
+
return list(DATASETS.values())
|
represolve/density.py
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"""Prediction-time regime diagnostics for routing.
|
|
2
|
+
|
|
3
|
+
`observed_agreement` measures between-half centered agreement on the
|
|
4
|
+
observed-gene mask only — no hidden-gene information — so the screen's
|
|
5
|
+
reliability regime is declarable before hidden-gene scoring.
|
|
6
|
+
|
|
7
|
+
`cosine_knn_density` is a scale-invariant perturbation-density diagnostic:
|
|
8
|
+
the median cosine distance from each perturbation to its k-th nearest
|
|
9
|
+
neighbour on L2-normalised profiles. It is invariant to signal magnitude
|
|
10
|
+
and preprocessing scale, unlike raw Euclidean kNN distance.
|
|
11
|
+
|
|
12
|
+
`route` maps the two diagnostics to the first-generation routing map
|
|
13
|
+
(Table 3 of the manuscript). It is a falsifiable hypothesis, not a fitted
|
|
14
|
+
model: new screens re-score on frozen partitions and update the map.
|
|
15
|
+
"""
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import numpy as np
|
|
19
|
+
|
|
20
|
+
from .metrics import pearson
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def observed_agreement(half_a_obs: np.ndarray, half_b_obs: np.ndarray,
|
|
24
|
+
train_mean: np.ndarray) -> float:
|
|
25
|
+
"""Centered correlation between the two halves on observed genes."""
|
|
26
|
+
return float(pearson(half_a_obs - train_mean, half_b_obs - train_mean))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def cosine_knn_density(train_profiles: np.ndarray, k: int = 10,
|
|
30
|
+
center: bool = True) -> float:
|
|
31
|
+
"""Median cosine distance to the k-th nearest neighbour.
|
|
32
|
+
|
|
33
|
+
train_profiles: (n_perturbations, n_genes) matrix (e.g. the pooled
|
|
34
|
+
two-half mean on the selected genes). Returns a value in [0, 2];
|
|
35
|
+
smaller means a denser perturbation grid.
|
|
36
|
+
"""
|
|
37
|
+
X = np.asarray(train_profiles, dtype=np.float64)
|
|
38
|
+
if center:
|
|
39
|
+
X = X - X.mean(axis=0)
|
|
40
|
+
nrm = np.linalg.norm(X, axis=1, keepdims=True)
|
|
41
|
+
nrm[nrm == 0] = 1.0
|
|
42
|
+
U = X / nrm
|
|
43
|
+
G = U @ U.T
|
|
44
|
+
np.fill_diagonal(G, -np.inf)
|
|
45
|
+
# distance to the k-th nearest neighbour: k-th largest cosine similarity
|
|
46
|
+
# (1-indexed), i.e. element k-1 of the distance partition. argpartition
|
|
47
|
+
# does not sort, so the k-th element must be taken by position, not
|
|
48
|
+
# by slicing an unordered top-k set.
|
|
49
|
+
return float(np.median(np.partition(1.0 - G, k - 1, axis=1)[:, k - 1]))
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def route(obs_agreement: float, cos_density: float | None = None,
|
|
53
|
+
n_perts: int | None = None) -> str:
|
|
54
|
+
"""First-generation routing hypothesis (Table 3), fit on the same
|
|
55
|
+
nine contexts it summarizes — in-sample, falsifiable.
|
|
56
|
+
|
|
57
|
+
Returns one of: 'flag_near_floor', 'centroid_nn50', 'centroid_nn10',
|
|
58
|
+
'nn10_dense_grid', 'lw_shrinkage', 'inherit_design_priors'.
|
|
59
|
+
"""
|
|
60
|
+
if obs_agreement is None:
|
|
61
|
+
return "inherit_design_priors"
|
|
62
|
+
if obs_agreement < 0.05:
|
|
63
|
+
return "flag_near_floor"
|
|
64
|
+
if obs_agreement < 0.15:
|
|
65
|
+
return "centroid_nn50"
|
|
66
|
+
if obs_agreement < 0.8:
|
|
67
|
+
return "centroid_nn10"
|
|
68
|
+
if cos_density is not None and cos_density < 0.05:
|
|
69
|
+
return "nn10_dense_grid"
|
|
70
|
+
return "lw_shrinkage"
|
represolve/metrics.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""Metrics for replicate-resolved perturbation-prediction evaluation.
|
|
2
|
+
|
|
3
|
+
All scores are *per-perturbation* centered Pearson correlations: both the
|
|
4
|
+
prediction and the measurement are expressed as deviations from the training
|
|
5
|
+
mean profile before correlating, so a predictor is credited only for
|
|
6
|
+
perturbation-specific signal, not for recovering shared variation.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import numpy as np
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def pearson(x: np.ndarray, y: np.ndarray) -> float:
|
|
14
|
+
"""Safe Pearson correlation; returns nan on degenerate input."""
|
|
15
|
+
x = np.asarray(x, dtype=np.float64)
|
|
16
|
+
y = np.asarray(y, dtype=np.float64)
|
|
17
|
+
sx = x.std()
|
|
18
|
+
sy = y.std()
|
|
19
|
+
if sx == 0 or sy == 0:
|
|
20
|
+
return float("nan")
|
|
21
|
+
return float(np.corrcoef(x, y)[0, 1])
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def centered_score(pred: np.ndarray, measured: np.ndarray, mu: np.ndarray) -> float:
|
|
25
|
+
"""Centered correlation between a prediction and a measured profile.
|
|
26
|
+
|
|
27
|
+
Parameters
|
|
28
|
+
----------
|
|
29
|
+
pred, measured : (n_genes,) arrays
|
|
30
|
+
mu : (n_genes,) array
|
|
31
|
+
Reference mean profile (e.g. the training-fold mean). Both vectors
|
|
32
|
+
are centered on ``mu`` before correlating.
|
|
33
|
+
"""
|
|
34
|
+
return pearson(pred - mu, measured - mu)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def replicate_agreement(half_a: np.ndarray, half_b: np.ndarray, mu: np.ndarray) -> float:
|
|
38
|
+
"""rep_cen: centered correlation between two replicate measurement halves.
|
|
39
|
+
|
|
40
|
+
This is the empirical reliability axis of the benchmark — the agreement
|
|
41
|
+
between two independent measurement partitions of the *same* perturbation.
|
|
42
|
+
It is a descriptive statistic, not a theoretical prediction ceiling.
|
|
43
|
+
"""
|
|
44
|
+
return pearson(half_a - mu, half_b - mu)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def neighbour_similarity(
|
|
48
|
+
train_profiles: np.ndarray,
|
|
49
|
+
train_mu: np.ndarray,
|
|
50
|
+
obs_pos: np.ndarray,
|
|
51
|
+
test_obs: np.ndarray,
|
|
52
|
+
) -> np.ndarray:
|
|
53
|
+
"""Centered correlation of every training perturbation to the test
|
|
54
|
+
perturbation's observed-gene effect. Used by the nearest-centroid model
|
|
55
|
+
and by coverage-aware analyses.
|
|
56
|
+
|
|
57
|
+
Returns one similarity per training perturbation (-inf where undefined).
|
|
58
|
+
"""
|
|
59
|
+
train_eff = train_profiles[:, obs_pos] - train_mu[obs_pos]
|
|
60
|
+
train_eff = train_eff - train_eff.mean(axis=1, keepdims=True)
|
|
61
|
+
test_eff = test_obs - train_mu[obs_pos]
|
|
62
|
+
test_eff = test_eff - test_eff.mean()
|
|
63
|
+
tn = np.linalg.norm(train_eff, axis=1)
|
|
64
|
+
den = tn * np.linalg.norm(test_eff)
|
|
65
|
+
with np.errstate(invalid="ignore", divide="ignore"):
|
|
66
|
+
out = (train_eff @ test_eff) / den
|
|
67
|
+
out[~np.isfinite(out)] = -np.inf
|
|
68
|
+
return out
|
represolve/models.py
ADDED
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
"""Masked-completion predictors.
|
|
2
|
+
|
|
3
|
+
A predictor is fit once per training fold on the training perturbation
|
|
4
|
+
profiles (perturbations x genes). Given the observed subset of genes for a
|
|
5
|
+
held-out perturbation, it predicts the hidden genes. All predictors return a
|
|
6
|
+
full-length prediction vector; the caller slices hidden positions for scoring.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import numpy as np
|
|
11
|
+
from sklearn.covariance import LedoitWolf
|
|
12
|
+
from sklearn.decomposition import PCA
|
|
13
|
+
from sklearn.mixture import GaussianMixture
|
|
14
|
+
|
|
15
|
+
from .metrics import neighbour_similarity
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class BaseCompletion:
|
|
19
|
+
"""Fit-once / predict-per-perturbation interface."""
|
|
20
|
+
|
|
21
|
+
name = "base"
|
|
22
|
+
|
|
23
|
+
def fit(self, train_profiles: np.ndarray) -> "BaseCompletion":
|
|
24
|
+
raise NotImplementedError
|
|
25
|
+
|
|
26
|
+
def predict(self, observed: np.ndarray, obs_mask: np.ndarray) -> np.ndarray:
|
|
27
|
+
"""observed: full-length profile (only obs_mask positions used).
|
|
28
|
+
obs_mask: boolean array, True = observed gene."""
|
|
29
|
+
raise NotImplementedError
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class SVDCompletion(BaseCompletion):
|
|
33
|
+
"""Low-rank completion via PCA loadings."""
|
|
34
|
+
|
|
35
|
+
def __init__(self, n_components: int = 20, random_state: int = 0):
|
|
36
|
+
self.n_components = n_components
|
|
37
|
+
self.random_state = random_state
|
|
38
|
+
self.name = f"svd{n_components}"
|
|
39
|
+
|
|
40
|
+
def fit(self, T: np.ndarray) -> "SVDCompletion":
|
|
41
|
+
self.mu_ = T.mean(axis=0)
|
|
42
|
+
k = min(self.n_components, min(T.shape) - 1)
|
|
43
|
+
self.W_ = PCA(k, random_state=self.random_state).fit(T).components_.T
|
|
44
|
+
return self
|
|
45
|
+
|
|
46
|
+
def predict(self, observed: np.ndarray, obs_mask: np.ndarray) -> np.ndarray:
|
|
47
|
+
coef = np.linalg.lstsq(
|
|
48
|
+
self.W_[obs_mask], observed[obs_mask] - self.mu_[obs_mask], rcond=None
|
|
49
|
+
)[0]
|
|
50
|
+
return self.mu_ + self.W_ @ coef
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class LinearCompletion(BaseCompletion):
|
|
54
|
+
"""Conditional Gaussian completion with a Ledoit-Wolf covariance."""
|
|
55
|
+
|
|
56
|
+
def __init__(self):
|
|
57
|
+
self.name = "lw"
|
|
58
|
+
|
|
59
|
+
def fit(self, T: np.ndarray) -> "LinearCompletion":
|
|
60
|
+
self.mu_ = T.mean(axis=0)
|
|
61
|
+
self.cov_ = LedoitWolf().fit(T).covariance_
|
|
62
|
+
return self
|
|
63
|
+
|
|
64
|
+
def predict(self, observed: np.ndarray, obs_mask: np.ndarray) -> np.ndarray:
|
|
65
|
+
hid = ~obs_mask
|
|
66
|
+
pred = self.mu_.copy()
|
|
67
|
+
pred[hid] = self.mu_[hid] + self.cov_[np.ix_(hid, obs_mask)] @ np.linalg.solve(
|
|
68
|
+
self.cov_[np.ix_(obs_mask, obs_mask)],
|
|
69
|
+
observed[obs_mask] - self.mu_[obs_mask],
|
|
70
|
+
)
|
|
71
|
+
return pred
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class MoPPCACompletion(BaseCompletion):
|
|
75
|
+
"""Mixture of probabilistic PCA experts (moPPCA)."""
|
|
76
|
+
|
|
77
|
+
def __init__(self, n_components: int = 5, latent_dim: int = 50, expert_dim: int = 10,
|
|
78
|
+
random_state: int = 0):
|
|
79
|
+
self.n_components = n_components
|
|
80
|
+
self.latent_dim = latent_dim
|
|
81
|
+
self.expert_dim = expert_dim
|
|
82
|
+
self.random_state = random_state
|
|
83
|
+
self.name = f"moppca{n_components}"
|
|
84
|
+
|
|
85
|
+
def fit(self, T: np.ndarray) -> "MoPPCACompletion":
|
|
86
|
+
self.mu_ = T.mean(axis=0)
|
|
87
|
+
k = min(self.latent_dim, min(T.shape) - 1)
|
|
88
|
+
self.W50_ = PCA(k, random_state=self.random_state).fit(T).components_.T
|
|
89
|
+
latent = T @ self.W50_
|
|
90
|
+
self.mix_ = GaussianMixture(
|
|
91
|
+
self.n_components, covariance_type="diag", reg_covar=1e-4,
|
|
92
|
+
random_state=self.random_state,
|
|
93
|
+
).fit(latent)
|
|
94
|
+
labels = self.mix_.predict(latent)
|
|
95
|
+
self.experts_ = {
|
|
96
|
+
c: PCA(self.expert_dim, random_state=self.random_state).fit(T[labels == c])
|
|
97
|
+
for c in range(self.n_components)
|
|
98
|
+
if (labels == c).sum() >= 15
|
|
99
|
+
}
|
|
100
|
+
return self
|
|
101
|
+
|
|
102
|
+
def predict(self, observed: np.ndarray, obs_mask: np.ndarray) -> np.ndarray:
|
|
103
|
+
query = np.linalg.lstsq(
|
|
104
|
+
self.W50_[obs_mask], observed[obs_mask] - self.mu_[obs_mask], rcond=None
|
|
105
|
+
)[0]
|
|
106
|
+
weights = self.mix_.predict_proba(query[None])[0]
|
|
107
|
+
weighted = np.zeros_like(self.mu_)
|
|
108
|
+
total = 0.0
|
|
109
|
+
for c, expert in self.experts_.items():
|
|
110
|
+
if weights[c] < 1e-6:
|
|
111
|
+
continue
|
|
112
|
+
W = expert.components_.T
|
|
113
|
+
estimate = expert.mean_ + W @ np.linalg.lstsq(
|
|
114
|
+
W[obs_mask], observed[obs_mask] - expert.mean_[obs_mask], rcond=None
|
|
115
|
+
)[0]
|
|
116
|
+
weighted += weights[c] * estimate
|
|
117
|
+
total += weights[c]
|
|
118
|
+
return weighted / total if total else self.mu_.copy()
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class MaskedMLPCompletion(BaseCompletion):
|
|
122
|
+
"""Nonlinear baseline: masked-input multilayer perceptron (masked-MLP).
|
|
123
|
+
|
|
124
|
+
Trained on augmented training perturbations: each sample is masked with
|
|
125
|
+
n_masks random masks, hidden positions are filled with the training mean,
|
|
126
|
+
and a mask indicator channel is appended. A 256-unit hidden layer, no
|
|
127
|
+
bottleneck — the deep-learning analogue of the completion task.
|
|
128
|
+
"""
|
|
129
|
+
|
|
130
|
+
def __init__(self, hidden_layer_sizes=(256,), n_masks: int = 6,
|
|
131
|
+
mask_fraction: float = 0.1, max_iter: int = 40,
|
|
132
|
+
random_state: int = 0):
|
|
133
|
+
self.hidden_layer_sizes = hidden_layer_sizes
|
|
134
|
+
self.n_masks = n_masks
|
|
135
|
+
self.mask_fraction = mask_fraction
|
|
136
|
+
self.max_iter = max_iter
|
|
137
|
+
self.random_state = random_state
|
|
138
|
+
self.name = "masked_mlp"
|
|
139
|
+
|
|
140
|
+
def fit(self, T: np.ndarray) -> "MaskedMLPCompletion":
|
|
141
|
+
from sklearn.neural_network import MLPRegressor
|
|
142
|
+
|
|
143
|
+
rng = np.random.RandomState(self.random_state)
|
|
144
|
+
self.mu_ = T.mean(axis=0)
|
|
145
|
+
G = T.shape[1]
|
|
146
|
+
reps = np.repeat(T, self.n_masks, axis=0)
|
|
147
|
+
masks = rng.rand(reps.shape[0], G) < self.mask_fraction
|
|
148
|
+
# hidden positions -> training mean
|
|
149
|
+
masked = reps.copy()
|
|
150
|
+
masked[~masks] = np.tile(self.mu_, (reps.shape[0], 1))[~masks]
|
|
151
|
+
X_in = np.concatenate([masked, masks.astype(np.float32)], axis=1).astype(np.float32)
|
|
152
|
+
y = reps.astype(np.float32)
|
|
153
|
+
self.net_ = MLPRegressor(
|
|
154
|
+
hidden_layer_sizes=self.hidden_layer_sizes,
|
|
155
|
+
activation="relu",
|
|
156
|
+
max_iter=self.max_iter,
|
|
157
|
+
early_stopping=True,
|
|
158
|
+
random_state=self.random_state,
|
|
159
|
+
)
|
|
160
|
+
self.net_.fit(X_in, y)
|
|
161
|
+
return self
|
|
162
|
+
|
|
163
|
+
def predict(self, observed: np.ndarray, obs_mask: np.ndarray) -> np.ndarray:
|
|
164
|
+
masked = np.where(obs_mask, observed, self.mu_)
|
|
165
|
+
x = np.concatenate([masked, obs_mask.astype(np.float32)])[None].astype(np.float32)
|
|
166
|
+
return self.net_.predict(x)[0]
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
class NearestCentroid(BaseCompletion):
|
|
170
|
+
"""Nearest-perturbation-centroid baseline.
|
|
171
|
+
|
|
172
|
+
For each held-out perturbation, find the k training perturbations whose
|
|
173
|
+
observed-gene effects are most (centered-)correlated with the test
|
|
174
|
+
observed effect, then predict hidden genes as their centroid.
|
|
175
|
+
"""
|
|
176
|
+
|
|
177
|
+
def __init__(self, k: int = 10):
|
|
178
|
+
self.k = k
|
|
179
|
+
self.name = f"nn{k}"
|
|
180
|
+
|
|
181
|
+
def fit(self, T: np.ndarray) -> "NearestCentroid":
|
|
182
|
+
self.T_ = T
|
|
183
|
+
self.mu_ = T.mean(axis=0)
|
|
184
|
+
return self
|
|
185
|
+
|
|
186
|
+
def predict(self, observed: np.ndarray, obs_mask: np.ndarray) -> np.ndarray:
|
|
187
|
+
obs_pos = np.flatnonzero(obs_mask)
|
|
188
|
+
sims = neighbour_similarity(self.T_, self.mu_, obs_pos, observed[obs_mask])
|
|
189
|
+
nn = np.argsort(-sims, kind="stable")[: self.k]
|
|
190
|
+
pred = self.mu_.copy()
|
|
191
|
+
pred[~obs_mask] = self.T_[nn][:, ~obs_mask].mean(axis=0)
|
|
192
|
+
pred[obs_mask] = observed[obs_mask]
|
|
193
|
+
return pred
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def default_models(nn_ks=(10, 50)) -> list:
|
|
197
|
+
"""The model set used in the paper's fold-frozen benchmarks."""
|
|
198
|
+
models = [
|
|
199
|
+
SVDCompletion(20),
|
|
200
|
+
LinearCompletion(),
|
|
201
|
+
MoPPCACompletion(5),
|
|
202
|
+
]
|
|
203
|
+
models += [NearestCentroid(k) for k in nn_ks]
|
|
204
|
+
return models
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
# Backward-compatible alias for pre-rename notebooks/scripts.
|
|
208
|
+
DAECompletion = MaskedMLPCompletion
|
represolve/null.py
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""Permutation nulls and type-I calibration.
|
|
2
|
+
|
|
3
|
+
Two nulls used in the paper:
|
|
4
|
+
1. Label-permutation null for signature-projection screen scores — permute
|
|
5
|
+
the signature labels to calibrate which screen hits exceed chance.
|
|
6
|
+
2. Synthetic no-signal screens — generate screens where no true signal exists
|
|
7
|
+
and count FDR<0.05 false positives, verifying the permutation procedure
|
|
8
|
+
itself is calibrated (paper: ~6.5% at alpha=0.05 across simulations).
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import numpy as np
|
|
13
|
+
from scipy.stats import false_discovery_control # type: ignore[attr-defined]
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _bh(p: np.ndarray) -> np.ndarray:
|
|
17
|
+
"""Benjamini-Hochberg q-values."""
|
|
18
|
+
try:
|
|
19
|
+
return false_discovery_control(p)
|
|
20
|
+
except Exception:
|
|
21
|
+
order = np.argsort(p)
|
|
22
|
+
q = np.empty_like(p, dtype=float)
|
|
23
|
+
n = len(p)
|
|
24
|
+
ranked = p[order] * n / np.arange(1, n + 1)
|
|
25
|
+
q[order] = np.minimum.accumulate(ranked[::-1])[::-1]
|
|
26
|
+
return np.clip(q, 0, 1)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def permutation_null(observed: np.ndarray, permuted: np.ndarray,
|
|
30
|
+
alternative: str = "two-sided") -> np.ndarray:
|
|
31
|
+
"""Empirical p-values from a permutation distribution.
|
|
32
|
+
|
|
33
|
+
observed : (n_tests,) observed statistics
|
|
34
|
+
permuted : (n_perms, n_tests) or (n_perms,) permutation draws
|
|
35
|
+
"""
|
|
36
|
+
observed = np.asarray(observed, dtype=float)
|
|
37
|
+
permuted = np.asarray(permuted, dtype=float)
|
|
38
|
+
if permuted.ndim == 1:
|
|
39
|
+
permuted = permuted[:, None]
|
|
40
|
+
if alternative == "two-sided":
|
|
41
|
+
extreme = np.abs(permuted) >= np.abs(observed)[None, :]
|
|
42
|
+
elif alternative == "greater":
|
|
43
|
+
extreme = permuted >= observed[None, :]
|
|
44
|
+
else:
|
|
45
|
+
extreme = permuted <= observed[None, :]
|
|
46
|
+
return (extreme.sum(axis=0) + 1) / (permuted.shape[0] + 1)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def bh_qvalues(p: np.ndarray) -> np.ndarray:
|
|
50
|
+
"""Benjamini-Hochberg FDR q-values (alias of _bh for public API)."""
|
|
51
|
+
return _bh(np.asarray(p, dtype=float))
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def type1_check(simulate_screen, n_sims: int = 200, alpha: float = 0.05,
|
|
55
|
+
seed: int = 0) -> dict:
|
|
56
|
+
"""Run `simulate_screen(rng)` under the null and count FDR<alpha hits.
|
|
57
|
+
|
|
58
|
+
`simulate_screen` must return a 1-D array of empirical p-values for a
|
|
59
|
+
no-signal screen. Returns the fraction of simulations with any
|
|
60
|
+
FDR-significant hit and the mean number of false positives.
|
|
61
|
+
"""
|
|
62
|
+
rng = np.random.RandomState(seed)
|
|
63
|
+
any_fp = 0
|
|
64
|
+
total_fp = 0
|
|
65
|
+
for _ in range(n_sims):
|
|
66
|
+
p = np.asarray(simulate_screen(rng), dtype=float)
|
|
67
|
+
fp = int((_bh(p) < alpha).sum())
|
|
68
|
+
any_fp += fp > 0
|
|
69
|
+
total_fp += fp
|
|
70
|
+
return {
|
|
71
|
+
"n_sims": n_sims,
|
|
72
|
+
"alpha": alpha,
|
|
73
|
+
"any_hit_rate": any_fp / n_sims,
|
|
74
|
+
"mean_false_positives": total_fp / n_sims,
|
|
75
|
+
}
|
represolve/regimes.py
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Regime-stratified analysis: model ranking by replicate-agreement decile.
|
|
2
|
+
|
|
3
|
+
The paper's headline analysis: rank perturbations by replicate agreement
|
|
4
|
+
(rep_cen) into deciles, then re-compute per-model independent-half scores
|
|
5
|
+
within each decile. The central finding is that model ranking reverses
|
|
6
|
+
across the detectable-response regime — there is no universally optimal
|
|
7
|
+
model.
|
|
8
|
+
"""
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
import pandas as pd
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def assign_deciles(df: pd.DataFrame, score_col: str = "rep_cen", n: int = 10,
|
|
16
|
+
by_fold: bool = True) -> pd.Series:
|
|
17
|
+
"""Assign each perturbation to a rep_cen decile (within fold if requested)."""
|
|
18
|
+
if by_fold:
|
|
19
|
+
return df.groupby("fold")[score_col].transform(
|
|
20
|
+
lambda s: pd.qcut(s.rank(method="first"), n, labels=False)
|
|
21
|
+
)
|
|
22
|
+
return pd.qcut(df[score_col].rank(method="first"), n, labels=False)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def decile_ranking(df: pd.DataFrame, score_suffix: str = "_B_cen",
|
|
26
|
+
n_deciles: int = 10) -> pd.DataFrame:
|
|
27
|
+
"""Mean independent-half score per model per agreement decile.
|
|
28
|
+
|
|
29
|
+
Returns a long DataFrame: decile, model, mean, sem, n.
|
|
30
|
+
"""
|
|
31
|
+
df = df.copy()
|
|
32
|
+
df["decile"] = assign_deciles(df, n=n_deciles)
|
|
33
|
+
model_cols = [c for c in df.columns if c.endswith(score_suffix)]
|
|
34
|
+
rows = []
|
|
35
|
+
for d, sub in df.groupby("decile"):
|
|
36
|
+
for c in model_cols:
|
|
37
|
+
v = sub[c].dropna()
|
|
38
|
+
rows.append(
|
|
39
|
+
{
|
|
40
|
+
"decile": int(d),
|
|
41
|
+
"model": c[: -len(score_suffix)],
|
|
42
|
+
"mean": v.mean(),
|
|
43
|
+
"sem": v.std() / np.sqrt(max(len(v), 1)),
|
|
44
|
+
"n": len(v),
|
|
45
|
+
}
|
|
46
|
+
)
|
|
47
|
+
return pd.DataFrame(rows)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def bootstrap_ci(df: pd.DataFrame, col_a: str, col_b: str, n_boot: int = 10000,
|
|
51
|
+
seed: int = 0) -> dict:
|
|
52
|
+
"""Paired perturbation bootstrap for the mean difference col_a - col_b."""
|
|
53
|
+
rng = np.random.RandomState(seed)
|
|
54
|
+
d = (df[col_a] - df[col_b]).dropna().to_numpy()
|
|
55
|
+
idx = rng.randint(0, len(d), size=(n_boot, len(d)))
|
|
56
|
+
boot = d[idx].mean(axis=1)
|
|
57
|
+
return {
|
|
58
|
+
"diff": d.mean(),
|
|
59
|
+
"ci_low": np.percentile(boot, 2.5),
|
|
60
|
+
"ci_high": np.percentile(boot, 97.5),
|
|
61
|
+
"n": len(d),
|
|
62
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: represolve
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Replicate-resolved masked-gene completion benchmarking with regime routing
|
|
5
|
+
Author-email: represolve authors <TBD@institution.edu>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/rht888666/represolve
|
|
8
|
+
Project-URL: Issues, https://github.com/rht888666/represolve/issues
|
|
9
|
+
Project-URL: Documentation, https://github.com/rht888666/represolve#readme
|
|
10
|
+
Keywords: single-cell,perturbation,CRISPR,benchmark,masked-gene-completion
|
|
11
|
+
Requires-Python: >=3.10
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Requires-Dist: numpy>=1.24
|
|
15
|
+
Requires-Dist: pandas>=2.0
|
|
16
|
+
Requires-Dist: scipy>=1.10
|
|
17
|
+
Requires-Dist: scikit-learn>=1.3
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# represolve
|
|
21
|
+
|
|
22
|
+
**Replicate-resolved masked-gene completion benchmarking.**
|
|
23
|
+
|
|
24
|
+
Installable companion to the manuscript:
|
|
25
|
+
|
|
26
|
+
> *represolve: Replicate-resolved masked-completion benchmarking reveals
|
|
27
|
+
> regime-dependent model rankings and calibrates keloid fibroblast
|
|
28
|
+
> candidates*
|
|
29
|
+
|
|
30
|
+
`represolve` scores masked-gene completion against an **independent
|
|
31
|
+
replicate measurement half** (held-out guides, cell pools, batches, or
|
|
32
|
+
biological replicates), not against the same partition used as model input.
|
|
33
|
+
It ships fold-frozen splits, SHA-256 manifests, six baselines, prediction-time
|
|
34
|
+
regime routing (`obs_agreement` + `d_cos10`), and a keloid case-study toolkit.
|
|
35
|
+
|
|
36
|
+
## Install
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install represolve # after PyPI publish (v1.0.0)
|
|
40
|
+
# or from a local checkout:
|
|
41
|
+
pip install -e .
|
|
42
|
+
# or conda:
|
|
43
|
+
conda env create -f environment.yml && conda activate represolve
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Requires Python ≥ 3.10. Core dependencies: NumPy, pandas, SciPy, scikit-learn.
|
|
47
|
+
|
|
48
|
+
## 30-second demo
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
python demo/run_demo.py
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
import numpy as np
|
|
56
|
+
from represolve import (
|
|
57
|
+
masked_completion_benchmark, summarize, decile_ranking,
|
|
58
|
+
observed_agreement, cosine_knn_density, route,
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
# half_a, half_b: (n_perturbations, n_genes) mean profiles of the SAME
|
|
62
|
+
# perturbations measured in two independent partitions.
|
|
63
|
+
df = masked_completion_benchmark(half_a, half_b, pert_names, genes)
|
|
64
|
+
print(summarize(df)) # same-half vs independent-half scores
|
|
65
|
+
print(decile_ranking(df)) # ranking by replicate-agreement decile
|
|
66
|
+
|
|
67
|
+
# Prediction-time regime (before hidden-gene scoring)
|
|
68
|
+
obs = observed_agreement(half_a, half_b, mask_frac=0.1, seed=0)
|
|
69
|
+
dcos = cosine_knn_density(half_a)
|
|
70
|
+
print(route(obs_agreement=float(np.nanmedian(obs)), d_cos10=float(dcos)))
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Core API
|
|
74
|
+
|
|
75
|
+
| Symbol | Purpose |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `masked_completion_benchmark` | Fold-frozen masked-gene completion vs two replicate halves |
|
|
78
|
+
| `summarize` / `decile_ranking` / `bootstrap_ci` | Tables and paired bootstrap CIs |
|
|
79
|
+
| `replicate_agreement` / `observed_agreement` | Hidden-half vs prediction-time agreement |
|
|
80
|
+
| `cosine_knn_density` / `route` | Scale-invariant density + first-generation regime router |
|
|
81
|
+
| `SVDCompletion`, `LinearCompletion`, `MoPPCACompletion`, `NearestCentroid`, `MaskedMLPCompletion` | Baselines (`DAECompletion` is kept as an alias of `MaskedMLPCompletion`) |
|
|
82
|
+
| `list_datasets` / `load_halves` | Frozen 9-benchmark + 4-external contexts (arrays archived at Zenodo) |
|
|
83
|
+
| `permutation_null`, `bh_qvalues`, `type1_check` | Screen-null calibration utilities |
|
|
84
|
+
|
|
85
|
+
## Frozen benchmark inputs
|
|
86
|
+
|
|
87
|
+
| Dataset | Split axis | Modality | Perturbations |
|
|
88
|
+
|---|---|---|---|
|
|
89
|
+
| `k562_essential` | gem-group | CRISPRi | 1,777 |
|
|
90
|
+
| `k562_gwps` | gem-group | CRISPRi GWPS | 9,211 |
|
|
91
|
+
| `norman` | gem-group | CRISPRa | 105 |
|
|
92
|
+
| `rpe1` / `rpe1_e150` | batch / gem-group | CRISPRi | 1,487 / 134 |
|
|
93
|
+
| `sciplex3` | biological replicate | chemical | 2,224 |
|
|
94
|
+
| `frangieh` | guide split | Cas9 KO | 233 |
|
|
95
|
+
| `tian2021i` | batch | CRISPRi | 183 |
|
|
96
|
+
| `tahoe_plate3` | sample split | chemical | 145 |
|
|
97
|
+
| External ×4 | gem / wells / batch | HepG2, Jurkat, sci-Plex4, Tian CRISPRa | 96–1,704 |
|
|
98
|
+
|
|
99
|
+
Checksums live in `src/represolve/DATA_MANIFEST.csv`. Large `.npz` arrays are
|
|
100
|
+
archived at Zenodo ([DOI: 10.5281/zenodo.24409221](https://doi.org/10.5281/zenodo.24409221)).
|
|
101
|
+
|
|
102
|
+
## Add your own predictor
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from represolve.models import BaseCompletion # or duck-type fit/predict
|
|
106
|
+
|
|
107
|
+
class MyModel:
|
|
108
|
+
def fit(self, X_train, genes): ...
|
|
109
|
+
def predict(self, x_obs, observed_mask): ...
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Plug into `masked_completion_benchmark(..., models={"mine": MyModel()})`.
|
|
113
|
+
|
|
114
|
+
## Tests & CI
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
python -m pytest tests/ -q # or: python -c "import runpy; runpy.run_path('tests/test_smoke.py')"
|
|
118
|
+
python demo/run_demo.py
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
GitHub Actions workflow: `.github/workflows/ci.yml`.
|
|
122
|
+
|
|
123
|
+
## Scope
|
|
124
|
+
|
|
125
|
+
- Replicate halves are **measurement partitions**, not necessarily donor biology.
|
|
126
|
+
- `rep_cen` is a descriptive reliability statistic, not a theoretical ceiling.
|
|
127
|
+
- This package is an evaluation protocol + baselines, not a new architecture.
|
|
128
|
+
- The keloid analysis is a **calibrated case study**, not a wet-lab-validated target claim.
|
|
129
|
+
|
|
130
|
+
## Citation
|
|
131
|
+
|
|
132
|
+
See `CITATION.cff`. After Zenodo deposition, update the DOI there and in the manuscript Data Availability statement.
|
|
133
|
+
|
|
134
|
+
## License
|
|
135
|
+
|
|
136
|
+
MIT — see `LICENSE`.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
represolve/__init__.py,sha256=0awwctvN7x6KuLkIGqH0_UaUiYEJkb-IzQ_PJHf7q4k,1719
|
|
2
|
+
represolve/benchmark.py,sha256=VfJqej2zVUc1Dgmv44wwdUNCEhI6q6pdEBcr_asHESo,4506
|
|
3
|
+
represolve/data.py,sha256=taYQRepusxPNX8kvs4NgVcEJu44bm0UTtW85Z4LBx4w,4309
|
|
4
|
+
represolve/density.py,sha256=x2Jpq_F9sQc-wdUxM99CKL_X2oeFYw-ffiFmESwNDLo,2898
|
|
5
|
+
represolve/metrics.py,sha256=SkIhTl_c7DQpDU3fN67ODV-lZ8bKV61ZB7wm2sJY7sY,2582
|
|
6
|
+
represolve/models.py,sha256=Uf6cttsJ09LXFR2VbxwLreJVuVWDdor2pbBkBkLiPL8,7943
|
|
7
|
+
represolve/null.py,sha256=AoSXdq4kH1nRob23M_-fqzaLCdZJiIr_cqOLHfvT5hs,2803
|
|
8
|
+
represolve/regimes.py,sha256=MWfMJBq2HeUtHfE-m46GcSvrw9QyZLjafKO61JK7984,2340
|
|
9
|
+
represolve-1.0.0.dist-info/licenses/LICENSE,sha256=qwhLpV87j3t5Q4IxKKIKpS8ViRw0P04pttqPdWgLdD4,1100
|
|
10
|
+
represolve-1.0.0.dist-info/METADATA,sha256=VNHJfSVyOB3fIFK1fdLj6NMcWY5wJAAz8ZiNX__cxa8,5134
|
|
11
|
+
represolve-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
12
|
+
represolve-1.0.0.dist-info/top_level.txt,sha256=XItt9HJiSXdda8XGh-rv2AZzSUnjensnsiUPxklLRGQ,11
|
|
13
|
+
represolve-1.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 scar_benchmark authors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
represolve
|