---
title: Read/write SingleCellExperiment objects using anndataR
package: anndataR
output: BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Read/write SingleCellExperiment objects using anndataR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette demonstrates how to read and write `SingleCellExperiment` objects using the **{anndataR}** package, leveraging the interoperability between `SingleCellExperiment` and the `AnnData` format.

Check out `?anndataR` for a full list of the functions provided by this package.

## Introduction

SingleCellExperiment is a widely used class for storing single-cell data in R, especially within the Bioconductor ecosystem.
**{anndataR}** enables conversion between `SingleCellExperiment` objects and `AnnData` objects, allowing you to leverage the strengths of both the scverse and Bioconductor ecosystems.

## Prerequisites

Before you begin, make sure you have both SingleCellExperiment and **{anndataR}** installed. You can install them using the following code:

```r
if (!requireNamespace("pak", quietly = TRUE)) {
    install.packages("pak")
}
pak::pak(c("SingleCellExperiment", "SummarizedExperiment"))
pak::pak("scverse/anndataR")
```

## Converting an AnnData Object to a SingleCellExperiment Object

Using an example `.h5ad` file included in the package, we will demonstrate how to read an `.h5ad` file and convert it to a `SingleCellExperiment` object.

```{r prep_h5ad_file}
library(anndataR)
library(SingleCellExperiment)

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

Read the `.h5ad` file:

```{r read_h5ad}
adata <- read_h5ad(h5ad_file)
adata
```

Convert to a `SingleCellExperiment` object:

```{r convert_implicit}
sce_obj <- adata$to_SingleCellExperiment()
sce_obj
```

Note that there is no one-to-one mapping possible between the AnnData and SingleCellExperiment data structures, so some information might be lost during conversion. It is recommended to carefully inspect the converted object to ensure that all necessary information has been transferred.

See the [in-depth vignette on conversion to and from SingleCellExperiment objects](singlecellexperiment.html) for more details on how to customize the conversion process. For instance:

```{r ex_mapping, eval=FALSE}
adata$to_SingleCellExperiment(
  assays_mapping = list(),
  colData_mapping = list(coldata1 = "integer", coldata2 = "numeric"),
  rowData_mapping = list(rowdata1 = "character", rowdata2 = "logical")
)
```

## Convert a SingleCellExperiment Object to an AnnData Object

Here's an example demonstrating how to create a `SingleCellExperiment` object from scratch, then convert it to `AnnData` and save it as `.h5ad`

```{r construct_sce}
counts <- matrix(rbinom(20000, 1000, .001), nrow = 100)
sce_obj <- SingleCellExperiment(list(counts = counts))

sce_obj
```

You can convert the `SingleCellExperiment` object to an `AnnData` object using the `from_SingleCellExperiment` function:

```{r from_SCE}
adata <- from_SingleCellExperiment(sce_obj)
adata
```

Again note that there is no one-to-one mapping possible between the AnnData and SingleCellExperiment data structures, so some information might be lost during conversion. It is recommended to carefully inspect the converted object to ensure that all necessary information has been transferred.

See the [in-depth vignette on conversion to and from SingleCellExperiment objects](singlecellexperiment.html) for more details on how to customize the conversion process. Example:

```{r from_SCE_ex}
from_SingleCellExperiment(
  sce_obj,
  x_mapping = "counts",
  layers_mapping = list()
)
```

## Session info

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