I Finally Couldn't Resist Fixing SeuratDisk

Although we discussed many methods for converting between Seurat objects and AnnData in Learning Single-Cell with Theis Lab: Format Conversion — Understanding the Underlying Logic (Part 2), several of the packages mentioned in that article are no longer actively maintained. This became especially problematic after Seurat updated to V5, which introduced a fundamentally different data structure from V3, rendering those older packages unreliable. While you can technically force-convert back to V3 format to accommodate legacy tools, this is clearly not a sustainable long-term strategy — future methods will inevitably be built around V5.

I've actually been itching to tackle SeuratDisk for a while now. It's an "official" package developed by the Seurat team that defines an HDF5-based Seurat format called h5Seurat, enabling Seurat objects to be stored and loaded using the HDF5 structure. The concept is excellent — HDF5 files offer many advantages, including hierarchical data organization, selective (lazy) loading, and optimized handling of sparse matrices, among others. Another key benefit is that HDF5 is well-supported in both Python and R, making it an ideal container for single-cell data. Unfortunately, the official GitHub repository hasn't been updated in two years, and attempting to install the package from the official source no longer works.

Some might think that requiring an intermediate h5Seurat file for format conversion sounds terribly inefficient. In reality, it's quite a clever design: it transforms what would be an in-memory conversion into an on-disk conversion, significantly reducing memory pressure. Furthermore, since both h5Seurat and h5ad are HDF5 formats under the hood, the conversion between them can leverage obj_copy_to() to copy data directly at the file-system level — which is very fast.

# What it looks like on the surface:
  Seurat object → h5Seurat file → h5ad file
# What actually happens:
  In-memory data → HDF5 format (h5Seurat) → HDF5 format (h5ad)
                 ↑                        ↑
          Requires serialization    Only needs structural reorganization

With the help of the mighty Claude, I implemented the following improvements:

1. Full support for V5's Assay5 objects, while maintaining backward compatibility with earlier versions
2. Fixed HDF5 method support for multi-dimensional arrays
3. Aligned with the latest AnnData API — primarily updating categories to categories/codes (i.e., adding integer encoding attributes for categorical data)
4. Added a LoadH5AD function that loads h5ad files directly into Seurat objects (still a bit rough around the edges)
5. Various fixes to the h5Seurat format: bidirectional h5ad ↔ h5Seurat conversion now works, and Seurat objects can be properly saved to and loaded from the h5Seurat format

Without further ado, install it with:

remotes::install_github("mianaz/seuratdisk-V5")

Basic usage:

library(SeuratDisk)

# Save a Seurat object to h5Seurat format
SaveH5Seurat(seurat_obj, filename = "data.h5Seurat")

# Load an h5Seurat file
seurat_obj <- LoadH5Seurat("data.h5Seurat")

# Convert to h5ad for use with Python/scanpy
Convert("data.h5Seurat", dest = "data.h5ad")

# Load an h5ad file directly into Seurat (recommended for V5)
seurat_obj <- LoadH5AD("scanpy_output.h5ad")

# Convert h5ad to h5Seurat
Convert("data.h5ad", dest = "data.h5Seurat")

Looking forward to your feedback — give it a try and let me know how it goes!

---

Originally posted on WeChat Official Account: bioinfo_studyroom