HDF5ArraySeed objects

HDF5ArraySeed is a low-level helper class for representing a pointer to an HDF5 dataset.

Note that an HDF5ArraySeed object is not intended to be used directly. Most end users will typically create and manipulate a higher-level HDF5Array object instead. See ?HDF5Array for more information.

Usage

## --- Constructor function ---

HDF5ArraySeed(filepath, name, as.sparse=FALSE, type=NA)

## --- Accessors --------------

# S4 method for class 'HDF5ArraySeed'
path(object)

# S4 method for class 'HDF5ArraySeed'
path(object) <- value

# S4 method for class 'HDF5ArraySeed'
dim(x)

# S4 method for class 'HDF5ArraySeed'
dimnames(x)

# S4 method for class 'HDF5ArraySeed'
type(x)

# S4 method for class 'HDF5ArraySeed'
is_sparse(x)

# S4 method for class 'HDF5ArraySeed'
is_sparse(x) <- value

# S4 method for class 'HDF5ArraySeed'
chunkdim(x)

## --- Data extraction --------

# S4 method for class 'HDF5ArraySeed'
extract_array(x, index)

# S4 method for class 'HDF5ArraySeed'
extract_sparse_array(x, index)

Arguments

filepath, name, as.sparse, type

See ?HDF5Array for a description of these arguments.

object, x

An HDF5ArraySeed object or derivative.

value

For the path() setter: The new path (as a single string) to the HDF5 file where the dataset is located.

For the is_sparse() setter: TRUE or FALSE.

index

See ?extract_array in the S4Arrays package.

Details

The HDF5ArraySeed class has one direct subclass: Dense_H5ADMatrixSeed. See ?Dense_H5ADMatrixSeed for more information.

Note that the implementation of HDF5ArraySeed objects follows the widely adopted convention of transposing HDF5 matrices when they get loaded into R.

Finally note that an HDF5ArraySeed object supports a very limited set of methods:

path(): Returns the path to the HDF5 file where the dataset is located.
dim(), dimnames().
type(), extract_array(), is_sparse(), extract_sparse_array(), chunkdim(): These generics are defined and documented in other packages e.g. in S4Arrays for extract_array() and is_sparse(), in SparseArray for extract_sparse_array(), and in DelayedArray for chunkdim().

Value

HDF5ArraySeed() returns an HDF5ArraySeed object.

HDF5ArraySeed vs HDF5Array objects

In order to have access to the full set of operations that are available for DelayedArray objects, an HDF5ArraySeed object first needs to be wrapped in a DelayedArray object, typically by calling the DelayedArray() constructor on it.

This is what the HDF5Array() constructor function does.

Note that the result of this wrapping is an HDF5Array object, which is just an HDF5ArraySeed object wrapped in a DelayedArray object.

Examples

library(h5vcData)
tally_file <- system.file("extdata", "example.tally.hfs5",
                          package="h5vcData")
h5ls(tally_file)
#>               group         name       otype  dclass                   dim
#> 0                 / ExampleStudy   H5I_GROUP                              
#> 1     /ExampleStudy           16   H5I_GROUP                              
#> 2  /ExampleStudy/16       Counts H5I_DATASET INTEGER 12 x 6 x 2 x 90354753
#> 3  /ExampleStudy/16    Coverages H5I_DATASET INTEGER      6 x 2 x 90354753
#> 4  /ExampleStudy/16    Deletions H5I_DATASET INTEGER      6 x 2 x 90354753
#> 5  /ExampleStudy/16    Reference H5I_DATASET INTEGER              90354753
#> 6     /ExampleStudy           22   H5I_GROUP                              
#> 7  /ExampleStudy/22       Counts H5I_DATASET INTEGER 12 x 6 x 2 x 51304566
#> 8  /ExampleStudy/22    Coverages H5I_DATASET INTEGER      6 x 2 x 51304566
#> 9  /ExampleStudy/22    Deletions H5I_DATASET INTEGER      6 x 2 x 51304566
#> 10 /ExampleStudy/22    Reference H5I_DATASET INTEGER              51304566

name <- "/ExampleStudy/16/Coverages"  # name of the dataset of interest
seed1 <- HDF5ArraySeed(tally_file, name)
seed1
#> An object of class "HDF5ArraySeed"
#> Slot "filepath":
#> [1] "/usr/local/lib/R/site-library/h5vcData/extdata/example.tally.hfs5"
#> 
#> Slot "name":
#> [1] "/ExampleStudy/16/Coverages"
#> 
#> Slot "as_sparse":
#> [1] FALSE
#> 
#> Slot "type":
#> [1] NA
#> 
#> Slot "dim":
#> [1]        6        2 90354753
#> 
#> Slot "chunkdim":
#> [1]     1     1 88238
#> 
#> Slot "first_val":
#> [1] 0
#> 
path(seed1)
#> [1] "/usr/local/lib/R/site-library/h5vcData/extdata/example.tally.hfs5"
dim(seed1)
#> [1]        6        2 90354753
chunkdim(seed1)
#> [1]     1     1 88238

seed2 <- HDF5ArraySeed(tally_file, name, as.sparse=TRUE)
seed2
#> An object of class "HDF5ArraySeed"
#> Slot "filepath":
#> [1] "/usr/local/lib/R/site-library/h5vcData/extdata/example.tally.hfs5"
#> 
#> Slot "name":
#> [1] "/ExampleStudy/16/Coverages"
#> 
#> Slot "as_sparse":
#> [1] TRUE
#> 
#> Slot "type":
#> [1] NA
#> 
#> Slot "dim":
#> [1]        6        2 90354753
#> 
#> Slot "chunkdim":
#> [1]     1     1 88238
#> 
#> Slot "first_val":
#> [1] 0
#> 

## Alternatively:
is_sparse(seed1) <- TRUE
seed1  # same as 'seed2'
#> An object of class "HDF5ArraySeed"
#> Slot "filepath":
#> [1] "/usr/local/lib/R/site-library/h5vcData/extdata/example.tally.hfs5"
#> 
#> Slot "name":
#> [1] "/ExampleStudy/16/Coverages"
#> 
#> Slot "as_sparse":
#> [1] TRUE
#> 
#> Slot "type":
#> [1] NA
#> 
#> Slot "dim":
#> [1]        6        2 90354753
#> 
#> Slot "chunkdim":
#> [1]     1     1 88238
#> 
#> Slot "first_val":
#> [1] 0
#> 

DelayedArray(seed1)
#> <6 x 2 x 90354753> sparse HDF5Array object of type "integer":
#> ,,1
#>      [,1] [,2]
#> [1,]    0    0
#> [2,]    0    0
#>  ...    .    .
#> [5,]    0    0
#> [6,]    0    0
#> 
#> ...
#> 
#> ,,90354753
#>      [,1] [,2]
#> [1,]    0    0
#> [2,]    0    0
#>  ...    .    .
#> [5,]    0    0
#> [6,]    0    0
#> 
stopifnot(class(DelayedArray(seed1)) == "HDF5Array")