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.
Files changed (122) hide show
  1. strsc-0.4.0/LICENSE +21 -0
  2. strsc-0.4.0/MANIFEST.in +9 -0
  3. strsc-0.4.0/NOTICE.md +13 -0
  4. strsc-0.4.0/PKG-INFO +173 -0
  5. strsc-0.4.0/README.md +137 -0
  6. strsc-0.4.0/configs/cell_protocol.json +51 -0
  7. strsc-0.4.0/docs/toolkit/api.md +192 -0
  8. strsc-0.4.0/docs/toolkit/cell.md +48 -0
  9. strsc-0.4.0/docs/toolkit/evaluation-bundle.md +73 -0
  10. strsc-0.4.0/docs/toolkit/export-results.md +32 -0
  11. strsc-0.4.0/docs/toolkit/fourier.md +72 -0
  12. strsc-0.4.0/docs/toolkit/her2.md +91 -0
  13. strsc-0.4.0/docs/toolkit/hest.md +39 -0
  14. strsc-0.4.0/docs/toolkit/training.md +60 -0
  15. strsc-0.4.0/examples/bundles/cell.json +1 -0
  16. strsc-0.4.0/examples/bundles/fourier.json +1 -0
  17. strsc-0.4.0/examples/bundles/her2.json +1 -0
  18. strsc-0.4.0/examples/bundles/hest.json +1 -0
  19. strsc-0.4.0/examples/export_results_example.py +97 -0
  20. strsc-0.4.0/examples/train_mlp.py +40 -0
  21. strsc-0.4.0/pyproject.toml +33 -0
  22. strsc-0.4.0/setup.cfg +4 -0
  23. strsc-0.4.0/src/strsc/__init__.py +15 -0
  24. strsc-0.4.0/src/strsc/__main__.py +30 -0
  25. strsc-0.4.0/src/strsc/api.py +1232 -0
  26. strsc-0.4.0/src/strsc/cell_biology.py +241 -0
  27. strsc-0.4.0/src/strsc/cell_core.py +420 -0
  28. strsc-0.4.0/src/strsc/cell_prepare.py +223 -0
  29. strsc-0.4.0/src/strsc/cell_rna.py +274 -0
  30. strsc-0.4.0/src/strsc/cell_score.py +361 -0
  31. strsc-0.4.0/src/strsc/evaluation_export.py +288 -0
  32. strsc-0.4.0/src/strsc/example.py +69 -0
  33. strsc-0.4.0/src/strsc/export.py +119 -0
  34. strsc-0.4.0/src/strsc/files.py +757 -0
  35. strsc-0.4.0/src/strsc/fourier.py +271 -0
  36. strsc-0.4.0/src/strsc/her2.py +303 -0
  37. strsc-0.4.0/src/strsc/her2_core.py +958 -0
  38. strsc-0.4.0/src/strsc/hest.py +246 -0
  39. strsc-0.4.0/src/strsc/hest_core.py +289 -0
  40. strsc-0.4.0/src/strsc/rsc_cli.py +101 -0
  41. strsc-0.4.0/src/strsc/training/__init__.py +5 -0
  42. strsc-0.4.0/src/strsc/training/adapters/__init__.py +0 -0
  43. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/__init__.py +40 -0
  44. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/engineering_gate.py +239 -0
  45. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/formal_runner.py +254 -0
  46. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/graph.py +228 -0
  47. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/initialization.py +36 -0
  48. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/objective.py +212 -0
  49. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/overlay.py +79 -0
  50. strsc-0.4.0/src/strsc/training/adapters/deepspot2cell/paired_data.py +229 -0
  51. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/__init__.py +48 -0
  52. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/batching.py +730 -0
  53. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/data.py +448 -0
  54. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/engineering_gate.py +312 -0
  55. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/export.py +173 -0
  56. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/formal_runner.py +480 -0
  57. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/models.py +95 -0
  58. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/objective.py +492 -0
  59. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/overlay.py +141 -0
  60. strsc-0.4.0/src/strsc/training/adapters/hest_deephis2exp/split.py +80 -0
  61. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/__init__.py +62 -0
  62. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/contract.py +136 -0
  63. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/data.py +746 -0
  64. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/deepspot.py +162 -0
  65. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/engineering_gate.py +498 -0
  66. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/formal_runner.py +1003 -0
  67. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/hist.py +164 -0
  68. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/manifest.py +108 -0
  69. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/objective.py +94 -0
  70. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/outputs.py +154 -0
  71. strsc-0.4.0/src/strsc/training/adapters/hest_deepspot_hist/paired.py +54 -0
  72. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/__init__.py +27 -0
  73. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/contracts.py +124 -0
  74. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/engineering_gate.py +729 -0
  75. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/exemplars.py +241 -0
  76. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/hest_data.py +448 -0
  77. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/model_inputs.py +139 -0
  78. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/outputs.py +137 -0
  79. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/overlay.py +388 -0
  80. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/pairing.py +66 -0
  81. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/train_pair.py +458 -0
  82. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/training.py +750 -0
  83. strsc-0.4.0/src/strsc/training/adapters/hest_egn_tcgn/upstream.py +345 -0
  84. strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/__init__.py +15 -0
  85. strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/engineering_gate.py +270 -0
  86. strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/hest_data.py +396 -0
  87. strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/overlay.py +260 -0
  88. strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/train_pair.py +584 -0
  89. strsc-0.4.0/src/strsc/training/adapters/hest_thitogene/upstream.py +336 -0
  90. strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/__init__.py +6 -0
  91. strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/hest_contract.py +135 -0
  92. strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/model.py +23 -0
  93. strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/ridge.py +55 -0
  94. strsc-0.4.0/src/strsc/training/adapters/ridge_mlp/train_pair.py +621 -0
  95. strsc-0.4.0/src/strsc/training/adapters/scellst/__init__.py +42 -0
  96. strsc-0.4.0/src/strsc/training/adapters/scellst/data.py +279 -0
  97. strsc-0.4.0/src/strsc/training/adapters/scellst/engineering_gate.py +148 -0
  98. strsc-0.4.0/src/strsc/training/adapters/scellst/formal_runner.py +311 -0
  99. strsc-0.4.0/src/strsc/training/adapters/scellst/lightning_overlay.py +148 -0
  100. strsc-0.4.0/src/strsc/training/adapters/scellst/objective.py +87 -0
  101. strsc-0.4.0/src/strsc/training/adapters/scellst/runtime.py +416 -0
  102. strsc-0.4.0/src/strsc/training/adapters/scellst/split.py +232 -0
  103. strsc-0.4.0/src/strsc/training/hest_data.py +413 -0
  104. strsc-0.4.0/src/strsc/training/non_neighbours.py +256 -0
  105. strsc-0.4.0/src/strsc/training/shared/__init__.py +25 -0
  106. strsc-0.4.0/src/strsc/training/shared/adjacency.py +169 -0
  107. strsc-0.4.0/src/strsc/training/shared/losses.py +92 -0
  108. strsc-0.4.0/src/strsc/training/shared/noop.py +102 -0
  109. strsc-0.4.0/src/strsc.egg-info/PKG-INFO +173 -0
  110. strsc-0.4.0/src/strsc.egg-info/SOURCES.txt +120 -0
  111. strsc-0.4.0/src/strsc.egg-info/dependency_links.txt +1 -0
  112. strsc-0.4.0/src/strsc.egg-info/entry_points.txt +2 -0
  113. strsc-0.4.0/src/strsc.egg-info/requires.txt +25 -0
  114. strsc-0.4.0/src/strsc.egg-info/top_level.txt +1 -0
  115. strsc-0.4.0/tests/test_api.py +129 -0
  116. strsc-0.4.0/tests/test_cell.py +32 -0
  117. strsc-0.4.0/tests/test_core.py +37 -0
  118. strsc-0.4.0/tests/test_evaluation_export.py +48 -0
  119. strsc-0.4.0/tests/test_export_constant_prediction.py +98 -0
  120. strsc-0.4.0/tests/test_fourier.py +91 -0
  121. strsc-0.4.0/tests/test_her2.py +114 -0
  122. 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.
@@ -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.