scoubi 1.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.
- scoubi-1.0/LICENSE +21 -0
- scoubi-1.0/PKG-INFO +143 -0
- scoubi-1.0/README.md +103 -0
- scoubi-1.0/pyproject.toml +59 -0
- scoubi-1.0/scoubi/__init__.py +5 -0
- scoubi-1.0/scoubi/data/__init__.py +1 -0
- scoubi-1.0/scoubi/data/pairs.pkl +0 -0
- scoubi-1.0/scoubi/io/__init__.py +1 -0
- scoubi-1.0/scoubi/io/_io.py +236 -0
- scoubi-1.0/scoubi/model/__init__.py +1 -0
- scoubi-1.0/scoubi/model/_annotate.py +254 -0
- scoubi-1.0/scoubi/plotting/__init__.py +3 -0
- scoubi-1.0/scoubi/plotting/_enrichment.py +399 -0
- scoubi-1.0/scoubi/plotting/_radviz.py +257 -0
- scoubi-1.0/scoubi/plotting/_sunburst.py +251 -0
- scoubi-1.0/scoubi/preprocess/__init__.py +1 -0
- scoubi-1.0/scoubi/preprocess/_preprocess.py +97 -0
- scoubi-1.0/scoubi/tools/__init__.py +7 -0
- scoubi-1.0/scoubi/tools/_communication.py +80 -0
- scoubi-1.0/scoubi/tools/_distance.py +19 -0
- scoubi-1.0/scoubi/tools/_empirical.py +141 -0
- scoubi-1.0/scoubi/tools/_enrichment.py +187 -0
- scoubi-1.0/scoubi/tools/_overview.py +237 -0
- scoubi-1.0/scoubi/tools/_profile.py +130 -0
- scoubi-1.0/scoubi/tools/_ptest.py +382 -0
- scoubi-1.0/scoubi.egg-info/PKG-INFO +143 -0
- scoubi-1.0/scoubi.egg-info/SOURCES.txt +30 -0
- scoubi-1.0/scoubi.egg-info/dependency_links.txt +1 -0
- scoubi-1.0/scoubi.egg-info/requires.txt +17 -0
- scoubi-1.0/scoubi.egg-info/top_level.txt +1 -0
- scoubi-1.0/setup.cfg +4 -0
- scoubi-1.0/tests/test_basic_workflows.py +129 -0
scoubi-1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Bhavay Aggarwal
|
|
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.
|
scoubi-1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: scoubi
|
|
3
|
+
Version: 1.0
|
|
4
|
+
Summary: Signaling-informed Characterization of Unresolved Biological Interfaces
|
|
5
|
+
Author-email: Bhavay Aggarwal <baggarwal9@gatech.edu>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Documentation, https://github.com/bhavayaggarwal/SCOUBI
|
|
8
|
+
Project-URL: Repository, https://github.com/bhavayaggarwal/SCOUBI
|
|
9
|
+
Project-URL: Issues, https://github.com/bhavayaggarwal/SCOUBI/issues
|
|
10
|
+
Keywords: spatial transcriptomics,neuroscience,bioinformatics
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: numpy>=1.26
|
|
23
|
+
Requires-Dist: pandas>=2.3
|
|
24
|
+
Requires-Dist: pyarrow>=15
|
|
25
|
+
Requires-Dist: scipy>=1.13
|
|
26
|
+
Requires-Dist: scikit-learn>=1.6
|
|
27
|
+
Requires-Dist: statsmodels>=0.13
|
|
28
|
+
Requires-Dist: torch>=2.5
|
|
29
|
+
Requires-Dist: anndata>=0.10
|
|
30
|
+
Requires-Dist: scanpy>=1.10
|
|
31
|
+
Requires-Dist: sparse>=0.17
|
|
32
|
+
Requires-Dist: matplotlib>=3.9
|
|
33
|
+
Requires-Dist: seaborn>=0.13
|
|
34
|
+
Requires-Dist: tqdm>=4.64
|
|
35
|
+
Requires-Dist: requests>=2.27
|
|
36
|
+
Requires-Dist: rich>=13.4
|
|
37
|
+
Requires-Dist: adjustText>=1.3
|
|
38
|
+
Requires-Dist: colorcet>=2.0
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<img src="files/scoubi_transparent.png" alt="SCOUBI logo" width="720">
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
# SCOUBI
|
|
46
|
+
|
|
47
|
+
SCOUBI is a computational framework for analyzing extrasomatic transcripts in imaging-based spatial transcriptomics data. Rather than discarding unassigned RNA as background, SCOUBI uses marker-gene expression of neurites and spatial ligand–receptor colocalization to classify extrasomatic regions as axon- or dendrite-enriched and to identify putative “interfaces” enriched for intercellular signaling programs. These interfaces provide a transcriptomic window into neuronal communication sites that are typically inaccessible to cell-centric spatial analyses. By preserving anatomical context, SCOUBI enables regional and molecular characterization of putative synaptic signaling environments directly from intact tissue.
|
|
48
|
+
|
|
49
|
+
**Preprint:** [add preprint link here](https://example.com/preprint)
|
|
50
|
+
|
|
51
|
+
## Overview
|
|
52
|
+
|
|
53
|
+
Imaging-based spatial transcriptomics often detects a substantial fraction of transcripts outside segmented cell bodies. SCOUBI treats this extrasomatic signal as a biologically informative layer of tissue organization.
|
|
54
|
+
|
|
55
|
+
The workflow has two main stages:
|
|
56
|
+
|
|
57
|
+
1. **Neurite identity classification**
|
|
58
|
+
Extrasomatic spatial bins are classified as axon- or dendrite-enriched using curated marker genes and a signaling-informed optimization objective.
|
|
59
|
+
|
|
60
|
+
2. **Interface identification**
|
|
61
|
+
SCOUBI scans for local regions where axonic and dendritic bins converge and where significant ligand–receptor pairs are colocalized.
|
|
62
|
+
|
|
63
|
+
The resulting interface map can be used to study:
|
|
64
|
+
|
|
65
|
+
- Spatial distribution of putative neuronal communication regions
|
|
66
|
+
- Neurite-enriched genes
|
|
67
|
+
- Interface-enriched genes
|
|
68
|
+
- Regional variation in interface transcriptomes
|
|
69
|
+
- Interface signatures compared with nearby cell bodies
|
|
70
|
+
|
|
71
|
+
## Installation
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pip install scoubi
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
For local development from a checkout:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pip install -e .
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Quickstart
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
import torch
|
|
87
|
+
import scoubi
|
|
88
|
+
|
|
89
|
+
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
|
|
90
|
+
|
|
91
|
+
adata = scoubi.io.load_data(
|
|
92
|
+
"data/data.parquet",
|
|
93
|
+
cell_type="data/cell_types.csv",
|
|
94
|
+
region="data/regions.csv",
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
adata = scoubi.pp.bin_data(adata, binsize=2)
|
|
98
|
+
adata = scoubi.md.train(adata, axon_markers, dendrite_markers, device=device)
|
|
99
|
+
adata = scoubi.tl.overview(adata, device=device)
|
|
100
|
+
adata = scoubi.tl.axon_dendrite_enrichment(adata)
|
|
101
|
+
adata = scoubi.tl.distance(adata)
|
|
102
|
+
adata = scoubi.tl.expression_profile(adata, key="region")
|
|
103
|
+
adata = scoubi.tl.communication_profile(adata, key="region")
|
|
104
|
+
|
|
105
|
+
adata.summarize()
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Module Map
|
|
109
|
+
|
|
110
|
+
| Module | Alias | Purpose |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `scoubi.io` | - | Data loading and AnnData helpers |
|
|
113
|
+
| `scoubi.preprocess` | `scoubi.pp` | Preprocessing (Spatial binning) |
|
|
114
|
+
| `scoubi.model` | `scoubi.md` | Neurite annotation |
|
|
115
|
+
| `scoubi.tools` | `scoubi.tl` | Downstream analysis utilities |
|
|
116
|
+
| `scoubi.plotting` | `scoubi.pl` | Visualization helpers |
|
|
117
|
+
|
|
118
|
+
## Data and Runtime Notes
|
|
119
|
+
|
|
120
|
+
- `scoubi.md.train()` can use a bundled ligand-receptor reference table (from NeuronChat) when `pairs=None`.
|
|
121
|
+
- GPU acceleration is optional; most workflows can run on CPU, although training and convolution-heavy steps are faster on CUDA when available.
|
|
122
|
+
|
|
123
|
+
## Tutorial
|
|
124
|
+
|
|
125
|
+
The guided walkthrough lives in [tutorial.ipynb](tutorial.ipynb). It covers data loading, model training, spatial overview generation, enrichment analysis, interface profiling, communication analysis, and save/load workflows.
|
|
126
|
+
|
|
127
|
+
## License
|
|
128
|
+
|
|
129
|
+
Released under the MIT License. See [LICENSE](LICENSE).
|
|
130
|
+
|
|
131
|
+
## Citation
|
|
132
|
+
|
|
133
|
+
> If you use SCOUBI in your work, please cite:
|
|
134
|
+
>
|
|
135
|
+
> ```bibtex
|
|
136
|
+
> @article{scoubi,
|
|
137
|
+
> title = {SCOUBI: Signaling-informed Characterization of Unresolved Biological Interfaces},
|
|
138
|
+
> author = {TODO},
|
|
139
|
+
> journal = {TODO},
|
|
140
|
+
> year = {TODO},
|
|
141
|
+
> doi = {TODO}
|
|
142
|
+
> }
|
|
143
|
+
> ```
|
scoubi-1.0/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="files/scoubi_transparent.png" alt="SCOUBI logo" width="720">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# SCOUBI
|
|
6
|
+
|
|
7
|
+
SCOUBI is a computational framework for analyzing extrasomatic transcripts in imaging-based spatial transcriptomics data. Rather than discarding unassigned RNA as background, SCOUBI uses marker-gene expression of neurites and spatial ligand–receptor colocalization to classify extrasomatic regions as axon- or dendrite-enriched and to identify putative “interfaces” enriched for intercellular signaling programs. These interfaces provide a transcriptomic window into neuronal communication sites that are typically inaccessible to cell-centric spatial analyses. By preserving anatomical context, SCOUBI enables regional and molecular characterization of putative synaptic signaling environments directly from intact tissue.
|
|
8
|
+
|
|
9
|
+
**Preprint:** [add preprint link here](https://example.com/preprint)
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
Imaging-based spatial transcriptomics often detects a substantial fraction of transcripts outside segmented cell bodies. SCOUBI treats this extrasomatic signal as a biologically informative layer of tissue organization.
|
|
14
|
+
|
|
15
|
+
The workflow has two main stages:
|
|
16
|
+
|
|
17
|
+
1. **Neurite identity classification**
|
|
18
|
+
Extrasomatic spatial bins are classified as axon- or dendrite-enriched using curated marker genes and a signaling-informed optimization objective.
|
|
19
|
+
|
|
20
|
+
2. **Interface identification**
|
|
21
|
+
SCOUBI scans for local regions where axonic and dendritic bins converge and where significant ligand–receptor pairs are colocalized.
|
|
22
|
+
|
|
23
|
+
The resulting interface map can be used to study:
|
|
24
|
+
|
|
25
|
+
- Spatial distribution of putative neuronal communication regions
|
|
26
|
+
- Neurite-enriched genes
|
|
27
|
+
- Interface-enriched genes
|
|
28
|
+
- Regional variation in interface transcriptomes
|
|
29
|
+
- Interface signatures compared with nearby cell bodies
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install scoubi
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
For local development from a checkout:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install -e .
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Quickstart
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
import torch
|
|
47
|
+
import scoubi
|
|
48
|
+
|
|
49
|
+
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
|
|
50
|
+
|
|
51
|
+
adata = scoubi.io.load_data(
|
|
52
|
+
"data/data.parquet",
|
|
53
|
+
cell_type="data/cell_types.csv",
|
|
54
|
+
region="data/regions.csv",
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
adata = scoubi.pp.bin_data(adata, binsize=2)
|
|
58
|
+
adata = scoubi.md.train(adata, axon_markers, dendrite_markers, device=device)
|
|
59
|
+
adata = scoubi.tl.overview(adata, device=device)
|
|
60
|
+
adata = scoubi.tl.axon_dendrite_enrichment(adata)
|
|
61
|
+
adata = scoubi.tl.distance(adata)
|
|
62
|
+
adata = scoubi.tl.expression_profile(adata, key="region")
|
|
63
|
+
adata = scoubi.tl.communication_profile(adata, key="region")
|
|
64
|
+
|
|
65
|
+
adata.summarize()
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Module Map
|
|
69
|
+
|
|
70
|
+
| Module | Alias | Purpose |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| `scoubi.io` | - | Data loading and AnnData helpers |
|
|
73
|
+
| `scoubi.preprocess` | `scoubi.pp` | Preprocessing (Spatial binning) |
|
|
74
|
+
| `scoubi.model` | `scoubi.md` | Neurite annotation |
|
|
75
|
+
| `scoubi.tools` | `scoubi.tl` | Downstream analysis utilities |
|
|
76
|
+
| `scoubi.plotting` | `scoubi.pl` | Visualization helpers |
|
|
77
|
+
|
|
78
|
+
## Data and Runtime Notes
|
|
79
|
+
|
|
80
|
+
- `scoubi.md.train()` can use a bundled ligand-receptor reference table (from NeuronChat) when `pairs=None`.
|
|
81
|
+
- GPU acceleration is optional; most workflows can run on CPU, although training and convolution-heavy steps are faster on CUDA when available.
|
|
82
|
+
|
|
83
|
+
## Tutorial
|
|
84
|
+
|
|
85
|
+
The guided walkthrough lives in [tutorial.ipynb](tutorial.ipynb). It covers data loading, model training, spatial overview generation, enrichment analysis, interface profiling, communication analysis, and save/load workflows.
|
|
86
|
+
|
|
87
|
+
## License
|
|
88
|
+
|
|
89
|
+
Released under the MIT License. See [LICENSE](LICENSE).
|
|
90
|
+
|
|
91
|
+
## Citation
|
|
92
|
+
|
|
93
|
+
> If you use SCOUBI in your work, please cite:
|
|
94
|
+
>
|
|
95
|
+
> ```bibtex
|
|
96
|
+
> @article{scoubi,
|
|
97
|
+
> title = {SCOUBI: Signaling-informed Characterization of Unresolved Biological Interfaces},
|
|
98
|
+
> author = {TODO},
|
|
99
|
+
> journal = {TODO},
|
|
100
|
+
> year = {TODO},
|
|
101
|
+
> doi = {TODO}
|
|
102
|
+
> }
|
|
103
|
+
> ```
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "scoubi"
|
|
7
|
+
version = "1.0"
|
|
8
|
+
authors = [
|
|
9
|
+
{ name="Bhavay Aggarwal", email="baggarwal9@gatech.edu" },
|
|
10
|
+
]
|
|
11
|
+
description = "Signaling-informed Characterization of Unresolved Biological Interfaces"
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
license = "MIT"
|
|
14
|
+
readme = "README.md"
|
|
15
|
+
keywords = ["spatial transcriptomics", "neuroscience", "bioinformatics"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 3 - Alpha",
|
|
18
|
+
"Intended Audience :: Science/Research",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Topic :: Scientific/Engineering :: Bio-Informatics",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"numpy>=1.26",
|
|
28
|
+
"pandas>=2.3",
|
|
29
|
+
"pyarrow>=15",
|
|
30
|
+
"scipy>=1.13",
|
|
31
|
+
"scikit-learn>=1.6",
|
|
32
|
+
"statsmodels>=0.13",
|
|
33
|
+
"torch>=2.5",
|
|
34
|
+
"anndata>=0.10",
|
|
35
|
+
"scanpy>=1.10",
|
|
36
|
+
"sparse>=0.17",
|
|
37
|
+
"matplotlib>=3.9",
|
|
38
|
+
"seaborn>=0.13",
|
|
39
|
+
"tqdm>=4.64",
|
|
40
|
+
"requests>=2.27",
|
|
41
|
+
"rich>=13.4",
|
|
42
|
+
"adjustText>=1.3",
|
|
43
|
+
"colorcet>=2.0",
|
|
44
|
+
]
|
|
45
|
+
|
|
46
|
+
[project.urls]
|
|
47
|
+
Documentation = "https://github.com/bhavayaggarwal/SCOUBI"
|
|
48
|
+
Repository = "https://github.com/bhavayaggarwal/SCOUBI"
|
|
49
|
+
Issues = "https://github.com/bhavayaggarwal/SCOUBI/issues"
|
|
50
|
+
|
|
51
|
+
[tool.setuptools]
|
|
52
|
+
include-package-data = true
|
|
53
|
+
|
|
54
|
+
[tool.setuptools.packages.find]
|
|
55
|
+
where = ["."]
|
|
56
|
+
include = ["scoubi*"]
|
|
57
|
+
|
|
58
|
+
[tool.setuptools.package-data]
|
|
59
|
+
"scoubi.data" = ["pairs.pkl"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Bundled SCOUBI resources."""
|
|
Binary file
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
from ._io import load_data
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import pandas as pd
|
|
3
|
+
import anndata as ad
|
|
4
|
+
import numpy as np
|
|
5
|
+
from scipy.sparse import coo_matrix
|
|
6
|
+
import types
|
|
7
|
+
|
|
8
|
+
class LazyTranscripts:
|
|
9
|
+
"""Lazy loader for transcripts parquet (cached after first load)."""
|
|
10
|
+
def __init__(self, path):
|
|
11
|
+
self.path = path
|
|
12
|
+
self._df = None
|
|
13
|
+
def load(self):
|
|
14
|
+
if self._df is None:
|
|
15
|
+
self._df = pd.read_parquet(self.path)
|
|
16
|
+
return self._df
|
|
17
|
+
def save(self):
|
|
18
|
+
if self._df is not None:
|
|
19
|
+
self._df.to_parquet(self.path)
|
|
20
|
+
else:
|
|
21
|
+
raise("DataFrame not loaded.")
|
|
22
|
+
def __call__(self):
|
|
23
|
+
return self.load()
|
|
24
|
+
def __getattr__(self, name):
|
|
25
|
+
raise AttributeError("Access only via .load()")
|
|
26
|
+
def __getitem__(self, key):
|
|
27
|
+
return self.load()[key]
|
|
28
|
+
|
|
29
|
+
def _attach_lazy_loader(adata):
|
|
30
|
+
"""Attach get_transcripts() method to adata in memory (not stored in .uns)."""
|
|
31
|
+
def _get_transcripts(self):
|
|
32
|
+
path = self.uns.get('transcripts_path', None)
|
|
33
|
+
if path is None:
|
|
34
|
+
raise KeyError("No 'transcripts_path' in adata.uns")
|
|
35
|
+
if not hasattr(self, '_transcripts') or self._transcripts.path != path:
|
|
36
|
+
self._transcripts = LazyTranscripts(path)
|
|
37
|
+
return self._transcripts
|
|
38
|
+
adata.get_transcripts = types.MethodType(_get_transcripts, adata)
|
|
39
|
+
|
|
40
|
+
def _summarize(self):
|
|
41
|
+
"""Structured summary of AnnData with grouped .uns fields.
|
|
42
|
+
|
|
43
|
+
Groups are: data, annotations, maps, enrichment, comparison, testing,
|
|
44
|
+
interface, communication, misc.
|
|
45
|
+
Any .uns keys not in a known group are printed under 'other'.
|
|
46
|
+
"""
|
|
47
|
+
print(f"AnnData object with n_obs × n_vars = {self.n_obs} × {self.n_vars}")
|
|
48
|
+
print("obs:", ", ".join(self.obs.columns.tolist()))
|
|
49
|
+
print("obsm:", ", ".join(self.obsm.keys()))
|
|
50
|
+
print("uns:")
|
|
51
|
+
|
|
52
|
+
# --- Predefined grouping map ---
|
|
53
|
+
group_map = {
|
|
54
|
+
'data': [
|
|
55
|
+
'transcripts_path', 'data_shape', 'binned_data_shape',
|
|
56
|
+
'mask_cell', 'mask_ecm', 'binned_data',
|
|
57
|
+
'axon_markers', 'dendrite_markers', 'genes', 'lr_pairs'
|
|
58
|
+
],
|
|
59
|
+
'annotations': ['bin_probabilities', 'bin_scores'],
|
|
60
|
+
'maps': [
|
|
61
|
+
'axon_map', 'dendrite_map', 'interface_map'
|
|
62
|
+
],
|
|
63
|
+
'enrichment': ['axon_enrichment_df', 'dendrite_enrichment_df'],
|
|
64
|
+
'comparison': ['ptest_a_vs_d'],
|
|
65
|
+
'testing': [
|
|
66
|
+
'empirical', 'regional_ptest',
|
|
67
|
+
'ptest_best_rank', 'ptest_best_rank_neuronal', 'ptest_best_rank_non_neuronal'
|
|
68
|
+
],
|
|
69
|
+
'interface': ['interface_cell_type_profile', 'interface_cell_type_region_profile', 'interface_region_profile'],
|
|
70
|
+
'communication': [
|
|
71
|
+
'cellwhisper', 'cellwhisper_unfiltered', 'cellwhisper_lr', 'cellwhisper_regionwise',
|
|
72
|
+
'communication_cell_type_profile', 'communication_cell_type_region_profile',
|
|
73
|
+
'communication_region_profile', 'lr_edges'
|
|
74
|
+
],
|
|
75
|
+
'misc': ['interface_knn_idx', 'interface_knn_dists', 'model_weights'],
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
# flatten group map for lookup
|
|
79
|
+
assigned = set(k for keys in group_map.values() for k in keys)
|
|
80
|
+
uns_keys = set(self.uns.keys())
|
|
81
|
+
ungrouped = sorted(uns_keys - assigned)
|
|
82
|
+
|
|
83
|
+
# print present keys per group
|
|
84
|
+
for group, keys in group_map.items():
|
|
85
|
+
present = [k for k in keys if k in self.uns]
|
|
86
|
+
if present:
|
|
87
|
+
print(f" {group:<22}: {', '.join(present)}")
|
|
88
|
+
|
|
89
|
+
if ungrouped:
|
|
90
|
+
print(f" {'other':<22}: {', '.join(ungrouped)}")
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _attach_summarize(adata):
|
|
94
|
+
"""Attach summarize() method to a single AnnData object in memory."""
|
|
95
|
+
adata.summarize = types.MethodType(_summarize, adata)
|
|
96
|
+
return adata
|
|
97
|
+
|
|
98
|
+
def load_data(
|
|
99
|
+
filename: str,
|
|
100
|
+
cell_type=None,
|
|
101
|
+
region=None,
|
|
102
|
+
qv_thresold=None,
|
|
103
|
+
filter_genes=('BLANK', 'NegControl', 'DeprecatedCodeword', 'UnassignedCodeword', 'Blank'),
|
|
104
|
+
usr_label="UNASSIGNED",
|
|
105
|
+
overwrite=False,
|
|
106
|
+
) -> ad.AnnData:
|
|
107
|
+
"""
|
|
108
|
+
Load spatial transcriptomics data and return an annotated AnnData object.
|
|
109
|
+
|
|
110
|
+
Reads transcript-level data from a CSV, Parquet, or pre-built H5AD file,
|
|
111
|
+
constructs a sparse cell × gene count matrix, stores spatial coordinates,
|
|
112
|
+
writes a sidecar Parquet for lazy transcript access, and attaches two
|
|
113
|
+
convenience methods to the returned object:
|
|
114
|
+
|
|
115
|
+
* ``adata.summarize()`` – prints a structured overview (see :func:`_summarize`)
|
|
116
|
+
* ``adata.get_transcripts()`` – lazily loads the transcript table (see :func:`_attach_lazy_loader`)
|
|
117
|
+
|
|
118
|
+
Parameters
|
|
119
|
+
----------
|
|
120
|
+
filename : str
|
|
121
|
+
Path to the input file. Accepted formats:
|
|
122
|
+
|
|
123
|
+
* ``.parquet`` / ``.csv`` – raw transcript table with columns
|
|
124
|
+
``cell_id``, ``gene`` (or ``feature_name``), and optionally
|
|
125
|
+
``x_location``, ``y_location``, ``z_location``, ``qv``.
|
|
126
|
+
* ``.h5ad`` – previously saved AnnData; loaded directly and
|
|
127
|
+
returned after re-attaching the lazy-loader and summarize methods.
|
|
128
|
+
cell_type : str, optional
|
|
129
|
+
Path to a CSV file (index = cell IDs) containing a single column
|
|
130
|
+
of cell-type labels. Stored in ``adata.obs['cell_type']``.
|
|
131
|
+
region : str, optional
|
|
132
|
+
Path to a CSV file (index = cell IDs) containing a single column
|
|
133
|
+
of region labels. Stored in ``adata.obs['region']``.
|
|
134
|
+
qv_thresold : float, optional
|
|
135
|
+
Minimum quality-value score. Transcripts with ``qv < qv_threshold``
|
|
136
|
+
are dropped before matrix construction. No filtering if ``None``.
|
|
137
|
+
filter_genes : tuple[str, ...], optional
|
|
138
|
+
Gene-name prefixes to exclude (e.g. blanks, negative controls).
|
|
139
|
+
Default: ``('BLANK', 'NegControl', 'DeprecatedCodeword',
|
|
140
|
+
'UnassignedCodeword', 'Blank')``.
|
|
141
|
+
usr_label : str, optional
|
|
142
|
+
Cell-ID value used to mark unassigned transcripts. Rows with this
|
|
143
|
+
label are excluded from the count matrix but retained in the saved
|
|
144
|
+
transcript Parquet. Default: ``'UNASSIGNED'``.
|
|
145
|
+
overwrite : bool, optional
|
|
146
|
+
If ``True``, the sidecar Parquet is written to `filename` directly
|
|
147
|
+
instead of ``<stem>_scoubi.parquet``. Default: ``False``.
|
|
148
|
+
|
|
149
|
+
Returns
|
|
150
|
+
-------
|
|
151
|
+
ad.AnnData
|
|
152
|
+
AnnData object with:
|
|
153
|
+
|
|
154
|
+
* ``X`` – sparse (CSR) cell × gene count matrix
|
|
155
|
+
* ``obsm['spatial']`` – mean (x, y[, z]) coordinates per cell
|
|
156
|
+
* ``uns['transcripts_path']`` – path to the sidecar Parquet
|
|
157
|
+
* ``adata.summarize()`` – bound summary method
|
|
158
|
+
* ``adata.get_transcripts()`` – bound lazy transcript accessor
|
|
159
|
+
|
|
160
|
+
Raises
|
|
161
|
+
------
|
|
162
|
+
ValueError
|
|
163
|
+
If ``filename`` does not end with ``.csv``, ``.parquet``, or ``.h5ad``.
|
|
164
|
+
|
|
165
|
+
See Also
|
|
166
|
+
--------
|
|
167
|
+
_summarize : Prints a grouped overview of all AnnData fields.
|
|
168
|
+
_attach_lazy_loader : Attaches the ``get_transcripts()`` method.
|
|
169
|
+
"""
|
|
170
|
+
# --- read input ---
|
|
171
|
+
if filename.endswith('.parquet'):
|
|
172
|
+
df = pd.read_parquet(filename)
|
|
173
|
+
elif filename.endswith('.csv'):
|
|
174
|
+
df = pd.read_csv(filename)
|
|
175
|
+
elif filename.endswith('.h5ad'):
|
|
176
|
+
adata = ad.read_h5ad(filename)
|
|
177
|
+
if 'transcripts_path' in adata.uns:
|
|
178
|
+
_attach_lazy_loader(adata)
|
|
179
|
+
_attach_summarize(adata)
|
|
180
|
+
return adata
|
|
181
|
+
else:
|
|
182
|
+
raise ValueError("Unsupported file format. Use .csv, .parquet, or .h5ad.")
|
|
183
|
+
|
|
184
|
+
# --- filter ---
|
|
185
|
+
if 'qv' in df.columns and qv_thresold is not None:
|
|
186
|
+
df = df[df.qv >= qv_thresold]
|
|
187
|
+
if 'feature_name' in df.columns:
|
|
188
|
+
df = df.rename(columns={'feature_name':'gene'})
|
|
189
|
+
df = df[~df['gene'].str.startswith(tuple(filter_genes), na=False)]
|
|
190
|
+
df.sort_values(by=['cell_id'], inplace=True, ascending=True)
|
|
191
|
+
df_cell = df[df.cell_id != usr_label].copy()
|
|
192
|
+
|
|
193
|
+
# --- build sparse counts from df_cell ---
|
|
194
|
+
cell_codes, cell_uniques = pd.factorize(df_cell['cell_id'].astype(str))
|
|
195
|
+
gene_codes, gene_uniques = pd.factorize(df_cell['gene'].astype(str))
|
|
196
|
+
data = np.ones(len(df_cell), dtype=np.int32)
|
|
197
|
+
X = coo_matrix((data, (cell_codes, gene_codes)),
|
|
198
|
+
shape=(len(cell_uniques), len(gene_uniques))).tocsr()
|
|
199
|
+
|
|
200
|
+
obs = pd.DataFrame(index=cell_uniques.astype(str))
|
|
201
|
+
var = pd.DataFrame(index=gene_uniques.astype(str))
|
|
202
|
+
adata = ad.AnnData(X=X, obs=obs, var=var)
|
|
203
|
+
|
|
204
|
+
# --- spatial coordinates ---
|
|
205
|
+
loc_cols = ['x_location','y_location']
|
|
206
|
+
if 'z_location' in df_cell.columns:
|
|
207
|
+
loc_cols.append('z_location')
|
|
208
|
+
if loc_cols:
|
|
209
|
+
spatial = df_cell.groupby(df_cell['cell_id'].astype(str))[loc_cols].mean()
|
|
210
|
+
spatial = spatial.reindex(obs.index)
|
|
211
|
+
adata.obsm['spatial'] = spatial.values
|
|
212
|
+
|
|
213
|
+
# --- save transcripts parquet (full df) ---
|
|
214
|
+
if not overwrite:
|
|
215
|
+
parquet_path = os.path.abspath(os.path.splitext(filename)[0] + "_scoubi.parquet")
|
|
216
|
+
else:
|
|
217
|
+
parquet_path = os.path.abspath(filename)
|
|
218
|
+
df.to_parquet(parquet_path, index=False)
|
|
219
|
+
adata.uns['transcripts_path'] = parquet_path
|
|
220
|
+
_attach_lazy_loader(adata)
|
|
221
|
+
_attach_summarize(adata)
|
|
222
|
+
ad.AnnData.summarize = _summarize
|
|
223
|
+
adata._transcripts = LazyTranscripts(parquet_path) # optional pre-cache
|
|
224
|
+
|
|
225
|
+
# --- cell type annotations ---
|
|
226
|
+
if cell_type is not None:
|
|
227
|
+
df_ct = pd.read_csv(cell_type, index_col=0)
|
|
228
|
+
df_ct.index = df_ct.index.astype(str)
|
|
229
|
+
adata.obs['cell_type'] = df_ct.reindex(obs.index)
|
|
230
|
+
if region is not None:
|
|
231
|
+
df_rg = pd.read_csv(region, index_col=0)
|
|
232
|
+
df_rg.index = df_rg.index.astype(str)
|
|
233
|
+
adata.obs['region'] = df_rg.reindex(obs.index)
|
|
234
|
+
|
|
235
|
+
del df, X, data
|
|
236
|
+
return adata
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
from ._annotate import train, get_zscore, do_conv, _prep_dict, kernel
|