Bioconductor objects are useful for their shared structure within the project, and that they enable rich metadata.
How then should one save a Bioconductor object so that a collaborator can load and use it? Or so that it persists reliably across time?
The answer depends on several factors:
Longevity: will the file need to be easily readable in 1 year, or 5-10 years from now?
Language interoperability: does the recipient use R, Python, or both?
Object size: is the object small enough to serialize entirely, or does it contain large on-disk arrays?
Is it easy enough to write out in common formats (BED) or plaintext?
Reproducibility: should the saved form capture provenance and metadata alongside data?
This vignette walks through the main options, their trade-offs, and some recommendations for common scenarios.
Acknowledgments
The content of this vignette has been informed by discussions on the Bioconductor community Zulip, including contributions from Kevin Rue-Albrecht, Johannes Rainer, Lori Shepherd, Jayaram Kancherla, Aaron Lun, Hervé Pagès, Laurent Gatto, Vince Carey, Sean Davis, Robert Castelo, Hugo Gruson, and Luke Zappia.
Version Info
R version: R version 4.6.1 (2026-06-24) Bioconductor version: 3.24 Package version: 0.99.1
R serialization
saveRDS and readRDS
The simplest approach is R’s built-in binary serialization. saveRDS() saves a single object to an RDS file (the acronym is not defined in the man pages but likely stands for “R Data Serialization”); save() bundles one or more named objects into an .RData (or .rda) file.
# Multiple objects in one filetmp_rda <-tempfile(fileext =".RData")save(se, file = tmp_rda)load(tmp_rda) # restores 'se' by name into the current environment
Prefer saveRDS() for most use cases. save() / load() silently overwrites any object in the calling environment that shares a name, which is a common source of confusion. The main remaining use case for save() is .rda data files shipped inside R packages (under data/).
Advantages:
Zero setup — works with any R object.
Compression applied automatically (gzip by default).
Round-trips perfectly: the loaded object is identical to the saved one.
Disadvantages:
R-only: Python or other languages cannot read these files without a bridge library.
Large objects are loaded entirely into RAM; there is no lazy / on-disk access.
When to use it: quick sharing between R users on the same project, saving intermediate objects in a pipeline, anything under ~1 GB.
If your workflow downloads RDS files from a remote URL, consider using BiocFileCache to cache them locally so they are only fetched once.
Python users can read RDS files with the rds2py package from the BiocPy ecosystem. Standard R types map to NumPy/SciPy equivalents (e.g. numeric vectors become numpy.ndarray), and Bioconductor classes such as SummarizedExperiment, SingleCellExperiment, GRanges, and MultiAssayExperiment are converted to their BiocPy counterparts. For unrecognised S4 classes the object falls back to a dictionary so no data is lost. Support for writing RDS files from Python is also in development.
Cross-release stability
There is no guarantee that an S4 object serialized today will work with older versions of Bioconductor. The most common reasons are that the S4 class is not defined at all in the earlier version, or that it exists but its definition has changed — new slots added, slots renamed or removed, or infrastructure moved between packages.
A concrete example: in Bioconductor 3.22, Seqinfo was moved out of GenomicRanges into its own package. A GRanges serialized under BioC ≥ 3.22 can still be loaded on a machine running BioC < 3.22, and many basic operations work — show(), seqnames(), ranges(), mcols(), and [ among them. But operations that require the Seqinfo package (such as shift() or reduce()) will fail with a confusing “package not available” error. The practical advice is to upgrade to BioC ≥ 3.22. The reverse was also true: older GRanges objects loaded into a newer session sometimes required updateObject() to migrate the internal representation:
# not evaluated — requires an object saved under an older Bioconductor releasegr <-readRDS("old_granges.rds")gr <-updateObject(gr, verbose =TRUE)
The general lesson is: if you can save your data in a format that is not tied to a particular version of Bioconductor — or better, not tied to R at all — you should. For a GRanges, for instance, a simple TSV is often enough:
This round-trip survives any Bioconductor version and is readable from Python or the command line. The alabaster ecosystem (described below) applies the same principle more systematically and with better support for complex objects, using HDF5 and JSON as the underlying storage formats.
HDF5-backed storage
Saving with HDF5Array
For large assay matrices (e.g., single-cell count matrices with millions of cells), it is impractical to hold the entire object in RAM. The HDF5Array package provides array classes backed by HDF5 files, enabling lazy loading and out-of-memory computation.
library(HDF5Array)tmp_hdf5 <-tempfile()saveHDF5SummarizedExperiment(se, dir = tmp_hdf5, replace =TRUE)# Assay data remains on disk until accessedse_from_hdf5 <-loadHDF5SummarizedExperiment(tmp_hdf5)se_from_hdf5
The saved directory contains an HDF5 file with the assay data and an RDS file for the non-assay metadata.
Advantages:
Assay data is stored on disk; only the chunks you access are read into RAM.
HDF5 is a widely used binary format with readers in Python (h5py, anndata), Julia, C/C++, and more.
Good for objects with tens of gigabytes of assay data.
Disadvantages:
The output is a directory, not a single file, which complicates transfer (use tar or zip before sharing).
The RDS envelope for metadata is still R-specific.
Write performance can be slower than saveRDS() for small objects.
When to use it: large single-cell or spatial datasets where you want on-disk access; workflows shared between R users who need memory efficiency.
SummarizedExperiment and AnnData
For single-cell workflows that move between R and Python, the .h5ad format used by scanpy and related tools is often the most convenient path when collaborators are working in Python. Like HDF5Array, .h5ad is an HDF5-based format. The trade-off relative to alabaster is that .h5ad is AnnData-specific rather than a general Bioconductor serialization format.
The recommended starting point is the anndataR package, a more recent and complete implementation that is actively maintained as part of the scverse ecosystem:
The zellkonverter package is an alternative that also converts directly between SingleCellExperiment and .h5ad. It remains actively maintained and has advantages in some cases, though at the cost of managing a Python environment via basilisk.
# not evaluated — zellkonverter installs a full Python environment via basilisk# on first use, which takes too long in CIlibrary(zellkonverter)writeH5AD(sce, file ="sce.h5ad")sce_from_h5ad <-readH5AD("sce.h5ad")sce_from_h5ad
The alabaster ecosystem
saveObject and readObject
The alabaster family of packages is part of the broader ArtifactDB project, which provides a multi-language system for storing and retrieving analysis-ready Bioconductor objects. The core idea is to save objects as directories of standard files (HDF5, JSON, CSV) whose format is defined by explicit, versioned specifications — meaning the saved form is readable without R, and can evolve over time without breaking previously saved objects.
The alabaster umbrella package pulls in support for the most common Bioconductor classes. Individual sub-packages cover specific classes: alabaster.se for SummarizedExperiment, alabaster.sce for SingleCellExperiment, and so on.
Validation with takane
A key part of the ArtifactDB design is that saved directories can be independently validated against the format specification. This is handled by takane, a C++ library that maintains separate, versioned specifications for 30+ Bioconductor object types. Calling takane::validate() on a saved directory checks that all files conform to the expected layout and types, which means a collaborator or downstream tool can verify the integrity of a saved object without needing to load it into R. This makes alabaster directories suitable for deposition in data repositories where format conformance needs to be auditable.
The Python counterpart to alabaster is the dolomite family of packages, which reads and writes the same on-disk format. An object saved with alabaster in R can be read with dolomite in Python, and vice versa, with no conversion step.
Advantages:
Truly language-agnostic: Python readers exist via the dolomite family of packages, enabling seamless R ↔︎ Python interoperability.
Built on open standards (HDF5, JSON); inspectable without R.
Versioned format specifications with independent validation via takane.
A good choice for archives or data portals.
Disadvantages:
Newer ecosystem; not all Bioconductor classes have alabaster support yet.
Requires installing the relevant alabaster.* sub-package for each class.
Like HDF5Array, the output is a directory.
When to use it: archival storage, data portal submissions, cross-language workflows, or any situation where you want the saved format to be readable without R.
BED format for ranges
Writing BED files
When the object is a GRanges or similar ranges object and the goal is interoperability with other tools (genome browsers, Python, command-line utilities), exporting to BED format is often more useful than R-specific serialization. Our gr has range names, a standard BED score column, and an extra metadata column log2fc:
When reading back, the standard score column is preserved, but log2fc is silently dropped — BED has no mechanism to carry arbitrary metadata columns. Range names are stored in the BED name field but come back as a $name metadata column rather than as R names on the object; restore them manually:
GRanges object with 3 ranges and 1 metadata column:
seqnames ranges strand | score
<Rle> <IRanges> <Rle> | <numeric>
peak1 chr1 100-149 * | 500
peak2 chr1 200-249 * | 800
peak3 chr1 300-349 * | 300
-------
seqinfo: 1 sequence from an unspecified genome; no seqlengths
Saving metadata columns
If preserving all metadata columns is the priority and BED compatibility is not required, the simplest approach is the TSV round-trip shown earlier: write.table(as.data.frame(gr), ...) followed by makeGRangesFromDataFrame(..., keep.extra.columns = TRUE) restores all mcols in one step without a sidecar.
When you do need a BED file (e.g. for a genome browser or a tool that expects BED input), extra mcols can be preserved by writing them to a sidecar file. Here using plyranges to read the BED back, then reattaching from the sidecar:
GRanges object with 3 ranges and 3 metadata columns:
seqnames ranges strand | name score log2fc
<Rle> <IRanges> <Rle> | <character> <numeric> <numeric>
[1] chr1 100-149 * | peak1 500 1.2
[2] chr1 200-249 * | peak2 800 -0.5
[3] chr1 300-349 * | peak3 300 2.1
-------
seqinfo: 1 sequence from an unspecified genome; no seqlengths
Saving Seqinfo separately
BED files do not store chromosome lengths or genome build information, so Seqinfo is silently dropped on export. To preserve it, write it out alongside the BED file and restore it on load:
Seqinfo object with 1 sequence from hg38 genome:
seqnames seqnames seqlengths isCircular genome
1 1 248956422 FALSE hg38
Propagating object metadata
Object-level metadata stored in metadata(object) — things like processing parameters, provenance notes, or experiment descriptors — is lost in any format that only encodes the ranges or assay data. This applies whether you are writing a BED file, an HDF5 matrix, or any other non-R format. Write it to a JSON sidecar file so it travels with the data:
toJSON handles simple R types (lists, vectors, data frames) well, but complex objects (S4 instances, environments) need to be simplified or omitted before serializing.
Summary and recommendations
Scenario
Recommended approach
Quick sharing between R users, same Bioc release
saveRDS()
Loading an object from an older Bioc release
updateObject() after readRDS()
Large assay matrices, R-only
saveHDF5SummarizedExperiment()
SingleCellExperiment ↔︎ Python AnnData
anndataR::write_h5ad() / read_h5ad() (or zellkonverter for Python-env integration)
Cross-language (R + Python), general
alabaster::saveObject()
Long-term archive / data portal
alabaster::saveObject()
In most new projects we recommend defaulting to saveRDS() for convenience and upgrading to alabaster when cross-language access or archival stability becomes a priority. Be aware that any R-serialized Bioconductor object may require updateObject() when loaded under a different Bioconductor release.