gene-edit-check 0.3.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.
Files changed (44) hide show
  1. gene_edit_check/__init__.py +7 -0
  2. gene_edit_check/adata_utils.py +42 -0
  3. gene_edit_check/ag_backend/__init__.py +4 -0
  4. gene_edit_check/ag_backend/live_client.py +339 -0
  5. gene_edit_check/ag_backend/protocol.py +102 -0
  6. gene_edit_check/ag_backend/simulator.py +173 -0
  7. gene_edit_check/agent/__init__.py +1 -0
  8. gene_edit_check/agent/reflexion_loop.py +429 -0
  9. gene_edit_check/benchmarks/__init__.py +1 -0
  10. gene_edit_check/benchmarks/hazard_coupling.py +319 -0
  11. gene_edit_check/benchmarks/state_fidelity.py +81 -0
  12. gene_edit_check/benchmarks/universality.py +341 -0
  13. gene_edit_check/budget.py +93 -0
  14. gene_edit_check/cache.py +79 -0
  15. gene_edit_check/cli.py +629 -0
  16. gene_edit_check/conditions.py +232 -0
  17. gene_edit_check/crispr/__init__.py +1 -0
  18. gene_edit_check/crispr/constraints.py +175 -0
  19. gene_edit_check/crispr/motifs.py +50 -0
  20. gene_edit_check/data/ag2_supported_conditions.tsv.gz +0 -0
  21. gene_edit_check/datasets/__init__.py +0 -0
  22. gene_edit_check/datasets/crc_pelka.py +166 -0
  23. gene_edit_check/datasets/generic_h5ad.py +364 -0
  24. gene_edit_check/mcp_server/server.py +88 -0
  25. gene_edit_check/models.py +288 -0
  26. gene_edit_check/paths.py +51 -0
  27. gene_edit_check/pipeline.py +130 -0
  28. gene_edit_check/provenance.py +29 -0
  29. gene_edit_check/sc_sketch/__init__.py +1 -0
  30. gene_edit_check/sc_sketch/coreset.py +101 -0
  31. gene_edit_check/sc_sketch/sketch_variance.py +152 -0
  32. gene_edit_check/scenarios/__init__.py +1 -0
  33. gene_edit_check/scenarios/registry.py +344 -0
  34. gene_edit_check/ui/__init__.py +1 -0
  35. gene_edit_check/ui/plots.py +409 -0
  36. gene_edit_check/ui/terminal_hud.py +239 -0
  37. gene_edit_check/verifier/__init__.py +1 -0
  38. gene_edit_check/verifier/off_tissue.py +80 -0
  39. gene_edit_check/verifier/two_tier.py +292 -0
  40. gene_edit_check-0.3.0.dist-info/METADATA +237 -0
  41. gene_edit_check-0.3.0.dist-info/RECORD +44 -0
  42. gene_edit_check-0.3.0.dist-info/WHEEL +4 -0
  43. gene_edit_check-0.3.0.dist-info/entry_points.txt +3 -0
  44. gene_edit_check-0.3.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,7 @@
1
+ """gene-edit-check: Two-tier single-cell selectivity & sequence-hazard verifier
2
+ and gradient-guided CRISPR base-editing optimizer for AlphaGenome 2.
3
+
4
+ Research-Use-Only (RUO): Not validated for clinical or diagnostic use.
5
+ """
6
+
7
+ __version__ = "0.3.0"
@@ -0,0 +1,42 @@
1
+ """Sparse-safe helpers shared by the live client, simulator and sketcher."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+
7
+ import anndata
8
+ import numpy as np
9
+ import scipy.sparse as sp
10
+
11
+
12
+ def counts_fingerprint(adata: anndata.AnnData) -> str:
13
+ """Content hash of the count matrix + gene IDs (dense or sparse, order-independent of storage)."""
14
+ h = hashlib.sha256()
15
+ x = adata.X
16
+ # Canonicalise to CSR so dense and sparse copies of the same counts share a cache key.
17
+ x = sp.csr_matrix(x) if not sp.issparse(x) else x.tocsr()
18
+ x.sum_duplicates()
19
+ x.eliminate_zeros()
20
+ x.sort_indices()
21
+ h.update(np.asarray(x.data, dtype=np.int32).tobytes())
22
+ h.update(np.asarray(x.indices, dtype=np.int32).tobytes())
23
+ h.update(np.asarray(x.indptr, dtype=np.int64).tobytes())
24
+ h.update(str(adata.shape).encode("utf-8"))
25
+ h.update("|".join(map(str, adata.var_names)).encode("utf-8"))
26
+ return h.hexdigest()
27
+
28
+
29
+ def dense_counts(adata: anndata.AnnData, dtype: type = np.float32) -> np.ndarray:
30
+ x = adata.X
31
+ return (x.toarray() if sp.issparse(x) else np.asarray(x)).astype(dtype, copy=False)
32
+
33
+
34
+ def drop_unexpressed_genes(adata: anndata.AnnData) -> anndata.AnnData:
35
+ """Remove genes with zero counts in every cell.
36
+
37
+ Lossless for conditioning: library size and every non-zero count are unchanged, it only
38
+ shrinks the request payload (e.g. 38k -> ~10k genes for a 128-cell sketch).
39
+ """
40
+ x = adata.X
41
+ n_cells_expressing = np.asarray((x > 0).sum(axis=0)).ravel()
42
+ return adata[:, n_cells_expressing > 0].copy()
@@ -0,0 +1,4 @@
1
+ """AlphaGenome 2 Backend Package (`ag_backend`).
2
+
3
+ Named `ag_backend` so it never shadows `import alphagenome`.
4
+ """
@@ -0,0 +1,339 @@
1
+ """Live AlphaGenome 2 Backend (`ag_backend/live_client.py`).
2
+
3
+ Wraps `alphagenome.models.v2.dna_client.DnaClient` with:
4
+ - Content-addressed SQLite disk caching (`cache.py`)
5
+ - Strict API & ISM window budget enforcement (`budget.py`)
6
+ - Exact GRCh38 sequence recovery from `InputGradientsOutput.gradients` one-hot channels
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import anndata
12
+ import numpy as np
13
+
14
+ from alphagenome.data import genome
15
+ from alphagenome.models.v2 import dna_client, dna_output, model_condition, variant_scorers
16
+
17
+ from gene_edit_check.ag_backend.protocol import (
18
+ GradientProfile,
19
+ VariantMultiModalScore,
20
+ VerifierBackend,
21
+ )
22
+ from gene_edit_check.adata_utils import counts_fingerprint
23
+ from gene_edit_check.budget import RunBudgetTracker
24
+ from gene_edit_check.cache import ContentAddressedCache
25
+ from gene_edit_check.models import BackendMode, GenomicInterval, SingleNucleotideVariant
26
+
27
+ CHANNEL_TO_BASE = {0: "A", 1: "C", 2: "G", 3: "T"}
28
+
29
+
30
+ def _hash_anndata_counts(adata: anndata.AnnData) -> str:
31
+ return counts_fingerprint(adata)
32
+
33
+
34
+ def recover_reference_sequence_from_gradients(gradients_4ch: np.ndarray) -> str:
35
+ """Recover exact GRCh38 DNA sequence from `InputGradientsOutput.gradients` (shape `[L, 4]`).
36
+
37
+ In AlphaGenome 2, `gradients` is `grad * one_hot_sequence`, so only the reference base
38
+ channel (`0=A, 1=C, 2=G, 3=T`) is non-zero at each position (N-padded regions are all 0).
39
+ """
40
+ abs_g = np.abs(gradients_4ch)
41
+ max_vals = np.max(abs_g, axis=-1)
42
+ arg_max = np.argmax(abs_g, axis=-1)
43
+ chars = [
44
+ CHANNEL_TO_BASE[int(ch)] if val > 0.0 else "N"
45
+ for ch, val in zip(arg_max, max_vals)
46
+ ]
47
+ return "".join(chars)
48
+
49
+
50
+ class LiveAlphaGenomeBackend(VerifierBackend):
51
+ def __init__(
52
+ self,
53
+ api_key: str,
54
+ budget: RunBudgetTracker,
55
+ cache: ContentAddressedCache,
56
+ ) -> None:
57
+ self._client = dna_client.create(api_key)
58
+ self._budget = budget
59
+ self._cache = cache
60
+ self._model_version = "alphagenome-2.0.0-all_folds"
61
+
62
+ @property
63
+ def backend_mode(self) -> BackendMode:
64
+ return BackendMode.LIVE_ALPHAGENOME_V2
65
+
66
+ @property
67
+ def model_version(self) -> str:
68
+ return self._model_version
69
+
70
+ def encode_cells(self, adata: anndata.AnnData, state_name: str) -> np.ndarray:
71
+ cond_hash = _hash_anndata_counts(adata)
72
+ key = self._cache.make_key("encode_cells", str(adata.shape), cond_hash, "CELL_EMBEDDINGS")
73
+ cached = self._cache.get(key)
74
+ if cached is not None:
75
+ self._budget.record_cache_hit()
76
+ return np.asarray(cached["embeddings"], dtype=np.float32)
77
+
78
+ self._budget.check_and_record_encode_cells(adata.shape[0])
79
+ emb = self._client.encode_cells(adata, progress_bar=False)
80
+ self._cache.put(key, "encode_cells", {"embeddings": emb.tolist()})
81
+ return np.asarray(emb, dtype=np.float32)
82
+
83
+ def compute_interval_gradients(
84
+ self,
85
+ gene_id: str,
86
+ gene_symbol: str,
87
+ cell_sketch: anndata.AnnData,
88
+ condition_name: str,
89
+ sequence_length: int = dna_client.SEQUENCE_LENGTH_100KB,
90
+ ) -> GradientProfile:
91
+ self._budget.check_conditioning_size(cell_sketch.shape[0])
92
+ cond_hash = _hash_anndata_counts(cell_sketch)
93
+ key = self._cache.make_key(
94
+ "predict_interval_gradients",
95
+ f"{gene_id}:{sequence_length}",
96
+ cond_hash,
97
+ "SC_GENE_EXPRESSION_DENOISED",
98
+ )
99
+ cached = self._cache.get(key)
100
+ if cached is not None:
101
+ self._budget.record_cache_hit()
102
+ return GradientProfile(
103
+ gene_id=cached["gene_id"],
104
+ gene_name=cached["gene_name"],
105
+ condition_name=condition_name,
106
+ interval=GenomicInterval(**cached["interval"]),
107
+ reference_sequence=cached["reference_sequence"],
108
+ signed_gradients_1bp=np.asarray(cached["signed_gradients_1bp"], dtype=np.float32),
109
+ scalar_score=float(cached["scalar_score"]),
110
+ )
111
+
112
+ self._budget.check_and_record_gradient_call(1)
113
+ out = self._client.predict_interval_gradients(
114
+ gene_id=gene_id,
115
+ requested_output=dna_output.OutputType.SC_GENE_EXPRESSION_DENOISED,
116
+ sequence_length=sequence_length,
117
+ cell_conditioning=cell_sketch,
118
+ cell_condition_name=condition_name,
119
+ )
120
+ ref_seq = recover_reference_sequence_from_gradients(out.gradients)
121
+ signed_1bp = out.gradients.sum(axis=-1).astype(np.float32)
122
+ iv = GenomicInterval(
123
+ chromosome=out.interval.chromosome,
124
+ start=int(out.interval.start),
125
+ end=int(out.interval.end),
126
+ )
127
+ payload = {
128
+ "gene_id": out.gene_id,
129
+ "gene_name": out.gene_name or gene_symbol,
130
+ "interval": iv.model_dump(),
131
+ "reference_sequence": ref_seq,
132
+ "signed_gradients_1bp": signed_1bp.tolist(),
133
+ "scalar_score": float(out.scalar_score),
134
+ }
135
+ self._cache.put(key, "predict_interval_gradients", payload)
136
+ return GradientProfile(
137
+ gene_id=out.gene_id,
138
+ gene_name=out.gene_name or gene_symbol,
139
+ condition_name=condition_name,
140
+ interval=iv,
141
+ reference_sequence=ref_seq,
142
+ signed_gradients_1bp=signed_1bp,
143
+ scalar_score=float(out.scalar_score),
144
+ )
145
+
146
+ def score_ism_window(
147
+ self,
148
+ parent_interval: GenomicInterval,
149
+ ism_window: GenomicInterval,
150
+ gene_id: str,
151
+ cell_sketch: anndata.AnnData,
152
+ condition_name: str,
153
+ ) -> dict[tuple[int, str, str], float]:
154
+ self._budget.check_conditioning_size(cell_sketch.shape[0])
155
+ window_bp = ism_window.width
156
+ n_variants = window_bp * 3
157
+ cond_hash = _hash_anndata_counts(cell_sketch)
158
+ iv_str = f"{parent_interval.chromosome}:{parent_interval.start}-{parent_interval.end}|{ism_window.start}-{ism_window.end}"
159
+ key = self._cache.make_key(
160
+ "score_ism_variants",
161
+ iv_str,
162
+ cond_hash,
163
+ f"SC_GENE_EXPRESSION_DENOISED:{gene_id}",
164
+ )
165
+ cached = self._cache.get(key)
166
+ if cached is not None:
167
+ self._budget.record_cache_hit()
168
+ return {
169
+ (int(item["pos"]), str(item["ref"]), str(item["alt"])): float(item["lfc"])
170
+ for item in cached["ism_scores"]
171
+ }
172
+
173
+ self._budget.check_and_record_ism_window(window_bp=window_bp, n_variants=n_variants)
174
+ ag_parent = genome.Interval(
175
+ chromosome=parent_interval.chromosome,
176
+ start=parent_interval.start,
177
+ end=parent_interval.end,
178
+ )
179
+ ag_ism = genome.Interval(
180
+ chromosome=ism_window.chromosome,
181
+ start=ism_window.start,
182
+ end=ism_window.end,
183
+ )
184
+ sc_scorer = variant_scorers.RECOMMENDED_VARIANT_SCORERS["SC_GENE_EXPRESSION_DENOISED"]
185
+ ism_tables = self._client.score_ism_variants(
186
+ interval=ag_parent,
187
+ ism_interval=ag_ism,
188
+ variant_scorers=[sc_scorer],
189
+ cell_conditioning=cell_sketch,
190
+ cell_condition_name=condition_name,
191
+ progress_bar=False,
192
+ )
193
+ out_map: dict[tuple[int, str, str], float] = {}
194
+ serialized_items = []
195
+ clean_target = gene_id.split(".")[0]
196
+ for variant_list in ism_tables:
197
+ tbl = variant_list[0]
198
+ var_obj = tbl.uns["variant"]
199
+ # Find row matching target gene_id
200
+ gene_col = tbl.obs["gene_id"].astype(str).str.split(".").str[0]
201
+ match_rows = np.where(gene_col == clean_target)[0]
202
+ row_idx = int(match_rows[0]) if len(match_rows) > 0 else 0
203
+ lfc_val = float(np.asarray(tbl.X)[row_idx, 0])
204
+ k_tuple = (int(var_obj.position), str(var_obj.reference_bases), str(var_obj.alternate_bases))
205
+ out_map[k_tuple] = lfc_val
206
+ serialized_items.append(
207
+ {
208
+ "pos": int(var_obj.position),
209
+ "ref": str(var_obj.reference_bases),
210
+ "alt": str(var_obj.alternate_bases),
211
+ "lfc": lfc_val,
212
+ }
213
+ )
214
+ self._cache.put(key, "score_ism_variants", {"ism_scores": serialized_items})
215
+ return out_map
216
+
217
+ def score_variant_multimodal(
218
+ self,
219
+ parent_interval: GenomicInterval,
220
+ variant: SingleNucleotideVariant,
221
+ gene_id: str,
222
+ cell_sketch: anndata.AnnData | None,
223
+ condition_name: str,
224
+ reference_curies: list[str] | None = None,
225
+ ) -> VariantMultiModalScore:
226
+ if cell_sketch is not None:
227
+ self._budget.check_conditioning_size(cell_sketch.shape[0])
228
+ cond_hash = _hash_anndata_counts(cell_sketch)
229
+ scorers = [
230
+ variant_scorers.RECOMMENDED_VARIANT_SCORERS["SC_GENE_EXPRESSION_DENOISED"],
231
+ variant_scorers.MethylationScorer(width=1201),
232
+ variant_scorers.SpliceJunctionScorer(),
233
+ ]
234
+ req_str = f"SC_EXPR+METH+SPLICE:{gene_id}"
235
+ else:
236
+ curies = reference_curies or ["UBERON:0000178", "CL:0000625"]
237
+ cond_hash = "_".join(curies)
238
+ scorers = [
239
+ variant_scorers.RECOMMENDED_VARIANT_SCORERS["RNA_SEQ"],
240
+ variant_scorers.MethylationScorer(width=1201),
241
+ variant_scorers.SpliceJunctionScorer(),
242
+ ]
243
+ req_str = f"RNA_SEQ+METH+SPLICE:{gene_id}"
244
+
245
+ v_str = f"{parent_interval.chromosome}:{parent_interval.start}-{parent_interval.end}|{variant.position}:{variant.reference}>{variant.alternate}"
246
+ key = self._cache.make_key("score_variant_multimodal", v_str, cond_hash, req_str)
247
+ cached = self._cache.get(key)
248
+ if cached is not None:
249
+ self._budget.record_cache_hit()
250
+ return VariantMultiModalScore(
251
+ variant=variant,
252
+ condition_name=condition_name,
253
+ target_gene_lfc=float(cached["target_gene_lfc"]),
254
+ cpg_methylation_mean_abs_shift=float(cached["cpg_methylation_mean_abs_shift"]),
255
+ snmc_seq3_max_abs_shift=float(cached["snmc_seq3_max_abs_shift"]),
256
+ max_splice_junction_delta=float(cached["max_splice_junction_delta"]),
257
+ neighbor_gene_lfcs={
258
+ str(k): float(v) for k, v in (cached.get("neighbor_gene_lfcs") or {}).items()
259
+ },
260
+ )
261
+
262
+ self._budget.check_and_record_variant_score(1)
263
+ ag_iv = genome.Interval(
264
+ chromosome=parent_interval.chromosome,
265
+ start=parent_interval.start,
266
+ end=parent_interval.end,
267
+ )
268
+ ag_var = genome.Variant(
269
+ chromosome=variant.chromosome,
270
+ position=variant.position,
271
+ reference_bases=variant.reference,
272
+ alternate_bases=variant.alternate,
273
+ )
274
+
275
+ if cell_sketch is not None:
276
+ tables = self._client.score_variant(
277
+ interval=ag_iv,
278
+ variant=ag_var,
279
+ variant_scorers=scorers,
280
+ cell_conditioning=cell_sketch,
281
+ cell_condition_name=condition_name,
282
+ )
283
+ else:
284
+ cond_obj = model_condition.from_curies(reference_curies or ["UBERON:0000178", "CL:0000625"])
285
+ tables = self._client.score_variant(
286
+ interval=ag_iv,
287
+ variant=ag_var,
288
+ condition=cond_obj,
289
+ variant_scorers=scorers,
290
+ )
291
+
292
+ expr_tbl, meth_tbl, splice_tbl = tables[0], tables[1], tables[2]
293
+ clean_target = gene_id.split(".")[0]
294
+ neighbor_lfcs: dict[str, float] = {}
295
+ if "gene_id" in expr_tbl.obs.columns and expr_tbl.shape[0] > 0:
296
+ gene_col = expr_tbl.obs["gene_id"].astype(str).str.split(".").str[0]
297
+ matches = np.where(gene_col == clean_target)[0]
298
+ row_idx = int(matches[0]) if len(matches) > 0 else 0
299
+ x = np.asarray(expr_tbl.X)
300
+ target_lfc = float(np.mean(x[row_idx]))
301
+ # The scorer already returned every gene in this interval; keeping the non-target rows
302
+ # costs no extra API call and gives us a neighbour-gene specificity check for free.
303
+ symbols = (
304
+ expr_tbl.obs["gene_name"].astype(str).tolist()
305
+ if "gene_name" in expr_tbl.obs.columns
306
+ else [""] * len(gene_col)
307
+ )
308
+ for i, gid in enumerate(gene_col.tolist()):
309
+ if gid == clean_target:
310
+ continue
311
+ label = symbols[i] if symbols[i] and symbols[i] != "nan" else gid
312
+ neighbor_lfcs[label] = float(np.mean(x[i]))
313
+ else:
314
+ target_lfc = 0.0
315
+
316
+ meth_arr = np.abs(np.asarray(meth_tbl.X)) if meth_tbl.shape[0] > 0 else np.zeros((1, 2))
317
+ cpg_mean = float(np.mean(meth_arr))
318
+ snmc_max = float(np.max(meth_arr[:, -1])) if meth_arr.shape[1] >= 2 else float(np.max(meth_arr))
319
+
320
+ splice_arr = np.abs(np.asarray(splice_tbl.X)) if splice_tbl.shape[0] > 0 else np.zeros((1, 1))
321
+ max_splice = float(np.max(splice_arr))
322
+
323
+ payload = {
324
+ "target_gene_lfc": target_lfc,
325
+ "cpg_methylation_mean_abs_shift": cpg_mean,
326
+ "snmc_seq3_max_abs_shift": snmc_max,
327
+ "max_splice_junction_delta": max_splice,
328
+ "neighbor_gene_lfcs": neighbor_lfcs,
329
+ }
330
+ self._cache.put(key, "score_variant_multimodal", payload)
331
+ return VariantMultiModalScore(
332
+ variant=variant,
333
+ condition_name=condition_name,
334
+ target_gene_lfc=target_lfc,
335
+ cpg_methylation_mean_abs_shift=cpg_mean,
336
+ snmc_seq3_max_abs_shift=snmc_max,
337
+ max_splice_junction_delta=max_splice,
338
+ neighbor_gene_lfcs=neighbor_lfcs,
339
+ )
@@ -0,0 +1,102 @@
1
+ """VerifierBackend Protocol (`ag_backend/protocol.py`).
2
+
3
+ Decouples the optimization loop, coreset sketcher, and unit tests from whether
4
+ predictions come from the live AlphaGenome 2 gRPC service or the offline surrogate.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from dataclasses import dataclass, field
10
+ from typing import Protocol, runtime_checkable
11
+ import anndata
12
+ import numpy as np
13
+
14
+ from gene_edit_check.models import BackendMode, GenomicInterval, SingleNucleotideVariant
15
+
16
+
17
+ @dataclass
18
+ class GradientProfile:
19
+ gene_id: str
20
+ gene_name: str
21
+ condition_name: str
22
+ interval: GenomicInterval
23
+ reference_sequence: str
24
+ signed_gradients_1bp: np.ndarray # shape: (interval.width,)
25
+ scalar_score: float
26
+
27
+
28
+ @dataclass
29
+ class VariantMultiModalScore:
30
+ variant: SingleNucleotideVariant
31
+ condition_name: str
32
+ target_gene_lfc: float
33
+ cpg_methylation_mean_abs_shift: float
34
+ snmc_seq3_max_abs_shift: float
35
+ max_splice_junction_delta: float
36
+ # Every *other* gene the scorer returned for this interval (`gene_id -> LFC`), which the
37
+ # expression scorer gives us for free in the same response. A base edit meant to silence one
38
+ # gene must not quietly move its neighbours, and a 100-KB window around PDCD1 contains
39
+ # several. Empty when the backend cannot resolve neighbours.
40
+ neighbor_gene_lfcs: dict[str, float] = field(default_factory=dict)
41
+
42
+ @property
43
+ def max_abs_neighbor_lfc(self) -> float:
44
+ return max((abs(v) for v in self.neighbor_gene_lfcs.values()), default=0.0)
45
+
46
+ @property
47
+ def worst_neighbor(self) -> tuple[str, float] | None:
48
+ if not self.neighbor_gene_lfcs:
49
+ return None
50
+ gid = max(self.neighbor_gene_lfcs, key=lambda g: abs(self.neighbor_gene_lfcs[g]))
51
+ return gid, self.neighbor_gene_lfcs[gid]
52
+
53
+
54
+ @runtime_checkable
55
+ class VerifierBackend(Protocol):
56
+ @property
57
+ def backend_mode(self) -> BackendMode: ...
58
+
59
+ @property
60
+ def model_version(self) -> str: ...
61
+
62
+ def encode_cells(self, adata: anndata.AnnData, state_name: str) -> np.ndarray:
63
+ """Return (n_cells, 256) float32 embeddings in AlphaGenome 2 latent space."""
64
+ ...
65
+
66
+ def compute_interval_gradients(
67
+ self,
68
+ gene_id: str,
69
+ gene_symbol: str,
70
+ cell_sketch: anndata.AnnData,
71
+ condition_name: str,
72
+ sequence_length: int = 131072,
73
+ ) -> GradientProfile:
74
+ """Compute 1-bp input gradients centered on `gene_id` TSS and recover GRCh38 sequence."""
75
+ ...
76
+
77
+ def score_ism_window(
78
+ self,
79
+ parent_interval: GenomicInterval,
80
+ ism_window: GenomicInterval,
81
+ gene_id: str,
82
+ cell_sketch: anndata.AnnData,
83
+ condition_name: str,
84
+ ) -> dict[tuple[int, str, str], float]:
85
+ """Run scoped ISM (`score_ism_variants`) on `ism_window` (<= 60 bp) and return
86
+ map of `(1based_pos, ref_base, alt_base) -> target_gene_lfc`.
87
+ """
88
+ ...
89
+
90
+ def score_variant_multimodal(
91
+ self,
92
+ parent_interval: GenomicInterval,
93
+ variant: SingleNucleotideVariant,
94
+ gene_id: str,
95
+ cell_sketch: anndata.AnnData | None,
96
+ condition_name: str,
97
+ reference_curies: list[str] | None = None,
98
+ ) -> VariantMultiModalScore:
99
+ """Score a candidate SNV for target gene expression LFC, CpG methylation (`WGBS`/`snmC-seq3`),
100
+ and splice junction shifts (`SpliceJunctionScorer`).
101
+ """
102
+ ...
@@ -0,0 +1,173 @@
1
+ """Offline Surrogate Backend (`ag_backend/simulator.py`).
2
+
3
+ Implements the `VerifierBackend` Protocol for deterministic unit tests and zero-key CI environments.
4
+ All outputs are explicitly stamped with `BackendMode.SURROGATE_SIMULATOR` in provenance records.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import anndata
11
+ import numpy as np
12
+
13
+ from gene_edit_check.ag_backend.protocol import (
14
+ GradientProfile,
15
+ VariantMultiModalScore,
16
+ VerifierBackend,
17
+ )
18
+ from gene_edit_check.adata_utils import counts_fingerprint, dense_counts
19
+ from gene_edit_check.budget import RunBudgetTracker
20
+ from gene_edit_check.models import BackendMode, GenomicInterval, SingleNucleotideVariant
21
+
22
+
23
+ class SurrogateSimulatorBackend(VerifierBackend):
24
+ def __init__(self, budget: RunBudgetTracker, seed: int = 42) -> None:
25
+ self._budget = budget
26
+ self._seed = seed
27
+
28
+ @property
29
+ def backend_mode(self) -> BackendMode:
30
+ return BackendMode.SURROGATE_SIMULATOR
31
+
32
+ @property
33
+ def model_version(self) -> str:
34
+ return "surrogate-simulator-v2.0 (OFFLINE)"
35
+
36
+ def encode_cells(self, adata: anndata.AnnData, state_name: str) -> np.ndarray:
37
+ self._budget.check_and_record_encode_cells(adata.shape[0])
38
+ x = dense_counts(adata)
39
+ log_x = np.log1p(x)
40
+ rng = np.random.default_rng(self._seed)
41
+ proj = rng.normal(0.0, 1.0 / np.sqrt(max(1, x.shape[1])), size=(x.shape[1], 256)).astype(np.float32)
42
+ emb = log_x @ proj
43
+ norms = np.linalg.norm(emb, axis=1, keepdims=True)
44
+ return emb / np.maximum(norms, 1e-6)
45
+
46
+ def compute_interval_gradients(
47
+ self,
48
+ gene_id: str,
49
+ gene_symbol: str,
50
+ cell_sketch: anndata.AnnData,
51
+ condition_name: str,
52
+ sequence_length: int = 131072,
53
+ ) -> GradientProfile:
54
+ self._budget.check_and_record_gradient_call(1)
55
+ start = 241_793_329
56
+ end = start + sequence_length
57
+ iv = GenomicInterval(chromosome="chr2", start=start, end=end)
58
+
59
+ # Deterministic synthetic sequence with embedded PAMs and TF motifs around center
60
+ rng = np.random.default_rng(self._seed)
61
+ bases = np.array(["A", "C", "G", "T"])
62
+ seq_arr = rng.choice(bases, size=sequence_length)
63
+ mid = sequence_length // 2
64
+
65
+ # Plant canonical motifs + PAMs near mid-200 (shared RUNX1) and mid+160 (exhaustion TOX/NR4A1)
66
+ shared_window = list("GCTATGTGGTTAGGCCAGGCTGG")
67
+ selective_window = list("CGATGCAAATGGAAAGGTCAGGG")
68
+ seq_arr[mid - 200 : mid - 200 + len(shared_window)] = shared_window
69
+ seq_arr[mid + 160 : mid + 160 + len(selective_window)] = selective_window
70
+ ref_seq = "".join(seq_arr.tolist())
71
+
72
+ grads = rng.normal(0.0, 0.002, size=sequence_length).astype(np.float32)
73
+ is_target = "exhausted" in condition_name.lower() or "target" in condition_name.lower()
74
+ # Shared motif has strong gradient in both target and healthy
75
+ grads[mid - 200 : mid - 180] = 0.085
76
+ # Selective motif has strong gradient ONLY in target state
77
+ if is_target:
78
+ grads[mid + 160 : mid + 182] = 0.115
79
+ else:
80
+ grads[mid + 160 : mid + 182] = 0.003
81
+
82
+ return GradientProfile(
83
+ gene_id=gene_id,
84
+ gene_name=gene_symbol,
85
+ condition_name=condition_name,
86
+ interval=iv,
87
+ reference_sequence=ref_seq,
88
+ signed_gradients_1bp=grads,
89
+ scalar_score=4.85 if is_target else 2.10,
90
+ )
91
+
92
+ def score_ism_window(
93
+ self,
94
+ parent_interval: GenomicInterval,
95
+ ism_window: GenomicInterval,
96
+ gene_id: str,
97
+ cell_sketch: anndata.AnnData,
98
+ condition_name: str,
99
+ ) -> dict[tuple[int, str, str], float]:
100
+ w = ism_window.width
101
+ self._budget.check_and_record_ism_window(window_bp=w, n_variants=w * 3)
102
+ out: dict[tuple[int, str, str], float] = {}
103
+ mid_genomic = parent_interval.start + (parent_interval.width // 2)
104
+ is_target = "exhausted" in condition_name.lower() or "target" in condition_name.lower()
105
+
106
+ for pos_0 in range(ism_window.start, ism_window.end):
107
+ pos_1 = pos_0 + 1
108
+ for ref_b in ("A", "C", "G", "T"):
109
+ for alt_b in ("A", "C", "G", "T"):
110
+ if ref_b == alt_b:
111
+ continue
112
+ dist_sel = abs(pos_0 - (mid_genomic + 165))
113
+ dist_shr = abs(pos_0 - (mid_genomic - 195))
114
+ if dist_sel <= 10:
115
+ val = -0.042 if is_target else -0.001
116
+ elif dist_shr <= 10:
117
+ val = -0.038
118
+ else:
119
+ val = -0.002
120
+ out[(pos_1, ref_b, alt_b)] = val
121
+ return out
122
+
123
+ def score_variant_multimodal(
124
+ self,
125
+ parent_interval: GenomicInterval,
126
+ variant: SingleNucleotideVariant,
127
+ gene_id: str,
128
+ cell_sketch: anndata.AnnData | None,
129
+ condition_name: str,
130
+ reference_curies: list[str] | None = None,
131
+ ) -> VariantMultiModalScore:
132
+ self._budget.check_and_record_variant_score(1)
133
+ mid_genomic = parent_interval.start + (parent_interval.width // 2)
134
+ pos_0 = variant.position - 1
135
+ dist_sel = abs(pos_0 - (mid_genomic + 165))
136
+ dist_shr = abs(pos_0 - (mid_genomic - 195))
137
+ is_target = "exhausted" in condition_name.lower() or "target" in condition_name.lower()
138
+
139
+ # Add slight deterministic sketch hash perturbation to model Sketch A vs Sketch B
140
+ sketch_jitter = 0.0
141
+ if cell_sketch is not None:
142
+ h_int = int(counts_fingerprint(cell_sketch)[:6], 16)
143
+ sketch_jitter = ((h_int % 100) - 50) * 1e-5
144
+
145
+ if dist_sel <= 12:
146
+ lfc = (-0.044 if is_target else -0.0012) + sketch_jitter
147
+ cpg = 0.004
148
+ splice = 0.002
149
+ elif dist_shr <= 12:
150
+ lfc = (-0.039 if is_target else -0.036) + sketch_jitter
151
+ cpg = 0.009
152
+ splice = 0.005
153
+ else:
154
+ lfc = -0.004 + sketch_jitter
155
+ cpg = 0.003
156
+ splice = 0.002
157
+
158
+ # Two stand-in neighbours so the neighbour-specificity check is exercised offline. The
159
+ # shared-enhancer site drags a neighbour with it; the selective site does not.
160
+ neighbors = {
161
+ "SIM_NEIGHBOR_PROXIMAL": float(lfc * (0.80 if dist_shr <= 12 else 0.05)),
162
+ "SIM_NEIGHBOR_DISTAL": float(lfc * 0.02),
163
+ }
164
+
165
+ return VariantMultiModalScore(
166
+ variant=variant,
167
+ condition_name=condition_name,
168
+ target_gene_lfc=float(lfc),
169
+ cpg_methylation_mean_abs_shift=cpg,
170
+ snmc_seq3_max_abs_shift=cpg * 1.4,
171
+ max_splice_junction_delta=splice,
172
+ neighbor_gene_lfcs=neighbors,
173
+ )
@@ -0,0 +1 @@
1
+ """Deterministic Gradient-Propose -> Scoped-ISM -> Reflexion Loop (`agent`)."""