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".

Output Arguments

• attrID — Identifier of created attribute.

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

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

 Details

Input Arguments

• locID — Identifier of the object to which the attributes are attached. The object can be a group, dataset, or named datatype.

• idx — Attribute index at which iteration begins.

• fnc — Callback function handle with this signature: f_status = fnc(f_locID,attName).

  Input Arguments for fnc

  • f_locID — Populated by locID input argument.

  • attName — Name of current attribute.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All attributes were processed.

  • positive — Short-circuit success. The value is the index value of the last attribute that was processed.

  • negative — Failure.

[status,idxStop,cdataOut] = H5A.iterate(objID,idxType,order,idxStart,fnc,cdataIn) executes the specified function fnc for each attribute of the group, dataset, or named datatype specified by objID. This interface corresponds to the H5Aiterate2 function in the HDF5 C library.

 Details

Input Arguments

• objID — Identifier of the object to which the attributes are attached. The object can be a group, dataset, or named datatype.

• idxType — Type of index, specified as one of these values or their numeric equivalents:

  • "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 or their numeric equivalents:

  • "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 — Attribute index at which iteration begins.

• fnc — Callback function handle with this signature: [f_status,f_cdataOut] = fnc(locID,attName,info,f_cdataIn).

  Input Arguments for fnc

  • locID — Populated by objID input argument.

  • attName — Name of current attribute.

  • info — Information structure of attribute.

  • f_cdataIn — Initially populated by cdataIn input argument; thereafter populated by f_cdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_cdataOut — Value that populates the f_cdataIn input argument of fnc for the next iteration step. The final f_cdataOut at the end of the iteration populates the cdataOut output argument.

• cdataIn — User-defined value or structure that populates the f_cdataIn input argument of fnc in the first step of the iteration.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All attributes were processed.

  • positive — Short-circuit success. The value is the index value of the last attribute that was processed.

  • negative — Failure.

• idxStop — Attribute index of the last attribute processed. This value can be used to resume an interrupted iteration.

• cdataOut — Populated by the final f_cdataOut output argument of fnc at the end of the iteration.

Note

The index type passed in idxtype is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

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".

Output Arguments

• attrID — Identifier of opened attribute.

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".

Output Arguments

• attrID — Identifier of opened attribute.

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".

Output Arguments

• attrID — Identifier of opened attribute.

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 writable 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.

attrID = H5A.open(gid,"attr1");
data = H5A.read(attrID);
H5A.close(attrID);

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");
typeID = H5T.copy("H5T_NATIVE_DOUBLE");
spaceID = H5S.create("H5S_SCALAR");

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

attrID = H5A.create(fid,"my_attr",typeID,spaceID,acpl);
H5A.write(attrID,"H5ML_DEFAULT",10.0)
H5A.close(attrID);
H5S.close(spaceID);
H5T.close(typeID);
H5F.close(fid);

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");
dsID = H5D.open(fid,"/g1/g1.1/dset1.1.1");
info = H5O.get_info(dsID);

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

for idx = 0:info.num_attrs-1
    attrID = H5A.open_by_idx(gid,"dset1.1.1","H5_INDEX_NAME","H5_ITER_DEC",idx);
    fprintf("attribute name:  %s\n",H5A.get_name(attrID));
    H5A.close(attrID);
end

attribute name:  attr2
attribute name:  attr1

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

Version History

Introduced before R2006a