Metadata-Version: 2.4
Name: randomized-spatial-pca
Version: 0.1.1
Summary: Randomized Spatial PCA (RASP): a computationally efficient method for dimensionality reduction of high-resolution spatial transcriptomics data
Author-email: Ian K Gingerich <gingerichik@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Goods Lab
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/gingerii/RASP
Project-URL: Repository, https://github.com/gingerii/RASP
Project-URL: Bug Tracker, https://github.com/gingerii/RASP/issues
Project-URL: Publication, https://doi.org/10.1371/journal.pcbi.1013759
Keywords: spatial transcriptomics,dimensionality reduction,PCA,single-cell,bioinformatics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scanpy
Requires-Dist: squidpy
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: python-igraph
Requires-Dist: leidenalg
Requires-Dist: glasbey
Requires-Dist: tqdm
Provides-Extra: mclust
Requires-Dist: rpy2==3.5.16; extra == "mclust"
Dynamic: license-file

# Randomized Spatial PCA (RASP)

![RASP overview](https://raw.githubusercontent.com/gingerii/RASP/main/figures/figure_1.png)


## Description

Here, we present Randomized Spatial PCA (RASP), a novel spatially aware dimensionality reduction method for spatial transcriptomics (ST) data. 
RASP is designed to be orders-of-magnitude faster than existing techniques, scale to ST data with hundreds of thousands of locations, support the 
flexible integration of non-transcriptomic covariates, and enable the reconstruction of de-noised and spatially smoothed expression values for individual genes. 
To achieve these goals, RASP uses a randomized two-stage principal component analysis (PCA) framework that leverages sparse matrix operations and configurable spatial smoothing.

## Features

- **High-Speed Performance**: RASP is optimized for fast processing of large spatial transcriptomics datasets.
- **Flexible Integration**: Seamlessly integrates non-transcriptomic covariates into the analysis.
- **Spatially Smoothed Values**: Produces reconstructed expression values that account for spatial context.
- **User-Friendly**: Designed to be accessible for researchers in spatial biology.

## Requirements

Dependencies are declared in `pyproject.toml` and installed automatically. The
manuscript results were produced with the following pinned versions (also in
`requirements.txt`):
```
- numpy==1.26.4
- pandas==2.2.2
- scanpy==1.10.1
- squidpy==1.2.2
- matplotlib==3.8.4
- scipy==1.13.1
- scikit-learn==1.5.0
- python-igraph==0.11.5
```
The `mclust` clustering option additionally requires `rpy2==3.5.16` and an R
installation with the `mclust` package; all other clustering methods
(`gmm`, `louvain`, `leiden`, `KMeans`, `walktrap`) are pure Python. `gmm` is an
R-free equivalent of `mclust` (a tied-covariance Gaussian mixture == mclust
`EEE`).

## Installation
Install from PyPI (the import name is `rasp`):
```bash
pip install randomized-spatial-pca
```
Or install the latest development version directly from GitHub:
```bash
pip install git+https://github.com/gingerii/RASP.git
```
To enable the optional R-backed `mclust` clustering:
```bash
pip install "randomized-spatial-pca[mclust]"   # then, in R: install.packages("mclust")
```
## Usage
See the tutorials folder for an end-to-end example. In brief:

```python
from rasp import RASP
import scanpy as sc

# adata: normalized expression in adata.X, coordinates in adata.obsm['spatial']
RASP.reduce(adata, n_pcs=20, n_neighbors=6, beta=2, platform='visium')
sc.pp.neighbors(adata, use_rep=adata.uns['RASP']['embedding_key'])
RASP.clustering(adata, n_clusters=7, method='leiden')
```

### Covariate integration (two-stage RASP)
RASP can integrate non-transcriptomic covariates (e.g. morphology or histology
features). When `covariates` are supplied, the smoothed stage-1 PC scores are
concatenated with the (optionally spatially smoothed) covariates and a second
randomized PCA produces the final embedding:

```python
# covariates: an (n_obs, d) array, adata.obs column name(s), or an adata.obsm key
RASP.reduce(adata, n_pcs=20, covariates=['morph_area', 'morph_ecc'])
# the integrated embedding is written to adata.obsm['X_pca_cov']; the key to use
# downstream is always adata.uns['RASP']['embedding_key']
sc.pp.neighbors(adata, use_rep=adata.uns['RASP']['embedding_key'])
```

Use `smooth_covariates` (bool or per-covariate list) and `scale_covariates` to
control covariate smoothing and z-scoring.

## Citation
If you use RASP in your research, please cite our publication in *PLOS Computational Biology*:

Gingerich et al. Randomized Spatial PCA (RASP): a computationally efficient method for dimensionality reduction of high-resolution spatial transcriptomics data. *PLOS Computational Biology* (2024). https://doi.org/10.1371/journal.pcbi.1013759

Article: https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1013759
