Development Environment

Exporting MATLAB Data in an HDF File

To export data from MATLAB in an HDF file, you must use the functions in the HDF API associated with the HDF data type. Each API has a particular programming model, that is, a prescribed way to use the routines to open the HDF file, access data sets in the file, and write data to the data sets. (In HDF terminology, the numeric arrays stored in HDF files are called data sets.)

To illustrate this concept, this section details the programming model of one particular HDF API: the Scientific Data (SD) API. For information about working with other HDF APIs, see the official NCSA documentation.

The HDF SD Export Programming Model

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

1. Create the HDF file, or open an existing one.
2. Create a data set in the file, or select an existing one.
3. Write data to the data set.
4. Close access to the data set and the HDF file.

You can optionally include information in the HDF file that describes your data. See Including Metadata in an HDF File for more information.

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');

If it can create (or open) the file, SDstart returns an HDF SD file identifier, named sd_id in the example. Otherwise, it returns -1.

When you specify the DFACC_CREATE access mode, SDstart creates the file and initializes the HDF SD multifile interface. 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 Opening HDF Files.

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. In the HDF SD API, you use the SDcreate routine to create data sets. In MATLAB, you use the hdfsd function, specifying create as the first argument. To write data to an existing data set, you must obtain the HDF SD data set identifier. See Selecting Data Sets in HDF Files for more information.

This table lists the other arguments to SDcreate.

Argument	MATLAB Data Type
Valid HDF SD file identifier	Returned from SDstart
Name you want assigned to the data set	Text string
Data type of the data set	Text string. For information about specifying data types, see Importing HDF Data into the MATLAB Workspace
Number of dimensions in the data set. This is called the rank of the data set in HDF terminology	Scalar numeric value
Size of each dimension	Vector

The values you assign to these arguments depend on the MATLAB array you want to export. For example, to export this 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 Writing MATLAB Data to an HDF File.

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 writedata as the first argument.

This table lists the other arguments to SDwritedata.

Argument	MATLAB Data Type
Valid 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	Vector of index values
Number of elements along each dimension to skip between each write operation, called the stride vector in HDF terminology	Vector of scalar values
Total number of elements to write along each dimension, called the edges vector in HDF terminology	Vector of scalar values
MATLAB array to be written	Array of doubles

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, this 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 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, this 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);

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);

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.

Importing HDF Data into the MATLAB Workspace

Including Metadata in an HDF File