Skip to contents

Upgrade or downgrade a Seurat object between the v3/v4 and v5 generations

Source: R/SeuratVersionAPI.R
seuratVersion.Rd

Seurat v5 (SeuratObject >= 5.0) stores expression data in Assay5 objects (named layers, per-layer cell and feature sets, on-disk matrices) and, since Seurat 5.1, Visium images in the FOV-based VisiumV2 class. Objects built that way cannot be loaded by Seurat v3/v4, and the coercion SeuratObject ships (as(x, "Assay")) is lossy: split layers are joined, layers other than counts/data/ scale.data are dropped, the default layer is forgotten and on-disk matrices are pulled into memory.

Usage

upgradeSeurat(
  object,
  dest = NULL,
  to = "v5",
  overwrite = FALSE,
  verbose = TRUE
)

downgradeSeurat(
  object,
  dest = NULL,
  to = c("v4", "v3"),
  overwrite = FALSE,
  verbose = TRUE
)

seuratGeneration(object)

Arguments

object

A Seurat object, or the path to an .rds / .h5seurat file holding one

dest

When object is a path: where to write the converted object (.rds or .h5seurat)

to

Target generation: "v5" (Assay5), "v4" or "v3" (Assay; the two differ only in the version stamp)

overwrite

Overwrite dest if it exists

verbose

Print what was converted and what went into the sidecar

Value

The converted Seurat object, or dest (invisibly) when converting a file. seuratGeneration returns an object of class seurat_generation describing the assay and image classes in use.

Details

downgradeSeurat converts every Assay5 to a v3-style Assay and every VisiumV2 image to VisiumV1, and stores everything the older classes cannot hold in a sidecar list under misc$.seurat_version_sidecar (of the assay, or of the object for images): split-layer cell membership, extra layers, the default layer, the original version stamp, image boundaries. upgradeSeurat converts back and consumes the sidecar, so that upgradeSeurat(downgradeSeurat(x)) reproduces x. Assay subclasses (SCTAssay, ChromatinAssay) are upgraded to Assay5 with their extra slots kept in the sidecar and restored on downgrade.

Both functions also accept a file path (.rds or .h5seurat): the object is read, converted and written to dest.

What is lossless

Layers (including split layers such as counts.sample1 and non-standard names), the default layer, per-layer cell/feature sets, feature-level metadata, variable features, keys, misc, assay subclasses, Visium image boundaries and the version stamp all round-trip exactly. On-disk (BPCells) layers are loaded into memory on downgrade and stay in memory after the upgrade; the sidecar records which layers were on disk.

Examples

if (FALSE) { # \dontrun{
v4 <- downgradeSeurat(pbmc_v5)          # loadable by Seurat v4
saveRDS(v4, "pbmc_v4.rds")
v5 <- upgradeSeurat(v4)                 # identical layers to pbmc_v5
upgradeSeurat("old_v3.rds", dest = "new_v5.h5seurat")
seuratGeneration(v5)
} # }