Dimension Scale (H5DS)

Dimension scale associated with dataset dimensions

Description

Use the MATLAB^® HDF5 dimension scale interface, H5DS, to access information about and manipulate HDF5 dimension scales.

An HDF5 dimension scale is an HDF5 dataset that is associated with the dimension of another dataset. A common case is a 2-dimensional array that has spatial information, such as latitude and longitude, associated with it.

Functions

H5DS.attach_scale

Attach dimension scale to specific dataset dimension

H5DS.attach_scale(dsID,dimscaleID,dim) attaches a dimension scale dimscaleID to the dimension dim of the dataset specified by dsID.

Note

The ordering of the dimension scale indices is the same as in the HDF5 library C API. For more information, see Report Data Set Dimensions.

H5DS.detach_scale

Detach dimension scale from specific dataset dimension

H5DS.detach_scale(dsID,dimscaleID,dim) detaches dimension scale dimscaleID from the dimension dim of the dataset specified by dsID.

Note

The ordering of the dimension scale indices is the same as in the HDF5 library C API. For more information, see Report Data Set Dimensions.

H5DS.get_label

Label from specific dataset dimension

label = H5DS.get_label(dsID,dim) returns the label for dimension dim of the dataset specified by dsID.

Note

The ordering of the dimension scale indices is the same as in the HDF5 library C API. For more information, see Report Data Set Dimensions.

H5DS.get_num_scales

Number of scales attached to dataset dimension

numscales = H5DS.get_num_scales(dsID,dim) determines the number of dimension scales that are attached to dimension dim of the dataset specified by dsID.

H5DS.get_scale_name

Name of dimension scale

dimscalename = H5DS.get_scale_name(dimscaleID) retrieves the name of the dimension scale dimscaleID.

H5DS.is_scale

Determine if dataset is a dimension scale

output = H5DS.is_scale(dsID) returns a positive value if the dataset specified by dsID is a dimension scale, and 0 if it is not.

H5DS.iterate_scales

Iterate on scales attached to dataset dimension

[status,idxOut,opdataOut] = H5DS.iterate_scales(dsID,dim,idxIn,fnc,opdataIn) iterates over the scales attached to dimension dim of the dataset specified by dsID to perform a common operation whose function handle is fnc.

 Details

Input Arguments

• dsID — Identifier of the dataset.

• dim — Dimension of the dataset dsID.

• idxIn — Index from which to start the iteration. If you specify idxIn as [], then the iterator starts the iteration at the first member.

• fnc — Callback function handle with this signature: [f_status,f_opdataOut] = fnc(f_dsID,f_dim,dimscaleID,f_opdataIn).

  Input Arguments for fnc

  • f_dsID — Populated by dsID input argument.

  • f_dim — Populated by dim input argument.

  • dimscaleID — Identifier of current dimension scale dataset.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut 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_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn 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 scales were processed.

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

  • negative — Failure.

• idxOut — Index at which iteration was stopped. This value can be used to resume an interrupted iteration.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

H5DS.set_label

Set label for dataset dimension

H5DS.set_label(dsID,dim,label) sets a label for dimension dim of the dataset specified by dsID.

Note

The ordering of the dimension scale indices is the same as in the HDF5 library C API. For more information, see Report Data Set Dimensions.

H5DS.set_scale

Convert dataset to dimension scale

H5DS.set_scale(dsID,dimname) converts the dataset specified by dsID to a dimension scale with name dimname.

Examples

Get Label from Specific Dataset Dimension

Open the file example.h5 and the dataset /g4/world.

fid = H5F.open("example.h5");
dsID = H5D.open(fid,"/g4/world");

Read the label of the dataset, and then close all identifiers.

label = H5DS.get_label(dsID,0);
H5D.close(dsID);
H5F.close(fid);

Set Label for Dimension of Dataset

Create a writable copy of the file example.h5.

plist = "H5P_DEFAULT";
srcFile = fullfile(matlabroot,"toolbox","matlab","demos","example.h5");
copyfile(srcFile,"myfile.h5");
fileattrib("myfile.h5","+w");
fid = H5F.open("myfile.h5","H5F_ACC_RDWR",plist);

Open the dataset /g4/world and set its labels for dimensions 0 and 1.

dsID = H5D.open(fid,"/g4/world",plist);
H5DS.set_label(dsID,0,"latitude");
H5DS.set_label(dsID,1,"longitude");

Close all identifiers.

H5D.close(dsID);
H5F.close(fid);

Version History

Introduced before R2006a