represolve 1.0.0__tar.gz

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.
@@ -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,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,117 @@
1
+ # represolve
2
+
3
+ **Replicate-resolved masked-gene completion benchmarking.**
4
+
5
+ Installable companion to the manuscript:
6
+
7
+ > *represolve: Replicate-resolved masked-completion benchmarking reveals
8
+ > regime-dependent model rankings and calibrates keloid fibroblast
9
+ > candidates*
10
+
11
+ `represolve` scores masked-gene completion against an **independent
12
+ replicate measurement half** (held-out guides, cell pools, batches, or
13
+ biological replicates), not against the same partition used as model input.
14
+ It ships fold-frozen splits, SHA-256 manifests, six baselines, prediction-time
15
+ regime routing (`obs_agreement` + `d_cos10`), and a keloid case-study toolkit.
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ pip install represolve # after PyPI publish (v1.0.0)
21
+ # or from a local checkout:
22
+ pip install -e .
23
+ # or conda:
24
+ conda env create -f environment.yml && conda activate represolve
25
+ ```
26
+
27
+ Requires Python ≥ 3.10. Core dependencies: NumPy, pandas, SciPy, scikit-learn.
28
+
29
+ ## 30-second demo
30
+
31
+ ```bash
32
+ python demo/run_demo.py
33
+ ```
34
+
35
+ ```python
36
+ import numpy as np
37
+ from represolve import (
38
+ masked_completion_benchmark, summarize, decile_ranking,
39
+ observed_agreement, cosine_knn_density, route,
40
+ )
41
+
42
+ # half_a, half_b: (n_perturbations, n_genes) mean profiles of the SAME
43
+ # perturbations measured in two independent partitions.
44
+ df = masked_completion_benchmark(half_a, half_b, pert_names, genes)
45
+ print(summarize(df)) # same-half vs independent-half scores
46
+ print(decile_ranking(df)) # ranking by replicate-agreement decile
47
+
48
+ # Prediction-time regime (before hidden-gene scoring)
49
+ obs = observed_agreement(half_a, half_b, mask_frac=0.1, seed=0)
50
+ dcos = cosine_knn_density(half_a)
51
+ print(route(obs_agreement=float(np.nanmedian(obs)), d_cos10=float(dcos)))
52
+ ```
53
+
54
+ ## Core API
55
+
56
+ | Symbol | Purpose |
57
+ |---|---|
58
+ | `masked_completion_benchmark` | Fold-frozen masked-gene completion vs two replicate halves |
59
+ | `summarize` / `decile_ranking` / `bootstrap_ci` | Tables and paired bootstrap CIs |
60
+ | `replicate_agreement` / `observed_agreement` | Hidden-half vs prediction-time agreement |
61
+ | `cosine_knn_density` / `route` | Scale-invariant density + first-generation regime router |
62
+ | `SVDCompletion`, `LinearCompletion`, `MoPPCACompletion`, `NearestCentroid`, `MaskedMLPCompletion` | Baselines (`DAECompletion` is kept as an alias of `MaskedMLPCompletion`) |
63
+ | `list_datasets` / `load_halves` | Frozen 9-benchmark + 4-external contexts (arrays archived at Zenodo) |
64
+ | `permutation_null`, `bh_qvalues`, `type1_check` | Screen-null calibration utilities |
65
+
66
+ ## Frozen benchmark inputs
67
+
68
+ | Dataset | Split axis | Modality | Perturbations |
69
+ |---|---|---|---|
70
+ | `k562_essential` | gem-group | CRISPRi | 1,777 |
71
+ | `k562_gwps` | gem-group | CRISPRi GWPS | 9,211 |
72
+ | `norman` | gem-group | CRISPRa | 105 |
73
+ | `rpe1` / `rpe1_e150` | batch / gem-group | CRISPRi | 1,487 / 134 |
74
+ | `sciplex3` | biological replicate | chemical | 2,224 |
75
+ | `frangieh` | guide split | Cas9 KO | 233 |
76
+ | `tian2021i` | batch | CRISPRi | 183 |
77
+ | `tahoe_plate3` | sample split | chemical | 145 |
78
+ | External ×4 | gem / wells / batch | HepG2, Jurkat, sci-Plex4, Tian CRISPRa | 96–1,704 |
79
+
80
+ Checksums live in `src/represolve/DATA_MANIFEST.csv`. Large `.npz` arrays are
81
+ archived at Zenodo ([DOI: 10.5281/zenodo.24409221](https://doi.org/10.5281/zenodo.24409221)).
82
+
83
+ ## Add your own predictor
84
+
85
+ ```python
86
+ from represolve.models import BaseCompletion # or duck-type fit/predict
87
+
88
+ class MyModel:
89
+ def fit(self, X_train, genes): ...
90
+ def predict(self, x_obs, observed_mask): ...
91
+ ```
92
+
93
+ Plug into `masked_completion_benchmark(..., models={"mine": MyModel()})`.
94
+
95
+ ## Tests & CI
96
+
97
+ ```bash
98
+ python -m pytest tests/ -q # or: python -c "import runpy; runpy.run_path('tests/test_smoke.py')"
99
+ python demo/run_demo.py
100
+ ```
101
+
102
+ GitHub Actions workflow: `.github/workflows/ci.yml`.
103
+
104
+ ## Scope
105
+
106
+ - Replicate halves are **measurement partitions**, not necessarily donor biology.
107
+ - `rep_cen` is a descriptive reliability statistic, not a theoretical ceiling.
108
+ - This package is an evaluation protocol + baselines, not a new architecture.
109
+ - The keloid analysis is a **calibrated case study**, not a wet-lab-validated target claim.
110
+
111
+ ## Citation
112
+
113
+ See `CITATION.cff`. After Zenodo deposition, update the DOI there and in the manuscript Data Availability statement.
114
+
115
+ ## License
116
+
117
+ MIT — see `LICENSE`.
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "represolve"
7
+ version = "1.0.0"
8
+ description = "Replicate-resolved masked-gene completion benchmarking with regime routing"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "represolve authors", email = "TBD@institution.edu" }]
13
+ keywords = [
14
+ "single-cell",
15
+ "perturbation",
16
+ "CRISPR",
17
+ "benchmark",
18
+ "masked-gene-completion",
19
+ ]
20
+ dependencies = [
21
+ "numpy>=1.24",
22
+ "pandas>=2.0",
23
+ "scipy>=1.10",
24
+ "scikit-learn>=1.3",
25
+ ]
26
+
27
+ [project.urls]
28
+ Homepage = "https://github.com/rht888666/represolve"
29
+ Issues = "https://github.com/rht888666/represolve/issues"
30
+ Documentation = "https://github.com/rht888666/represolve#readme"
31
+
32
+ [tool.setuptools.packages.find]
33
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ ]
@@ -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)
@@ -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())
@@ -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"
@@ -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
@@ -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
@@ -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
+ }
@@ -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,17 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/represolve/__init__.py
5
+ src/represolve/benchmark.py
6
+ src/represolve/data.py
7
+ src/represolve/density.py
8
+ src/represolve/metrics.py
9
+ src/represolve/models.py
10
+ src/represolve/null.py
11
+ src/represolve/regimes.py
12
+ src/represolve.egg-info/PKG-INFO
13
+ src/represolve.egg-info/SOURCES.txt
14
+ src/represolve.egg-info/dependency_links.txt
15
+ src/represolve.egg-info/requires.txt
16
+ src/represolve.egg-info/top_level.txt
17
+ tests/test_smoke.py
@@ -0,0 +1,4 @@
1
+ numpy>=1.24
2
+ pandas>=2.0
3
+ scipy>=1.10
4
+ scikit-learn>=1.3
@@ -0,0 +1 @@
1
+ represolve
@@ -0,0 +1,75 @@
1
+ """Synthetic smoke test: construct two correlated replicate halves of
2
+ perturbation profiles and check the benchmark runs end-to-end."""
3
+ import numpy as np
4
+
5
+ from represolve import (
6
+ masked_completion_benchmark,
7
+ summarize,
8
+ decile_ranking,
9
+ bootstrap_ci,
10
+ bh_qvalues,
11
+ permutation_null,
12
+ type1_check,
13
+ )
14
+
15
+
16
+ def make_toy(n_pert=60, n_genes=300, seed=0):
17
+ rng = np.random.RandomState(seed)
18
+ latent = rng.randn(n_pert, n_genes) * 0.3
19
+ a = latent + rng.randn(n_pert, n_genes) * 0.7
20
+ b = latent + rng.randn(n_pert, n_genes) * 0.7
21
+ perts = np.array([f"pert{i}" for i in range(n_pert)])
22
+ genes = np.array([f"g{j}" for j in range(n_genes)])
23
+ return a, b, perts, genes
24
+
25
+
26
+ def test_end_to_end():
27
+ a, b, perts, genes = make_toy()
28
+ df = masked_completion_benchmark(
29
+ a, b, perts, genes, n_folds=3, n_genes_selected=200
30
+ )
31
+ assert len(df) == len(perts)
32
+ s = summarize(df)
33
+ assert set(s.columns) == {"model", "same_half", "independent_half", "inflation", "n"}
34
+ assert "rep_cen" in df.columns
35
+
36
+
37
+ def test_decile_and_bootstrap():
38
+ a, b, perts, genes = make_toy()
39
+ df = masked_completion_benchmark(a, b, perts, genes, n_folds=3, n_genes_selected=200)
40
+ dr = decile_ranking(df, n_deciles=5)
41
+ assert {"decile", "model", "mean", "sem", "n"} <= set(dr.columns)
42
+ ci = bootstrap_ci(df, "nn10_B_cen", "svd20_B_cen", n_boot=200)
43
+ assert ci["ci_low"] <= ci["diff"] <= ci["ci_high"]
44
+
45
+
46
+ def test_nulls():
47
+ rng = np.random.RandomState(0)
48
+ obs = rng.randn(50)
49
+ perm = rng.randn(1000, 50)
50
+ p = permutation_null(obs, perm)
51
+ assert p.shape == (50,)
52
+ q = bh_qvalues(p)
53
+ assert q.shape == (50,)
54
+
55
+ def sim(r):
56
+ return r.uniform(0, 1, size=30)
57
+
58
+ res = type1_check(sim, n_sims=20)
59
+ assert 0 <= res["any_hit_rate"] <= 1
60
+
61
+
62
+ def test_load_halves(tmp_path):
63
+ import numpy as np
64
+ from represolve.data import load_halves, list_datasets
65
+
66
+ a, b, perts, genes = make_toy(n_pert=10, n_genes=20)
67
+ path = tmp_path / "toy_halves.npz"
68
+ np.savez(path, S=np.stack([a, b]).astype(np.float32),
69
+ N=np.array([[10] * 10, [10] * 10]),
70
+ perts=perts, genes=genes)
71
+ ha, hb, hp, hg = load_halves(path)
72
+ assert ha.shape == a.shape and np.allclose(ha, a)
73
+ assert list(hp) == list(perts)
74
+ names = [d.name for d in list_datasets()]
75
+ assert "sciplex3" in names and "k562_gwps" in names