writeHDF5Array {HDF5Array} | R Documentation

## Write an array-like object to an HDF5 file

### Description

A function for writing an array-like object to an HDF5 file.

### Usage

    writeHDF5Array(x, filepath=NULL, name=NULL, chunkdim=NULL, level=NULL,
                   verbose=FALSE)

### Arguments

`x` | The array-like object to write to an HDF5 file. If `x` is a DelayedArray object, `writeHDF5Array` realizes it on disk, that is, all the delayed operations carried by the object are executed while the object is written to disk. See "On-disk realization of a DelayedArray object as an HDF5 dataset" section below for more information.
`filepath` | `NULL` or the path (as a single string) to the (new or existing) HDF5 file where to write the dataset. If `NULL`, then the dataset will be written to the current HDF5 dump file i.e. to the file whose path is `getHDF5DumpFile`.
`name` | `NULL` or the name of the HDF5 dataset to write. If `NULL`, then the name returned by `getHDF5DumpName` will be used.
`chunkdim` | The dimensions of the chunks to use for writing the data to disk. By default (i.e. when `chunkdim` is set to `NULL`), `getHDF5DumpChunkDim(dim(x))` will be used. See `?getHDF5DumpChunkDim` for more information. Set `chunkdim` to 0 to write unchunked data (a.k.a. contiguous data).
`level` | The compression level to use for writing the data to disk. By default, `getHDF5DumpCompressionLevel()` will be used. See `?getHDF5DumpCompressionLevel` for more information.
`verbose` | Set to `TRUE` to make the function display progress.

### Details

Please note that, depending on the size of the data to write to disk and the performance of the disk, `writeHDF5Array` can take a long time to complete. Use `verbose=TRUE` to see its progress.

Use `setHDF5DumpFile` and `setHDF5DumpName` to control the location of automatically created HDF5 datasets.

Use `setHDF5DumpChunkLength`, `setHDF5DumpChunkShape`, and `setHDF5DumpCompressionLevel`, to control the physical properties of automatically created HDF5 datasets.

### Value

An HDF5Array object pointing to the newly written HDF5 dataset on disk.

### On-disk realization of a DelayedArray object as an HDF5 dataset

When passed a DelayedArray object, `writeHDF5Array` realizes it on disk, that is, all the delayed operations carried by the object are executed on-the-fly while the object is written to disk. This uses a block-processing strategy so that the full object is not realized at once in memory. Instead the object is processed block by block i.e. the blocks are realized in memory and written to disk one at a time.

In other words, `writeHDF5Array(x, ...)` is semantically equivalent to `writeHDF5Array(as.array(x), ...)`, except that `as.array(x)` is not called because this would realize the full object at once in memory.

See `?DelayedArray` for general information about DelayedArray objects.

### See Also

- HDF5Array objects.

- `saveHDF5SummarizedExperiment` and `loadHDF5SummarizedExperiment` in this package (the HDF5Array package) for saving/loading an HDF5-based SummarizedExperiment object to/from disk.

- HDF5-dump-management to control the location and physical properties of automatically created HDF5 datasets.

- `h5ls` in the rhdf5 package.

### Examples

    ## ---------------------------------------------------------------------
    ## WRITE AN ORDINARY ARRAY TO AN HDF5 FILE
    ## ---------------------------------------------------------------------
    m <- matrix(runif(350, min=-1), nrow=25)
    out_file <- tempfile()

    M1 <- writeHDF5Array(m, out_file, name="M1", chunkdim=c(5, 5))
    M1
    chunkdim(M1)

    ## ---------------------------------------------------------------------
    ## WRITE A DelayedArray OBJECT TO AN HDF5 FILE
    ## ---------------------------------------------------------------------
    M2 <- log(t(DelayedArray(m)) + 1)
    M2 <- writeHDF5Array(M2, out_file, name="M2", chunkdim=c(5, 5))
    M2
    chunkdim(M2)

    library(rhdf5)
    library(h5vcData)

    tally_file <- system.file("extdata", "example.tally.hfs5",
                              package="h5vcData")
    h5ls(tally_file)

    cvg0 <- HDF5Array(tally_file, "/ExampleStudy/16/Coverages")

    cvg1 <- cvg0[ , , 29000001:29000007]

    writeHDF5Array(cvg1, out_file, "cvg1")
    h5ls(out_file)

[Package HDF5Array version 1.14.4 Index]