% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/WriteH5Group.R
\name{WriteH5Group}
\alias{WriteH5Group}
\alias{WriteH5Group,ANY-method}
\alias{WriteH5Group,array-method}
\alias{WriteH5Group,Assay-method}
\alias{WriteH5Group,data.frame-method}
\alias{WriteH5Group,dgCMatrix-method}
\alias{WriteH5Group,DimReduc-method}
\alias{WriteH5Group,factor-method}
\alias{WriteH5Group,Graph-method}
\alias{WriteH5Group,list-method}
\alias{WriteH5Group,logical-method}
\alias{WriteH5Group,Neighbor-method}
\alias{WriteH5Group,SeuratCommand-method}
\title{Write data to an HDF5 group}
\usage{
WriteH5Group(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{ANY}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{array}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{Assay}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{data.frame}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{dgCMatrix}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{DimReduc}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{factor}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{Graph}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{list}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{logical}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{Neighbor}(x, name, hgroup, verbose = TRUE)

\S4method{WriteH5Group}{SeuratCommand}(x, name, hgroup, verbose = TRUE)
}
\arguments{
\item{x}{An object}

\item{name}{Name to save data as}

\item{hgroup}{An HDF5 file or group (\code{H5File} or \code{H5Group} objects
from hdf5r)}

\item{verbose}{Show progress updates}
}
\value{
Invisibly returns \code{NULL}
}
\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. \code{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 \link{h5Seurat} files, see
\code{\href{../doc/h5Seurat-spec.html}{vignette("h5Seurat-spec")}} for more
details
}
\examples{
\donttest{
# Setup an HDF5 file
hfile <- hdf5r::H5File$new(filename = tempfile(fileext = '.h5'), mode = 'a')
}

\donttest{
# 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']]
}

\donttest{
# 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']]
}

\donttest{
# 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()
}

\donttest{
# Close and remove the HDF5 file
hfile$close_all()
file.remove(hfile$filename)
}

}
