h5create#

Purpose#

Creates an HDF5 data file, or adds a new dataset to an existing HDF5 file.

Format#

retcode = h5create(fname, dname, dims[, datatype[, chunk_size]])#
Parameters:

  • fname (string) – name of the HDF5 file. The file extension, .h5, is recommended, but not required.

  • dname (string) – a name of the dataset in HDF5 file. e.g. "/mydata".

  • dims (Nx1 matrix) – where \(N\) is the number of dimensions of the dataset, the size of each of the dimensions of the dataset.

  • datatype (string) –

    data type. Valid options include:

    • "double"

    • "float"

    • "int64"

    • "int32"

    • "uint64"

    • "uint32"

    Default is "double".

  • chunk_size (matrix or array) – with the same dimensions as the dataset, specifying the size of the chunks of data that will be created in the file.

Returns:

retcode (scalar) – 0 if successful, non-zero otherwise.

Examples#

Create a fixed size 2-dimensional dataset#

// Define a name of a  HDF5 file
fname = "testdata.h5";

// Define a dataset name under the HDF5 file
dname = "/mydata";

// Define the size of the dataset, 100 rows and 5 columns
r = 100;
c = 5;
dims = r|c;

// Create a dataset under the HDF5 file
call h5create(fname, dname, dims);

// Fill dataset with random normal data
x = rndn(100, 5);
h5write(fname, dname, x);

Create a 2-dimensional dataset with 5 columns and a flexible number of rows#

// Define filename
fname = "expandable_data.h5";

// Define dataset in HDF5 file
dname = "/data";

// Define a size of flexible rows and 5 columns
r = __INFP;
c = 5;
dims  = r|c;

// Create a dataset
call h5create(fname, dname, dims);

Create a 3-Dimensional dataset and one intermediate group#

// Define file name
fname = "surveys.h5";

// Define a new dataset name, including one intermediate group
dname = "/household/Washington";

/*
** Define a 3-dimensional dataset, containing 3 matrices with
** 8 columns and an expandable number of rows
*/
num_matrices = 3;
r = __INFP;
c = 8;
dims = num_matrices|r|c;

// Store the data in chunks of 1000x8 elements
chunk_size = { 1, 1000, 8 };

// Store data as 4 byte floating point (about 8 digits of precision)
dtype = "float";

// Create the dataset
call h5create(fname, dname, dims, dtype, chunk_size);

/*
** Define another dataset of same type
** inside the same file
*/
dname_new =  "/household/Oregon";

// Create new dataset
call h5create(fname, dname_new, dims, dtype, chunk_size);

Remarks#

  • HDF5 files can hold more than one dataset. They are referenced in the same manner as a Linux or macOS file system. The base or root node is /. All datasets are relative to this root node.

  • If a dataset name contains multiple intermediate groups, for example:

    "/surveys/household/Washington"

    and the intermediate groups, surveys and household in the above string, do not yet exist, h5create() will create them.

  • By default, HDF5 datasets may not change size. To make one of the dimensions expandable, set it to __INFP.

  • All columns of an HDF5 dataset must be of the same data type. However, multiple datasets with different data types may be created in a single HDF5 file.

  • Information about a dataset, called an attribute, may be attached to a dataset in an HDF5 file with the function h5writeAttribute().

  • Chunk size must be specified when users create a dataset with more than 2 dimensions and one of those dimensions is unlimited (__INFP).

See also

Functions h5read(), h5write(), open, create, writer(), seekr(), eof()

On this page