Importing and Exporting Data (Development Environment)

Development Environment

Using the HDF Command-Line Interface

To import HDF data into MATLAB, you can use the routines in the HDF API associated with the particular 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 read data from the data sets.

To illustrate this concept, this section describes the programming model of one particular HDF API: the Scientific Data (SD) API. To view a complete list of the HDF APIs supported by MATLAB, see HDF APIs Supported by MATLAB. For information about working with other HDF APIs, see the official NCSA documentation.

Note The following sections, when referring to specific routines in the HDF SD API, use the C library name rather than the MATLAB function name. The MATLAB syntax is used in all examples.

The HDF SD Import Programming Model

To import data in HDF SD format, you must use API routines to perform these steps:

There are several additional steps that you might also need to perform, such as retrieving information about the contents of the HDF file or the data sets in the file. The following sections provide more detail about the basic steps as well as optional steps.

Opening HDF Files

To import an HDF SD data set, you must first open the file containing the data set. In the HDF SD API, you use the SDstart routine to open the file and initialize the HDF interface. In MATLAB, you use the hdfsd function with start specified as the first argument.

SDstart accepts these arguments:

A text string specifying the name of the file you want to open
A text string specifying the mode in which you want to open it

For example, this code opens the file mydata.hdf for read access:

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

If SDstart can find and open the file specified, it returns an HDF SD file identifier, named sd_id in the example. Otherwise, it returns -1.

The HDF SD API supports several file access modes. You use a symbolic constant, defined by the HDF SD API, to specify each mode. In MATLAB, you specify these constants as text strings. You can specify the full HDF constant or one of the abbreviated forms listed in the table.

HDF File Creation Mode
HDF Symbolic Constant
MATLAB String

Create a new file
Read access
'DFACC_CREATE'
'DFACC_RDONLY'
'create'
'read'or'rdonly'

Read and write access
'DFACC_RDWR'
'rdwr'or'write'

HDF File Creation Mode	HDF Symbolic Constant	MATLAB String
Create a new file Read access	`'DFACC_CREATE'` `'DFACC_RDONLY'`	`'create`' '`read`'`or`'`rdonly`'
Read and write access	`'DFACC_RDWR'`	'`rdwr`'`or`'write'

Retrieving Information About an HDF File

After opening a file, you can get information about what the file contains using the SDfileinfo routine. In MATLAB, you use the hdfsd function with fileinfo specified as the first argument. This function returns the number of data sets in the file and whether the file includes any global attributes. (For more information about global attributes, see Retrieving Attributes from an HDF File.)

As an argument, SDfileinfo accepts the SD file identifier, sd_id, returned by SDstart. In this example, the HDF file contains three data sets and one global attribute.

[ndatasets, nglobal_atts, stat] = hdfsd('fileinfo',sd_id)

ndatasets =
    3

nglobal_atts =
    1

status =
    0

Retrieving Attributes from an HDF File

HDF files are self-documenting; that is, they can optionally include information, called attributes, that describes the data the file contains. Attributes associated with an HDF file are called global attributes. (You can also associate attributes with data sets or dimensions. For more information about these attributes, see Including Metadata in an HDF File.)

In the HDF SD API, you use the SDreadattr routine to retrieve global attributes from an HDF file. In MATLAB, you use the hdfsd function, specifying readattr as the first argument. As other arguments, you specify

The HDF SD file identifier (sd_id) returned by the SDstart routine.
The index value specifying the attribute you want to view. HDF uses zero-based indexing, so the first global attribute has index value 0, the second has index value 1, and so on.

For example, this code returns the contents of the first global attribute, which is simply the character string my global attribute.

attr_idx = 0;
[attr, status] = hdfsd('readattr', sd_id, attr_idx) 

attr =
    my global attribute

stat =
    0

MATLAB automatically sizes the return value, attr, to fit the data in the attribute.

Retrieving Attributes by Name. Attributes have names as well as values. If you know the name of an attribute, you can use the SDfindattr function to determine its index value so you can retrieve it. In MATLAB, you use the hdfsd function, specifying findattr as the first argument.

As other arguments, you specify

The HDF SD file identifier, when searching for global attributes
A text string specifying the name of the attribute

SDfindattr searches all the global attributes associated with the file. If it finds an attribute with this name, SDfindattr returns the index of the attribute. You can then use this index value to retrieve the attribute using SDreadattr.

This example uses SDfindattr to obtain the index for the attribute named my_att and then passes this index as an argument to SDreadattr:

attr_idx = hdfsd('findattr',sd_id,'my_att');
[attr, status] = hdfsd('readattr', sd_id, attr_idx);

Selecting Data Sets in HDF Files

After opening an HDF file, you must specify the data set in the file that you want to read. An HDF file can contain multiple data sets. In the HDF SD API, you use the SDselect routine to select a data set. In MATLAB, you use the hdfsd function, specifying select as the first argument.

As arguments, this function accepts

The HDF SD file identifier (sd_id) returned by SDstart.
The index value specifying the attribute you want to view. HDF uses zero-based indexing, so the first global attribute has index value 0, the second has index value 1, and so on.

For example, this code selects the third data set in the HDF file identified by sd_id. If SDselect finds the specified data set in the file, it returns an HDF SD data set identifier, called sds_id in the example. If it cannot find the data set, it returns -1.

Note Do not confuse HDF SD file identifiers, named sd_id in the examples, with HDF SD data set identifiers, named sds_id in the examples.

sds_idx = 2; % HDF uses zero-based indexing. 
sds_id = hdfsd('select',sd_id,sds_idx)

Retrieving Data Sets by Name

Data sets in HDF files can be named. If you know the name of the data set you are interested in, but not its index value, you can determine its index by using the SDnametoindex routine. In MATLAB, use the hdfsd function, specifying nametoindex as the first argument.

Getting Information About a Data Set

After you select a data set in an HDF file, you can obtain information about the data set, such as the number and size of the array dimensions. You need this information to read the data set using the SDreaddata function. (See Reading Data from an HDF File for more information.)

In the HDF SD API, you use the SDgetinfo routine to gather this information. In MATLAB, use the hdfsd function, specifying getinfo as the first argument. In addition, you must specify the HDF SD data set identifier returned by SDselect (sds_id).

This table lists the information returned by SDgetinfo.

Data Set Information Returned
MATLAB Data Type

Name
Character array

Number of dimensions
Scalar

Size of each dimension
Vector

Data type of the data stored in the array
Character array

Number of attributes associated with the data set
Scalar

Data Set Information Returned	MATLAB Data Type
Name	Character array
Number of dimensions	Scalar
Size of each dimension	Vector
Data type of the data stored in the array	Character array
Number of attributes associated with the data set	Scalar

For example, this code retrieves information about the data set identified by sds_id:

[dsname, dsndims, dsdims, dstype, dsatts, stat] =
              hdfsd('getinfo',sds_id)
dsname =
      A

dsndims =
      2

dsdims =
      5     3

dstype =
      double

dsatts =
      0

stat =
      0

Retrieving Data Set Attributes

Like HDF files, HDF SD data sets are self-documenting; that is, they can optionally include information, called attributes, that describes the data in the data set. Attributes associated with a data set are called local attributes. (You can also associate attributes with files or dimensions. For more information about these attributes, see Including Metadata in an HDF File.)

In the HDF SD API, you use the SDreadattr routine to retrieve local attributes. In MATLAB, use the hdfsd function, specifying readattr as the first argument. As other arguments, specify

The HDF SD data set identifier (sds_id) returned by SDselect.
The index of the attribute you want to view. HDF uses zero-based indexing, so the first global attribute has index value 0, the second has index value 1, and so on.

This code example returns the contents of the first attribute associated with a data set identified by sds_id. In this case, the value of the attribute is the character string 'my local attribute'. MATLAB automatically sizes the return value, ds_attr, to fit the value of the attribute:

attr_idx = 0;
[ds_attr, status] = hdfsd('readattr', sds_id, attr_idx) 

ds_attr =
    my local attribute

stat =
    0

Reading Data from an HDF File

After you open an HDF file and select a data set in the file, you can read the entire data set, or part of the data set. In the HDF SD API, you use the SDreaddata routine to read a data set. In MATLAB, use the hdfsd function, specifying readdata as the first argument. As other arguments, specify

The HDF SD data set identifier (sds_id) returned by SDselect
The location in the data set where you want to start reading data, specified as a vector of index values, called the start vector in HDF terminology
The number of elements along each dimension to skip between each read operation, specified as a vector of scalar values, called the stride vector in HDF terminology
The total number of elements to read along each dimension, specified as a vector of scalar values, called the edges vector in HDF terminology

For example, to read the entire contents of a data set containing this 3-by-5 matrix of numeric values,

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

you could use this code:

[ds_name, ds_ndims, ds_dims, ds_type, ds_atts, stat] =
                              hdfsd('getinfo',sds_id);

ds_start = zeros(1,ds_ndims); % Creates the vector [0 0]
ds_stride = []; 
ds_edges = ds_dims; 

[ds_data, status] =
           hdfsd('readdata',sds_id,ds_start,ds_stride,ds_edges)
;

disp(ds_data)
    1    2    3    4    5
    6    7    8    9    10
   11   12   13   14    15

In this example, note the following:

The return values of SDgetinfo are used to specify the dimensions of the return values and as arguments to SDreaddata.
To read from the beginning of a data set, specify zero for each element of the start vector (ds_start). Note how the example uses SDgetinfo to determine the length of the start vector.
To read every element of a data set, specify one for each element of the stride vector or specify an empty array ([]).
To read every element of a data set, set each element of the edges vector to the size of each dimension of the data set.

Note Use the dimensions vector returned by SDgetinfo, dsdims, to set the value of the edges vector, because SDgetinfo returns these values in row-major order, the ordering used by HDF. MATLAB stores data in column-major order. An array referred to as a 3-by-5 array in MATLAB is described as a 5-by-3 array in HDF.

Reading a Portion of a Data Set

To read less than the entire data set, use the start, stride, and edges vectors to specify where you want to start reading data and how much data you want to read.

For example, the following code fragment uses SDreaddata to read the entire second row of this sample data set:

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

Note that in the start, stride, and edges arguments, you must specify the dimensions in column-major order, that is, [columns,rows]. In addition, note that you must use zero-based indexing in these arguments:

ds_start = [0 1] % Start reading at the first column, second row
ds_stride = []; % Read each element
ds_edges = [5 1]; % Read a 1-by-5 vector of data 

[ds_data, status] =
           hdfsd('readdata',sds_id,ds_start,ds_stride,ds_edges)
;

disp(ds_data)
    6    7    8    9    10

For more information about specifying ranges in data sets, see Writing MATLAB Data to an HDF File.

Closing HDF Files and HDF Data Sets

After reading data from a data set in an HDF file, you must close access to the data set and the file. The HDF SD API includes functions to perform these tasks. See Closing HDF Data Sets for more information.

Using the MATLAB High-Level Import Function MATLAB HDF Function Calling Conventions