anndataR.Rmd

---
title: "Using anndataR"
author:
  - name: Robrecht Cannoodt
  - name: Luke Zappia
  - name: Martin Morgan
  - name: Louise Deconinck
package: anndataR
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Using anndataR to read and convert}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

# already load SeuratObject and SingleCellExperiment
# so warnings generated by these packages are not shown
library(SeuratObject)
library(SingleCellExperiment)
```

## Introduction
**{anndataR}** allows users to work with `.h5ad` files, access various slots in the datasets and convert these files to `SingleCellExperiment` objects or `Seurat` objects, and vice versa.
This enables users to move data easily between the different programming languages and analysis ecosystems needed to perform single-cell data analysis.
This package differs from [**{zellkonverter}**](https://bioconductor.org/packages/release/bioc/html/zellkonverter.html) because it reads and writes these `.h5ad` files natively in R, and allows conversion to and from `Seurat` objects as well as `SingleCellExperiment`.

## Installation

Install using either **{BiocManager}** or from GitHub using **{pak}**:

```{r, eval = FALSE}
if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("anndataR")
```

```{r, eval = FALSE}
if (!require("pak", quietly = TRUE)) {
  install.packages("pak")
}
pak::pak("scverse/anndataR")
```

## Usage

Here's a quick example of how to use **{anndataR}**.

First, we fetch an example `.h5ad` file included in the package:

```{r}
library(anndataR)

h5ad_path <- system.file("extdata", "example.h5ad", package = "anndataR")
```

By default, a H5AD is read to an in-memory `AnnData` object:

```{r read-in-memory}
adata <- read_h5ad(h5ad_path)
```

It can also be read as a `SingleCellExperiment` object:

```{r read-as-SingleCellExperiment}
sce <- read_h5ad(h5ad_path, as = "SingleCellExperiment")
```

Or as a `Seurat` object:

```{r read-as-Seurat}
obj <- read_h5ad(h5ad_path, as = "Seurat")
```

There is also a HDF5-backed `AnnData` object:

```{r read-on-disk}
adata <- read_h5ad(h5ad_path, as = "HDF5AnnData")
```

View structure:

```{r show-structure}
adata
```

Access `AnnData` slots:

```{r access-slots}
dim(adata$X)
adata$obs[1:5, 1:6]
adata$var[1:5, 1:6]
```

## Interoperability

Convert the `AnnData` object to a `SingleCellExperiment` object:

```{r as-SingleCellExperiment}
sce <- adata$as_SingleCellExperiment()
sce
```

Convert the `AnnData` object to a `Seurat` object:

```{r as-Seurat}
obj <- adata$as_Seurat()
obj
```

Convert a `SingleCellExperiment` object to an `AnnData` object:

```{r as-AnnData-from-SingleCellExperiment}
adata <- as_AnnData(sce)
adata
```

Convert a `Seurat` object to an `AnnData` object:

```{r as-AnnData-from-Seurat}
adata <- as_AnnData(obj)
adata
```

## Manually create an `AnnData` object

```{r manually-create-object}
adata <- AnnData(
  X = matrix(rnorm(100), nrow = 10),
  obs = data.frame(
    cell_type = factor(rep(c("A", "B"), each = 5))
  ),
  var = data.frame(
    gene_name = paste0("gene_", 1:10)
  )
)

adata
```

## Write to disk:

Write an `AnnData` object to disk:

```{r write-to-disk}
tmpfile <- tempfile(fileext = ".h5ad")
write_h5ad(adata, tmpfile)
```

Write a `SingleCellExperiment` object to disk:

```{r write-SingleCellExperiment-to-disk}
tmpfile <- tempfile(fileext = ".h5ad")
write_h5ad(sce, tmpfile)
```

Write a `Seurat` object to disk:

```{r write-Seurat-to-disk}
tmpfile <- tempfile(fileext = ".h5ad")
write_h5ad(obj, tmpfile)
```

## Session info

```{r}
sessionInfo()
```