WriteH5Group: Write data to an HDF5 group

In mojaveazure/seurat-disk: Interfaces for HDF5-Based Single Cell File Formats

Write data to an HDF5 group

Description

Writing data to HDF5 files can be done simply with usually sensible defaults. However, when wanting any semblance of control over how an R object is written out, the code constructs get complicated quickly. WriteH5Group provides a wrapper with sensible defaults over some of these complex code constructs to provide greater control over how data are written to disk. These defaults were chosen to fit best with h5Seurat files, see vignette("h5Seurat-spec") for more details

Usage

WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'ANY'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'array'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'Assay'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'data.frame'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'dgCMatrix'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'DimReduc'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'factor'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'Graph'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'list'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'logical'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'Neighbor'
WriteH5Group(x, name, hgroup, verbose = TRUE)

## S4 method for signature 'SeuratCommand'
WriteH5Group(x, name, hgroup, verbose = TRUE)

Arguments

x	An object
name	Name to save data as
hgroup	An HDF5 file or group (H5File or H5Group objects from hdf5r)
verbose	Show progress updates

Value

Invisibly returns NULL

Examples

# Setup an HDF5 file
hfile <- hdf5r::H5File$new(filename = tempfile(fileext = '.h5'), mode = 'a')



# Data frames are stored as either datasets or groups, depending on the
# presence of factor columns
df <- data.frame(
  x = c('g1', 'g1', 'g2', 'g1', 'g2'),
  y = 1:5,
  stringsAsFactors = FALSE
)

# When no factor columns are present, the data frame is written as a single
# HDF5 compound dataset
WriteH5Group(x = df, name = 'df', hgroup = hfile)
hfile[['df']]

# When factors are present, the data frame is written as a group
# This is because h5py does not implement HDF5 Enums, so factor level
# information would be lost
df$x <- factor(x = df$x)
WriteH5Group(x = df, name = 'df.factor', hgroup = hfile)
hfile[['df.factor']]



# Factors turn into a group with two components: values and levels
# This is to preserve level information for HDF5 APIs that don't implement
# the HDF5 Enum type (eg. h5py)
# values corresponds to the integer values of each member of a factor
# levels is a string dataset with one entry per level
fctr <- factor(x = c('g1', 'g1', 'g2', 'g1', 'g2'))
WriteH5Group(x = fctr, name = 'factor', hgroup = hfile)
hfile[['factor']]



# Logicals get encoded as integers with the following mapping
# FALSE becomes 0L
# TRUE becomes 1L
# NA becomes 2L
# These are stored as H5T_INTEGERS instead of H5T_LOGICALS
# Additionally, an attribute called "s3class" is written with the value of "logical"
WriteH5Group(c(TRUE, FALSE, NA), name = "logicals", hgroup = hfile)
hfile[["logicals"]]
hfile[["logicals"]]$attr_open("s3class")$read()



# Close and remove the HDF5 file
hfile$close_all()
file.remove(hfile$filename)

mojaveazure/seurat-disk documentation built on Nov. 5, 2023, 9:40 a.m.