/
README.Rmd
217 lines (162 loc) · 8.78 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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
---
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%"
)
```
```{r gh.url, echo=FALSE}
ghurl <- function(x) {
x <- unlist(x = strsplit(x = x, split = ','))
x <- trimws(x = x)
x <- grep(pattern = "https://github.com", x = x, value = TRUE)[1]
return(unname(obj = x))
}
```
```{r cran.cannoncial, echo=FALSE}
cran.cannoncial <- "https://cran.r-project.org/package="
```
```{r parse.description, echo=FALSE}
description <- read.dcf(file = "DESCRIPTION")
# Get package name
pkg <- as.vector(x = description[, "Package"])
# Get GitHub URL
github.url <- ghurl(x = description[, "URL"])
# Get depedencies
deps <- as.vector(x = description[, c("Depends", "Imports")])
deps <- unlist(x = strsplit(x = deps, split = "\n"))
deps <- vapply(
X = deps,
FUN = function(x) {
return(unlist(x = strsplit(x = x, split = "(", fixed = TRUE))[1])
},
FUN.VALUE = character(length = 1L),
USE.NAMES = FALSE
)
deps <- trimws(x = deps)
deps <- gsub(pattern = ",$", replacement = "", x = deps)
deps <- deps[deps != "R"]
```
```{r parse.version, echo=FALSE}
pkg.version <- package_version(x = description[1, 'Version'])
stage <- if (pkg.version >= package_version(x = "1.0.0")) {
"stable"
} else if (pkg.version >= package_version(x = "0.1.0")) {
"maturing"
} else {
"experimental"
}
color <- c("experimental" = "orange", "maturing" = "blue", "stable" = "brightgreen")[stage]
```
```{r launchcmd, echo=FALSE}
launchcmd <- function(...) {
args <- c(...)
return(paste0(
pkg,
"::AzimuthApp(",
paste(args, collapse = ","),
")"
))
}
```
```{r mdemit, echo=FALSE}
mdemit <- function(..., highlight = "r") {
ticks <- "```"
return(paste(
paste0(ticks, highlight),
...,
ticks,
sep = "\n"
))
}
```
# `r pkg` v`r pkg.version`
<!-- badges: start -->
[](`r github.url`)
<!-- badges: end -->
`r pkg` is a Shiny app demonstrating a query-reference mapping algorithm for single-cell data. The reference data accompanying the app and the algorithms used are described in the publication ["Integrated analysis of multimodal single-cell data" (Y. Hao, S. Hao, et al., Cell 2021)](https://doi.org/10.1016/j.cell.2021.04.048).
We have made instances of the app available for public use, [described here](https://azimuth.hubmapconsortium.org).
All the analysis and visualization functionality available in the app - and much more - is available in version 5 of the the [Seurat R package](https://satijalab.org/seurat).
## Installation
**Note**: you may need to update some packages prior to installing `r pkg`; from a fresh R session run:
```{r upgrade, eval=FALSE}
update.packages(oldPkgs = c("withr", "rlang"))
```
You can install `r pkg` from GitHub with:
```{r devel.install, echo=FALSE, results="asis"}
github.base <- unlist(x = strsplit(x = github.url, split = "/"))
github.base <- paste(rev(x = rev(x = github.base)[1:2]), collapse = "/")
cat(
"```r",
"if (!requireNamespace('remotes', quietly = TRUE) {",
" install.packages('remotes')",
"}",
paste0("remotes::install_github('satijalab/azimuth', ref = 'master')"),
"```",
sep = "\n"
)
```
## Running the app
The app is launched as:
```{r launch, echo=FALSE, results="asis"}
cat(mdemit(launchcmd()))
```
By default, the appropriate reference files are loaded into memory by accessing a web URL. If you instead have a directory containing reference files at `/path/to/reference` (directory must contain files named `ref.Rds` and `idx.annoy`), specify it as:
```{r launch.ref, echo=FALSE, results="asis"}
cat(mdemit(launchcmd("reference = '/path/to/reference'")))
```
### Downloading the app reference files
You can download the reference files that would be automatically loaded by default from Zenodo. Links are available on the Azimuth website [here](https://azimuth.hubmapconsortium.org/references/).
### Specifying options
You can set options by passing a parameter to the `AzimuthApp` function. If you would like to run the Azimuth ATAC workflow with a sc/snATAC-seq query, specify: `"Azimuth.app.do_bridge": "TRUE"`. Options in the `Azimuth.app` namespace (e.g. `max_cells` as shown in the example below) can omit the "Azimuth.app." prefix. Options in other namespaces (e.g. `Azimuth.de.digits` as shown in the example below) including non-Azimuth namespaces, must be specified using their full name.
```{r launch.param, echo=FALSE, results="asis"}
cat(mdemit(launchcmd("max_cells = 100000"), "\n", launchcmd("'Azimuth.de.digits' = 5")))
```
We also support reading options from a JSON-formatted config file. Provide the path to the config file as the parameter `config` to `AzimuthApp`. [Example config file](inst/resources/config.json). As described above regarding setting options through parameters, the "Azimuth.app." prefix may be omitted.
```{r launch.config, echo=FALSE, results="asis"}
cat(mdemit(launchcmd("config = 'config.json'")))
```
You can also set Azimuth or other options in R. (The full name must always be specified, even for options in the Azimuth.app namespace.)
```{r launch.opt, echo=FALSE, results="asis"}
cat(mdemit("options('Azimuth.de.digits' = 5)", launchcmd()))
```
Options can be set in any of these three ways simultaneously. Please note that options set in R will be overwritten by the same option specified in a config file, which are both overwritten by the same option provided as a parameter to the `AzimuthApp` function.
## Docker
First, build the Docker image. Clone the repository and run the following while in the root of the repository to build the image and tag it with the name "azimuth":
```
docker build -t azimuth .
```
Next, launch a container based on the image `azimuth` with a bind mount mounting the directory on the host containing the reference files (e.g. `/path/to/reference`) as `/reference-data` in the container.
```
docker run -it -p 3838:3838 -v /path/to/reference:/reference-data:ro azimuth
```
If port 3838 is already in use on the host or you wish to use a different port, use `-p NNNN:3838` in the run command instead, to bind port NNNN on the host to port 3838 on the container.
The container runs the command `R -e "Azimuth::AzimuthApp(reference = '/reference-data')"` by default.
### Rebuilding the Docker image more quickly in certain cases
The docker image takes about 20 minutes to build from scratch. To save time, adding the argument `--build-arg SEURAT_VER=$(date +%s)` to the `docker build` command will use cached layers of the image (if available) and only reinstall Seurat and Azimuth (and not any of the dependencies), which takes less than a minute. Alternatively, to only reinstall Azimuth (and not Seurat or other dependencies) use the argument `--build-arg AZIMUTH_VER=$(date +%s)`.
### Specifying options
You can set options by passing a parameter to the `AzimuthApp` function:
```
docker run -it -p 3838:3838 -v /path/to/reference:/reference-data:ro azimuth R -e "Azimuth::AzimuthApp(reference = '/reference-data', max_cells = 100000)"
```
or providing the path to a config file (in this example, for convenience, the config file is assumed to be in the reference directory that is bind mounted to the container):
```
docker run -it -p 3838:3838 -v /path/to/reference:/reference-data:ro azimuth R -e "Azimuth::AzimuthApp(config = '/reference-data/config.json', max_cells = 100000)"
```
or setting the option in R:
```
docker run -it -p 3838:3838 -v /path/to/reference:/reference-data:ro azimuth R -e "options('Azimuth.map.pbcorthresh' = 0.5)" -e "Azimuth::AzimuthApp(reference = '/reference-data')"
```
or just starting a shell in the container, from which you can launch an interactive R session and set options as desired:
```
docker run -it -p 3838:3838 -v /path/to/reference:/reference-data:ro azimuth /bin/bash
```
## Support
Azimuth annotation is currently supported in two ways; via the Azimuth app or via the `RunAzimuth()` function. Both methods accept the same kinds of files and run the same annotation workflow. To run the app please visit the website [here](https://azimuth.hubmapconsortium.org). To use `RunAzimuth()` please see [this tutorial](https://satijalab.github.io/azimuth/articles/run_azimuth_tutorial.html).
If you use the instance of the app we are hosting on the web, you can download a Seurat R script once your analysis is complete that will guide you in reproducing the analysis. You do not need Azimuth to reproduce the analysis.
If you would like to help us improve the app, and you believe a dataset meets the requirements and it is publicly available for us to use for debugging but the app doesn’t work, please file a Github issue linking to the dataset and describing the problem on [the issues page](https://github.com/satijalab/azimuth/issues).