strsc 0.4.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.
- strsc-0.4.0/LICENSE +21 -0
- strsc-0.4.0/MANIFEST.in +9 -0
- strsc-0.4.0/NOTICE.md +13 -0
- strsc-0.4.0/PKG-INFO +173 -0
- strsc-0.4.0/README.md +137 -0
- strsc-0.4.0/configs/cell_protocol.json +51 -0
- strsc-0.4.0/docs/toolkit/api.md +192 -0
- strsc-0.4.0/docs/toolkit/cell.md +48 -0
- strsc-0.4.0/docs/toolkit/evaluation-bundle.md +73 -0
- strsc-0.4.0/docs/toolkit/export-results.md +32 -0
- strsc-0.4.0/docs/toolkit/fourier.md +72 -0
- strsc-0.4.0/docs/toolkit/her2.md +91 -0
- strsc-0.4.0/docs/toolkit/hest.md +39 -0
- strsc-0.4.0/docs/toolkit/training.md +60 -0
- strsc-0.4.0/examples/bundles/cell.json +1 -0
- strsc-0.4.0/examples/bundles/fourier.json +1 -0
- strsc-0.4.0/examples/bundles/her2.json +1 -0
- strsc-0.4.0/examples/bundles/hest.json +1 -0
- strsc-0.4.0/examples/export_results_example.py +97 -0
- strsc-0.4.0/examples/train_mlp.py +40 -0
- strsc-0.4.0/pyproject.toml +33 -0
- strsc-0.4.0/setup.cfg +4 -0
- strsc-0.4.0/src/strsc/__init__.py +15 -0
- strsc-0.4.0/src/strsc/__main__.py +30 -0
- strsc-0.4.0/src/strsc/api.py +1232 -0
- strsc-0.4.0/src/strsc/cell_biology.py +241 -0
- strsc-0.4.0/src/strsc/cell_core.py +420 -0
- strsc-0.4.0/src/strsc/cell_prepare.py +223 -0
- strsc-0.4.0/src/strsc/cell_rna.py +274 -0
- strsc-0.4.0/src/strsc/cell_score.py +361 -0
- strsc-0.4.0/src/strsc/evaluation_export.py +288 -0
- strsc-0.4.0/src/strsc/example.py +69 -0
- strsc-0.4.0/src/strsc/export.py +119 -0
- strsc-0.4.0/src/strsc/files.py +757 -0
- strsc-0.4.0/src/strsc/fourier.py +271 -0
- strsc-0.4.0/src/strsc/her2.py +303 -0
- strsc-0.4.0/src/strsc/her2_core.py +958 -0
- strsc-0.4.0/src/strsc/hest.py +246 -0
- strsc-0.4.0/src/strsc/hest_core.py +289 -0
- strsc-0.4.0/src/strsc/rsc_cli.py +101 -0
- strsc-0.4.0/src/strsc/training/__init__.py +5 -0
- strsc-0.4.0/src/strsc/training/adapters/__init__.py +0 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/__init__.py +40 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/engineering_gate.py +239 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/formal_runner.py +254 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/graph.py +228 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/initialization.py +36 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/objective.py +212 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/overlay.py +79 -0
- strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/paired_data.py +229 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/__init__.py +48 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/batching.py +730 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/data.py +448 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/engineering_gate.py +312 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/export.py +173 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/formal_runner.py +480 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/models.py +95 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/objective.py +492 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/overlay.py +141 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/split.py +80 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/__init__.py +62 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/contract.py +136 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/data.py +746 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/deepspot.py +162 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/engineering_gate.py +498 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/formal_runner.py +1003 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/hist.py +164 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/manifest.py +108 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/objective.py +94 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/outputs.py +154 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/paired.py +54 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/__init__.py +27 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/contracts.py +124 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/engineering_gate.py +729 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/exemplars.py +241 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/hest_data.py +448 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/model_inputs.py +139 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/outputs.py +137 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/overlay.py +388 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/pairing.py +66 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/train_pair.py +458 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/training.py +750 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/upstream.py +345 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/__init__.py +15 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/engineering_gate.py +270 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/hest_data.py +396 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/overlay.py +260 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/train_pair.py +584 -0
- strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/upstream.py +336 -0
- strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/__init__.py +6 -0
- strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/hest_contract.py +135 -0
- strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/model.py +23 -0
- strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/ridge.py +55 -0
- strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/train_pair.py +621 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/__init__.py +42 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/data.py +279 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/engineering_gate.py +148 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/formal_runner.py +311 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/lightning_overlay.py +148 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/objective.py +87 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/runtime.py +416 -0
- strsc-0.4.0/src/strsc/training/adapters/scellst/split.py +232 -0
- strsc-0.4.0/src/strsc/training/hest_data.py +413 -0
- strsc-0.4.0/src/strsc/training/non_neighbours.py +256 -0
- strsc-0.4.0/src/strsc/training/shared/__init__.py +25 -0
- strsc-0.4.0/src/strsc/training/shared/adjacency.py +169 -0
- strsc-0.4.0/src/strsc/training/shared/losses.py +92 -0
- strsc-0.4.0/src/strsc/training/shared/noop.py +102 -0
- strsc-0.4.0/src/strsc.egg-info/PKG-INFO +173 -0
- strsc-0.4.0/src/strsc.egg-info/SOURCES.txt +120 -0
- strsc-0.4.0/src/strsc.egg-info/dependency_links.txt +1 -0
- strsc-0.4.0/src/strsc.egg-info/entry_points.txt +2 -0
- strsc-0.4.0/src/strsc.egg-info/requires.txt +25 -0
- strsc-0.4.0/src/strsc.egg-info/top_level.txt +1 -0
- strsc-0.4.0/tests/test_api.py +129 -0
- strsc-0.4.0/tests/test_cell.py +32 -0
- strsc-0.4.0/tests/test_core.py +37 -0
- strsc-0.4.0/tests/test_evaluation_export.py +48 -0
- strsc-0.4.0/tests/test_export_constant_prediction.py +98 -0
- strsc-0.4.0/tests/test_fourier.py +91 -0
- strsc-0.4.0/tests/test_her2.py +114 -0
- strsc-0.4.0/tests/test_training.py +30 -0
strsc-0.4.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 stRSC contributors
|
|
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.
|
strsc-0.4.0/MANIFEST.in
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
include README.md LICENSE NOTICE.md
|
|
2
|
+
recursive-include src *.py
|
|
3
|
+
recursive-include docs/toolkit *.md
|
|
4
|
+
recursive-include configs *.json
|
|
5
|
+
recursive-include examples *.py
|
|
6
|
+
recursive-include examples/bundles *.json
|
|
7
|
+
recursive-include tests *.py
|
|
8
|
+
global-exclude *.pyc
|
|
9
|
+
global-exclude __pycache__
|
strsc-0.4.0/NOTICE.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Attribution and data terms
|
|
2
|
+
|
|
3
|
+
stRSC source code is distributed under the [MIT license](LICENSE).
|
|
4
|
+
|
|
5
|
+
Python dependencies retain their respective licenses. They are declared in
|
|
6
|
+
`pyproject.toml`; the figure scripts list theirs in `paper/requirements.txt`.
|
|
7
|
+
|
|
8
|
+
Model adapters integrate upstream implementations installed from their original
|
|
9
|
+
repositories. Those implementations, pretrained weights and datasets retain
|
|
10
|
+
their providers' terms.
|
|
11
|
+
|
|
12
|
+
Data sources, example assets and access requirements are described in
|
|
13
|
+
[DATA_SOURCES.md](DATA_SOURCES.md).
|
strsc-0.4.0/PKG-INFO
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: strsc
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Reproducible-signal correlation (RSC) for spatial transcriptomics predicted from histology
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://stRSC.org
|
|
7
|
+
Project-URL: Repository, https://github.com/oyjr/stRSC
|
|
8
|
+
Project-URL: Documentation, https://github.com/oyjr/stRSC#readme
|
|
9
|
+
Project-URL: Issues, https://github.com/oyjr/stRSC/issues
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
License-File: NOTICE.md
|
|
14
|
+
Requires-Dist: numpy<3,>=1.26
|
|
15
|
+
Requires-Dist: scipy<2,>=1.11
|
|
16
|
+
Requires-Dist: pandas<3,>=2.1
|
|
17
|
+
Requires-Dist: h5py<4,>=3.9
|
|
18
|
+
Requires-Dist: torch<3,>=2.2
|
|
19
|
+
Requires-Dist: scikit-learn>=1.3
|
|
20
|
+
Provides-Extra: io
|
|
21
|
+
Requires-Dist: pyarrow>=14; extra == "io"
|
|
22
|
+
Provides-Extra: cell
|
|
23
|
+
Requires-Dist: anndata<0.13,>=0.10; extra == "cell"
|
|
24
|
+
Requires-Dist: pyarrow>=14; extra == "cell"
|
|
25
|
+
Requires-Dist: shapely>=2; extra == "cell"
|
|
26
|
+
Requires-Dist: geopandas>=0.14; extra == "cell"
|
|
27
|
+
Provides-Extra: training
|
|
28
|
+
Requires-Dist: scikit-learn>=1.3; extra == "training"
|
|
29
|
+
Requires-Dist: pillow>=10; extra == "training"
|
|
30
|
+
Requires-Dist: pyyaml>=6; extra == "training"
|
|
31
|
+
Requires-Dist: lightning>=2.2; extra == "training"
|
|
32
|
+
Requires-Dist: torchvision>=0.17; extra == "training"
|
|
33
|
+
Provides-Extra: test
|
|
34
|
+
Requires-Dist: pytest<10,>=8; extra == "test"
|
|
35
|
+
Dynamic: license-file
|
|
36
|
+
|
|
37
|
+
# stRSC
|
|
38
|
+
|
|
39
|
+
Reproducible-signal correlation (RSC) for spatial transcriptomics predicted from
|
|
40
|
+
histology.
|
|
41
|
+
|
|
42
|
+
[Website](https://stRSC.org/) · [Interactive examples](https://stRSC.org/examples) · [User guide](https://stRSC.org/docs)
|
|
43
|
+
|
|
44
|
+
This repository accompanies **A noise-corrected metric for evaluating spatial
|
|
45
|
+
transcriptomics predicted from histology**. It contains the code for RSC, the
|
|
46
|
+
evaluations in the study and the pairwise difference loss, together with the
|
|
47
|
+
scripts that produce the study's result tables and figures.
|
|
48
|
+
|
|
49
|
+
## What RSC measures
|
|
50
|
+
|
|
51
|
+
Correlation with measured RNA counts mixes the expression signal with sampling
|
|
52
|
+
noise, which dominates sparse counts at fine spatial scales. RSC splits the
|
|
53
|
+
counts of each gene in each bin, spot or cell binomially into two halves. The
|
|
54
|
+
two halves share the expected expression and carry independent sampling noise.
|
|
55
|
+
At each spatial scale `b`, with halves `A` and `B` and prediction `P`:
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
C = (<P, A>_b + <P, B>_b) / 2 mean covariance of the prediction with the halves
|
|
59
|
+
V_model = <P, P>_b variance of the prediction
|
|
60
|
+
V_RNA = <A, B>_b covariance between the halves
|
|
61
|
+
RSC = C / sqrt(V_model * V_RNA)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The split-half reliability `V_RNA / sqrt(<A, A>_b <B, B>_b)` is the correlation
|
|
65
|
+
between the two halves. Sums run over all genes and all bins, spots or cells of
|
|
66
|
+
a section, and scores are averaged over repeated count splits. Counts must be
|
|
67
|
+
raw integer molecule counts, split before normalization, and predictions must
|
|
68
|
+
not use the counts they are evaluated against.
|
|
69
|
+
|
|
70
|
+
## Installation
|
|
71
|
+
|
|
72
|
+
Use Python 3.10 or later:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
python -m pip install strsc
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`python -m pip install "strsc[io]"` adds support for Parquet files.
|
|
79
|
+
|
|
80
|
+
## Score your predictions
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
import strsc
|
|
84
|
+
|
|
85
|
+
counts = strsc.read_counts("sample.h5ad") # a table, .h5ad, Space Ranger or Xenium folder
|
|
86
|
+
result = strsc.rsc(counts, {"my_model": "predictions.csv"}, layout="spots")
|
|
87
|
+
print(result.scales) # RSC, Pearson r and split-half reliability per scale
|
|
88
|
+
result.save("strsc-output")
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The command line runs the same analysis:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
strsc rsc sample.h5ad -p my_model=predictions.csv --layout spots --out strsc-output
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`layout` is `"spots"`, `"grid"` or `"cells"`. `strsc.regions` scores between
|
|
98
|
+
and within annotated regions, and `strsc.ideal_check` runs the paper's test
|
|
99
|
+
with the expected expression as the prediction. See
|
|
100
|
+
[RSC on your own data](docs/toolkit/api.md). The Calculate RSC tab of
|
|
101
|
+
[stRSC.org](https://stRSC.org/analyze) runs the same code in the browser.
|
|
102
|
+
|
|
103
|
+
## Run an example
|
|
104
|
+
|
|
105
|
+
Generate counts and two predictions, then compute RSC in five spatial bands:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
strsc example --output outputs/example
|
|
109
|
+
strsc export-results --run outputs/example/scores --output outputs/results.json --synthetic
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The example writes:
|
|
113
|
+
|
|
114
|
+
- `outputs/example/scores/`: RSC by band, gene-wise Pearson correlations and the RNA components;
|
|
115
|
+
- `outputs/example/analysis-bundle.json`: paired spatial maps for the website;
|
|
116
|
+
- `outputs/results.json`: saved evaluation results for the website.
|
|
117
|
+
|
|
118
|
+
The example runs on a CPU with generated data. Choose a new output directory for
|
|
119
|
+
each run.
|
|
120
|
+
|
|
121
|
+
To inspect the output online, open
|
|
122
|
+
[Computed results](https://stRSC.org/analyze?input=results), upload
|
|
123
|
+
`outputs/example/analysis-bundle.json` or `outputs/results.json`, then select
|
|
124
|
+
**View results**. Files are processed in the browser. The same workflow
|
|
125
|
+
applies to results computed from your own data.
|
|
126
|
+
|
|
127
|
+
## Evaluate your predictions
|
|
128
|
+
|
|
129
|
+
| Analysis | Command or API | Inputs and instructions |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| RSC on your own data, between and within regions | `strsc.rsc`, `strsc rsc`, `strsc.regions` | [RSC on your own data](docs/toolkit/api.md) |
|
|
132
|
+
| Pairwise accuracy across and within tissue regions | `strsc her2` | [Spot pairs](docs/toolkit/her2.md) |
|
|
133
|
+
| RSC in graph-frequency bands of spot data | `strsc hest` | [HEST workflow](docs/toolkit/hest.md) |
|
|
134
|
+
| RSC by physical wavelength on regular grids | `strsc fourier` | [Fourier workflow](docs/toolkit/fourier.md) |
|
|
135
|
+
| RSC for cells and aggregated grids, proliferation hotspots | `python -m strsc.cell_score` | [Cell workflow](docs/toolkit/cell.md) |
|
|
136
|
+
| Pairwise difference loss and model adapters | `strsc.training` | [Loss and model adapters](docs/toolkit/training.md) |
|
|
137
|
+
| Export evaluation results | `strsc export-results` | [Result format](docs/toolkit/export-results.md) |
|
|
138
|
+
|
|
139
|
+
Each guide specifies the expression transform, cell or site identifiers, gene
|
|
140
|
+
identifiers and spatial coordinates required by its workflow. Install optional
|
|
141
|
+
dependencies for cell preparation or model training:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python -m pip install "strsc[cell]"
|
|
145
|
+
python -m pip install "strsc[training]"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Paper analyses and figures
|
|
149
|
+
|
|
150
|
+
The [paper directory](paper/README.md) contains result tables, aggregation
|
|
151
|
+
scripts and figure sources. The documented aggregation commands run from bundled
|
|
152
|
+
tables. [Count-level recalculation](paper/RAW_INPUTS.md) uses source RNA counts
|
|
153
|
+
and saved predictions supplied in the specified formats.
|
|
154
|
+
|
|
155
|
+
## Tests
|
|
156
|
+
|
|
157
|
+
From a clone of this repository:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
git clone https://github.com/oyjr/stRSC.git
|
|
161
|
+
cd stRSC
|
|
162
|
+
python -m pip install -e ".[test]"
|
|
163
|
+
python -m pytest -q
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Citation and license
|
|
167
|
+
|
|
168
|
+
Author information and the software version are in [CITATION.cff](CITATION.cff).
|
|
169
|
+
The accompanying manuscript is *A noise-corrected metric for evaluating spatial
|
|
170
|
+
transcriptomics predicted from histology* by Ouyang, Gao and colleagues.
|
|
171
|
+
|
|
172
|
+
The code is released under the [MIT license](LICENSE). Third-party
|
|
173
|
+
dependencies, models and datasets retain their own terms; see [NOTICE.md](NOTICE.md).
|
strsc-0.4.0/README.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# stRSC
|
|
2
|
+
|
|
3
|
+
Reproducible-signal correlation (RSC) for spatial transcriptomics predicted from
|
|
4
|
+
histology.
|
|
5
|
+
|
|
6
|
+
[Website](https://stRSC.org/) · [Interactive examples](https://stRSC.org/examples) · [User guide](https://stRSC.org/docs)
|
|
7
|
+
|
|
8
|
+
This repository accompanies **A noise-corrected metric for evaluating spatial
|
|
9
|
+
transcriptomics predicted from histology**. It contains the code for RSC, the
|
|
10
|
+
evaluations in the study and the pairwise difference loss, together with the
|
|
11
|
+
scripts that produce the study's result tables and figures.
|
|
12
|
+
|
|
13
|
+
## What RSC measures
|
|
14
|
+
|
|
15
|
+
Correlation with measured RNA counts mixes the expression signal with sampling
|
|
16
|
+
noise, which dominates sparse counts at fine spatial scales. RSC splits the
|
|
17
|
+
counts of each gene in each bin, spot or cell binomially into two halves. The
|
|
18
|
+
two halves share the expected expression and carry independent sampling noise.
|
|
19
|
+
At each spatial scale `b`, with halves `A` and `B` and prediction `P`:
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
C = (<P, A>_b + <P, B>_b) / 2 mean covariance of the prediction with the halves
|
|
23
|
+
V_model = <P, P>_b variance of the prediction
|
|
24
|
+
V_RNA = <A, B>_b covariance between the halves
|
|
25
|
+
RSC = C / sqrt(V_model * V_RNA)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The split-half reliability `V_RNA / sqrt(<A, A>_b <B, B>_b)` is the correlation
|
|
29
|
+
between the two halves. Sums run over all genes and all bins, spots or cells of
|
|
30
|
+
a section, and scores are averaged over repeated count splits. Counts must be
|
|
31
|
+
raw integer molecule counts, split before normalization, and predictions must
|
|
32
|
+
not use the counts they are evaluated against.
|
|
33
|
+
|
|
34
|
+
## Installation
|
|
35
|
+
|
|
36
|
+
Use Python 3.10 or later:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
python -m pip install strsc
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`python -m pip install "strsc[io]"` adds support for Parquet files.
|
|
43
|
+
|
|
44
|
+
## Score your predictions
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
import strsc
|
|
48
|
+
|
|
49
|
+
counts = strsc.read_counts("sample.h5ad") # a table, .h5ad, Space Ranger or Xenium folder
|
|
50
|
+
result = strsc.rsc(counts, {"my_model": "predictions.csv"}, layout="spots")
|
|
51
|
+
print(result.scales) # RSC, Pearson r and split-half reliability per scale
|
|
52
|
+
result.save("strsc-output")
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The command line runs the same analysis:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
strsc rsc sample.h5ad -p my_model=predictions.csv --layout spots --out strsc-output
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`layout` is `"spots"`, `"grid"` or `"cells"`. `strsc.regions` scores between
|
|
62
|
+
and within annotated regions, and `strsc.ideal_check` runs the paper's test
|
|
63
|
+
with the expected expression as the prediction. See
|
|
64
|
+
[RSC on your own data](docs/toolkit/api.md). The Calculate RSC tab of
|
|
65
|
+
[stRSC.org](https://stRSC.org/analyze) runs the same code in the browser.
|
|
66
|
+
|
|
67
|
+
## Run an example
|
|
68
|
+
|
|
69
|
+
Generate counts and two predictions, then compute RSC in five spatial bands:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
strsc example --output outputs/example
|
|
73
|
+
strsc export-results --run outputs/example/scores --output outputs/results.json --synthetic
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The example writes:
|
|
77
|
+
|
|
78
|
+
- `outputs/example/scores/`: RSC by band, gene-wise Pearson correlations and the RNA components;
|
|
79
|
+
- `outputs/example/analysis-bundle.json`: paired spatial maps for the website;
|
|
80
|
+
- `outputs/results.json`: saved evaluation results for the website.
|
|
81
|
+
|
|
82
|
+
The example runs on a CPU with generated data. Choose a new output directory for
|
|
83
|
+
each run.
|
|
84
|
+
|
|
85
|
+
To inspect the output online, open
|
|
86
|
+
[Computed results](https://stRSC.org/analyze?input=results), upload
|
|
87
|
+
`outputs/example/analysis-bundle.json` or `outputs/results.json`, then select
|
|
88
|
+
**View results**. Files are processed in the browser. The same workflow
|
|
89
|
+
applies to results computed from your own data.
|
|
90
|
+
|
|
91
|
+
## Evaluate your predictions
|
|
92
|
+
|
|
93
|
+
| Analysis | Command or API | Inputs and instructions |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| RSC on your own data, between and within regions | `strsc.rsc`, `strsc rsc`, `strsc.regions` | [RSC on your own data](docs/toolkit/api.md) |
|
|
96
|
+
| Pairwise accuracy across and within tissue regions | `strsc her2` | [Spot pairs](docs/toolkit/her2.md) |
|
|
97
|
+
| RSC in graph-frequency bands of spot data | `strsc hest` | [HEST workflow](docs/toolkit/hest.md) |
|
|
98
|
+
| RSC by physical wavelength on regular grids | `strsc fourier` | [Fourier workflow](docs/toolkit/fourier.md) |
|
|
99
|
+
| RSC for cells and aggregated grids, proliferation hotspots | `python -m strsc.cell_score` | [Cell workflow](docs/toolkit/cell.md) |
|
|
100
|
+
| Pairwise difference loss and model adapters | `strsc.training` | [Loss and model adapters](docs/toolkit/training.md) |
|
|
101
|
+
| Export evaluation results | `strsc export-results` | [Result format](docs/toolkit/export-results.md) |
|
|
102
|
+
|
|
103
|
+
Each guide specifies the expression transform, cell or site identifiers, gene
|
|
104
|
+
identifiers and spatial coordinates required by its workflow. Install optional
|
|
105
|
+
dependencies for cell preparation or model training:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
python -m pip install "strsc[cell]"
|
|
109
|
+
python -m pip install "strsc[training]"
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Paper analyses and figures
|
|
113
|
+
|
|
114
|
+
The [paper directory](paper/README.md) contains result tables, aggregation
|
|
115
|
+
scripts and figure sources. The documented aggregation commands run from bundled
|
|
116
|
+
tables. [Count-level recalculation](paper/RAW_INPUTS.md) uses source RNA counts
|
|
117
|
+
and saved predictions supplied in the specified formats.
|
|
118
|
+
|
|
119
|
+
## Tests
|
|
120
|
+
|
|
121
|
+
From a clone of this repository:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
git clone https://github.com/oyjr/stRSC.git
|
|
125
|
+
cd stRSC
|
|
126
|
+
python -m pip install -e ".[test]"
|
|
127
|
+
python -m pytest -q
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Citation and license
|
|
131
|
+
|
|
132
|
+
Author information and the software version are in [CITATION.cff](CITATION.cff).
|
|
133
|
+
The accompanying manuscript is *A noise-corrected metric for evaluating spatial
|
|
134
|
+
transcriptomics predicted from histology* by Ouyang, Gao and colleagues.
|
|
135
|
+
|
|
136
|
+
The code is released under the [MIT license](LICENSE). Third-party
|
|
137
|
+
dependencies, models and datasets retain their own terms; see [NOTICE.md](NOTICE.md).
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
{
|
|
2
|
+
"protocol_id": "G0-050_CELL_RESOLVED_VALIDATION_V1",
|
|
3
|
+
"specimens": [
|
|
4
|
+
"TENX98", "TENX99", "TENX95", "TENX97", "TENX94",
|
|
5
|
+
"TENX96", "NCBI784", "NCBI785", "NCBI783"
|
|
6
|
+
],
|
|
7
|
+
"split_seeds": [20260819, 20260820, 20260821, 20260822, 20260823],
|
|
8
|
+
"preflight_split_seeds": [
|
|
9
|
+
20260819, 20260820, 20260821, 20260822, 20260823,
|
|
10
|
+
20260824, 20260825, 20260826, 20260827, 20260828,
|
|
11
|
+
20260829, 20260830, 20260831, 20260832, 20260833,
|
|
12
|
+
20260834, 20260835, 20260836, 20260837, 20260838
|
|
13
|
+
],
|
|
14
|
+
"quality_value_min_exclusive": 20.0,
|
|
15
|
+
"control_prefixes": [
|
|
16
|
+
"BLANK_", "NegControlCodeword_", "NegControlProbe_", "antisense_"
|
|
17
|
+
],
|
|
18
|
+
"graph": {
|
|
19
|
+
"neighbors": 8,
|
|
20
|
+
"native_max_edge_um": 40.0,
|
|
21
|
+
"minimum_component_cells": 20,
|
|
22
|
+
"lazy_diffusion_powers": [16, 8, 4, 2, 0],
|
|
23
|
+
"bands": ["B1", "B2", "B3", "B4", "B5"]
|
|
24
|
+
},
|
|
25
|
+
"aggregation_um": [32, 64, 128, 256],
|
|
26
|
+
"aggregation_target": "mean_expression_per_cell",
|
|
27
|
+
"cellvit_mapping": {
|
|
28
|
+
"rule": "nearest_centroid",
|
|
29
|
+
"maximum_distance_um": 5.0
|
|
30
|
+
},
|
|
31
|
+
"model": {
|
|
32
|
+
"name": "sCellST",
|
|
33
|
+
"training_slide": "TENX39",
|
|
34
|
+
"primary_test_shape": "xenium_nucleus",
|
|
35
|
+
"supplementary_test_shape": "cellvit",
|
|
36
|
+
"supplementary_alignment": "mutual_nearest_centroid_max_5um",
|
|
37
|
+
"output_level": "cell"
|
|
38
|
+
},
|
|
39
|
+
"proliferation": {
|
|
40
|
+
"population": "Neoplastic",
|
|
41
|
+
"genes": ["MKI67", "TOP2A", "CENPF", "PCLAF"],
|
|
42
|
+
"cell_score": "log1p_1000_module_half_over_all_gene_half",
|
|
43
|
+
"rna_hotspot_split": "independent_binomial_module_and_other_counts_per_seed",
|
|
44
|
+
"radius_um": 64.0,
|
|
45
|
+
"minimum_neoplastic_cells": 5,
|
|
46
|
+
"hotspot_fraction": 0.10
|
|
47
|
+
},
|
|
48
|
+
"primary_endpoint": "within_Neoplastic_q_B4_plus_B5",
|
|
49
|
+
"formal_n": "patient",
|
|
50
|
+
"same_patient_slide_rule": "equal_weight_mean"
|
|
51
|
+
}
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# RSC on your own data
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
pip install strsc
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
`pip install "strsc[io]"` adds pyarrow, for Parquet position files of Space
|
|
8
|
+
Ranger and Xenium. Python 3.10 or later is needed.
|
|
9
|
+
|
|
10
|
+
```python
|
|
11
|
+
import strsc
|
|
12
|
+
|
|
13
|
+
counts = strsc.read_counts("sample.h5ad") # a table, .h5ad, Space Ranger or Xenium folder
|
|
14
|
+
result = strsc.rsc(counts, {"my_model": "predictions.csv"}, layout="spots")
|
|
15
|
+
print(result.scales) # RSC, Pearson r and split-half reliability per scale
|
|
16
|
+
result.save("strsc-output")
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The same analysis from the command line:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
strsc rsc sample.h5ad -p my_model=predictions.csv --layout spots --out strsc-output
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
This is the calculation that the Calculate RSC tab of
|
|
26
|
+
[stRSC.org](https://stRSC.org/analyze) runs in the browser, with the same steps
|
|
27
|
+
and random seeds. Each result page there shows the Python call and the command
|
|
28
|
+
for its own files.
|
|
29
|
+
|
|
30
|
+
## Counts
|
|
31
|
+
|
|
32
|
+
`strsc.read_counts(path)` reads raw integer molecule counts with the position
|
|
33
|
+
of every spot, bin or cell:
|
|
34
|
+
|
|
35
|
+
- a CSV or TSV table with `sample_id`, `unit_id`, `x` and `y`, optional
|
|
36
|
+
`patient_id`, `region`, `cell_class` and `area` columns, then one column per
|
|
37
|
+
gene (the test files of the website have this format);
|
|
38
|
+
- an AnnData `.h5ad` file, such as a HEST-1k sample. Counts come from
|
|
39
|
+
`layers['counts']` when present, otherwise from `X`; coordinates from
|
|
40
|
+
`obsm['spatial']`, otherwise from `obs` columns `x` and `y`;
|
|
41
|
+
- a 10x Genomics `.h5` matrix or `filtered_feature_bc_matrix` folder with the
|
|
42
|
+
`tissue_positions` file of Space Ranger (Visium spots or Visium HD bins), or
|
|
43
|
+
`cell_feature_matrix.h5` with the `cells` file of Xenium;
|
|
44
|
+
- a folder that holds one of these, such as a Space Ranger `outs` folder, a
|
|
45
|
+
Visium HD `square_016um` folder or a Xenium output folder. A folder that holds
|
|
46
|
+
several such folders gives one section per folder.
|
|
47
|
+
|
|
48
|
+
A list of paths gives one section per path. Options: `sample` names the
|
|
49
|
+
section, `positions` points to the positions file of a 10x matrix,
|
|
50
|
+
`layer`, `spatial_key`, `sample_column` and `columns` select parts of an
|
|
51
|
+
`.h5ad` file, and `um_per_unit` converts coordinates to micrometers when the
|
|
52
|
+
file does not say how. `counts.with_labels("labels.csv")` adds columns such as
|
|
53
|
+
`region` or `cell_class` from a table with `unit_id` (and `sample_id` when
|
|
54
|
+
there are several sections).
|
|
55
|
+
|
|
56
|
+
Counts must be whole numbers from before any normalization or log transform,
|
|
57
|
+
because RSC splits molecules. Xenium control probes are left out.
|
|
58
|
+
|
|
59
|
+
## Predictions
|
|
60
|
+
|
|
61
|
+
A prediction is a CSV or TSV table with `unit_id` (and `sample_id` when there
|
|
62
|
+
are several sections) and one column per gene, or an `.h5ad` file whose
|
|
63
|
+
observation names are the unit IDs. Give one or more as a dict of model name to
|
|
64
|
+
file, `Prediction` or array of the shape of the counts. RSC is computed on the
|
|
65
|
+
genes that the counts and every prediction share, and on the locations that
|
|
66
|
+
have a value for each of them.
|
|
67
|
+
|
|
68
|
+
## Layouts
|
|
69
|
+
|
|
70
|
+
| `layout` | Data | Scales | Half-count transform | Count splits | Gene weighting |
|
|
71
|
+
|---|---|---|---|---|---|
|
|
72
|
+
| `"spots"` | Visium, HEST | five relative scales, Broadest to Finest: equal-rank groups of the nonconstant eigenvectors of the neighbor-graph Laplacian | log(1 + 2 N_half) | 20 | two or more sections: agreement of the halves in the other sections, as for the HEST samples; one section: a common factor for each gene's halves |
|
|
73
|
+
| `"grid"` | Visium HD bins and other regular grids | seven physical scales of a two-dimensional Fourier basis, from below 128 µm to 4,096 µm and above | sqrt(N_half / (0.5 a)), with a the bin area | 5 | a common factor for each gene's halves |
|
|
74
|
+
| `"cells"` | Xenium and other single-cell data | five relative scales from lazy diffusion on the graph of the eight nearest neighbors within 40 µm | log(1 + 2 N_half) | 5 | a common factor for each gene's halves |
|
|
75
|
+
|
|
76
|
+
These are the steps of the paper (Methods, "Reproducible-signal correlation"
|
|
77
|
+
and "Scales and count transforms"). The `"grid"` layout gives the same RSC as
|
|
78
|
+
`strsc.fourier.score`. One spot section and several spot sections are weighted
|
|
79
|
+
differently, so their values are not directly comparable.
|
|
80
|
+
|
|
81
|
+
Further arguments of `strsc.rsc`:
|
|
82
|
+
|
|
83
|
+
| Argument | Meaning |
|
|
84
|
+
|---|---|
|
|
85
|
+
| `spacing_um` | Grid spacing in micrometers (`"grid"`); read from Visium HD files when not given |
|
|
86
|
+
| `within` | One or more values of the `cell_class` column to score on their own graphs (`"cells"`), as for the malignant cells of the paper |
|
|
87
|
+
| `all_cells` | Whether to score all cells as well (default `True`) |
|
|
88
|
+
| `cell_class` | Column that holds the cell classes (default `"cell_class"`) |
|
|
89
|
+
| `genes` | Restrict the genes |
|
|
90
|
+
| `splits` | Use only the first count splits of the paper; fewer splits give noisier values |
|
|
91
|
+
| `progress` | A function that receives progress events |
|
|
92
|
+
|
|
93
|
+
## Results
|
|
94
|
+
|
|
95
|
+
`strsc.rsc` returns a `Result` with three tables:
|
|
96
|
+
|
|
97
|
+
- `scales`: one row per model, section and scale, with `rsc`, `pearson_r` (the
|
|
98
|
+
Pearson r of the prediction with the mean of the two halves at that scale),
|
|
99
|
+
`split_half_reliability` (the correlation between the two halves), the terms
|
|
100
|
+
`C`, `V_model`, `V_RNA`, `V_A` and `V_B`, the lowest and highest RSC over the
|
|
101
|
+
count splits (`rsc_split_min`, `rsc_split_max`) and a `status`;
|
|
102
|
+
- `summary`: one row per model and section. For spots and cells, fine-scale RSC
|
|
103
|
+
(Fine and Finest scales) and broad-scale RSC (Broadest and Broad), the
|
|
104
|
+
difference between the broadest and finest scales, the fine-scale split-half
|
|
105
|
+
reliability and the whole-section Pearson r. For a grid, the broadest and
|
|
106
|
+
finest scales instead;
|
|
107
|
+
- `genes`: the same scores gene by gene.
|
|
108
|
+
|
|
109
|
+
With two or more sections, rows named `All sections` give the mean over
|
|
110
|
+
sections, as the means over samples in the paper. For cells, `C`, `V_model` and
|
|
111
|
+
`V_RNA` are averaged over sections before the ratio, as for the patients of the
|
|
112
|
+
paper.
|
|
113
|
+
|
|
114
|
+
`status` is `ESTIMABLE`, `NO_PREDICTED_VARIANCE` (the prediction does not vary
|
|
115
|
+
at that scale) or `RNA_UNRESOLVED` (the covariance between the two halves is
|
|
116
|
+
not positive, so RSC is not defined); `All sections` rows have
|
|
117
|
+
`MEAN_OVER_SECTIONS`. `result.save(folder)` writes `scales.tsv`,
|
|
118
|
+
`summary.tsv`, `genes.tsv`, `settings.json` and `strsc-evaluation.json`. The
|
|
119
|
+
last file opens under [Computed results](https://stRSC.org/analyze?input=results)
|
|
120
|
+
on the website; `result.to_bundle()` returns the same content as a dict.
|
|
121
|
+
|
|
122
|
+
## Between and within regions
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
counts = strsc.read_counts("sample.h5ad").with_labels("regions.csv")
|
|
126
|
+
result = strsc.regions(counts, {"my_model": "predictions.csv"}, focus="TLS")
|
|
127
|
+
print(result.summary)
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`strsc.regions` scores agreement between and within annotated regions, as for
|
|
131
|
+
the TLS sections of the paper (Methods, "Decomposition by region" and
|
|
132
|
+
"TLS-associated genes"). Each prediction and each RNA half is split into the
|
|
133
|
+
mean of its region and the residual from that mean. RSC is computed for the
|
|
134
|
+
whole section, between regions and within regions; when `focus` names a
|
|
135
|
+
region, also within it, between its structures (connected groups of its spots)
|
|
136
|
+
and within one structure. There is no spatial decomposition.
|
|
137
|
+
|
|
138
|
+
Measured expression is log(1 + 10,000 N / total), so predictions should be on
|
|
139
|
+
the same log scale. Every gene is divided by the standard deviation of its
|
|
140
|
+
unsplit expression over the spots of the term. Intervals are 95% percentile
|
|
141
|
+
intervals from 2,000 resamples of focus structures (terms within the focus
|
|
142
|
+
region) and of blocks of 10 × 10 spots (the other terms). A term is scored in a
|
|
143
|
+
section only when the lower limit of the interval of its split-half
|
|
144
|
+
reliability is above zero; otherwise its RSC is missing and its status is
|
|
145
|
+
`NOT_TESTABLE`. The region column is `region` unless `region=` names another.
|
|
146
|
+
|
|
147
|
+
From the command line, add `--regions region` and, optionally,
|
|
148
|
+
`--focus TLS` and `--labels regions.csv`.
|
|
149
|
+
|
|
150
|
+
## Expected expression as a prediction
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
table = strsc.ideal_check(counts, layout="spots", draws=3)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`strsc.ideal_check` repeats the paper's test of RSC (Methods, "Expected
|
|
157
|
+
expression as a prediction"). The measured counts are taken as Poisson rates,
|
|
158
|
+
count matrices are drawn from them, and on each the expected transformed
|
|
159
|
+
half-count is scored as the prediction. Its RSC should be near 1 at every
|
|
160
|
+
scale; in the paper it was 0.956 to 1.000. The table gives the mean, lowest and
|
|
161
|
+
highest RSC over the draws at each scale.
|
|
162
|
+
|
|
163
|
+
## Command line
|
|
164
|
+
|
|
165
|
+
```text
|
|
166
|
+
strsc rsc COUNTS [COUNTS ...] -p NAME=FILE [-p NAME=FILE ...] [options]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
| Option | Meaning |
|
|
170
|
+
|---|---|
|
|
171
|
+
| `-p`, `--prediction` | A prediction file, as `name=file` or a file alone; repeat for each model |
|
|
172
|
+
| `--layout` | `spots` (default), `grid` or `cells` |
|
|
173
|
+
| `--spacing-um` | Grid spacing in micrometers |
|
|
174
|
+
| `--within CLASS` | Score the cells of this class on their own graph; repeat for several classes |
|
|
175
|
+
| `--only-within` | With `--within`, do not score all cells as well |
|
|
176
|
+
| `--cell-class` | Column that holds the cell classes |
|
|
177
|
+
| `--regions COLUMN` | Score between and within the regions in this column |
|
|
178
|
+
| `--focus REGION` | With `--regions`, also score within this region and its structures |
|
|
179
|
+
| `--labels FILE` | A table with `unit_id` and columns such as `region` or `cell_class` |
|
|
180
|
+
| `--um-per-unit` | Micrometers per coordinate unit, when the files do not say |
|
|
181
|
+
| `--genes` | Comma-separated genes to score |
|
|
182
|
+
| `--splits` | Use only the first count splits |
|
|
183
|
+
| `--out` | Output folder (default `strsc-output`) |
|
|
184
|
+
|
|
185
|
+
## Reproducibility
|
|
186
|
+
|
|
187
|
+
The toolkit and the website use the same steps and seeds. The numbers agree
|
|
188
|
+
except at locations with many molecules of a gene, where numpy draws the count
|
|
189
|
+
split with floating-point steps that can differ between computers or numpy
|
|
190
|
+
versions; the results then differ within the scatter between count splits
|
|
191
|
+
(`rsc_split_min` to `rsc_split_max`). For spots, the projections onto the scales
|
|
192
|
+
run in single precision, so the last digits can differ.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Cell-level evaluation
|
|
2
|
+
|
|
3
|
+
The cell pipeline uses the same graph and five lazy-diffusion filters for RNA halves and predictions. It evaluates native cells and aggregated grids. `configs/cell_protocol.json` defines the molecule-split seeds, graph parameters, grid sizes and proliferation gene programme.
|
|
4
|
+
|
|
5
|
+
Install the cell dependencies:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
python -m pip install -e ".[cell]"
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Prepare counts and cell metadata
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
python -m strsc.cell_prepare --specimen MY_SLIDE --patient MY_PATIENT \
|
|
15
|
+
--transcripts data/transcripts.parquet \
|
|
16
|
+
--xenium-nuclei data/xenium_nuclei.parquet \
|
|
17
|
+
--cellvit data/cellvit_cells.parquet --metadata data/metadata.json \
|
|
18
|
+
--protocol configs/cell_protocol.json --output-root data/canonical
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
This entry point follows the study's HEST Xenium format: transcript Parquet columns `cell_id`, `feature_name` and `qv`; Xenium nuclei in GeoParquet with cell IDs in the index and registered pixel-space geometries; CellViT GeoParquet with `geometry` and `class` columns (and cell IDs in a column or index); and JSON metadata containing `pixel_size_um_estimated`, `pixel_size_um_embedded` or `pixel_size`. It counts retained transcripts, aligns cell identities and records the spatial units. Use `--gene-list` for an explicit input panel.
|
|
22
|
+
|
|
23
|
+
The command writes a sparse `counts_cells_by_genes.npz`, `cell_axis.parquet`, `gene_axis.parquet` and `metadata.json` to the canonical directory.
|
|
24
|
+
|
|
25
|
+
For already prepared inputs, `strsc.cell_core.save_canonical` accepts a CSR integer count matrix, a cell table, a gene table and metadata. Cell rows need `cell_id`, `x_um`, `y_um` and `cell_class`; gene rows need `gene_index` and `gene_symbol`; metadata needs `patient`. Array order must match both tables. The optional CellViT-native track additionally requires the alignment columns produced by the preparation step.
|
|
26
|
+
|
|
27
|
+
## Split-half reliability
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
python -m strsc.cell_rna --specimen MY_SLIDE \
|
|
31
|
+
--canonical-root data/canonical --protocol configs/cell_protocol.json \
|
|
32
|
+
--cache-root outputs/views --results outputs/rna --device cpu
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The command constructs native and aggregated views, splits molecules and accumulates RNA components using the protocol's filtering, exposure normalization and graph support.
|
|
36
|
+
|
|
37
|
+
## Score predictions
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
python -m strsc.cell_score --model sCellST --specimen MY_SLIDE \
|
|
41
|
+
--prediction data/prediction.h5ad --canonical-root data/canonical \
|
|
42
|
+
--view-cache-root outputs/views --protocol configs/cell_protocol.json \
|
|
43
|
+
--results outputs/cell_scores --device cpu
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use `--model DeepSpot2Cell` for that model. The prediction H5AD stores cells in rows, genes in columns, IDs in `obs_names` and gene symbols in `var_names`, with the model's native log1p-normalized output in `X`. The scorer aligns IDs explicitly and records missing coverage. The two model entry points share the same numerical implementation.
|
|
47
|
+
|
|
48
|
+
The five filters are `S^16`, `S^8-S^16`, `S^4-S^8`, `S^2-S^4` and `I-S^2`, where `S` is the lazy symmetric diffusion operator. The filters sum to the identity. Cell scoring also evaluates proliferation hotspots within Neoplastic cells, using the four programme genes specified in the protocol.
|