Dataset (H5D)

Multidimensional arrays of data elements and supporting metadata

Description

Use the MATLAB^® HDF5 dataset interface, H5D, to create, read, and write datasets, and access information about them.

An HDF5 dataset is an object composed of a collection of data elements, or raw data, and metadata that stores a description of the data elements, data layout, and all other information necessary to write, read, and interpret the stored data.

Functions

H5D.close

Close dataset

H5D.close(dsID) ends access to a dataset specified by dsID and releases resources used by it.

H5D.create

Create new dataset

dsID = H5D.create(locID,dsname,typeID,spaceID,dcplID) creates the dataset with the name dsname in the file or in the group specified by locID. This syntax corresponds to the H5Dcreate1 interface in version 1.6 of the HDF5 C library.

dsID = H5D.create(locID,dsname,typeID,spaceID,lcplID,dcplID,daplID) creates the dataset with three property list identifiers, lcplID, dcplID, and daplID. This syntax corresponds to the H5Dcreate2 interface in version 1.8 of the HDF5 C library.

 Details

Input Arguments

• locID — File or group identifier.

• dsname — Dataset name.

• typeID — Datatype identifier.

• spaceID — Dataspace identifier.

• lcplID — Link creation property list identifier.

• dcplID — Dataset creation property list identifier.

• daplID — Dataset access property list identifier.

Output Arguments

• dsID — Identifier of created dataset.

H5D.flush

Flush all data buffers to disk

H5D.flush(dsID) causes all buffers for the dataset associated with identifier dsID to be immediately flushed to disk without removing data from the cache.

H5D.get_access_plist

Copy of dataset access property list

plistID = H5D.get_access_plist(dsID) returns the identifier to a copy of the dataset access property list used to open the dataset specified by dsID.

H5D.get_create_plist

Copy of dataset creation property list

plistID = H5D.get_create_plist(dsID) returns the identifier to a copy of the dataset creation property list for the dataset specified by dsID.

H5D.get_offset

Location of dataset in file

offset = H5D.get_offset(dsID) returns the location in the file of the dataset specified by dsID. The location is expressed as an offset, in bytes, from the beginning of the file.

H5D.get_space

Copy of dataset dataspace

dspaceID = H5D.get_space(dsID)returns an identifier for a copy of the dataspace for the dataset specified by dsID.

H5D.get_space_status

Determine if space is allocated

status = H5D.get_space_status(dsID) determines whether space has been allocated for the dataset specified by dsID.

H5D.get_storage_size

Determine required storage size

dsetsize = H5D.get_storage_size(dsID) returns the amount of storage, in bytes, that is required for the dataset specified by dsID.

H5D.get_type

Copy of datatype

typeID = H5D.get_type(dsID) returns an identifier for a copy of the datatype for the dataset specified by dsID.

H5D.open

Open specified dataset

dsID = H5D.open(locID,dsname) opens the dataset specified by dsname in the file or group specified by locID.

dsID = H5D.open(locID,dsname,daplID) opens the dataset specified by dsname in the file or group specified by locID with the dataset access property list specified by daplID.

 Details

Input Arguments

• locID — File or group identifier.

• dsname — Dataset name.

• daplID — Dataset access property list identifier.

Output Arguments

• dsID — Identifier of opened dataset.

H5D.read

Read data from HDF5 dataset

data = H5D.read(dsID) reads the entire dataset specified by dsID.

data = H5D.read(dsID,memtypeID,memspaceID,filespaceID,dxplID) reads the dataset specified by dsID with additional parameters.

 Details

Input Arguments

• dsID — Dataset identifier.

• memtypeID — Memory datatype identifier. The memtypeID argument should usually be "H5ML_DEFAULT" to allow MATLAB to determine the appropriate value.

• memspaceID — Memory dataspace identifier that describes how the data is to be arranged in memory. The memspaceID argument should usually be set to "H5S_ALL".

• filespaceID — File dataspace identifier that describes how the data is to be selected from the file. It can be given as "H5S_ALL", but this results in the entire dataset being read into memory.

• dxplID — Dataset transfer property list identifier, and should usually be set to "H5P_DEFAULT".

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. For more information, see Report Data Set Dimensions.

H5D.refresh

Clear and reload all data buffers

H5D.refresh(dsID) clears all buffers associated with dataset dsID and immediately reloads them with updated content from disk.

H5D.set_extent

Change size of dataset dimensions

H5D.set_extent(dsID,extents) changes the dimensions of the dataset specified by dsID to the sizes specified in extents.

 Details

Input Arguments

• dsID — Dataset identifier.

• extents — Dataset dimensions.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. The extents parameter assumes C-style ordering. For more information, see Report Data Set Dimensions.

H5D.vlen_get_buf_size

Determine variable length storage requirements

size = H5D.vlen_get_buf_size(dsID,typeID,spaceID) determines the number of bytes required to store the variable-length data from the dataset specified by dsID.

 Details

Input Arguments

• dsID — Dataset identifier.

• typeID — Dataset datatype identifier used for the memory representation of the variable-length data in memory.

• spaceID — Dataset dataspace identifier used for the selection in the dataset on disk.

H5D.write

Write data to HDF5 dataset

H5D.write(dsID,memtypeID,memspaceID,filespaceID,dxplID,buf) writes the dataset specified by dsID from the application memory buffer buf into the file.

 Details

Input Arguments

• dsID — Dataset identifier.

• memtypeID — Memory datatype of the dataset. The memory datatype should usually be "H5ML_DEFAULT", which specifies that MATLAB determines the appropriate memory datatype.

• memspaceID — Memory dataspace that defines the part of the dataset to write.

• filespaceID — File dataspace that defines the part of the dataset to write.

• dxplID — Dataset transfer property list identifier.

• buf — Application memory buffer.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. For more information, see Report Data Set Dimensions.

Limitations

• You can write to variable-length datasets only if the datatype class of the dataset is one of these values:

  • "H5T_INTEGER"

  • "H5T_FLOAT"

  • "H5T_STRING" with variable-length or a fixed length of 1

Examples

Write Hyperslab of Data to Dataset

Select a hyperslab of data and write it to a dataset.

Create a writeable copy of the file example.h5.

srcFile = fullfile(matlabroot,"toolbox","matlab","demos","example.h5");
copyfile(srcFile,"myfile.h5");
fileattrib("myfile.h5","+w");
plist = "H5P_DEFAULT";
fid = H5F.open("myfile.h5","H5F_ACC_RDWR",plist);

Open the dataset.

% Open the dataset
dsID = H5D.open(fid,"/g4/world");
start = [15 5];
h5_start = fliplr(start);
block = [10 5];
h5_block = fliplr(block);
memSpaceID = H5S.create_simple(2,h5_block,[]);

Copy identifier of dataspace and select hyperslab within it to write to the dataset.

dspaceID = H5D.get_space(dsID);
H5S.select_hyperslab(dspaceID,"H5S_SELECT_SET",h5_start,[],[],h5_block);
data = rand(block);

Write the selected hyperslab to the dataset.

% Write to the dataset
H5D.write(dsID,"H5ML_DEFAULT",memSpaceID,dspaceID,plist,data);
H5S.close(dspaceID);
H5S.close(memSpaceID);
H5D.close(dsID);
H5F.close(fid);

Change Dimensions of Dataset

Open a dataset in an HDF5 file and change its dimensions.

Create a writeable copy of the file example.h5.

srcFile = fullfile(matlabroot,"toolbox","matlab","demos","example.h5");
copyfile(srcFile,"myfile.h5");
fileattrib("myfile.h5","+w");
fid = H5F.open("myfile.h5","H5F_ACC_RDWR","H5P_DEFAULT");

Open a dataset and change the size of its dimensions.

dsID = H5D.open(fid,"/g4/time");
H5D.set_extent(dsID,20);
H5D.close(dsID);
H5F.close(fid);

Read Entire Dataset

Read an entire dataset from an HDF5 file.

Open the file example.h5 and the dataset /g1/g1.1/dset1.1.1.

fid = H5F.open("example.h5"); 
dsID = H5D.open(fid,"/g1/g1.1/dset1.1.1");

Read the entire dataset dsID.

data = H5D.read(dsID);
H5D.close(dsID);
H5F.close(fid);

Read Hyperslab from Dataset

Read a 2x3 hyperslab of data from a dataset, starting in the 4th row and 5th column of the example dataset.

Create a property list identifier, then open the HDF5 file and the dataset /g1/g1.1/dset1.1.1.

plist = "H5P_DEFAULT";
fid = H5F.open("example.h5"); 
dsID = H5D.open(fid,"/g1/g1.1/dset1.1.1");

Create a 2 x 3 simple dataspace. Then, create a copy of the dataset dataspace identifier.

dims = fliplr([2 3]);
memSpaceID = H5S.create_simple(2,dims,[]);
dspaceID = H5D.get_space(dsID);
offset = fliplr([3 4]);
block = fliplr([2 3]);

Select the hyperslab from the dataset, then read it.

H5S.select_hyperslab(dspaceID,"H5S_SELECT_SET",offset,[],[],block);
data = H5D.read(dsID,"H5ML_DEFAULT",memSpaceID,dspaceID,plist);
H5S.close(dspaceID);
H5S.close(memSpaceID);
H5D.close(dsID);
H5F.close(fid);

Create Double-Precision Dataset

Create a 10x5 double precision dataset with default property list settings.

Create an HDF5 file myfile.h5, and identify the datatype.

fid = H5F.create("myfile.h5");
typeID = H5T.copy("H5T_NATIVE_DOUBLE");

Creating a 10x5 simple dataspace and a dataset with identifier dsID.

dims = [10 5];
h5_dims = fliplr(dims);
h5_maxdims = h5_dims;
spaceID = H5S.create_simple(2,h5_dims,h5_maxdims);
dcpl = "H5P_DEFAULT";
dsID = H5D.create(fid,"DS",typeID,spaceID,dcpl);

Close the identifiers.

H5D.close(dsID);
H5S.close(spaceID);
H5T.close(typeID);
H5F.close(fid);
h5disp("myfile.h5");

Create Fixed-Length String Dataset

Create a 6x3 fixed length string dataset. Each string will have a length of 4 characters.

Create an HDF5 file myfile.h5, and identify the datatype.

fid = H5F.create("myfile_strings.h5");
typeID = H5T.copy("H5T_C_S1");

Create a 6x3 simple dataspace and a fixed-length string size of 4 bytes.

H5T.set_size(typeID,4);
dims = [6 3];
h5_dims = fliplr(dims);
h5_maxdims = h5_dims;
spaceID = H5S.create_simple(2,h5_dims,h5_maxdims);
dcpl = "H5P_DEFAULT";

Create the dataset, then close all identifiers.

dsID = H5D.create(fid,"DS",typeID,spaceID,dcpl);
H5D.close(dsID);
H5S.close(spaceID);
H5T.close(typeID);
H5F.close(fid);
h5disp("myfile_strings.h5");

Version History

Introduced before R2006a

R2021b: Flush and refresh buffers associated with a dataset

You can use H5D.flush to flush the buffers associated with a dataset to disk and H5D.refresh to clear the buffer associated with a dataset and reload with updated contents from disk.