AnnData-Conversion: Convert between AnnData and SingleCellExperiment

In theislab/zellkonverter: Conversion Between scRNA-seq Objects

Convert between AnnData and SingleCellExperiment

Description

Conversion between Python AnnData objects and SingleCellExperiment::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::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

Python environment

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.

Conversion mapping

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

Matrix conversion

In SCE2AnnData(), matrices are converted to a numpy-friendly format. Sparse matrices are converted to Matrix::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.

metadata/uns conversion

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

uns conversion

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

SpatialExperiment conversion

In SCE2AnnData(), if sce is a SpatialExperiment::SpatialExperiment object, the spatial coordinates are added to the reducedDims slot before conversion to an AnnData object.

Value

AnnData2SCE() will return a SingleCellExperiment::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)
}

theislab/zellkonverter documentation built on April 11, 2025, 4:21 p.m.