Package 'SeuratDisk'

Description

The h5Seurat file format is specifically designed for the storage and analysis of multi-modal single-cell and spatially-resolved expression experiments, for example, from CITE-seq or 10X Visium technologies. It holds all molecular information and associated metadata, including (for example) nearest-neighbor graphs, dimensional reduction information, spatial coordinates and image data, and cluster labels. We also support rapid and on-disk conversion between h5Seurat and AnnData objects, with the goal of enhancing interoperability between Seurat and Scanpy.

Package options

SeuratDisk uses the following options to control behavior, users can configure these with options:

SeuratDisk.dtypes.logical_to_int

When writing logical vectors, coerce to integer types to ensure compatibility across languages (see BoolToInt for more details)

SeuratDisk.dtypes.dataframe_as_group

When writing data.frames, always write out as a group regardless of factor presence

SeuratDisk.chunking.MARGIN

Default direction for chunking datasets; choose from:

largest

Chunk along the largest dimension of a dataset

smallest

Chunk along the smallest dimension

first

Chunk along the first dimension

last

Chunk along the last dimension

SeuratDisk.dimreducs.allglobal

Treat all DimReducs as global, regardless of actual global status

Author(s)

Maintainer: Paul Hoffman [email protected] (ORCID)

Other contributors:

• Rahul Satija [email protected] (ORCID) [contributor]

See Also

Useful links:

• https://mojaveazure.github.io/seurat-disk/

• https://github.com/mojaveazure/seurat-disk

• Report bugs at https://github.com/mojaveazure/seurat-disk/issues

Append data from an h5Seurat file to a preexisting Seurat object

Description

Append data from an h5Seurat file to a preexisting Seurat object

Usage

AppendData(
  file,
  object,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  images = NULL,
  extras = "commands",
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## S3 method for class 'character'
AppendData(
  file,
  object,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  images = NULL,
  extras = "commands",
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## S3 method for class 'H5File'
AppendData(
  file,
  object,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  images = NULL,
  extras = "commands",
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## S3 method for class 'h5Seurat'
AppendData(
  file,
  object,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  images = NULL,
  extras = "commands",
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

object with the extra data requested

Description

Connect to a single-cell HDF5 dataset

Usage

Connect(filename, type = NULL, mode = c("r", "r+"), force = FALSE)

Arguments

Value

An object of class type, opened in mode mode

Description

HDF5-based single-cell datasets can be converted from one format to another using minimal memory. Details about conversion formats implemented are provided below

Usage

Convert(source, dest, assay, overwrite = FALSE, verbose = TRUE, ...)

## S3 method for class 'character'
Convert(source, dest, assay, overwrite = FALSE, verbose = TRUE, ...)

## S3 method for class 'H5File'
Convert(
  source,
  dest = "h5seurat",
  assay = "RNA",
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## S3 method for class 'h5Seurat'
Convert(
  source,
  dest = "h5ad",
  assay = DefaultAssay(object = source),
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

If source is a character, invisibly returns dest; otherwise, returns an H5File, or filetype-specific subclass of H5File (eg. h5Seurat), connection to dest

AnnData/H5AD to h5Seurat

The AnnData/H5AD to h5Seurat conversion will try to automatically fill in datasets based on data presence. It works in the following manner:

Expression data

The expression matrices counts, data, and scale.data are filled by /X and /raw/X in the following manner:

• counts will be filled with /raw/X if present; otherwise, it will be filled with /X

• data will be filled with /raw/X if /raw/X is present and /X is dense; otherwise, it will be filled with /X

• scale.data will be filled with /X if it dense; otherwise, it will be empty

Feature names are taken from the feature-level metadata

Feature-level metadata

Feature-level metadata is added to the meta.features datasets in each assay. Feature names are taken from the dataset specified by the “_index” attribute, the “_index” dataset, or the “index” dataset, in that order. Metadata is populated with /raw/var if present, otherwise with /var; if both /raw/var and /var are present, then meta.features will be populated with /raw/var first, then /var will be added to it. For columns present in both /raw/var and /var, the values in /var will be used instead. Note: it is possible for /var to have fewer features than /raw/var; if this is the case, then only the features present in /var will be overwritten, with the metadata for features not present in /var remaining as they were in /raw/var or empty

Cell-level metadata

Cell-level metadata is added to meta.data; the row names of the metadata (as determined by the value of the “_index” attribute, the “_index” dataset, or the “index” dataset, in that order) are added to the “cell.names” dataset instead. If the “__categories” dataset is present, each dataset within “__categories” will be stored as a factor group. Cell-level metadata will be added as an HDF5 group unless factors are not present and SeuratDisk.dtype.dataframe_as_group is FALSE

Dimensional reduction information:

Cell embeddings are taken from /obsm; dimensional reductions are named based on their names from obsm by removing the preceding “X_”.For example, if a dimensional reduction is named “X_pca” in /obsm, the resulting dimensional reduction information will be named “pca”. The key will be set to one of the following:

• “PC_” if “pca” is present in the dimensional reduction name (grepl("pca", reduction.name, ignore.case = TRUE))

• “tSNE_” if “tsne” is present in the dimensional reduction name (grepl("tsne", reduction.name, ignore.case = TRUE))

• reduction.name_ for all other reductions

Remember that the preceding “X_” will be removed from the reduction name before converting to a key. Feature loadings are taken from /varm and placed in the associated dimensional reduction. The dimensional reduction is determine from the loadings name in /varm:

• “PCs” will be added to a dimensional reduction named “pca”

• All other loadings in /varm will be added to a dimensional reduction named tolower(loading) (eg. a loading named “ICA” will be added to a dimensional reduction named “ica”)

If a dimensional reduction cannot be found according to the rules above, the loading will not be taken from the AnnData/H5AD file. Miscellaneous information will be taken from /uns/reduction where reduction is the name of the reduction in /obsm without the preceding “X_”; if no dimensional reduction information present, then miscellaneous information will not be taken from the AnnData/H5AD file. Standard deviations are taken from a dataset /uns/reduction/variance; the variances will be converted to standard deviations and added to the stdev dataset of a dimensional reduction

Nearest-neighbor graph

If a nearest neighbor graph is present in /uns/neighbors/distances, it will be added as a graph dataset in the h5Seurat file and associated with assay; if a value is present in /uns/neighbors/params/method, the name of the graph will be assay_method, otherwise, it will be assay_anndata

Layers

TODO: add this

Miscellaneous information

All groups and datasets from /uns will be copied to misc in the h5Seurat file except for the following:

• Any group or dataset named the same as a dimensional reduction (eg. /uns/pca)

• /uns/neighbors

h5Seurat to AnnData/H5AD

The h5Seurat to AnnData/H5AD conversion will try to automatically fill in datasets based on data presence. Data presense is determined by the h5Seurat index (source$index()). It works in the following manner:

Assay data

• X will be filled with scale.data if scale.data is present; otherwise, it will be filled with data

• var will be filled with meta.features only for the features present in X; for example, if X is filled with scale.data, then var will contain only features that have been scaled

• raw.X will be filled with data if X is filled with scale.data; otherwise, it will be filled with counts. If counts is not present, then raw will not be filled

• raw.var will be filled with meta.features with the features present in raw.X; if raw.X is not filled, then raw.var will not be filled

Cell-level metadata

Cell-level metadata is added to obs

Dimensional reduction information

Only dimensional reductions associated with assay or marked as global will be transfered to the H5AD file. For every reduction reduc:

• cell embeddings are placed in obsm and renamed to X_reduc

• feature loadings, if present, are placed in varm and renamed to either “PCs” if reduc is “pca” otherwise reduc in all caps

For example, if reduc is “ica”, then cell embeddings will be “X_ica” in obsm and feature loaodings, if present, will be “ICA” in varm

Nearest-neighbor graphs

If a nearest-neighbor graph is associated with assay, it will be added to uns/neighbors/distances; if more than one graph is present, then only the last graph according to the index will be added.

Layers

Data from other assays can be added to layers if they have the same shape as X (same number of cells and features). To determine this, the shape of each alternate assays's scale.data and data slots are determined. If they are the same shape as X, then that slot (scale.data is given priority over data) will be added as a layer named the name of the assay (eg. “SCT”). In addition, the features names will be added to var as assay_features (eg. “SCT_features”).

Description

Seurat bindings for h5Seurat files

Usage

## S3 method for class 'h5Seurat'
Cells(x)

## S3 method for class 'h5Seurat'
DefaultAssay(object, ...)

## S3 replacement method for class 'h5Seurat'
DefaultAssay(object, ...) <- value

## S3 method for class 'h5Seurat'
Idents(object, ...)

## S3 method for class 'H5Group'
IsGlobal(object)

## S3 method for class 'H5Group'
Key(object, ...)

## S3 method for class 'h5Seurat'
Project(object, ...)

## S3 replacement method for class 'h5Seurat'
Project(object, ...) <- value

## S3 method for class 'h5Seurat'
Stdev(object, reduction = "pca")

Description

A class for connections to h5Seurat files

A class for connections to h5Seurat files

Format

An R6Class object

Super classes

hdf5r::H5RefClass -> hdf5r::H5File -> SeuratDisk::scdisk -> h5Seurat

Methods

Public methods

• h5Seurat$index()

• h5Seurat$set.version()

• h5Seurat$version()

Method index()

Get the index for this h5Seurat file

Usage

h5Seurat$index()

Method set.version()

Set the version attribute

Usage

h5Seurat$set.version(version)

Arguments

Method version()

Get the version attribute

Usage

h5Seurat$version()

See Also

H5File

Description

Load a saved Seurat object from an h5Seurat file

Usage

LoadH5Seurat(file, ...)

## S3 method for class 'character'
LoadH5Seurat(
  file,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  neighbors = NULL,
  images = NULL,
  meta.data = TRUE,
  commands = TRUE,
  misc = is.null(x = assays),
  tools = is.null(x = assays),
  verbose = TRUE,
  ...
)

## S3 method for class 'H5File'
LoadH5Seurat(
  file,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  neighbors = NULL,
  images = NULL,
  meta.data = TRUE,
  commands = TRUE,
  misc = is.null(x = assays),
  tools = is.null(x = assays),
  verbose = TRUE,
  ...
)

## S3 method for class 'h5Seurat'
LoadH5Seurat(
  file,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  neighbors = NULL,
  images = NULL,
  meta.data = TRUE,
  commands = TRUE,
  misc = is.null(x = assays),
  tools = is.null(x = assays),
  verbose = TRUE,
  ...
)

## S3 method for class 'h5Seurat'
as.Seurat(
  x,
  assays = NULL,
  reductions = NULL,
  graphs = NULL,
  neighbors = NULL,
  images = NULL,
  meta.data = TRUE,
  commands = TRUE,
  misc = TRUE,
  tools = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Value

A Seurat object with the data requested

Description

Load data from a loom file into a Seurat object

Usage

LoadLoom(
  file,
  assay = NULL,
  cells = "CellID",
  features = "Gene",
  normalized = NULL,
  scaled = NULL,
  filter = c("cells", "features", "all", "none"),
  verbose = TRUE,
  ...
)

## S3 method for class 'character'
LoadLoom(file, ...)

## S3 method for class 'H5File'
LoadLoom(file, ...)

## S3 method for class 'loom'
LoadLoom(file, ...)

## S3 method for class 'loom'
as.Seurat(
  x,
  assay = NULL,
  cells = "CellID",
  features = "Gene",
  normalized = NULL,
  scaled = NULL,
  filter = c("cells", "features", "all", "none"),
  verbose = TRUE,
  ...
)

Arguments

Details

LoadLoom will try to automatically fill slots of a Seurat object based on data presence or absence in a given loom file. This method varies by loom specification version. For version-specific details, see sections below

Value

A Seurat object

Loom 0.1 Loading

Loading data from loom files less than version 3.0.0 is not currently supported

Loom 3.0.0 Loading

blah

See Also

Loom file conventions

Description

Seurat binding for loom files

Usage

## S3 method for class 'loom'
DefaultAssay(object, ...)

## S3 method for class 'loom'
dim(x)

Description

A class for connections to loom files

A class for connections to loom files

Format

An R6Class object

Super classes

hdf5r::H5RefClass -> hdf5r::H5File -> SeuratDisk::scdisk -> loom

Methods

Public methods

• loom$add_attribute()

• loom$add_graph()

• loom$add_layer()

• loom$version()

• loom$timestamp()

• loom$last.modified()

Method add_attribute()

Add an attribute

Usage

loom$add_attribute(x, name, type = c("global", "row", "col"))

Arguments

Method add_graph()

Add a graph

Usage

loom$add_graph(x, name, type = c("col", "row"), verbose = TRUE)

Arguments

Method add_layer()

Add a layer to this loom file

Usage

loom$add_layer(x, name, transpose = TRUE, verbose = TRUE)

Arguments

Returns

Invisibly returns NULL

Method version()

Get version information

Usage

loom$version()

Returns

A numeric_version object with the loom specification version information

Method timestamp()

Add a timestamp to a dataset or group as an HDF5 attribute

Usage

loom$timestamp(name = NULL)

Arguments

Returns

Invisibly returns the object

Method last.modified()

Retrieve a timestamp from a dataset or group

Usage

loom$last.modified(name = NULL, locale = FALSE)

Arguments

Returns

A character with the timestamp

See Also

H5File

Description

HDF5 allows storing data in an arbitrary fashion, which makes reading data into memory a hassle. The methods here serve as convenience functions for reading data stored in a certain format back into a certain R object. For details regarding how data should be stored on disk, please see the h5Seurat file specification.

Usage

## S3 method for class 'H5D'
as.array(x, ...)

## S3 method for class 'H5D'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'H5Group'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S4 method for signature 'H5Group'
as.factor(x)

## S4 method for signature 'H5Group'
as.list(x, which = NULL, ...)

## S3 method for class 'H5D'
as.logical(x, ...)

## S3 method for class 'H5D'
as.matrix(x, transpose = FALSE, ...)

## S3 method for class 'H5Group'
as.matrix(x, ...)

## S3 method for class 'H5D'
as.sparse(x, verbose = TRUE, ...)

## S3 method for class 'H5Group'
as.sparse(x, ...)

## S3 method for class 'H5D'
dimnames(x)

Arguments

Value

as.array: returns an array with the data from the HDF5 dataset

as.data.frame: returns a data.frame with the data from the HDF5 dataset or group

as.factor: returns a factor with the data from the HDF5 group

as.list: returns a list with the data from the HDF5 group

as.logical: returns a logical with the data from the HDF5 dataset

as.matrix, H5D method: returns a matrix with the data from the HDF5 dataset

as.sparse, H5D method: returns a sparse matrix with the data from the HDF5 dataset

as.sparse, as.matrix, H5Group method: returns a sparseMatrix with the data from the HDF5 group

dimnames: returns a two-length list of character vectors for row and column names. Row names should be in a column named index

Get and Register scdisk Subclasses

Description

Mechanisms for registration of scdisk subclass generators for use in functions that rely on the class definition instead of an object.

Usage

GetSCDisk(r6class = NULL)

RegisterSCDisk(r6class)

Arguments

Details

While scdisk-subclassed objects (eg. h5Seurat objects) follow traditional inheritance patterns (can be determined through inherits), the class definitions and object generators do not. These functions provide a simple mechanism for adding and getting the defintions of scdisk subclasses for functions that utilize the object generators or other aspects of the class definition (such as Convert)

To register a subclass of scdisk, simply add a call to RegisterSCDisk in your load hook

.onLoad <- function(libname, pkgname) {
  RegisterSCDisk(classgen)
  # Other code to be run on load
}

Value

GetSCDisk: if r6class is NULL, then a vector of all registered scdisk subclasses; otherwise, a generator for the requested scdisk subclass

RegisterSCDisk: adds r6class to the internal subclass registry and invisibly returns NULL

Examples

GetSCDisk()
GetSCDisk("h5Seurat")

## Not run: 
RegisterSCDisk(h5Seurat)

## End(Not run)

Description

Save a Seurat object to an h5Seurat file

Usage

SaveH5Seurat(object, filename, overwrite = FALSE, verbose = TRUE, ...)

as.h5Seurat(x, ...)

## Default S3 method:
SaveH5Seurat(object, filename, overwrite = FALSE, verbose = TRUE, ...)

## S3 method for class 'Seurat'
SaveH5Seurat(
  object,
  filename = paste0(Project(object = object), ".h5Seurat"),
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## Default S3 method:
as.h5Seurat(x, filename, overwrite = FALSE, verbose = TRUE, ...)

## S3 method for class 'H5File'
as.h5Seurat(x, ...)

## S3 method for class 'Seurat'
as.h5Seurat(
  x,
  filename = paste0(Project(object = x), ".h5seurat"),
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

SaveH5Seurat: Invisbly returns filename

as.h5Seurat: An h5Seurat object

Save a Seurat object to a loom file

Description

Save a Seurat object to a loom file

Usage

SaveLoom(object, filename, overwrite = FALSE, verbose = TRUE, ...)

as.loom(x, ...)

## Default S3 method:
SaveLoom(object, filename, overwrite = FALSE, verbose = TRUE, ...)

## S3 method for class 'Seurat'
SaveLoom(
  object,
  filename = paste0(Project(object = object), ".loom"),
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## Default S3 method:
as.loom(x, filename, overwrite = FALSE, verbose = TRUE)

## S3 method for class 'H5File'
as.loom(x, ...)

## S3 method for class 'Seurat'
as.loom(
  x,
  filename = paste0(Project(object = x), ".loom"),
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

SaveLoom: Invisibly returns filename

as.loom: A loom object

Description

A disk-based object for single-cell analysis

A disk-based object for single-cell analysis

Format

An R6Class object

Super classes

hdf5r::H5RefClass -> hdf5r::H5File -> scdisk

Methods

Public methods

• scdisk$new()

• scdisk$finalizer()

• scdisk$chunk.points()

• scdisk$timestamp()

• scdisk$last.modified()

Method new()

Create a new scdisk object

Usage

scdisk$new(
  filename = NULL,
  mode = c("a", "r", "r+", "w", "w-", "x"),
  validate = TRUE,
  ...
)

Arguments

Method finalizer()

Handle the loss of reference to this scdisk object

Usage

scdisk$finalizer()

Method chunk.points()

Generate chunk points for a dataset

Usage

scdisk$chunk.points(
  dataset,
  MARGIN = getOption(x = "SeuratDisk.chunking.MARGIN", default = "largest"),
  csize = NULL
)

Arguments

Returns

A matrix where each row is a chunk, column 1 is start points, column 2 is end points

Method timestamp()

Add a timestamp to a dataset or group as an HDF5 attribute

Usage

scdisk$timestamp(
  name = NULL,
  attr = "ts",
  tz = "UTC",
  format = TSFormats(type = "R")
)

Arguments

Returns

Invisilby returns the object

Method last.modified()

Retrieve a timestamp from a dataset or group

Usage

scdisk$last.modified(
  name = NULL,
  attr = "ts",
  locale = TRUE,
  tz = "UTC",
  format = TSFormats(type = "R")
)

Arguments

Returns

A character with the timestamp

See Also

H5File

Description

Transpose a matrix

Usage

Transpose(x, ...)

## S3 method for class 'dgCMatrix'
Transpose(x, ...)

## S3 method for class 'H5D'
Transpose(
  x,
  dest = GetParent(x = x),
  dname = paste0("t_", basename(path = x$get_obj_name())),
  overwrite = FALSE,
  verbose = TRUE,
  ...
)

## S3 method for class 'H5Group'
Transpose(
  x,
  dest = GetParent(x = x),
  dname = paste0("t_", basename(path = x$get_obj_name())),
  overwrite = FALSE,
  ...
)

Arguments

Value

dgCMatrix method: returns a dgCMatrix with the data of x transposed

H5D and H5Group methods: Invisibly returns 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. 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

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)