Attribute (H5A)

Metadata associated with datasets or groups

Description

Use the MATLAB^® HDF5 attribute interface, H5A, to create, read, and write dataset and group attributes, and access information about them.

An HDF5 attribute is a small metadata object that describes the nature and/or intended usage of a primary data object, which may be a dataset, group, or named datatype.

Functions

H5A.close

Close specified attribute

H5A.close(attrID) terminates access to the attribute specified by attrID, releasing the identifier.

H5A.create

Create attribute

attrID = H5A.create(locID,attname,typeID,spaceID,acplID) creates the attribute with name attname that is attached to the object specified by locID. This syntax corresponds to the H5Acreate in version 1.6 of the HDF5 C library.

attrID = H5A.create(locID,attname,typeID,spaceID,acplID,aaplID) creates an attribute with the additional attribute access property list identifier aaplID. This syntax corresponds to the H5Acreate in version 1.8 of the HDF5 C library.

 Details

Input Arguments

• locID — Group, dataset, or named datatype identifier.

• attname — Attribute name.

• typeID — Attribute datatype identifier, created using the H5T interface.

• spaceID — Attribute dataspace identifier, created using the H5S interface.

• acplID — Attribute property list identifier. This argument is currently unused and should be set to 'H5P_DEFAULT'.

• aaplID — Additional attribute access property list identifier. This value should currently be set to 'H5P_DEFAULT'.

H5A.delete

Delete attribute

H5A.delete(locID,attname) removes the attribute specified by attname from the dataset, group, or named datatype specified by locID.

H5A.get_info

Information about attribute

info = H5A.get_info(attrID) returns information about an attribute specified by attrID.

H5A.get_name

Attribute name

attname = H5A.get_name(attrID) returns the name of the attribute specified by attrID.

attname = H5A.get_name(attrID,'TextEncoding',encoding) specifies the text encoding to use to interpret the attribute name.

 Details

Input Arguments

• attrID — Attribute identifier.

• encoding — Text encoding, specified as one of these values:

  • 'system' — Interpret the attribute name using the system default encoding. This is the default value of encoding.

  • 'UTF-8' — Interpret the attribute name using UTF-8 encoding.

H5A.get_space

Copy of attribute dataspace

dspaceID = H5A.get_space(attrID) returns a copy of the dataspace for the attribute specified by attrID.

H5A.get_type

Copy of attribute datatype

typeID = H5A.get_type(attrID) returns a copy of the datatype for the attribute specified by attrID.

H5A.iterate

Execute function for attributes attached to object

H5A.iterate(locID,idx,fnc) executes the specified function for each attribute of the group, dataset, or named datatype specified by locID. This interface corresponds to H5Aiterate1 function in the HDF5 C library.

 Details

Input Arguments

• locID — Group, dataset, or named datatype identifier.

• idx — Index at which iteration begins.

• fnc — Callback function handle with this signature: status = fnc(locID,attname).

• attname — Current attribute.

Output Arguments

Output argument of the fnc function:

• status — Value returned by the callback function fnc and interpreted as one of these values:

  • zero — Continues with the iteration or returns zero status value to the caller if all members have been processed.

  • positive — Stops the iteration and returns the positive status value to the caller.

  • negative — Stops the iteration and throws an error indicating failure.

[status,idxStop,cdataOut] = H5A.iterate(objID,idxType,order,idxStart,fnc,cdataIn) executes the specified function fnc for each attribute connected to an object. This interface corresponds to H5Aiterate2 function in the HDF5 C library.

 Details

Input Arguments

• objID — Object to which attributes are attached.

• idxType — Type of index, specified as one of these values:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute name.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• order — Index traversal order, specified as one of these values:

  • 'H5_ITER_INC' — Iteration from beginning to end.

  • 'H5_ITER_DEC' — Iteration from end to beginning.

  • 'H5_ITER_NATIVE' — Iteration in the fastest available order.

• idxStart — Starting point of the iteration.

• fnc — Callback function with this signature: [status,cdataOut] = fnc(locID,attname,info,cdataIn).

• attname — Current attribute.

• info — Information structure of attribute.

• cdataIn — User-defined value or structure and is passed to the first step of the iteration in the fnc cdataIn parameter.

Output Arguments

• status — Value returned by the callback function fnc and interpreted as one of these values:

  • zero — Continues with the iteration or returns zero status value to the caller if all members have been processed.

  • positive — Stops the iteration and returns the positive status value to the caller.

  • negative — Stops the iteration and throws an error indicating failure.

• idxStop — Stopping point of the iteration. The H5A.iterate function returns the value of idxStop, which can be used to resume an interrupted iteration.

• cdataOut — Value that forms the cdataIn for the next iteration step. Then, the final cdataOut at the end of the iteration is returned to the caller as cdataOut.

H5A.open

Open attribute

attrID = H5A.open(objID,attname) opens an attribute for an object specified by a parent object identifier objID and attribute name attname.

attrID = H5A.open(objID,attname,aaplID) opens an attribute with an attribute access property list identifier aaplID.

 Details

Input Arguments

• objID — Parent object identifier.

• attname — Attribute name.

• aaplID — Attribute access property list identifier. The only currently valid value for aaplID is 'H5P_DEFAULT'.

H5A.open_by_idx

Open attribute specified by index

attrID = H5A.open_by_idx(locID,objname,idxType,order,n) opens an existing attribute at index n attached to an object specified by its location, locID, and name, objname.

attrID = H5A.open_by_idx(locID,objname,idxType,order,n,aaplID,laplID) opens an attribute with an attribute access property list identifier aaplID and link access property list identifier laplID.

 Details

Input Arguments

• locID — Group, dataset, or named datatype identifier.

• objname — Name of group, dataset, or named datatype.

• idxType — Type of index, specified as one of these values:

  • 'H5_INDEX_NAME' — Alpha-numeric index by attribute name.

  • 'H5_INDEX_CRT_ORDER' — Index by creation order.

• order — Index traversal order, specified as one of these values:

  • 'H5_ITER_INC' — Iteration from beginning to end.

  • 'H5_ITER_DEC' — Iteration from end to beginning.

  • 'H5_ITER_NATIVE' — Iteration in the fastest available order.

• n— Index at which to open the existing attribute.

• aaplID — Attribute access property list identifier. The aaplID argument must currently be specified as 'H5P_DEFAULT'.

• laplID — Link access property list identifier. laplID may be specified as 'H5P_DEFAULT'.

H5A.open_by_name

Open attribute specified by name

attrID = H5A.open_by_name(locID,objname,attname) opens an existing attribute attached to an object specified by its location locID and name objname.

attrID = H5A.open_by_name(locID,objname,attname,aaplID,laplID) opens an existing attribute with the attribute access property list identifier aaplID and link access property list identifier laplID.

 Details

Input Arguments

• locID — Group, dataset, or named datatype identifier.

• objname — Name of group, dataset, or named datatype.

• attname — Existing attribute name.

• aaplID — Attribute access property list identifier. The aaplID argument must be specified as 'H5P_DEFAULT'.

• laplID — Link access property list identifier. The laplID argument may be specified as 'H5P_DEFAULT'.

H5A.read

Read attribute

attr = H5A.read(attrID) reads the attribute specified by attrID. MATLAB will determine the appropriate memory datatype.

attr = H5A.read(attrID,memtypeID) reads the attribute specified by attrID.

 Details

Input Arguments

• attrID — Attribute identifier.

• memtypeID — Memory datatype of attribute, and should usually be given as 'H5ML_DEFAULT', which specifies that MATLAB will determine the appropriate memory datatype.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. For example, if the HDF5 library reports the attribute size as 3-by-4-by-5, then the corresponding MATLAB array size is 5-by-4-by-3. For more information see, Report Data Set Dimensions.

H5A.write

Write attribute

H5A.write(attrID,typeID,buf) writes the data in the buffer buf into the attribute specified by attrID using memory datatype typeID.

 Details

Input Arguments

• attrID — Attribute identifier.

• typeID — Memory datatype of the attribute. The memory datatype should be 'H5ML_DEFAULT', which specifies that MATLAB should determine the appropriate memory datatype.

• buf — Data buffer.

Note

The HDF5 library uses C-style ordering for multidimensional arrays, while MATLAB uses FORTRAN-style ordering. For example, if the MATLAB array size is 5-by-4-by-3, then the HDF5 library should be reporting the attribute size as 3-by-4-by-5. For more information see, Report Data Set Dimensions.

Examples

Read Attribute from HDF5 File and Delete It

Read an attribute from the root group of an HDF5 file into the MATLAB workspace, delete it, then close the file.

Create a writeable copy of the file 'example.h5' in the current directory, and open the new file and its root group.

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');
gid = H5G.open(fid,'/');

Open the attribute attr1, read it into the workspace, then close it.

attr_id = H5A.open(gid,'attr1');
data = H5A.read(attr_id);
H5A.close(attr_id);

Delete the attribute from the root group of the HDF5 file, then close the root group and file.

H5A.delete(gid,'attr1');
H5G.close(gid);
H5F.close(fid);

Create Attribute and Write Data Buffer to It

Create an attribute in an HDF5 file and write a data buffer to it.

Create an HDF5 file named myfile.h5.

fid = H5F.create('myfile.h5');

Create an attribute create property list identifier, a datatype identifier of type 'H5T_NATIVE_DOUBLE', and a data space identifier of type 'H5S_SCALAR'.

acpl = H5P.create('H5P_ATTRIBUTE_CREATE');
type_id = H5T.copy('H5T_NATIVE_DOUBLE');
space_id = H5S.create('H5S_SCALAR');

Create an attribute with identifier attr_id, and write a data buffer of 10.0 to it. Then, close the attribute and HDF5 file.

attr_id = H5A.create(fid,'my_attr',type_id,space_id,acpl);
H5A.write(attr_id,'H5ML_DEFAULT',10.0)
H5A.close(attr_id);
H5F.close(fid);
H5T.close(type_id);

Display Dataset Attribute Names

Open each attribute in a dataset and print their names.

Open the dataset dset1.1.1 in the file example.h5.

fid = H5F.open('example.h5');
gid = H5G.open(fid,'/g1/g1.1');
dset_id = H5D.open(fid,'/g1/g1.1/dset1.1.1');
info = H5O.get_info(dset_id);

Open each attribute, print its name, then close it.

for idx = 0:info.num_attrs-1

	attr_id =H5A.open_by_idx(gid,'dset1.1.1','H5_INDEX_NAME','H5_ITER_DEC',idx);
	fprintf('attribute name:  %s\n',H5A.get_name(attr_id));
	H5A.close(attr_id);
end

attribute name:  attr2
attribute name:  attr1

H5G.close(gid);
H5F.close(fid);