# {anndataR}: An R package for working with AnnData objects <img src="man/figures/logo.png" align="right" alt="anndataR logo" width=120 />

<!-- badges: start -->
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![R-CMD-check-bioc](https://github.com/scverse/anndataR/actions/workflows/R-CMD-check-bioc.yaml/badge.svg)](https://github.com/scverse/anndataR/actions/workflows/R-CMD-check-bioc.yaml)
[![Codecov test coverage](https://codecov.io/gh/scverse/anndataR/graph/badge.svg)](https://app.codecov.io/gh/scverse/anndataR)
[![Bioc release status](http://www.bioconductor.org/shields/build/release/bioc/anndataR.svg)](https://bioconductor.org/checkResults/release/bioc-LATEST/anndataR)
[![Bioc devel status](http://www.bioconductor.org/shields/build/devel/bioc/anndataR.svg)](https://bioconductor.org/checkResults/devel/bioc-LATEST/anndataR)
[![Bioc downloads rank](https://bioconductor.org/shields/downloads/release/anndataR.svg)](http://bioconductor.org/packages/stats/bioc/anndataR/)
[![Bioc support](https://bioconductor.org/shields/posts/anndataR.svg)](https://support.bioconductor.org/tag/anndataR)
[![Bioc history](https://bioconductor.org/shields/years-in-bioc/anndataR.svg)](https://bioconductor.org/packages/release/bioc/html/anndataR.html#since)
[![Bioc last commit](https://bioconductor.org/shields/lastcommit/devel/bioc/anndataR.svg)](http://bioconductor.org/checkResults/devel/bioc-LATEST/anndataR/)
[![Bioc dependencies](https://bioconductor.org/shields/dependencies/release/anndataR.svg)](https://bioconductor.org/packages/release/bioc/html/anndataR.html#since)
<!-- badges: end -->

**{anndataR}** aims to make the `AnnData` format a first-class citizen in the R ecosystem, and to make it easy to work with AnnData files in R, either directly or by converting them to a `SingleCellExperiment` or `Seurat` object.

**{anndataR}** is a an scverse® community project fiscally sponsored by the [Chan Zuckerberg Initiative](https://chanzuckerberg.com/).

## Features of {anndataR}

- Provide an `R6` class to work with `AnnData` objects in R (either in-memory or on-disk)
- Read/write `*.h5ad` files and `*.zarr` stores natively
- Convert to/from `SingleCellExperiment` objects
- Convert to/from `Seurat` objects

Please [report](https://github.com/scverse/anndataR/issues) any issues you encounter.

## Installation

You can install **{anndataR}** from Bioconductor using **BiocManager**:

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

Or you can install the development version of **{anndataR}** from GitHub like so:

``` r
# install.packages("pak")
pak::pak("scverse/anndataR")
```

You will need to install additional dependencies, depending on
the task you want to perform.

- To read/write `*.h5ad` files, install [rhdf5](https://www.bioconductor.org/packages/rhdf5):  
  `BiocManager::install("rhdf5")`
- To read/write `*.zarr` stores, install [Rarr](https://www.bioconductor.org/packages/Rarr):  
  `BiocManager::install("Rarr")`
- To convert to/from `SingleCellExperiment` objects, install [SingleCellExperiment](https://bioconductor.org/packages/release/bioc/html/SingleCellExperiment.html):  
  `BiocManager::install("SingleCellExperiment")`
- To convert to/from `Seurat` objects, install [SeuratObject](https://cran.r-project.org/package=SeuratObject):  
  `install.packages("SeuratObject")`

Alternatively, you can install all suggested dependencies at once:

``` r
pak::pak("scverse/anndataR", dependencies = TRUE)
```

## Getting started

The best way to get started with **{anndataR}** is to explore the package vignettes (available at https://anndataR.scverse.org/articles/).

In order to browse these vignettes locally, you need to build them during installation:

``` r
options(pkg.build_vignettes = TRUE)
pak::pak("scverse/anndataR")
```

Take note that you need all suggested dependencies available, and that building them can take some time.

- [**Getting started**](https://anndataR.scverse.org/articles/anndataR.html): An introduction to the package and its features.  
  `vignette("anndataR", package = "anndataR")`
- [**Read/write `Seurat` objects**](https://anndataR.scverse.org/articles/usage_seurat.html): How to convert between `AnnData` and `Seurat` objects.  
  `vignette("usage_seurat", package = "anndataR")`
- [**Read/write `SingleCellExperiment` objects**](https://anndataR.scverse.org/articles/usage_singlecellexperiment.html): How to convert between `AnnData` and `SingleCellExperiment` objects  
  `vignette("usage_singlecellexperiment", package = "anndataR")`
- [**Software Design**](https://anndataR.scverse.org/articles/software_design.html): An overview of the design of the package
- [**Development Status**](https://anndataR.scverse.org/articles/development_status.html): An overview of the development status of the package

## Citing **{anndataR}**

If you use **{anndataR}** in your work, please cite [_"anndataR improves interoperability between R and Python in single-cell transcriptomics"_](https://doi.org/10.1101/2025.08.18.669052):

```r
citation("anndataR")
```

    Deconinck L, Zappia L, Cannoodt R, Morgan M, scverse core, Virshup I, Sang-aram C, Bredikhin D, Seurinck R, Saeys Y (2025).
    “anndataR improves interoperability between R and Python in single-cell transcriptomics.” _bioRxiv_, 2025.08.18.669052.
    doi:10.1101/2025.08.18.669052 <https://doi.org/10.1101/2025.08.18.669052>.

    A BibTeX entry for LaTeX users is

      @Article{,
        title = {{anndataR} improves interoperability between R and Python in single-cell transcriptomics},
        author = {Louise Deconinck and Luke Zappia and Robrecht Cannoodt and Martin Morgan and {scverse core} and Isaac Virshup and Chananchida Sang-aram and Danila Bredikhin and Ruth Seurinck and Yvan Saeys},
        journal = {bioRxiv},
        year = {2025},
        pages = {2025.08.18.669052},
        doi = {10.1101/2025.08.18.669052},
      }
