Skip to content

Commit 53d6b29

Browse files
xiachenruixiachenrui
committed
📌 Update dependencies
1 parent 2d2f327 commit 53d6b29

File tree

13 files changed

+138
-108
lines changed

13 files changed

+138
-108
lines changed

‎.readthedocs.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,14 @@ build:
55
python: "3.8"
66
apt_packages:
77
- pandoc
8+
jobs:
9+
post_create_environment:
10+
- pip install torch==1.11.0+cpu --extra-index-url https://download.pytorch.org/whl/cpu
11+
- pip install https://data.pyg.org/whl/torch-1.11.0%2Bcpu/torch_cluster-1.6.0-cp38-cp38-linux_x86_64.whl
12+
- pip install https://data.pyg.org/whl/torch-1.11.0%2Bcpu/torch_scatter-2.0.9-cp38-cp38-linux_x86_64.whl
13+
- pip install https://data.pyg.org/whl/torch-1.11.0%2Bcpu/torch_sparse-0.6.15-cp38-cp38-linux_x86_64.whl
14+
- pip install torch-geometric
15+
- pip install scSLAT
816
sphinx:
917
configuration: docs/conf.py
1018
python:

‎README.md

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -36,24 +36,30 @@ Tutorial of `scSLAT` is [here](https://slat.readthedocs.io/en/latest/tutorials.h
3636
## Installation
3737

3838
### Docker
39-
Dockerfile of `scSLAT` is available at [`env/Dockerfile`](env/Dockerfile). You can also pull the docker image directly from [here](https://hub.docker.com/repository/docker/huhansan666666/slat) by :
40-
```
39+
Dockerfile of `scSLAT` is available at [`env/Dockerfile`](env/Dockerfile). You can also pull the docker image directly from [here](https://hub.docker.com/repository/docker/huhansan666666/slat) by:
40+
41+
``` bash
4142
docker pull huhansan666666/slat:latest
4243
```
4344

4445
### PyPI
46+
> **Note**
4547
> Installing `scSLAT` within a new [conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) is recommended.
4648
4749
First, we create a clean environment and install `scSLAT` from PyPI. We need install dependency `torch` before install `pyg`.
4850

49-
> Warning: machine with old NVIDIA driver may raise error, please update NVIDIA driver to the latest version or use Docker.
51+
> **Warning**
52+
> old NVIDIA driver may raise error, please update NVIDIA driver to the latest version.
5053
5154
```bash
5255
conda create -n scSLAT python=3.8 -y && conda activate scSLAT
5356
pip install "scSLAT[torch]"
5457
pip install "scSLAT[pyg]"
5558
```
5659

60+
> **Note**
61+
> Some dependencies such as `torch-scatter` need to compile from source, which may take a long time. Please refer our solution to accelerate the install [here](https://slat.readthedocs.io/en/latest/install.html)
62+
5763
### Development version
5864
For development purpose, clone this repo and install:
5965

@@ -70,14 +76,6 @@ We plan to provide a conda package of `scSLAT` in the near future.
7076

7177
## Reproduce manuscript results
7278
1. Please follow the [`env/README.md`](env/README.md) to install all dependencies. Please checkout the repository to v0.2.0 before install `scSLAT`:
73-
74-
```
75-
git clone git@github.com:gao-lab/SLAT.git
76-
git checkout tags/v0.2.0
77-
pip install -e ".[torch]"
78-
pip install -e ".[pyg,dev,doc]"
79-
```
80-
8179
2. Download and pre-process data follow the [`data/README.md`](data/README.md)
82-
3. Whole benchmark and evaluation procedure can be found in `/benchmark` and `/evaluation`, respectively.
83-
4. Every case study is recorded in the `/case` directory in the form of jupyter notebook.
80+
3. Whole benchmark and evaluation procedure can be found in [`/benchmark`](benchmark/README.md) and [`/evaluation`](evaluation/README.md), respectively.
81+
4. Every case study is recorded in the [`/case`](case/README.md) directory in the form of jupyter notebook.

‎benchmark/README.md

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,48 @@
11
# Methods
2-
We benchmark with following methods
3-
| Method | Graph based | For spatial | Cross platform |
4-
| ------- | ----------- | ----------- | -------------- |
5-
| SLAT | yes | yes | yes |
6-
| PASTE | no | yes | no |
7-
| STAGATE | yes | yes | no |
8-
| Seurat | no | no | yes |
9-
| Harmony | no | no | yes |
2+
We benchmark with following methods:
103

4+
| Method | Graph based | Spatial aware | Cross platform |
5+
| ------- | ----------- | ------------- | -------------- |
6+
| SLAT | yes | yes | yes |
7+
| PASTE | no | yes | no |
8+
| STAGATE | yes | yes | no |
9+
| Seurat | no | no | yes |
10+
| Harmony | no | no | yes |
1111

12+
# Metric
13+
Due to we can not know ground truth between real spatial datasets, we newly design CRI (Celltype and Region matching Index) metric to measure the performance of spatial alignment. CRI checks how much alignment method recover corresponding celltype and histology region simultaneously.
1214

13-
# Metric and datasets
15+
$$
16+
CRI= \frac{1}{M} \sum_{v_i,v_j \in M} I(i,j),\\
1417
18+
f(x)=\left\lbrace
19+
\begin{aligned}
20+
1 &,\ c_1^{i}=c_2^{j} \ \mathbf{and} \ r_1^{i}=r_2^{j} \\
21+
0 &,\ otherwise, \\
22+
\end{aligned}
23+
\right.
24+
$$
1525

16-
Due to we can not know ground truth between real spatial datasets, so we newly design CRI (Celltype and Region matching Index) score to measure the performance of spatial alignment. First, we annotate every dataset by its histology region and cell type, according to source literature, then check how do alignment method recover corresponding celltype and histology region simultaneously.
26+
We also use Euclidean distance to measure the performance of spatial alignment:
1727

18-
<img src = "../docs/_static/formula_benchmark1.png" width="400" height="150"/>
28+
$$
29+
Euclidean\ distance = \frac{1}{M} \sum_{v_i,v_j \in M} ||\mathbf{s_i} - \mathbf{s_j}||_F^2
30+
$$
1931

20-
We benchmark on following datasets:
21-
> NOTE: Dataset download links are available at [`../data/README.md`](../data/README.md)
32+
# Datasets
33+
> **Note**
34+
> Dataset download links are available at [`here`](../data/README.md)
2235
36+
We do benchmark on following datasets:
2337
| Index | Paper | Species | Tissue | Technology | Resolution | Cells/Spots | Genes | Download |
2438
| ----- | ------------------------------------------------------------ | ------- | -------------------------------------------- | ------------ | ---------- | ----------- | ----- | ------------------------------------------------------------ |
2539
| 1 | [Kristen et al.](https://www.nature.com/articles/s41593-020-00787-0) | Human | Brain(dorsolateral prefrontal cortex, DLPFC) | 10x Visium | 50μm | ~3500 | >20,000 | [website](https://github.com/LieberInstitute/spatialLIBD) |
2640
| 2 | [Jeffrey et al.](https://www.science.org/doi/10.1126/science.aau5324) | Mouse | Brain(hypothalamic preoptic) | MERFISH | subcellular | ~6,500 | 151 | [website](https://datadryad.org/stash/dataset/doi:10.5061/dryad.8t8s248) |
2741
| 3 | [Chen et al.](https://doi.org/10.1016/j.cell.2022.04.003) | Mouse | Whole embryo | Stereo-seq | 0.2μm | 5000-100,000 | >20,000 | [website](https://db.cngb.org/stomics/mosta/download.html) |
2842

29-
30-
31-
# Run
32-
> NOTE: you may need install `snakemake` and other dependencies following [`env/README.md`](../env/README.md)
43+
# Run benchmark pipeline
44+
> **Note**
45+
> You need install extra dependencies following [`env/README.md`](../env/README.md).
3346
3447
To repeat our benchmark, just run:
3548
```shell

‎case/README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Case studies
22
Here are notebooks of all case studies in our paper, if you need any intermediate files, please contact us.
33

4-
- spatial_cross_platform: Spatial alignment of Stereo-seq and MERFISH in mouse embryo
5-
- spatial_multi-omics: Spatial alignment of Stereo-seq and spatial-ATAC-seq in mouse embryo
4+
- spatial_cross_platform: Spatial alignment of Stereo-seq and MERFISH datasets
5+
- visium_xenium: Spatial alignment of Visium and Xenium datasets
6+
- spatial_multi-omics: Spatial alignment of Stereo-seq and spatial-ATAC-seq datasets
67
- mouse_development: Mouse E11.5 and E12.5 embryo spatial-temporal analysis
7-
- multiple_datasets: 3D structure re-build via multi-dataset alignment
8+
- multiple_datasets: 3D structure re-build via multi-datasets alignment

‎docs/_static/formula_benchmark1.png

-15 KB
Binary file not shown.

‎docs/api.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
This section provides detailed API documentation for all public functions
44
and classes in ``scSLAT``.
55

6+
```{warning}
7+
If this page cannot show properly, please view codes on [github](https://github.com/gao-lab/SLAT/tree/main/scSLAT)
8+
```
9+
10+
611
```{eval-rst}
712
.. autosummary::
813
:toctree: api

‎docs/index.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,15 @@
2525

2626
## Key applications of scSLAT
2727

28-
1. **Heterogeneous alignment**: as the first algorithm designed for heterogeneous spatial alignment, scSLAT enable
28+
1. **Heterogeneous alignment**: as the first method designed for heterogeneous spatial alignment, scSLAT enables
2929

30-
* **Cross technologies alignment**: such as Stereo-seq and MERFISH, Visium and Xenium.
31-
* **Multi modalities alignment**: such as spatial-ATAC-seq and Stereo-seq (cooperate with our previous work [scglue](https://scglue.readthedocs.io/en/latest/)).
32-
* **Define spatial dynamics**: such as revealing spatial-temporal changes in time-series developmental datasets.
30+
* **Cross technologies alignment**: Stereo-seq and MERFISH, Visium and Xenium, ...
31+
* **Multi modalities alignment**: spatial-ATAC-seq and Stereo-seq (with our previous work [scglue](https://scglue.readthedocs.io/en/latest/)).
32+
* **Defining development changes**: revealing spatial-temporal changes in time-series developmental datasets.
3333

34-
2. **Atlas alignment**: precisely align large single cell spatial atlas containing 200,000+ cells less than 3 minutes.
34+
2. **Atlas alignment**: precisely align large single cell spatial atlas (200,000+ cells) in 3 minutes.
3535

36-
3. **3D reconstruction**: align multiple continuous spatial slices in parallel to rebuild 3D.
36+
3. **3D reconstruction**: align multiple continuous spatial slices in parallel to rebuild 3D structure.
3737

3838
```{eval-rst}
3939
.. image:: _static/imgalignment.gif

‎docs/install.md

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Installing `scSLAT` within a new [conda environment](https://conda.io/projects/c
77
First, create a clean environment and activate it. Then we install `scSLAT`. We recommend you install on a machine equipped CUDA-enabled GPU, `scSLAT` will be 10x faster than running on CPU.
88

99
```{warning}
10-
Install in machine with old NVIDIA driver may raise error, please update NVIDIA driver to the latest version or use Docker.
10+
Install in machine with old NVIDIA driver may raise error, please update NVIDIA driver to the latest version.
1111
```
1212

1313
```bash
@@ -17,6 +17,36 @@ pip install "scSLAT[torch]"
1717
pip install "scSLAT[pyg]"
1818
```
1919

20+
## Accelerate the install
21+
Some dependencies such as `torch-scatter` need to compile from source, which may take a long time. We provide solutions to accelerate the install on different platforms:
22+
23+
### CPU-only
24+
We install cpu version of dependencies from pre-built wheel, which is faster than compiling from source. Then install `scSLAT` from PyPI:
25+
26+
```bash
27+
pip install torch==1.11.0+cpu --extra-index-url https://download.pytorch.org/whl/cpu
28+
pip install https://data.pyg.org/whl/torch-1.11.0%2Bcpu/torch_cluster-1.6.0-cp38-cp38-linux_x86_64.whl
29+
pip install https://data.pyg.org/whl/torch-1.11.0%2Bcpu/torch_scatter-2.0.9-cp38-cp38-linux_x86_64.whl
30+
pip install https://data.pyg.org/whl/torch-1.11.0%2Bcpu/torch_sparse-0.6.15-cp38-cp38-linux_x86_64.whl
31+
pip install torch-geometric
32+
pip install scSLAT
33+
```
34+
35+
### GPU-enabled
36+
```{warning}
37+
Install in machine with old NVIDIA driver may raise error, please update NVIDIA driver to the latest version.
38+
```
39+
40+
PyG Team provides pre-built wheels for specific CUDA version ([here](https://data.pyg.org/whl/)). If your cuda version is in the list, please install the corresponding version torch and pyg dependencies. At last install `scSLAT`. We provide an example for CUDA 10.2:
41+
42+
```bash
43+
pip install torch==1.11.0+cu102 --extra-index-url https://download.pytorch.org/whl/cu102
44+
pip install https://data.pyg.org/whl/torch-1.11.0%2Bcu102/torch_cluster-1.6.0-cp38-cp38-linux_x86_64.whl
45+
pip install https://data.pyg.org/whl/torch-1.11.0%2Bcu102/torch_sparse-0.6.13-cp38-cp38-linux_x86_64.whl
46+
pip install https://data.pyg.org/whl/torch-1.11.0%2Bcu102/torch_cluster-1.6.0-cp38-cp38-linux_x86_64.whl
47+
pip install torch-geometric
48+
pip install scSLAT
49+
```
2050

2151
## Install from Github
2252
You can also install `scSLAT` from Github for development purpose, clone this repo and install:

‎docs/release.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
## v0.2.0
77
Here are major changes in v0.2.0:
88

9-
* Speed up the graph building.
10-
* Set default embedding method to `DPCA`.
11-
* Fix bugs on plotting and 3D reconstruction.
12-
* Provide [docker image](https://hub.docker.com/repository/docker/huhansan666666/slat).
13-
* Add more benchmarks and case studies.
9+
1. Speed up the graph building.
10+
2. Set default embedding method to `DPCA`.
11+
3. Fix bugs on plotting and 3D reconstruction.
12+
4. Provide [docker image](https://hub.docker.com/repository/docker/huhansan666666/slat).
13+
5. Add more benchmarks and case studies.

‎docs/tutorials/basic_usage.ipynb

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -250,10 +250,11 @@
250250
]
251251
},
252252
{
253+
"attachments": {},
253254
"cell_type": "markdown",
254255
"metadata": {},
255256
"source": [
256-
"## Aligning nd visualization \n",
257+
"## Aligning and visualization \n",
257258
"Then we align the datasets base on SLAT embedding"
258259
]
259260
},
@@ -1551,9 +1552,9 @@
15511552
],
15521553
"metadata": {
15531554
"kernelspec": {
1554-
"display_name": "SLAT",
1555+
"display_name": "Python 3",
15551556
"language": "python",
1556-
"name": "slat"
1557+
"name": "python3"
15571558
},
15581559
"language_info": {
15591560
"codemirror_mode": {
@@ -1565,7 +1566,7 @@
15651566
"name": "python",
15661567
"nbconvert_exporter": "python",
15671568
"pygments_lexer": "ipython3",
1568-
"version": "3.8.13"
1569+
"version": "3.8.13 | packaged by conda-forge | (default, Mar 25 2022, 06:04:18) \n[GCC 10.3.0]"
15691570
},
15701571
"vscode": {
15711572
"interpreter": {

‎env/README.md

Lines changed: 30 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
# More complex env config
2-
## Benchmark env
3-
If you want repeat our whole benchmark and evaluation workflow, please configure environment as follow, you need to install extra packages such as:
1+
# Env for reproducing
2+
If you want repeat our whole benchmark and evaluation workflow, please configure environment as follow.
3+
4+
## Python env
5+
First, you need to install extra Python packages such as:
46
- snakemake
57
- papermill
68
- jupyter
7-
- dill
8-
- parse
99

10-
> NOTE: Do **NOT** change install order !
11-
```
10+
> **Warning**
11+
> Do **NOT** change install order !
12+
13+
```bash
1214
mamba create -p ./conda python==3.8 -y && conda activate ./conda
1315
mamba install pytorch=1.11.0 torchvision torchaudio cudatoolkit=11.3 -c pytorch -y
1416
mamba install pyg -c pyg -y
@@ -18,64 +20,40 @@ mamba install -c bioconda -c conda-forge snakemake==7.12.0 tabulate==0.8.10 -y
1820

1921
git clone git@github.com:gao-lab/SLAT.git
2022
cd SLAT
21-
pip install -e ".[torch]"
22-
pip install -e ".[pyg,dev,doc]"
23+
git checkout tags/v0.2.0
24+
pip install -e ".[dev,doc]"
2325
```
24-
And then you also should configure `R` environment as below.
2526

2627
## R env
27-
We strong recommend to compile a **new** R without rather than use environment manage tools (conda, pakrat, renv). We use `R-4.1.3`, but `R` version > 4 may be enough.
28+
### STEP 1: Install R
29+
You also should configure `R` environment. We strong recommend to compile a **new** `R-4.1.3` rather than install R in conda.
2830

29-
> NOTE: Please make sure you have **deactivated** any conda env before using `R`
31+
> **Warning**
32+
> Please make sure you have **deactivated** any conda env before using `R`
3033
31-
```
32-
cd resource
34+
```bash
35+
cd SLAT/resource
3336
wget https://cran.r-project.org/src/base/R-4/R-4.1.3.tar.gz
3437
tar -xzvf R-4.1.3.tar.gz && cd R-4.1.3 &&
35-
./configure --without-x --with-cairo --with-libpng --with-libtiff --with-jpeglib --enable-R-shlib --prefix={your path} &&
38+
./configure --without-x --with-cairo --with-libpng --with-libtiff --with-jpeglib --enable-R-shlib --prefix={YOUR_PATH} &&
3639
make && make install
3740
```
3841

39-
Please install R packages in specific version from `renv.lock` (nedd install `renv` first)
42+
### STEP 2: Register R kernel
43+
Then register the jupyter kernel for `R` so snakemake can call `R` in benchmark workflow.
4044
```R
41-
install.packages('renv')
42-
renv::restore()
43-
```
44-
You can manually install following packages:
45-
46-
- Seurat (4.1.1)
47-
- reticulate (any version)
48-
- IRkernel (any version)
49-
- tidyverse (any version)
50-
- data.table (any version)
51-
- yaml (any version)
52-
- ggpubr (any version)
53-
54-
55-
Then register the jupyter kernel for `R` so that we can call `R` in benchmark workflow.
56-
```
45+
install.packages('IRkernel')
5746
IRkernel::installspec(name = 'slat_r', displayname = 'slat_r')
5847
```
5948

60-
Before running snakemake, you should install `IRkernel` again outside of `renv` env, so that `papermill` can call `R` kernel before `renv` env initialization.
61-
62-
63-
## Slurm env
64-
We failed to install `torch_geometric` via conda in slurm cluster. If you meet similar problem please use `pip` instead.
49+
### STEP 3: Install R packages
50+
At last, please install all R packages we used from `renv.lock` (see [`renv`](https://rstudio.github.io/renv/articles/renv.html)).
51+
```R
52+
install.packages('renv')
53+
install.packages('IRkernel')
54+
renv::restore()
6555
```
66-
mamba create -p ./conda python==3.8 -y && conda activate ./conda
67-
pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cu113
68-
pip install pytorch-lightning
69-
pip install torch-scatter -f https://data.pyg.org/whl/torch-1.11.0+cu113.html
70-
pip install torch-sparse -f https://data.pyg.org/whl/torch-1.11.0+cu113.html
71-
pip install torch-cluster -f https://data.pyg.org/whl/torch-1.11.0+cu113.html
72-
pip install torch-geometric
73-
74-
mamba install -c conda-forge papermill parse jupyter dill -y
75-
mamba install -c bioconda -c conda-forge snakemake==7.12.0 tabulate==0.8.10 -y
7656

77-
git clone git@github.com:gao-lab/SLAT.git
78-
cd SLAT
79-
pip install -e ".[torch]"
80-
pip install -e ".[pyg,dev,doc]"
81-
```
57+
## System env
58+
### Singularity
59+
You also need install [`singularity`](https://docs.sylabs.io/guides/3.0/user-guide/index.html), because we use container to ensure the repeatability.

‎evaluation/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Evaluation of SLAT
2-
We evaluate the robustness of `SLAT` to hyperparameters, you can test on different hyperparameters values by modifying `config/config.yaml`
2+
We evaluate the robustness of `SLAT` to hyperparameters, you can test with different hyperparameters values by modifying `config/config.yaml`. To repeat our evaluation, just run:
33

44
```
55
snakemake --profile profiles/local -p

0 commit comments

Comments
 (0)