forked from yanfang-li/STADIA
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
170 lines (128 loc) · 6.74 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# STADIA <img src="man/figures/logo.png" align="right" width="160" />
<!--[](https://github.com/yanfang-li/stadia/actions/workflows/R-CMD-check.yaml)
<!-- [](https://app.codecov.io/gh/yanfang-li/stadia?branch=master) -->
[](https://cran.r-project.org/package=stadia)
## Overview
STADIA is designed to integrate multiple spatial transcriptomics slices, which simultaneously achieve
- dimension reduction
- batch effects correction
- spatial domains identification
Overall, STADIA is a Bayesian hierarchical hidden Markov random field model that first uses Bayesian factor regression and location-and-scale adjustment to learn a batch-corrected low-dimensional representation of the gene expression profiles, and then spatially clusters the embedding using a Gaussian mixture model with a Potts spatial prior to promote local consistency.
The homepage for the R package stadia can be accessed at: [https://yanfang-li.github.io/STADIA/index.html](https://yanfang-li.github.io/STADIA/index.html).
## Installation
<!-- Install the released version of stadia R package from CRAN:
```{r, eval=FALSE}
# Install released version from CRAN
install.packages("stadia")
```
or install the development version from GitHub with:-->
It's recommended to create a separate `conda` environment for running STADIA:
```{r, eval=FALSE}
conda create -n env_stadia -c conda-forge r-base r-essentials
conda activate env_stadia
```
<!-- First, make sure all dependencies are available: -->
<!-- ```{r, eval=FALSE} -->
<!-- dependencies <- c('Seurat','mclust','irlba','mombf','progress','Rcpp','BiocSingular','BiocParallel','BiocNeighbors','RcppArmadillo','RcppDist') -->
<!-- ap <- available.packages() -->
<!-- install.packages(dependencies[!(dependencies %in% row.names(installed.packages())) & (dependencies %in% row.names(ap))]) -->
<!-- if (!requireNamespace("BiocManager", quietly = TRUE)) -->
<!-- install.packages("BiocManager") -->
<!-- BiocManager::install(dependencies[!(dependencies %in% row.names(installed.packages())) & !(dependencies %in% row.names(ap))]) -->
<!-- ``` -->
<!-- The `stadia`'s dependency package `mombf` depends on `sparseMatrixStats`, which sometimes cannot be installed automatically, so we install `sparseMatrixStats` first to prevent errors later: -->
<!-- ```{r, eval=FALSE} -->
<!-- if (!require("BiocManager", quietly = TRUE)) -->
<!-- install.packages("BiocManager") -->
<!-- BiocManager::install("sparseMatrixStats") -->
<!-- ``` -->
Install the stadia package from GitHub (may take some time):
```{r, eval=FALSE}
# Install released version from github
if (!requireNamespace("remotes", quietly = TRUE))
install.packages("remotes")
remotes::install_bioc(c("BiocParallel", "sparseMatrixStats", "BiocNeighbors", "BiocSingular"))
remotes::install_github("yanfang-li/STADIA")
```
or from the source in the terminal ( [Package source](https://drive.google.com/file/d/1_ApLsFLm60Bpf7VQnOE6ZxFSsSil4zHN/view?usp=drive_link)):
```{r, eval=FALSE}
R CMD INSTALL stadia_1.0.0.tar.gz
```
or from precompiled binary package ([Windows binaries](https://drive.google.com/file/d/1tr6HkGJ_o2mdHGSHAO27qgaATJxCkTIk/view?usp=drive_link), [macOS binaries]()):
```{r, eval=FALSE}
install.packages("stadia")
```
The stadia package has been built and tested on the following operating system:
* Windows: 10, version 22H2 [Rtools required]
* Linux: Ubuntu 20.04.4 LTS
* MacOS: Monterey 12.7.1 (Apple M1), Monterey 12.0.1 (Intel Core i7)
## Setup to install source package stadia on MacOS.
Since the stadia package uses C++ and openmp, some additional configuration is required
to install it from source on MacOS. For details, please refer to
the following steps:
1. Install **Command Line Tools for Xcode** from [https://developer.apple.com/download/all](https://developer.apple.com/download/all).
2. Download **homebrew** from [https://github.com/Homebrew/brew/releases/tag/4.1.24](https://github.com/Homebrew/brew/releases/tag/4.1.24) and install it.
3. Install gcc using **brew install gcc**.
4. Install LLVM using **brew install llvm**.
5. Install libomp package using **brew install libomp**.
6. Make file **~/.R/Makevars**: (all paths must to be replaced with the paths
on your own computer)
```{bash, eval = FALSE}
# MacOS Xcode header location
# (do "xcrun -show-sdk-path" in terminal to get path)
XC_LOC = /Applications/Xcode.13.4.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk
# (do "echo $(brew --prefix **)" in terminal to get path)
LLVM_LOC = /opt/homebrew/opt/llvm
GCC_LOC = /opt/homebrew/Cellar/gcc/12.2.0
GETTEXT_LOC = /opt/homebrew/opt/gettext
OMP_LOC= /opt/homebrew/opt/libomp
OPENSSL_LOC=/opt/homebrew/opt/[email protected]
CC=$(LLVM_LOC)/bin/clang
CXX=$(LLVM_LOC)/bin/clang++
CXX11=$(LLVM_LOC)/bin/clang++
CXX14=$(LLVM_LOC)/bin/clang++
CXX17=$(LLVM_LOC)/bin/clang++
CXX1X=$(LLVM_LOC)/bin/clang++
CFLAGS=-g -O2 -Wall -pedantic -std=gnu99 -mtune=native -pipe
CXXFLAGS=-g -O2 -Wall -pedantic -std=c++11 -mtune=native -pipe
LDFLAGS=-L"$(LLVM_LOC)/lib" -L"$(GETTEXT_LOC)/lib" -Wl,-rpath,$(LLVM_LOC)/lib --sysroot="$(XC_LOC)" -lomp -L"$(OPENSSL_LOC)/lib"
CPPFLAGS=-I"$(GETTEXT_LOC)/include" -I"$(LLVM_LOC)/include" -I"$(OMP_LOC)/include" -isysroot "$(XC_LOC)" -Xclang -fopenmp -I"$(OPENSSL_LOC)/include"
FC=$(GCC_LOC)/bin/gfortran
F77=$(GCC_LOC)/bin/gfortran
FLIBS=-L$(GCC_LOC)/lib/gcc/11/ -lm
```
## Steps to use
The main steps to run the STADIA algorithm using the *stadia* package are (it is recommended
to run in the server background for large data sets)
```{r, eval=FALSE}
## load packages
library(stadia)
## set hyperparameters
hyper <- HyperParameters(obj, dim = d, eta = eta)
## run model
out <- stadia(obj, hyper, dim = d, n_cluster = K,
platform = "visium")
```
where
* obj: a list of Seurat objects containing information of ST slices
* dim: the dimension of latent factors
* eta: the spatial smoothness parameter used in Potts model
* n_cluster: the number of spatial domains
* platform: specifics the platform
## Demonstration
Files in the [Applications](https://yanfang-li.github.io/STADIA/articles/stadia.html) demonstrate
how to use the stadia package to run the STADIA algorithm in the `Run` section.
## Paper Citation
Yanfang Li and Shihua Zhang (2024+). "Statistical batch-aware embedded integration, dimension reduction and alignment for spatial transcriptomics".