anndatar-seurat-scanpy-conversion
Convert between AnnData (.h5ad, Python/scverse) and Seurat (.rds, R/Seurat5) using the modern anndataR API. Use when bridging R and Python workflows, loading .h5ad in R, or exporting a Seurat object t
SKILL.mdskills/anndatar-seurat-scanpy-conversion/SKILL.md
GitHubanndataR: Seurat ↔ h5ad Conversion Skill
Purpose
Convert h5ad <-> Seurat using modern anndataR API
Quick Reference
Read h5ad → Seurat
library(anndataR)
library(Seurat)
# Direct read
seurat <- read_h5ad("file.h5ad", as = "Seurat")
# Two-step (for customization)
adata <- read_h5ad("file.h5ad")
seurat <- adata$as_Seurat()
Write Seurat → h5ad
# Direct write
write_h5ad(seurat, "output.h5ad")
# Two-step (for customization)
adata <- as_AnnData(seurat)
adata$write_h5ad("output.h5ad")
Custom Mapping
# Read with mapping
seurat <- adata$as_Seurat(
layers_mapping = c("counts", "dense_counts"), # which layers to include
object_metadata_mapping = c(new_name = "obs_column"),
reduction_mapping = list(
pca = c(key = "PC_", embeddings = "X_pca", loadings = "PCs")
),
graph_mapping = TRUE # or FALSE to skip
)
# NOTE — reduction key format: the key string (e.g. "PC_") must be purely alphanumeric
# with a trailing underscore (e.g. "umapunsup_"), NOT "umap_unsup_" or "umap.unsup_".
# Embedded underscores or dots in the key fragment corrupt the resulting dimension column
# names (e.g. "umap_unsup_1" splits incorrectly). The reduction SLOT NAME (e.g. "umap.unsup")
# may contain dots — only the key is restricted.
# Write with mapping
adata <- as_AnnData(seurat,
x_mapping = "counts", # main assay layer
layers_mapping = c("data"), # additional layers
obs_mapping = c(cell_type = "celltype"), # metadata
obsm_mapping = list(X_pca = "pca", X_umap = "umap") # reductions
)
Structure Mapping
Key difference: matrices are TRANSPOSED
- AnnData: cells × genes (obs × var)
- Seurat: genes × cells (features × samples)
AnnData → Seurat
X → Assay layer (data/counts)
obs → meta.data (columns)
var → feature metadata
obsm (X_pca) → reductions (pca@cell.embeddings)
varm (PCs) → reductions (pca@feature.loadings)
obsp → graphs
uns → misc
layers → assay layers
Common Issues & Solutions
1. Memory Issues (large files)
# Use HDF5-backed for reading
adata <- read_h5ad("big.h5ad", as = "HDF5AnnData")
# Process in chunks/subsets before converting
subset <- adata[1:1000, ]
seurat <- subset$as_Seurat()
2. Missing Metadata After Conversion
# Check what's available
names(adata$obs) # cell metadata
names(adata$var) # gene metadata
names(adata$uns) # unstructured data
# Explicitly map
seurat <- adata$as_Seurat(
object_metadata_mapping = c("leiden", "cell_type", "batch")
)
3. R Version Error
# Requires R >= 4.5.0
getRversion() # check version
# If < 4.5.0, install dependencies may fail
4. Layer/Assay Confusion
# List available layers
names(adata$layers)
# ["counts", "data", "scale.data"]
# Specify which to convert
seurat <- adata$as_Seurat(layers_mapping = c("counts", "data"))
5. Sparse Matrix Handling
# anndataR handles sparse automatically
# But check if preserved:
class(seurat[["RNA"]]$counts) # dgCMatrix for sparse
6. Ensembl IDs as rownames (var_names round-trip)
read_h5ad(as = "Seurat") preserves whatever var_names the upstream h5ad has — including Ensembl IDs when the producing scanpy pipeline used var_names_strategy = "ensembl". The symptom: FeaturePlot("Xbp1") returns "feature not found" because rownames are ENSMUSG…. The var/gene_name column is in the h5ad but NOT carried into the Seurat assay's @meta.data.
Quick detection:
head(rownames(obj)) # ENSMUSG... → quirk present
"Xbp1" %in% rownames(obj) # FALSE → biologist queries fail
colnames(obj[["RNA"]]@meta.data) # only var.features / var.features.rank → no gene_name
Fix: read the same h5ad as a SingleCellExperiment (which DOES carry var into rowData), pull gene_name, sum-collapse counts on duplicate symbols, re-derive data via NormalizeData() (do not collapse log-normalized values in place — log(a+b) ≠ log(a) + log(b)).
Full recipe — including HVG handling, scale.data + PCA-loading rename, and the reasons not to recompute PCA — at references/ensembl-vs-symbol-rownames.md.
When to skip as_Seurat(): if the h5ad was pre-finalized (symbols as var_names, Ensembl in var['gene_id'], lognorm X, raw counts layer), the two-source collapse is unnecessary — build manually:
adata <- read_h5ad("finalized.h5ad")
genes <- as.character(adata$var_names) # already symbols
cells <- as.character(adata$obs_names)
to_gc <- function(m) { m <- as(Matrix::t(m), "CsparseMatrix"); rownames(m) <- genes; colnames(m) <- cells; m }
counts <- to_gc(adata$layers[["counts"]])
data <- to_gc(adata$X)
rna <- CreateAssay5Object(counts = counts); LayerData(rna, "data") <- data
obj <- CreateSeuratObject(counts = rna, meta.data = `rownames<-`(as.data.frame(adata$obs), cells))
This guarantees h5ad/rds identity and sidesteps as_Seurat() version differences.
7. Seurat5 feature metadata requires a NAMED vector
Assigning a plain vector to an assay's feature metadata errors with "No feature overlap between new meta data and assay". The value must be a NAMED vector whose names equal rownames(assay):
# Fails: "No feature overlap between new meta data and assay"
assay[["gene_id"]] <- var_df$gene_id
# Works: names must equal rownames(assay)
feat <- rownames(assay)
assay[["gene_id"]] <- setNames(var_df[feat, "gene_id"], feat)
assay[["gene_name"]] <- setNames(var_df[feat, "gene_name"], feat)
obj[["RNA"]] <- assay # re-attach after modifying the assay
For the full production pattern — both ids in native slots, the HVG-subset trap, and raw-counts alignment — see §Producing a fully Seurat-native .rds below.
Producing a fully Seurat-native .rds carrying BOTH gene ids
The pattern above renames rows to symbols. But a deliverable .rds should carry both identifiers in Seurat-native, discoverable slots so no downstream consumer has to re-read the h5ad. This is a validated production pattern (PanSci 02_analysis/helpers/convert_ops.R). Target layout, Seurat v5 / Assay5:
- Active feature id = gene SYMBOL → the assay rownames (what
FeaturePlot/VlnPlotquery). Ensembl is the secondary id. - Both ids live in the RNA assay's feature-level metadata — the native, discoverable location — attached via the standard accessor
obj[["RNA"]][[]] <- fm. - The same table is also stashed in
obj@misc$gene_metadataas a convenience (survives operations that reset feature meta.data), but the assay feature metadata is the authoritative Seurat-native home.
Attaching feature metadata the right way (and the pitfall)
# fm: a data.frame, one row per feature, row.names == the ACTIVE feature names
# (the sanitized symbols that are the object's rownames), columns e.g.
# gene_name, gene_id (Ensembl), gene_type.
fm <- gene_meta_df
rownames(fm) <- rownames(obj) # MUST equal the active features
obj[["RNA"]][[]] <- fm # attaches all columns at once
head(obj[["RNA"]][[]]) # queryable the standard way
obj[["RNA"]][["gene_id"]] # single column, as a 1-col data.frame
Pitfall — "No feature overlap": assigning a bare, unnamed vector to a single feature-meta column fails, because Seurat aligns feature metadata by name:
obj[["RNA"]][["gene_id"]] <- ensembl_vector # ERROR: No feature overlap
Fix — pass a named vector (names == features) or a data.frame whose rownames match:
names(ensembl_vector) <- rownames(obj)
obj[["RNA"]][["gene_id"]] <- ensembl_vector # OK
# or, preferred for several columns at once:
obj[["RNA"]][[]] <- fm # fm rownames == features
Also stash the convenience copy:
obj@misc$gene_metadata <- fm
The HVG-subset trap (source gene metadata from raw/var, not main var)
A very common upstream shape: the h5ad's main var is an HVG subset (e.g.
3000–5000 genes) while the counts matrix + rownames span the full gene space
(~55k genes, held in raw/). If you source the gene annotation from the truncated
main var, ~50k features silently lose their Ensembl id (and everything else). The
gene metadata MUST come from the full raw/var group, aligned to
raw/var/_index, so every feature is annotated 1:1.
Read raw/var columns via hdf5r, decoding categorical columns
(categories + codes), aligned to the counts rownames:
library(hdf5r)
extract_gene_metadata <- function(h5path,
want = c("gene_name", "gene_id", "gene_type")) {
f <- H5File$new(h5path, "r"); on.exit(f$close_all(), add = TRUE)
vgrp <- "raw/var" # FULL gene space, not "var" (HVG subset)
syms <- as.character(f[["raw/var/_index"]]$read())
read_col <- function(col) {
p <- file.path(vgrp, col)
if (!f$exists(p)) return(NULL)
o <- f[[p]]
if (inherits(o, "H5Group")) { # categorical: categories + integer codes
cats <- as.character(o[["categories"]]$read())
codes <- as.integer(o[["codes"]]$read())
out <- cats[codes + 1L]; out[codes < 0L] <- NA # AnnData codes are 0-based; -1 = NA
out
} else o$read()
}
cols <- Filter(Negate(is.null), setNames(lapply(want, read_col), want))
if (!length(cols)) return(NULL)
gm <- as.data.frame(cols, stringsAsFactors = FALSE, check.names = FALSE)
rownames(gm) <- make.unique(syms) # same keys as the counts rownames
gm
}
make.unique(syms) matches the row keys read_raw_counts() assigns below, so the
table aligns 1:1 to the full feature set.
Raw counts, X, and the sanitized-name alignment
anndataR 1.0.2 ignores the nested .raw group, so read raw counts straight from
the h5ad's raw/X CSR group via hdf5r; the log-normalized adata.X (which
anndataR does read) becomes the data layer. CreateSeuratObject sanitizes
feature names (_ → -), so re-derive every layer's rownames from the object.
library(anndataR); library(Seurat); library(Matrix); library(hdf5r)
read_raw_counts <- function(h5path, cells) { # genes x cells (dgCMatrix)
f <- H5File$new(h5path, "r"); on.exit(f$close_all(), add = TRUE)
data <- f[["raw/X/data"]]$read()
indices <- f[["raw/X/indices"]]$read()
indptr <- f[["raw/X/indptr"]]$read()
genes <- as.character(f[["raw/var/_index"]]$read())
# raw/X is CSR over cells (rows); build cells x genes then transpose.
m_cg <- new("dgRMatrix", p = as.integer(indptr), j = as.integer(indices),
x = as.numeric(data), Dim = as.integer(c(length(cells), length(genes))))
counts <- as(Matrix::t(m_cg), "CsparseMatrix")
rownames(counts) <- make.unique(genes); colnames(counts) <- cells
counts
}
adata <- read_h5ad(h5path)
cells <- as.character(adata$obs_names)
counts <- read_raw_counts(h5path, cells)
obs <- as.data.frame(adata$obs); rownames(obs) <- cells
obj <- CreateSeuratObject(counts = counts, meta.data = obs)
feats <- rownames(obj) # SANITIZED names (_ -> -)
# gene metadata from the FULL gene space -> both native locations
gm <- extract_gene_metadata(h5path)
if (!is.null(gm) && nrow(gm) == length(feats)) {
fm <- gm; rownames(fm) <- feats
obj[["RNA"]][[]] <- fm # native, discoverable
obj@misc$gene_metadata <- fm # convenience copy
}
# log-norm X -> data layer, aligned to the SAME sanitized feature names
X <- adata$X
if (!is.null(X) && length(X@x) > 0 && max(X@x) > 0 && ncol(X) == length(feats)) {
data_mat <- as(Matrix::t(X), "CsparseMatrix") # genes x cells
rownames(data_mat) <- feats; colnames(data_mat) <- cells
obj[["RNA"]]$data <- data_mat
}
If the upstream var_names are Ensembl (not symbols) you must additionally rename
rows to symbols and sum-collapse duplicate symbols on counts first — see the two
conventions below and references/ensembl-vs-symbol-rownames.md.
Loupe caveat
If you also export a .cloupe from this object, loupeR caps a categorical grouping
at 32768 groups — never pass a per-cell factor (one level per cell) as a
"cluster"; it is rejected for any object larger than that and is useless for
browsing anyway. See louper-seurat-conversion.
Inspection
# AnnData structure
adata
dim(adata)
names(adata$obs) # cell metadata columns
names(adata$var) # gene metadata columns
names(adata$obsm) # embeddings (PCA, UMAP)
names(adata$layers) # data layers
# Seurat structure
seurat
dim(seurat)
colnames(seurat@meta.data) # cell metadata
Reductions(seurat) # PCA, UMAP
Layers(seurat) # data layers
Subsetting (creates views)
# Subset by condition (lazy evaluation)
subset <- adata[adata$obs$cell_type == "T cell", ]
# Convert view to concrete
concrete <- subset$as_InMemoryAnnData()
# Then convert to Seurat
seurat <- concrete$as_Seurat()
Installation
# Install anndataR
BiocManager::install("anndataR")
# With all dependencies
install.packages("pak")
pak::pak("scverse/anndataR", dependencies = TRUE)
Version note: this skill targets anndataR >= 1.1.0. On R 4.4.x, BiocManager::install('anndataR')
may resolve 1.0.2, which has different as_Seurat() parameter names. Check with
packageVersion('anndataR'); if locked to 1.0.2, use the manual build pattern described in Issue 6.
Multi-Assay / Multimodal Conversion
anndataR converts one assay at a time. For multi-assay Seurat objects (RNA + ATAC, CITE-seq), export each assay separately and assemble in Python.
Quick Path
# Export each assay
rna_adata <- as_AnnData(seurat_obj, assay_name = "RNA", x_mapping = "counts")
rna_adata$write_h5ad("rna.h5ad")
atac_adata <- as_AnnData(seurat_obj, assay_name = "ATAC")
atac_adata$write_h5ad("atac.h5ad")
# Assemble in Python
import mudata as md
rna = sc.read_h5ad("rna.h5ad")
atac = sc.read_h5ad("atac.h5ad")
mdata = md.MuData({"rna": rna, "atac": atac})
ChromatinAssay Warning
Signac's ChromatinAssay has extra slots (peak GRanges, fragment file paths) that are lost during anndataR conversion. Extract these manually before converting.
For full multi-assay conversion workflow, see multimodal-anndata-mudata.md.
Debug Checklist
- Check R version:
getRversion() >= "4.5.0" - Verify file exists:
file.exists("file.h5ad") - Check structure:
adata(print object) - List available slots:
names(adata$obs),names(adata$obsm) - Test small subset first:
adata[1:100, 1:500] - Check memory:
pryr::object_size(seurat) - Validate conversion: compare dimensions, metadata columns
When not to use
- Do not use for multi-assay Seurat objects (CITE-seq, multiome). Use multimodal-anndata-mudata.
- Do not use the older SeuratDisk API. This skill uses modern anndataR.
- Do not pass AnnData X layer name when calling as_Seurat — pass layer NAMES only (e.g., c('counts')).
See also
anndatamultimodal-anndata-mudatalouper-seurat-conversion
Upstream docs: https://scverse.org/anndataR/