hdf5write

(Not recommended) Write data to file in HDF5 format

hdf5write is not recommended. Use h5write instead.

Syntax

hdf5write(filename,loc,ds)

hdf5write(filename,details1,ds1,details2,ds2,...details,ds)

hdf5write(filename,details,attr)

hdf5write(___,Name,Value)

Description

hdf5write(filename,loc,ds) writes the data ds to an HDF5 file specified by filename. If filename does not exist, hdf5write creates it. If filename exists, hdf5write overwrites the existing data in the file by default. The data can be appended to an existing file using an optional name-value argument.

hdf5write(filename,details1,ds1,details2,ds2,...details,ds) writes one or more datasets ds to filename using the values in one or more input structures.

hdf5write(filename,details,attr) writes the metadata attr to filename using the values in details.

hdf5write(___,Name,Value) specifies optional name-value arguments, in addition to any of the input arguments in the previous syntaxes.

Input Arguments

filename — File name

character vector | string scalar

File name, specified as a character vector or string scalar containing the name of an HDF5 file.

Depending on the location you are writing to, filename can take on one of these forms.

Location	Form
Current folder	Specify the name of the file in filename. Example: 'myFile.h5'
Other folders	If the file is not in the current folder or in a folder on the MATLAB® path, then specify the full or relative path name in filename. Example: 'C:\myFolder\myFile.h5' Example: 'myFolder\myFile.h5'

loc — Location in file

character vector | string scalar

Location in file, specified as a character vector or string scalar containing the full path name of a dataset or group to which the data is written.

details — Input structure

structure array

Input structure that hdf5write uses to write data to an HDF5 file, specified as one or more structure arrays. The details structure can contain different fields depending on whether you are writing a dataset or an attribute to a file.

For datasets, details can have the following fields:

• Location — Character vector or string scalar containing the full path name of a group or dataset to which you want to write the data.

• Name — Character vector or string scalar containing the name to assign to the input dataset.

For attributes, details can have the following fields:

• AttachedTo — Structure array containing the location of the object that the input attribute modifies.

• AttachType — Object type that the input attribute modifies, specified as 'group' or 'dataset'.

• Name — Character vector or string scalar containing the name to assign to the input attribute.

ds — Input dataset

numeric array | character vector | string scalar | cell array of character vectors | string array | cell array of numeric data | structure array | HDF5 object

Input data to write to the HDF5 file, specified as one or more of these:

• numeric array

• character vector

• string scalar

• cell array of character vectors

• string array

• cell array of numeric data

• structure array

• HDF5 object.

attr — Attribute name

character vector | string scalar

Attribute name, specified as a character vector or string scalar containing the name of an attribute belonging to a group or dataset.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'WriteMode','append' appends data to an existing HDF5 file.

V71Dimensions — Compatibility with MATLAB 7.1 and earlier

false (default) | true

Compatibility with MATLAB 7.1 and earlier, specified as the comma-separated pair consisting of 'V71Dimensions' and either true or false. If you specify true, then hdf5write permutes the first two dimensions of the dataset, making the dimension order of the dataset written to the file consistent with previous versions of hdf5write (MATLAB 7.1 [R14SP3] and earlier).

The default value of 'V71Dimensions' is false, which does not change the order of the output data dimensions.

HDF5 describes dataset dimensions in row-major order, while MATLAB stores data in column-major order. However, permuting these dimensions may not correctly reflect the intent of the data and may invalidate metadata. The data written to the file correctly reflects the data ordering of the datasets; each dimension in the output datasets matches the same dimension in the corresponding MATLAB variable.

Example: 'V71Dimensions',true

WriteMode — Writing mode

character vector | string scalar

Writing mode, specified as the comma-separated pair consisting of 'WriteMode' and a character vector or a string scalar. Specify 'WriteMode' as one of the following values:

• 'overwrite' (default) — Overwrite the file.

• 'append' — Append data to an existing HDF5 file.

Example: 'WriteMode','append'

Examples

Write Data to HDF5 Files

Write data to three different HDF5 files named myfile.h5, myfile2.h5, and myfile3.h5.

Write a 5-by-5 dataset of uint8 values to the root group of the file myfile.h5.

hdf5write('myfile.h5','/dataset1',uint8(magic(5)))

Write a 2-by-2 dataset of text entries into a subgroup in the file myfile2.h5.

dataset = {'north','south';'east','west'};
hdf5write('myfile2.h5','/group1/dataset1.1',dataset);

Write a dataset and attribute to an existing group in myfile2.h5.

dset = single(rand(10,10));
dset_details.Location = '/group1/dataset1.2';
dset_details.Name = 'Random';

attr = 'Some random data';
attr_details.Name = 'Description';
attr_details.AttachedTo = '/group1/dataset1.2/Random';
attr_details.AttachType = 'dataset';

hdf5write('myfile2.h5',dset_details,dset,...
           attr_details,attr,'WriteMode','append');

Write a dataset to the file myfile3.h5 using objects.

dset = hdf5.h5array(magic(5));
hdf5write('myfile3.h5','/g1/objects',dset);

More About

Data Type Mappings

The following table lists how hdf5write maps the data type from the workspace into an HDF5 file. If the data in the workspace that is being written to the file is a MATLAB data type, hdf5write uses the following rules when mapping MATLAB data into HDF5 data objects.

MATLAB Data Type	HDF5 Dataset or Attribute
Numeric	Corresponding HDF5 native data type. For example, if the workspace data type is uint8, the hdf5write function writes the data to the file as 8-bit integers. The size of the HDF5 dataspace is the same size as the MATLAB array.
Character vector or string scalar	Single, null-terminated string.
Cell array of character vectors or string array	Multiple, null-terminated strings, each the same length. Length is determined by the length of the longest string in the cell array. The size of the HDF5 dataspace is the same size as the cell array.
Cell array of numeric data	Numeric array, the same dimensions as the cell array. The elements of the array must all have the same size and type. The data type is determined by the first element in the cell array.
Structure array	HDF5 compound type. Individual fields in the structure employ the same data translation rules for individual data types. For example, a cell array of strings becomes a multiple, null-terminated strings.
HDF5 objects	If the data being written to the file is composed of HDF5 objects, hdf5write uses the same data type when writing to the file. For all HDF5 objects, except HDF5.h5enum objects, the dataspace has the same dimensions as the array of HDF5 objects passed to the function. For HDF5.h5enum objects, the size and dimensions of the dataset in the HDF5 file is the same as the object's Data field.

Version History

Introduced before R2006a