Skip to contents

Inspect, upgrade or downgrade the on-disk layout of an h5ad file

Source: R/H5ADVersionAPI.R
h5adVersion.Rd

anndata changed its h5ad layout in 0.8.0 (every element became tagged with encoding-type/encoding-version, categoricals became groups, pandas nullable dtypes gained a values + mask layout), extended it in 0.11 (nullable-string-array) and made those extensions the default in 0.13 when used with pandas 3 (string columns and the obs/var index are written as nullable string arrays, None as null). Older anndata releases, scanpy pinned to them, and every converter derived from SeuratDisk cannot open files written in the newer layouts, while modern anndata still reads the legacy layout.

Usage

upgradeH5AD(
  source,
  dest,
  overwrite = FALSE,
  strings = c("keep", "categorical"),
  verbose = TRUE
)

downgradeH5AD(source, dest, overwrite = FALSE, verbose = TRUE)

h5adLayout(file)

Arguments

source

Path to the input h5ad file

dest

Path to the output h5ad file

overwrite

Overwrite dest if it exists

strings

How to write nullable string arrays when upgrading: "keep" preserves the nullable-string-array encoding (anndata >= 0.11); "categorical" rewrites them as categoricals (when they hold missing values) or plain string arrays, which every anndata >= 0.8 can read.

verbose

Print progress

file

Path to an h5ad file

Value

upgradeH5AD and downgradeH5AD return dest invisibly. h5adLayout returns an object of class h5ad_layout describing the layout ("encoded", "legacy" or "compound"), the oldest anndata release able to read the file, and which encodings it contains.

Details

These functions rewrite an h5ad file between layouts losslessly: matrices are copied at the HDF5 level, dataframes and uns are re-encoded, and anything the target layout cannot represent (a nullable integer with missing values, a null entry, a nullable string index) is written in the closest representable form and recorded in uns/__h5ad_compat_manifest__. Running the opposite conversion on the result restores the original encodings exactly.

Layouts

encoded

anndata >= 0.8. Written by upgradeH5AD.

legacy

anndata 0.7 (dataframe 0.1.0 with a __categories group referenced by HDF5 object references, no encoding attributes on arrays, dicts and scalars). Written by downgradeH5AD; readable by anndata 0.7 through 0.13 and by SeuratDisk.

compound

anndata < 0.7 (obs/var stored as compound datasets). Read-only; upgradeH5AD converts it.

Examples

if (FALSE) { # \dontrun{
h5adLayout("modern.h5ad")
downgradeH5AD("modern.h5ad", "legacy.h5ad")   # for anndata 0.7 / SeuratDisk
upgradeH5AD("legacy.h5ad", "restored.h5ad")   # exact original encodings back
} # }