AnnData-Conversion {zellkonverter} | R Documentation

## Convert AnnData between and SingleCellExperiment

### Description

Conversion between Python AnnData objects and SingleCellExperiment objects.

### Usage

    AnnData2SCE(
      adata,
      X_name = NULL,
      layers = TRUE,
      uns = TRUE,
      var = TRUE,
      obs = TRUE,
      varm = TRUE,
      obsm = TRUE,
      varp = TRUE,
      obsp = TRUE,
      raw = FALSE,
      skip_assays = FALSE,
      hdf5_backed = TRUE,
      verbose = NULL
    )

    SCE2AnnData(
      sce,
      X_name = NULL,
      assays = TRUE,
      colData = TRUE,
      rowData = TRUE,
      varm = TRUE,
      reducedDims = TRUE,
      metadata = TRUE,
      colPairs = TRUE,
      rowPairs = TRUE,
      skip_assays = FALSE,
      verbose = NULL
    )

### Arguments

`adata` | A reticulate reference to a Python AnnData object.
`X_name` | For `SCE2AnnData()` name of the assay to use as the primary matrix (`X`) of the AnnData object. If `NULL`, the first assay of `sce` will be used by default. For `AnnData2SCE()` name used when saving `X` as an assay. If `NULL` looks for an `X_name` value in `uns`, otherwise uses `"X"`.
`layers, uns, var, obs, varm, obsm, varp, obsp, raw` | Arguments specifying how these slots are converted. If `TRUE` everything in that slot is converted, if `FALSE` nothing is converted and if a character vector only those items or columns are converted.
`skip_assays` | Logical scalar indicating whether to skip conversion of any assays in `sce` or `adata`, replacing them with empty sparse matrices instead.
`hdf5_backed` | Logical scalar indicating whether HDF5-backed matrices in `adata` should be represented as HDF5Array objects. This assumes that `adata` is created with `backed="r"`.
`verbose` | Logical scalar indicating whether to print progress messages. If `NULL` uses `getOption("zellkonverter.verbose")`.
`sce` | A SingleCellExperiment object.
`assays, colData, rowData, reducedDims, metadata, colPairs, rowPairs` | Arguments specifying how these slots are converted. If `TRUE` everything in that slot is converted, if `FALSE` nothing is converted and if a character vector only those items or columns are converted.

### Details

These functions assume that an appropriate Python environment has already been loaded. As such, they are largely intended for developer use, most typically inside a basilisk context.

The conversion is not entirely lossless. The current mapping is shown below (also at https://tinyurl.com/AnnData2SCE):

In `SCE2AnnData()`, matrices are converted to a numpy-friendly format. Sparse matrices are converted to dgCMatrix objects while all other matrices are converted into ordinary matrices. If `skip_assays = TRUE`, empty sparse matrices are created instead and the user is expected to fill in the assays on the Python side.

For `AnnData2SCE()`, a warning is raised if there is no corresponding R format for a matrix in the AnnData object, and an empty sparse matrix is created instead as a placeholder. If `skip_assays = NA`, no warning is emitted but variables are created in the `int_metadata()` of the output to specify which assays were skipped.

If `skip_assays = TRUE`, empty sparse matrices are created for all assays, regardless of whether they might be convertible to an R format or not. In both cases, the user is expected to fill in the assays on the R side, see `readH5AD()` for an example.

We attempt to convert between items in the SingleCellExperiment `metadata()` slot and the `AnnData` `uns` slot. If an item cannot be converted a warning will be raised.

Values stored in the `varm` slot of an `AnnData` object are stored in a column of `rowData()` in a SingleCellExperiment as a DataFrame of matrices. If this column is present an attempt is made to transfer this information when converting from SingleCellExperiment to `AnnData`.

### Value

`AnnData2SCE()` will return a SingleCellExperiment containing the equivalent data from `adata`.

`SCE2AnnData()` will return a reticulate reference to an AnnData object containing the content of `sce`.

### Author(s)

Luke Zappia

Aaron Lun

### See Also

`writeH5AD()` and `readH5AD()` for dealing directly with H5AD files.

### Examples

    if (requireNamespace("scRNAseq", quietly = TRUE)) {
        library(basilisk)
        library(scRNAseq)
        seger <- SegerstolpePancreasData()

        # These functions are designed to be run inside
        # a specified Python environment
        roundtrip <- basiliskRun(fun = function(sce) {
            # Convert SCE to AnnData:
            adata <- zellkonverter::SCE2AnnData(sce)

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

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

[Package zellkonverter version 1.4.0 Index]