Example: Exporting Data to an HDF4 File :: Data Import and Export (Programming)

Programming

Example: Exporting Data to an HDF4 File

The programming model for exporting HDF SD data involves these steps:

Step 1: Creating an HDF File

To export MATLAB data in HDF format, you must first create an HDF file, or open an existing one. In the HDF SD API, you use the SDstart routine. In MATLAB, use the hdfsd function, specifying start as the first argument. As other arguments, specify

A text string specifying the name you want to assign to the HDF file (or the name of an existing HDF file)
A text string specifying the HDF SD interface file access mode

For example, this code creates an HDF file named mydata.hdf:

sd_id = hdfsd('start','mydata.hdf','DFACC_CREATE');

When you specify the DFACC_CREATE access mode, SDstart creates the file and initializes the HDF SD multifile interface, returning an HDF SD file identifier, named sd_id in the example.

If you specify DFACC_CREATE mode and the file already exists, SDstart fails, returning -1. To open an existing HDF file, you must use HDF read or write modes. For information about using SDstart in these modes, see Step 1: Opening the HDF4 File.

Step 2: Creating an HDF Data Set

After creating the HDF file, or opening an existing one, you must create a data set in the file for each MATLAB array you want to export.

Note To write data to an existing data set, you can skip this step.

In the HDF SD API, you use the SDcreate routine to create data sets. In MATLAB, you use the hdfsd function, specifying as arguments:

Name of the SD API routine, create in this case
Valid HDF SD file identifier, sd_id, returned by SDstart
Name you want assigned to the data set
Data type of the data set. For information about specifying data types, see Importing HDF4 and HDF-EOS Data.
Number of dimensions in the data set. This is called the rank of the data set in HDF terminology.
Size of each dimension, specified as a vector

The values you assign to these arguments depend on the MATLAB array you want to export. For example, to export the following MATLAB 3-by-5 array of doubles,

A = [ 1 2 3 4 5 ; 6 7 8 9 10 ; 11 12 13 14 15 ];

you could set the values of these arguments as in this code fragment:

ds_name = 'A'; 
ds_type = 'double';
ds_rank = ndims(A);
ds_dims = fliplr(size(A));

sds_id = hdfsd('create',sd_id,ds_name,ds_type,ds_rank,ds_dims);

If SDcreate can successfully create the data set, it returns an HDF SD data set identifier, (sds_id). Otherwise, SDcreate returns -1.

Note In this example, note how the code fragment reverses the order of the values in the dimensions argument (ds_dims). This processing is necessary because the MATLAB size function returns the dimensions in column-major order and HDF expects to receive dimensions in row-major order.

Once you create a data set, you cannot change its characteristics. You can, however, modify the data it contains. To do this, initiate access to the data set, using SDselect, and write to the data set as described in Step 3: Writing MATLAB Data to an HDF File.

Step 3: Writing MATLAB Data to an HDF File

After creating an HDF file and creating a data set in the file, you can write data to the entire data set or just a portion of the data set. In the HDF SD API, you use the SDwritedata routine. In MATLAB, use the hdfsd function, specifying specifying as arguments:

Name of the SD API routine, writedata in this case
Valid HDF SD data set identifier, sds_id, returned by SDcreate
Location in the data set where you want to start writing data, called the start vector in HDF terminology
Number of elements along each dimension to skip between each write operation, called the stride vector in HDF terminology
Total number of elements to write along each dimension, called the edges vector in HDF terminology
MATLAB array to be written

Note You must specify the values of the start, stride, and edges arguments in row-major order, rather than the column-major order used in MATLAB. Note how the example uses fliplr to reverse the order of the dimensions in the vector returned by the size function before assigning it as the value of the edges argument.

The values you assign to these arguments depend on the MATLAB array you want to export. For example, the following code fragment writes this MATLAB 3-by-5 array of doubles,

A = [ 1 2 3 4 5; 6 7 8 9 10; 11 12 13 14 15 ];

into an HDF file:

ds_start = zeros(1:ndims(A)); % Start at the beginning
ds_stride = [];               % Write every element. 
ds_edges = fliplr(size(A));   % Reverse the dimensions.

stat = hdfsd('writedata',sds_id,...
                         ds_start, ds_stride, ds_edges, A)

If it can write the data to the data set, SDwritedata returns 0; otherwise, it returns -1.

Note SDwritedata queues write operations. To ensure that these queued write operations are executed, you must close the file, using the SDend routine. See Step 6: Closing an HDF File for more information. As a convenience, MATLAB provides a function, MLcloseall, that you can use to close all open data sets and file identifiers with a single call. See Using the MATLAB HDF Utility API for more information.

Writing Data to Portions of Data Sets. To write less than the entire data set, use the start, stride, and edges vectors to specify where you want to start writing data and how much data you want to write.

For example, the following code fragment uses SDwritedata to replace the values of the entire second row of the sample data set:

```
1 2 3 4 5
6 7 8 9 10
11 12 13 14 15
```

with the vector B:

```
B = [ 9 9 9 9 9];
```

In the example, the start vector specifies that you want to start the write operation in the first column of the second row. Note how HDF uses zero-based indexing and specifies the column dimension first. In MATLAB, you would specify this location as (2,1). The edges argument specifies the dimensions of the data to be written. Note that the size of the array of data to be written must match the edge specification.

ds_start = [0 1]; % Start writing at the first column, second row.
ds_stride = []; % Write every element.
ds_edges = [5 1]; % Each row is a 1-by-5 vector. 

stat = hdfsd('writedata',sds_id,ds_start,ds_stride,ds_edges,B);

Step 4: Writing Metadata to an HDF File

You can optionally include information in an HDF file, called attributes, that describes the file and its contents. Using the HDF SD API, you can associate attributes with three types of HDF objects:

An entire HDF file -- File attributes, also called global attributes, generally contain information pertinent to all the data sets in the file.
A data set in an HDF file -- Data set attributes, also called local attributes, describe individual data sets.
A dimension of a data set -- Dimension attributes provide information about one particular dimension of a data set.

Associating Multiple Attributes with a Single Object. You can associate multiple attributes with a single HDF object. HDF maintains an attribute index for each object. The attribute index is zero-based. The first attribute has index value 0, the second has index value 1, and so on. You access an attribute by its index value.

Each attribute has the format name=value, where name (called label in HDF terminology) is a text string up to 256 characters in length and value contains one or more entries of the same data type. A single attribute can have multiple values.

Creating Attributes. To create an attribute in the HDF SD API, use the SDsetattr routine. In MATLAB, use the hdfsd function, specifying setattr as the first argument. As other arguments, specify

A valid HDF SD identifier associated with the object. This value can be a file identifier (sd_id), a data set identifier (sds_id), or a dimension identifier (dim_id).
A text string that defines the name of the attribute. The SD interface supports predefined attributes that have reserved names and, in some cases, data types. For information about these attributes, see Creating Predefined Attributes.
The attribute value.

For example, this code creates a global attribute, named my_global_attr, and associates it with the HDF file identified by sd_id:

status = hdfsd('setattr',sd_id,'my_global_attr','my_attr_val');

Note In the NCSA documentation, the SDsetattr routine has two additional arguments: data type and the number of values in the attribute. When calling this routine from MATLAB, you do not have to include these arguments. The MATLAB HDF function can determine the data type and size of the attribute from the value you specify.

Creating Predefined Attributes. Predefined attributes are identical to user-defined attributes except that the HDF SD API has already defined their names and data types. For example, the HDF SD API defines an attribute, named cordsys, in which you can specify the coordinate system used by the data set. Possible values of this attribute include the text strings 'cartesian', 'polar', and 'spherical'.

Predefined attributes can be useful because they establish conventions that applications can depend on. The HDF SD API supports predefined attributes for data sets and dimensions only; there are no predefined attributes for files. For a complete list of the predefined attributes, see the NCSA documentation.

In the HDF SD API, you create predefined attributes the same way you create user-defined attributes, using the SDsetattr routine. In MATLAB, use the hdfsd function, specifying setattr as the first argument:

attr_name = 'cordsys';
attr_value = 'polar';

status = hdfsd('setattr',sds_id,attr_name,attr_value);

The HDF SD API also includes specialized functions for writing and reading the predefined attributes. These specialized functions, such as SDsetdatastrs, are sometimes easier to use, especially when you are reading or writing multiple related predefined attributes. You must use specialized functions to read or write the predefined dimension attributes.

Step 5: Closing HDF Data Sets

After writing data to a data set in an HDF file, you must close access to the data set. In the HDF SD API, you use the SDendaccess routine to close a data set. In MATLAB, use the hdfsd function, specifying endaccess as the first argument. As the only other argument, specify a valid HDF SD data set identifier, sds_id in this example:

```
stat = hdfsd('endaccess',sds_id);
```

Step 6: Closing an HDF File

After writing data to a data set and closing the data set, you must also close the HDF file. In the HDF SD API, you use the SDend routine. In MATLAB, use the hdfsd function, specifying end as the first argument. As the only other argument, specify a valid HDF SD file identifier, sd_id in this example:

```
stat = hdfsd('end',sd_id);
```

You must close access to all the data sets in an HDF file before closing it.

Note Closing an HDF file executes all the write operations that have been queued using SDwritedata. As a convenience, the MATLAB HDF Utility API provides a function, MLcloseall, that can close all open data set and file identifiers with a single call. See Using the MATLAB HDF Utility API for more information.

Exporting MATLAB Data to an HDF4 File Using the MATLAB HDF Utility API