Skip to content

Commit 754fb4d

Browse files
hutaobohutaobo
authored
Prepare GSE274058 reference release artifacts
Includes the A100 rerun confirmation, refreshed RTD result summaries, and release packaging assets for GSE274058.
1 parent de274fc commit 754fb4d

64 files changed

Lines changed: 7667 additions & 63 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,7 @@ dist/
55
build/
66
*.egg-info/
77
.ipynb_checkpoints/
8+
.spatialperturb-cache/
9+
reports/
10+
artifacts/
11+
.tmp_sphinx_html/

‎CITATION.cff‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@ message: If you use this package, please cite it.
44
authors:
55
- family-names: Hu
66
given-names: Taobo
7-
version: 0.1.0
8-
repository-code: https://github.com/yourname/SpatialPerturb
7+
version: 0.3.0
8+
repository-code: https://github.com/hutaobo/SpatialPerturb

‎README.md‎

Lines changed: 112 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,138 @@
11
# SpatialPerturb
22

3-
Toolkit for combining **Spatial Transcriptomics** with **Perturb-seq** workflows — signatures, label transfer, spatial scoring, and graph/structure analysis.
3+
SpatialPerturb is an AnnData-native framework for spatial perturbation inference across sequencing-based and imaging-based platforms.
4+
5+
It now ships a benchmark-oriented workflow built around:
6+
7+
- a stable `AnnData` schema,
8+
- `fetch -> prepare -> load` public dataset lifecycle helpers,
9+
- intrinsic and neighborhood differential effects with `simple` and `pseudobulk` modes,
10+
- ligand-receptor differential scoring with fixed fallback or custom LR resources,
11+
- perturbation-program and cross-platform concordance metrics,
12+
- paper-style figure rendering and report manifests.
413

514
## Install
615

716
```bash
817
pip install SpatialPerturb
9-
# or with GNN extras:
10-
pip install 'SpatialPerturb[gnn]'
18+
```
19+
20+
For heavier ecosystem interop:
21+
22+
```bash
23+
pip install "SpatialPerturb[interop]"
1124
```
1225

1326
## Quick start
1427

1528
```python
1629
import spatialperturb as sp
1730

18-
print(sp.__version__)
31+
adata = sp.load_demo_dataset()
32+
33+
intrinsic = sp.intrinsic_de(
34+
adata,
35+
perturbation="Lrrk2",
36+
control="control",
37+
method="pseudobulk",
38+
sample_col="sample",
39+
cell_type="neuron",
40+
roi="hippocampus",
41+
)
42+
43+
neighbor = sp.neighbor_de(
44+
adata,
45+
perturbation="Lrrk2",
46+
control="control",
47+
method="pseudobulk",
48+
sample_col="sample",
49+
aggregate="pseudobulk",
50+
cell_type="neuron",
51+
roi="hippocampus",
52+
)
53+
54+
lr = sp.differential_lr(adata, perturbation="Lrrk2", control="control", lr_network="fallback")
55+
power = sp.power_curve(adata, perturbation="Lrrk2", control="control", method="pseudobulk", sample_col="sample")
56+
programs = sp.derive_perturbation_programs(intrinsic, top_n=10, direction="both")
57+
```
58+
59+
## Public dataset lifecycle
60+
61+
```python
62+
import spatialperturb as sp
63+
64+
sp.available_datasets()
65+
66+
sp.fetch_dataset("shen_2026_scrnaseq", cache_dir=".spatialperturb-cache")
67+
sp.prepare_dataset("shen_2026_scrnaseq", cache_dir=".spatialperturb-cache")
68+
adata = sp.load_public_dataset("shen_2026_scrnaseq", cache_dir=".spatialperturb-cache")
1969
```
2070

21-
CLI:
71+
Registered public tracks:
72+
73+
- `shen_2026_stereoseq` -> `GSE274447`
74+
- `shen_2026_scrnaseq` -> `GSE274058`
75+
- `demo_spatialperturb` -> deterministic paired demo data
76+
77+
Notes:
78+
79+
- `shen_2026_scrnaseq` supports automatic fetch and preparation from the GEO raw archive.
80+
- `shen_2026_stereoseq` supports automatic fetch and extraction, but final preparation still requires a preconverted `.h5ad` or tabular export from the raw GEF files.
81+
82+
## Paper-grade benchmark workflow
83+
84+
```python
85+
import spatialperturb as sp
86+
87+
results = sp.run_core_benchmark(
88+
"demo_spatialperturb",
89+
config={
90+
"cache_dir": ".spatialperturb-cache",
91+
"reference_dataset": "demo_spatialperturb",
92+
"method": "pseudobulk",
93+
"sample_col": "sample",
94+
"concordance_level": "both",
95+
},
96+
output_dir="reports/demo_spatialperturb",
97+
)
98+
```
99+
100+
This writes:
101+
102+
- tidy tables under `reports/.../tables/`
103+
- fixed paper figures under `reports/.../figures/`
104+
- a machine-readable `manifest.json`
105+
- the exact `input.h5ad` used for the run
106+
107+
## CLI
108+
22109
```bash
23-
SpatialPerturb version
110+
spatialperturb datasets
111+
spatialperturb fetch-dataset shen_2026_scrnaseq
112+
spatialperturb prepare-dataset shen_2026_scrnaseq
113+
spatialperturb run-benchmark demo_spatialperturb --output-dir reports/demo
114+
spatialperturb render-paper-figures demo_spatialperturb --output-dir reports/demo-figs
115+
spatialperturb validate path/to/data.h5ad
24116
```
25117

118+
## Package layout
119+
120+
- `spatialperturb.io`: AnnData ingestion helpers.
121+
- `spatialperturb.pp`: perturbation assignment and QC.
122+
- `spatialperturb.gr`: spatial graph construction and neighbor collection.
123+
- `spatialperturb.tl`: intrinsic DE, neighbor DE, ligand-receptor scoring, concordance, and power.
124+
- `spatialperturb.pl`: plotting helpers for benchmark figures.
125+
- `spatialperturb.signatures`: perturbation program derivation and scoring.
126+
- `spatialperturb.datasets`: dataset registry plus public `fetch/prepare/load`.
127+
- `spatialperturb.benchmarks`: benchmark orchestration and report manifests.
128+
- `spatialperturb.reports`: fixed paper figure rendering.
129+
26130
## Development
27131

28132
```bash
29-
python -m pip install --upgrade build twine
133+
python -m pip install --upgrade build pytest twine
30134
python -m build
31-
twine upload --repository testpypi dist/*
135+
pytest -q
32136
```
33137

34138
## Citation

‎docs/_static/results/gse274058_reference/barcode_spread.png‎

36.8 KB
Loading

‎docs/api.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# API 参考
2+
3+
## 包入口
4+
5+
```{eval-rst}
6+
.. automodule:: spatialperturb
7+
:members:
8+
```
9+
10+
## I/O 与 Schema
11+
12+
```{eval-rst}
13+
.. automodule:: spatialperturb.io
14+
:members:
15+
```
16+
17+
```{eval-rst}
18+
.. automodule:: spatialperturb.schema
19+
:members:
20+
```
21+
22+
## 预处理与图
23+
24+
```{eval-rst}
25+
.. automodule:: spatialperturb.pp
26+
:members:
27+
```
28+
29+
```{eval-rst}
30+
.. automodule:: spatialperturb.gr
31+
:members:
32+
```
33+
34+
## 分析工具
35+
36+
```{eval-rst}
37+
.. automodule:: spatialperturb.tl
38+
:members:
39+
```
40+
41+
```{eval-rst}
42+
.. automodule:: spatialperturb.signatures
43+
:members:
44+
```
45+
46+
## 数据集与 benchmark
47+
48+
```{eval-rst}
49+
.. automodule:: spatialperturb.datasets
50+
:members:
51+
```
52+
53+
```{eval-rst}
54+
.. automodule:: spatialperturb.benchmarks
55+
:members:
56+
```
57+
58+
```{eval-rst}
59+
.. automodule:: spatialperturb.reports
60+
:members:
61+
```
62+
63+
## 绘图与 CLI
64+
65+
```{eval-rst}
66+
.. automodule:: spatialperturb.pl
67+
:members:
68+
```
69+
70+
```{eval-rst}
71+
.. automodule:: spatialperturb.cli
72+
:members:
73+
```

‎docs/benchmarks.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Benchmarks
2+
3+
SpatialPerturb 当前把 benchmark 固定成两条主轨道：
4+
5+
- `shen_2026_core`
6+
目标是复现空间扰动数据上的 intrinsic / neighbor / ligand-receptor / power / figure 主链。
7+
- `cross_platform_concordance`
8+
目标是比较 spatial 和 dissociated reference 中的 perturbation signatures 与 programs。
9+
10+
## 查看 catalog
11+
12+
```python
13+
import spatialperturb as sp
14+
15+
sp.available_datasets()
16+
sp.available_benchmarks()
17+
```
18+
19+
## Public benchmark backbone
20+
21+
### `shen_2026_scrnaseq`
22+
23+
- accession: `GSE274058`
24+
- role: reference / cross-platform track
25+
- raw format: nested `10x tar.gz`
26+
- status: automatic `fetch -> prepare -> load` supported
27+
28+
### `shen_2026_stereoseq`
29+
30+
- accession: `GSE274447`
31+
- role: spatial core track
32+
- raw format: `tar of GEF`
33+
- status: automatic fetch and extraction supported; final prepare still expects a preconverted `.h5ad` or tabular cell-level export
34+
35+
## 运行 core benchmark
36+
37+
```python
38+
import spatialperturb as sp
39+
40+
results = sp.run_core_benchmark(
41+
"demo_spatialperturb",
42+
config={
43+
"cache_dir": ".spatialperturb-cache",
44+
"method": "pseudobulk",
45+
"sample_col": "sample",
46+
"reference_dataset": "demo_spatialperturb",
47+
"concordance_level": "both",
48+
},
49+
output_dir="reports/demo_spatialperturb",
50+
)
51+
```
52+
53+
这个入口会自动：
54+
55+
- 载入 prepared dataset
56+
- 补 spatial graph（如果还没建）
57+
- 运行 `intrinsic_de`
58+
- 运行 `neighbor_de`
59+
- 运行 `differential_lr`
60+
- 运行 `power_curve`
61+
- 如果给了 reference，再运行 `platform_concordance`
62+
- 输出 tables、figures、`manifest.json` 和 `input.h5ad`
63+
64+
## 运行 cross-platform benchmark
65+
66+
```python
67+
spatial, reference = sp.load_demo_dataset(paired=True)
68+
69+
spatial_de = sp.intrinsic_de(
70+
spatial,
71+
perturbation="Lrrk2",
72+
control="control",
73+
method="pseudobulk",
74+
sample_col="sample",
75+
)
76+
77+
reference_de = sp.intrinsic_de(
78+
reference,
79+
perturbation="Lrrk2",
80+
control="control",
81+
method="pseudobulk",
82+
sample_col="sample",
83+
)
84+
85+
concordance = sp.run_cross_platform_benchmark(
86+
spatial_de,
87+
reference_de,
88+
config={"top_n": 50, "level": "both"},
89+
)
90+
```
91+
92+
## Benchmark 输出目录
93+
94+
`run_core_benchmark(..., output_dir=...)` 会生成固定目录结构：
95+
96+
- `tables/intrinsic_de.tsv`
97+
- `tables/neighbor_de.tsv`
98+
- `tables/differential_lr.tsv`
99+
- `tables/power_curve.tsv`
100+
- `tables/platform_concordance.tsv`（如果提供 reference）
101+
- `figures/workflow_schema.png`
102+
- `figures/assignment_qc.png`
103+
- `figures/own_vs_neighbor.png`
104+
- `figures/lr_differential.png`
105+
- `figures/platform_concordance.png`
106+
- `figures/power_curve.png`
107+
- `manifest.json`
108+
- `config.json`
109+
- `input.h5ad`

0 commit comments

Comments
 (0)