README.Rmd

---
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 -->
[![Lifecycle](https://img.shields.io/badge/lifecycle-`r stage`-`r color`.svg)](`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 4 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. 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 v4 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).