---
title: Converting single-cell data structures between Bioconductor and Python
author: 
- name: Luke Zappia
  email: luke@lazappi.id.au
- name: Aaron Lun
  email: infinite.monkeys.with.keyboards@gmail.com
date: "Revised: 19 June 2020"
output:
  BiocStyle::html_document:
    toc_float: true
package: zellkonverter 
vignette: >
  %\VignetteIndexEntry{Converting to/from AnnData to SingleCellExperiments}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}    
---

```{r setup, echo = FALSE, results = "hide", message = FALSE}
require(knitr)
library(BiocStyle)
opts_chunk$set(error = FALSE, message = FALSE, warning = FALSE)
```

Overview
========

This package provides a lightweight interface between the Bioconductor
`SingleCellExperiment` data structure and the Python `AnnData`-based single-cell
analysis environment. The idea is to enable users and developers to easily move
data between these frameworks to construct a multi-language analysis pipeline
across R/Bioconductor and Python.

Reading and writing H5AD files
==============================

The `readH5AD()` function can be used to read a `SingleCellExperiment` from a
H5AD file. This can be manipulated in the usual way as described in the
`r Biocpkg("SingleCellExperiment")` documentation.

```{r read}
library(zellkonverter)

# Obtaining an example H5AD file.
example_h5ad <- system.file("extdata", "krumsiek11.h5ad",
                            package = "zellkonverter")
readH5AD(example_h5ad)
```

We can also write a `SingleCellExperiment` to a H5AD file with the
`writeH5AD()` function. This is demonstrated below on the classic Zeisel mouse
brain dataset from the `r Biocpkg("scRNAseq")` package. The resulting file can
then be directly used in compatible Python-based analysis frameworks.

```{r write}
library(scRNAseq)

sce_zeisel <- ZeiselBrainData()
out_path <- tempfile(pattern = ".h5ad")
writeH5AD(sce_zeisel, file = out_path)
```

Converting between `SingleCellExperiment` and `AnnData` objects
===============================================================

Developers and power users who control their Python environments can directly
convert between `SingleCellExperiment` and
[`AnnData` objects](https://anndata.readthedocs.io/en/stable/) using the
`SCE2AnnData()` and `AnnData2SCE()` utilities. These functions expect that
`r CRANpkg("reticulate")` has already been loaded along with an appropriate
version of the [_anndata_](https://pypi.org/project/anndata/) package. We
suggest using the `r Biocpkg("basilisk")` package to set up the Python
environment before using these functions.

```{r convert}
library(basilisk)
library(scRNAseq)

seger <- SegerstolpePancreasData()
roundtrip <- basiliskRun(fun = function(sce) {
     # Convert SCE to AnnData:
     adata <- SCE2AnnData(sce)

     # Maybe do some work in Python on 'adata':
     # BLAH BLAH BLAH

     # Convert back to an SCE:
     AnnData2SCE(adata)
}, env = zellkonverter:::anndata_env, sce = seger)
```

Package developers can guarantee that they are using the same versions of Python
packages as `r Biocpkg("zellkonverter")` by using the `.AnnDataDependencies`
variable to set up their Python environments.

```{r anndata-deps}
.AnnDataDependencies
```

Session information
===================

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