Update README

JiayuSuPKU · Nov 30, 2023 · 1f5667f · 1f5667f
1 parent 185f230
commit 1f5667f
Show file tree

Hide file tree

Showing 7 changed files with 234 additions and 141 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,37 @@
 # Smoother: A Unified and Modular Framework to Incorporate Structural Dependency in Spatial Omics Data
 ![Overview](/docs/img/Smoother_overview.png)
-Check [the notes](/docs/Smoother_sup_notes.pdf) and [documentations](/docs/smoother/index.md) for method details.
+
+## Description
+Smoother is a Python package that provides a unified framework to incorporate dependency in spatial omics data by formulating spatial priors from neighborhood graph. Implemented in `Pytorch`, Smoother is modular and ultra-efficient, often capable of analyzing samples tens of thousands of spots in seconds. The key innovation of Smoother is the decoupling of the prior belief on spatial structure (i.e., neighboring spots tend to be more similar) from the likelihood of a non-spatial data-generating model. This flexibility allows the same prior to be used in different models, and the same model to accommodate data with varying or even zero spatial structures. In other words, Smoother can be seamlessly integrated into existing non-spatial models and pipelines (e.g. single-cell analyses) and make them spatially aware. In particular, Smoother provides the following functionalities:
+
+1. **Spatial loss**: A quadratic loss equivalent to an MVN prior reflecting the spatial structure of the data. It can be used to regularize any spatial random variable of interest.
+2. **Data imputation**: Mitigates technical noise by borrowing information from the neighboring spots. It can also be applied to enhance the resolution of the data to an arbitrary level in seconds.
+3. **Cell-type deconvolution**: Infers the spatially coherent cell-type composition of each spot using reference cell-type expression profiles. Smoother is one of the few deconvolution methods that actually enforce spatial coherence by design.
+4. **Dimension reduction**: Find the spatially aware latent representations of spatial omics data in a model-agnostic manner, such that single-cell data without spatial structure can be jointly analyzed using the same pipeline.
+
+For method details, check [the Smoother paper (Su Jiayu, et al. 2022)](https://www.biorxiv.org/content/10.1101/2022.10.25.513785v2.full) and [the Supplementary Notes](/docs/Smoother_sup_notes.pdf).
 
 ## Installation
-Smoother can be directly installed using `pip`
+If you only want to use the core functionalities, namely `SpatialWeightMatrix` and `SpatialLoss`, Smoother can be directly installed using `pip` 
 ```zsh
 pip install git+https://github.com/JiayuSuPKU/Smoother.git#egg=smoother
 ```
 
-However, we recommend clone the repository and use `conda` to manage dependencies, especially if you want to use the [simulation scripts](/simulation/README.md).
+The dimensionality reduction module (`SpatialAE`, `SpatialVAE`) is built upon [scvi-tools](https://docs.scvi-tools.org/en/stable/index.html). Here we refer to the [original repository for installation instructions on different systems](https://docs.scvi-tools.org/en/stable/installation.html).
+```zsh
+pip install scvi-tools
+```
+
+
+- Note that `scvi-tools` doesn't officially support Apple's M chips yet. To run `SCVI` and the corresponding `SpatialVAE` on Macs with Apple silicon, a temporary solution is to [compile both Pytorch and PyG on M1 chips using compatible wheel files](https://github.com/rusty1s/pytorch_scatter/issues/241#issuecomment-1086887332). 
+
+To solve data imputation and deconvolution models using convex optimization, you need to also install the ['cvxpy' package](https://www.cvxpy.org/).
+
+```zsh
+conda install -c conda-forge cvxpy
+```
+
+To run other functions, e.g. the [simulation scripts](/simulation/README.md), we recommend using the conda environment provided in the repo. You can create a new conda environment called 'smoother' and install the package in it using the following commands:
 ```zsh
 # download the repo from github
 git clone git@github.com:JiayuSuPKU/Smoother.git
@@ -24,27 +47,15 @@ python -m ipykernel install --user --name=smoother
 pip install -e .
 ```
 
-(Optional) To solve the deconvolution problem via convex optimization, 
-you need to also install the ['cvxpy' package](https://www.cvxpy.org/).
-
-```zsh
-conda install -c conda-forge cvxpy
-```
-
-(Optional) To use the topological loss, you need to also install the 
-['TopologyLayer' package](https://github.com/bruel-gabrielsson/TopologyLayer).
-
-```zsh
-pip install git+https://github.com/bruel-gabrielsson/TopologyLayer.git
-```
-
 ## Smoother tutorials:
-1. [Smoother-guided data imputation in the DLPFC dataset](/tutorials/tutorial_impute.ipynb)
-2. [Smoother-guided cell-type deconvolution in the DLPFC dataset](/tutorials/tutorial_deconv.ipynb)
-3. [Smoother-guided dimension reduction in the DLPFC dataset](/tutorials/tutorial_dr.ipynb)
+Under construction. Check back soon!
+1. ~~[Smoother-guided data imputation in the DLPFC dataset](/tutorials/tutorial_impute.ipynb)~~
+2. ~~[Smoother-guided cell-type deconvolution in the DLPFC dataset](/tutorials/tutorial_deconv.ipynb)~~
+3. ~~[Smoother-guided dimension reduction in the DLPFC dataset](/tutorials/tutorial_dr.ipynb)~~
 4. [Spatial transcriptomics data simulation](/simulation/README.md)
 
-## Sample usage:
+## Basic usage:
+### Spatial loss construction:
 ```python
 # import spatial losses and models
 import torch
@@ -65,11 +76,19 @@ weights.calc_weights_knn(coords)
 weights.scale_by_expr(y)
 
 # transform it into spatial loss
-spatial_loss = SpatialLoss('icar', weights, scale_weights=0.99)
+spatial_loss = SpatialLoss('icar', weights, rho=0.99)
+
 # or contrastive loss
 spatial_loss = ContrastiveSpatialLoss(
     spatial_weights=weights, num_perm=20, neg2pos_ratio=0.1)
 
+# regularize any spatial random variable of interest
+variable_of_interest = torch.tensor(...) # n_vars x n_spot
+loss = spatial_loss(variable_of_interest)
+```
+
+### Downstream tasks:
+```python
 # choose model and solve the problem
 # deconvolution
 model = NNLS()
@@ -81,5 +100,5 @@ model.reduce(y, ...)
 ```
 
 ## References:
-Su, Jiayu, et al. "A Unified Modular Framework to Incorporate Structural Dependency in Spatial Omics Data." bioRxiv (2022): 2022-10.
-https://www.biorxiv.org/content/10.1101/2022.10.25.513785v1
+Su, Jiayu, et al. "Smoother: A Unified and Modular Framework for Incorporating Structural Dependency in Spatial Omics Data." bioRxiv (2022): 2022-10.
+https://www.biorxiv.org/content/10.1101/2022.10.25.513785v2.full
diff --git a/docs/Smoother_sup_notes.pdf b/docs/Smoother_sup_notes.pdf
diff --git a/docs/img/Smoother_overview.png b/docs/img/Smoother_overview.png
diff --git a/environment.yml b/environment.yml
@@ -5,16 +5,20 @@ dependencies:
   - python<4.0
   - pip
   - scipy
-  - scikit-learn
   - pytorch
   - pandas
+  - scanpy
+  - python-igraph 
+  - leidenalg
+  - scvi-tools
+  - scikit-learn
   - matplotlib==3.5.3
   - plotnine==0.8.0
   - jupyterlab
   - ipywidgets
-  - scanpy # for simulation
-  - python-igraph # for simulation
-  - leidenalg # for simulation
+  - pynndescent
+  - cvxpy
   - pip:
-    - squidpy # for simulation
-    - fuzzy-c-means # for simulation
+    - squidpy
+    - fuzzy-c-means
+    - scikit-bio==0.5.8
diff --git a/setup.cfg b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = Smoother
-version = 0.1.0
+version = 1.0.0
 description = A Unified and Modular Framework to Incorporate Structural Dependency in Spatial Omics Data
 author = Jiayu Su
 

diff --git a/tutorials/tutorial_deconv.ipynb b/tutorials/tutorial_deconv.ipynb
diff --git a/tutorials/tutorial_impute.ipynb b/tutorials/tutorial_impute.ipynb