MATLAB Function Reference

hdf5write

Write a Hierarchical Data Format (HDF) Version 5 file

Syntax

• hdf5write(filename,location,dataset)
  hdf5write(filename,details,dataset)
  hdf5write(filename,details1,dataset1,details2,dataset2,...)
  hdf5write(filename,...,'WriteMode',mode,...)
  

Description

hdf5write(filename,location,dataset) writes the data dataset to the HDF5 file named filename. If filename does not exist, hdf5write creates it. If filename exists, hdf5write overwrites the existing file, by default, but you can also append data to an existing file using an optional syntax.

location defines where to write the data set in the file. HDF5 files are organized in a hierarchical structure similar to a UNIX directory structure. location is a string that resembles a UNIX path.

hdf5write maps the data in dataset to HDF5 data types according to rules outlined below.

hdf5write(filename,details,dataset) writes dataset to filename using the values in the details structure. For a data set, the details structure can contain the following fields.

Field Name	Description	Data Type
Location	Location of the data set in the file	Character array
Name	Name to attach to the data set	String

hdf5write(filename,details,attribute) writes the metadata attribute to filename using the values in the details structure. For an attribute, the details structure can contain following fields.

Field Name	Description	Data Type
AttachedTo	Location of the object this attribute modifies	Structure array
AttachType	String that identifies what kind of object this attribute modifies; possible values are 'group' and 'dataset'	String
Name	Name to attach to the data set	Character array

hdf5write(filename, details1, dataset1, details2, dataset2,...) writes multiple data sets and associated attributes to filename in one operation. Each data set and attribute must have an associated details structure.

hdf5write(filename,...,'WriteMode',mode,...) specifies whether hdf5write overwrites the existing file (the default) or appends data sets and attributes to the file. Possible values for mode are 'overwrite' and 'append'.

Data Type Mappings

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 HDF5.h5enum objects, the size and dimensions of the data set in the HDF5 file, called the dataspace in HDF5 terminology, is the same as the object's Data field.

Field Name	Description	Data Type
AttachedTo	Location of the object this attribute modifies	Structure array
AttachType	String that identifies what kind of object this attribute modifies. Possible values are 'group' and 'dataset'	String
Name	Name to attach to the data set	Character array

If the data in the workspace that is being written to the file is a MATLAB data type, hdf5write uses the following rules when translating MATLAB data into HDF5 data objects.

MATLAB Data Type	HDF5 Data Set 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.
String	Single, null-terminated string
Cell array of strings	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 have 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.

Examples

Write a 5-by-5 data set of uint8 values to the root group.

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

Write a 2-by-2 string data set in a subgroup.

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

Write a data set and attribute to an existing group.

• dset = single(rand(10,10));
  dset_details.Location = '/group1/dataset1.2';
  dset_details.Name = 'Random';
  
  attr = 'Some random data';
  attr_details.AttachedTo = '/group1/dataset1.2';
  attr_details.AttachType = 'dataset';
  
  hdf5write('myfile2.h5', dset_details, dset, ...
             attr_details, attr, 'WriteMode', 'append');
  

Write a data set using objects.

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

See Also

hdf5, hdf5read, hdf5info

hdf5read

hdfinfo

© 1994-2005 The MathWorks, Inc.