hdfqlr: an HDF API based on HDFql

Description

This package provides an R interface to HDF files using the HDFql.

Package options

hdfqlr uses the following options() to configure behavior:

• hdfqlr.dir: The HDFql install directory.

Alternatively, the HDFql install directory can be saved to an environment variable HDFQL_DIR.

Author(s)

Maintainer: Michael Koohafkan michael.koohafkan@gmail.com

Format Sequence For HDFql

Description

Format an integer sequence for selection with HDFql.

Usage

as_hdfql_sequence(s)

Arguments

Value

A vector of character representations of the integer sequence.

Create HDF Object

Description

Generic helper for creating HDF objects.

Usage

create(
  what = c("FILE", "GROUP", "DATASET", "ATTRIBUTE"),
  path,
  data.type,
  size,
  overwrite = FALSE,
  parallel = FALSE
)

create_group(group, overwrite = FALSE)

create_dataset(
  dataset,
  data.type,
  size = NULL,
  overwrite = FALSE,
  parallel = FALSE
)

create_attribute(
  attribute,
  data.type,
  size = NULL,
  overwrite = FALSE,
  parallel = FALSE
)

Arguments

Functions

• create_group: Create HDF group.

• create_dataset: Create HDF dataset.

• create_attribute: Create HDF attribute.

Drop HDF objects.

Description

Drop HDF objects.

Usage

drop(what = c("FILE", "GROUP", "DATASET", "ATTRIBUTE"), path)

hql_drop_dataset(dataset)

hql_drop_group(group, recursive = FALSE)

hql_drop_attribute(attribute)

hql_drop_all_attributes(path)

Arguments

Functions

• hql_drop_dataset: Drop HDF dataset.

• hql_drop_group: Drop HDF group.

• hql_drop_attribute: Drop HDF attribute.

• hql_drop_all_attributes: Drop all attributes from an HDF dataset or group.

HDF Data Type to R Type

Description

HDF Data Type to R Type

Usage

dtype_to_rtype(dtype)

Arguments

Value

The equivalent R class, or NULL if not found.

Execute With Memory

Description

Generic helper for executing HDFql operations using memory.

Usage

execute_with_memory(
  script,
  variable = NULL,
  direction = c("INTO", "FROM"),
  suffix = NULL,
  stop.on.error = TRUE
)

Arguments

Value

The script output, or NULL.

Get HDF Attribute Names

Description

Get HDF Attribute Names

Usage

get_attr_names(path)

Arguments

Value

A vector of attribute names.

Get Character Data

Description

Get character data from HDF file.

Usage

get_char_data(path, otype, parallel = FALSE)

Arguments

Value

An R array.

Get HDF Object Charset

Description

Get HDF Object Charset

Usage

get_charset(path, otype)

Arguments

Value

The HDF object charset.

Value From Cursor

Description

Generic helper for executing HDFql cursor operations.

Usage

get_cursor_values(script)

Arguments

Value

The script output, or NULL.

Get Data

Description

Get data from HDF file.

Usage

get_data(path, otype, transpose = TRUE, parallel = FALSE)

Arguments

Value

An R array.

Get HDF Object Data Type

Description

Get HDF Object Data Type

Usage

get_data_type(path, otype)

Arguments

Value

The HDF object data type.

Get HDF Object Dimension

Description

Get HDF Object Dimension

Usage

get_dimension(path, otype)

Arguments

Value

The HDF object dimensions.

Get List Keys or Values

Description

Get the value of a list key, or the key of a list value.

Usage

get_key(x, l, invert = FALSE)

Arguments

Value

A key or value.

Get HDF Object Type

Description

Get HDF Object Type

Usage

get_object_type(path)

Arguments

Value

The HDF object type.

Get HDF Object Size

Description

Get HDF Object Size

Usage

get_size(path, otype)

Arguments

Value

The HDF object size.

HDFql Wrapper Constants and Functions

Description

Access the constants and functions provided by the HDFql wrapper. The wrapper contents are stored in an environment when the HDFql library is loaded and used internally by hdfqlr to perform operations.

Usage

hql

Format

An object of class environment of length 1.

Details

This environment is exported so that users can directly use the HDFql wrapper functions. The intended method of use is to attach() the environment to the search path. For more information on what is provided by the wrapper, consult the HDFql reference manual.

Examples

## Not run: 
  attach(hql$wrapper)

## End(Not run)

HDFql Library Paths

Description

Environment containing information related to the HDFql library on the user's system.

Usage

hql.paths

Format

An object of class environment of length 4.

Create HDF Files, Datasets or Attribute

Description

Create HDF files and groups.

Usage

hql_create_file(file, overwrite = FALSE, parallel = FALSE)

hql_create_group(group, overwrite = FALSE)

Arguments

Functions

• hql_create_file: Create HDF file.

• hql_create_group: Create HDF group.

Examples

if(hql_is_loaded()) {
  tf = tempfile(fileext = ".h5")
  hql_create_file(tf)

  hql_use_file(tf)
  hql_create_group("group1")

  hql_close_file(tf)
}

Drop HDF groups, datasets, and attributes

Description

Drop a datset, attribute, or group from an HDF file.

Examples

if(hql_is_loaded()){
  tf = tempfile(fileext = ".h5")
  hql_create_file(tf)

  hql_use_file(tf)
  x = rnorm(10)
  attr(x, "myattribute") = "some information"
  hql_write_dataset(x, "mygroup/mydataset")

  hql_drop_attribute("mygroup/mydataset/myattribute")
  hql_drop_dataset("mygroup/mydataset")
  hql_drop_group("mygroup")
  
  hql_close_file(tf)
}

Access HDF Files

Description

Open (use) and close HDF files.

Usage

hql_use_file(file)

hql_close_file(file, all = FALSE)

Arguments

Functions

• hql_use_file: Open (use) an HDF file.

• hql_close_file: Close an HDF file.

Examples

if(hql_is_loaded()){
  tf = tempfile(fileext = ".h5")
  hql_create_file(tf)

  hql_use_file(tf)
  hql_flush()

  hql_close_file(tf)
}

Flush HDF Files

Description

Flush HDF file(s) to write buffered data to the disk.

Usage

hql_flush(global = TRUE)

Arguments

HDFql Library Status

Description

Check if the HDFql library loaded.

Usage

hql_is_loaded()

Value

Logical TRUE if DLLs are found, FALSE otherwise.

List HDF Groups, Datasets or Attributes

Description

List groups, datasets or attribute in an HDF file.

Usage

hql_list_groups(path, recursive = FALSE)

hql_list_datasets(path, recursive = FALSE)

hql_list_attributes(path)

Arguments

Value

A vector of paths.

Functions

• hql_list_groups: List groups.

• hql_list_datasets: List datasets.

• hql_list_attributes: List Attributes

Load HDFql DLLs

Description

Load the HDFql library.

Usage

hql_load(path)

hql_unload()

Arguments

Functions

• hql_unload: Unload HDFql Library.

Read HDF Dataset or Attribute

Description

Read a dataset or attribute from an HDF file into memory.

Generic helper for reading HDF objects into memory.

Usage

hql_read(what = c("DATASET", "ATTRIBUTE"), path, parallel = FALSE)

hql_read_dataset(path, include.attributes = TRUE, parallel = FALSE)

hql_read_attribute(path, parallel = FALSE)

hql_read_all_attributes(path, parallel = FALSE)

Arguments

Value

A matrix.

The attribute value.

A named list of attributes.

Functions

• hql_read_dataset: Read a dataset from an HDF file.

• hql_read_attribute: Read a single attribute from an HDF file.

• hql_read_all_attributes: Read attributes from an HDF file.

Examples

if(hql_is_loaded()){
  tf = tempfile(fileext = ".h5")
  hql_create_file(tf)

  hql_use_file(tf)
  x = matrix(rnorm(100), nrow = 20)
  hql_write_dataset(x, "dataset0")
  hql_write_attribute("normal", "dataset0/dist")
 y = month.name
 attr(y, "abbreviation") = month.abb
 attr(y, "number") = 1:12
 hql_write_dataset(y, "group1/dataset1")

hql_read_dataset("dataset0")
hql_read_dataset("group1/dataset1")
hql_read_attribute("group1/dataset1/abbreviation")
hql_read_all_attributes("group1/dataset1")

hql_close_file(tf)
}

Write HDF Dataset or Attribute

Description

Write a dataset or attribute to an HDF file.

Usage

hql_write_dataset(
  dataset,
  path,
  include.attributes = TRUE,
  overwrite = FALSE,
  parallel = FALSE
)

hql_write_attribute(attribute, path, overwrite = FALSE, parallel = FALSE)

hql_write_all_attributes(attributes, path, overwrite = FALSE, parallel = FALSE)

Arguments

Functions

• hql_write_dataset: Write a dataset to an HDF file.

• hql_write_attribute: Write an attribute to an HDF file.

• hql_write_all_attributes: Write multiple attributes to an HDF file.

Examples

if(hql_is_loaded()){
  tf = tempfile(fileext = ".h5")
  hql_create_file(tf)

  hql_use_file(tf)
  x = matrix(rnorm(100), nrow = 20)
  hql_write_dataset(x, "dataset0")
  hql_write_attribute("normal", "dataset0/dist")

  y = month.name
  attr(y, "abbreviation") = month.abb
  hql_write_dataset(y, "group1/dataset1")

  hql_close_file(tf)
}

HDF Integer Output to Character

Description

Convert integer data from an HDF file to characters.

Usage

int_to_char(x, trim = FALSE)

Arguments

Value

A character array.

List HDF Objects

Description

List HDF Objects

Usage

list_hdf(what = c("GROUP", "DATASET", "ATTRIBUTE"), path)

HDFql Default Path

Description

Retrieve the HDFql installation directory from existing options. This function is used to automatically connect to HDFql without needing to specify the installation path.

Usage

path_from_options(startup = FALSE)

Arguments

Details

The function first looks for the R option hdfqlr.dir, and second looks for the environment variable HDFQL_DIR.

Recursively Walk Group Structure

Description

Recursively walk through HDF groups.

Usage

recurse_groups(path)

rev_recurse_groups(path)

R Type to HDF Data Type

Description

R Type to HDF Data Type

Usage

rtype_to_dtype(rtype, stop.on.error = TRUE)

Arguments

Value

The equivalent HDF data type, or NULL if not found.

Set Character Data

Description

Set character data in HDF file.

Usage

set_char_data(x, path, otype, transpose = FALSE, parallel = FALSE)

Arguments

Set Data

Description

Set data in HDF file.

Usage

set_data(x, path, otype, transpose = TRUE, parallel = FALSE)

Arguments

HDFql Paths

Description

Set the partial paths to the HDFql library and wrapper.

Usage

set_paths()

HDFql Load Requirement

Description

Return an error if the HDFql library is not loaded.

Usage

stop_not_loaded()

Write HDF Object

Description

Write HDF Object

Usage

write(what, x, path, overwrite = FALSE, parallel = FALSE)