Main Content

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

H5D.flush

Flush all data buffers to disk (since R2021b)

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 a 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 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

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

H5D.refresh

Clear and reload all data buffers (since R2021b)

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

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

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

Examples

expand all

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
dset_id = H5D.open(fid,'/g4/world');
start = [15 5];
h5_start = fliplr(start);
block = [10 5];
h5_block = fliplr(block);
mem_space_id = H5S.create_simple(2,h5_block,[]);

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

dspace_id = H5D.get_space(dset_id);
H5S.select_hyperslab(dspace_id,'H5S_SELECT_SET',h5_start,[],[],h5_block);
data = rand(block);

Write the selected hyperslab to the dataset.

% Write to the dataset
H5D.write(dset_id,'H5ML_DEFAULT',mem_space_id,dspace_id,plist,data);
H5D.close(dset_id);
H5F.close(fid);

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.

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

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'); 
dset_id = H5D.open(fid,'/g1/g1.1/dset1.1.1');

Read the entire dataset dset_id.

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

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'); 
dset_id = 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]);
mem_space_id = H5S.create_simple(2,dims,[]);
dspace_id = H5D.get_space(dset_id);
offset = fliplr([3 4]);
block = fliplr([2 3]);

Select the hyperslab from the dataset, then read it.

H5S.select_hyperslab(dspace_id,'H5S_SELECT_SET',offset,[],[],block);
data = H5D.read(dset_id,'H5ML_DEFAULT',mem_space_id,dspace_id,plist);
H5D.close(dset_id);
H5F.close(fid);

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');
type_id = H5T.copy('H5T_NATIVE_DOUBLE');

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

dims = [10 5];
h5_dims = fliplr(dims);
h5_maxdims = h5_dims;
space_id = H5S.create_simple(2,h5_dims,h5_maxdims);
dcpl = 'H5P_DEFAULT';
dset_id = H5D.create(fid,'DS',type_id,space_id,dcpl);

Close the identifiers.

H5S.close(space_id);
H5T.close(type_id);
H5D.close(dset_id);
H5F.close(fid);
h5disp('myfile.h5');

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');
type_id = H5T.copy('H5T_C_S1');

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

H5T.set_size(type_id,4);
dims = [6 3];
h5_dims = fliplr(dims);
h5_maxdims = h5_dims;
space_id = H5S.create_simple(2,h5_dims,h5_maxdims);
dcpl = 'H5P_DEFAULT';

Create the dataset, then close all identifiers.

dset_id = H5D.create(fid,'DS',type_id,space_id,dcpl);
H5S.close(space_id);
H5T.close(type_id);
H5D.close(dset_id);
H5F.close(fid);
h5disp('myfile_strings.h5');
Introduced before R2006a