Skip to Main Content Skip to Search
Product Documentation

Exporting to Scientific Data Files

On this page…

Exporting to Common Data File Format (CDF) Files

Exporting to Network Common Data Form (NetCDF) Files

Exporting to Hierarchical Data Format (HDF5) Files

Exporting to Hierarchical Data Format (HDF4) Files

Exporting to Common Data File Format (CDF) Files

The Common Data Format (CDF) was created by the National Space Science Data Center (NSSDC) to provide a self-describing data storage and manipulation format that matches the structure of scientific data and applications (i.e., statistical and numerical methods, visualization, and management). For more information about this format, see the CDF Web site.

MATLAB provides two methods to export data from a CDF file:

Using the High-Level CDF Function to Export Data

To write data from the MATLAB workspace to a Common Data Format file use the cdfwrite function. Using this function, you can write variables and attributes to the file, specifying their names and associated values.

This example shows how to write date information to a CDF file. Note how the example uses the CDF epoch object constructor, cdfepoch, to convert a MATLAB serial date number into a CDF epoch.

cdfwrite('myfile',{'Time_val',cdfepoch(now)});

You can convert a cdfepoch object back into a MATLAB serial date number with the todatenum function. For more information, see Representing CDF Time Values.

Using the Low-level CDF Functions to Export Data

To export (write) data from a Common Data Format (CDF) file, you can use the MATLAB low-level CDF functions. The MATLAB functions correspond to dozens of routines in the CDF C API library. For a complete list of all the MATLAB low-level CDF functions, see cdflib.

This section does not attempt to describe all features of the CDF library or explain basic CDF programming concepts. To use the MATLAB CDF low-level functions effectively, you must be familiar with the CDF C interface. Documentation about CDF, version 3.3.0, is available at the CDF Web site.

The following example shows how to use low-level functions to write data to a CDF file.

  1. Create a new CDF file. For information about opening an existing CDF file, see Using the CDF Library Low-Level Functions to Import Data.

    cdfid = cdflib.create('my_file.cdf');

  2. Create some variables in the CDF file. 

    time_id = cdflib.createVar(cdfid,'Time','cdf_int4',1,[],true,[]);

lat_id = cdflib.createVar(cdfid,'Latitude','cdf_int2',1,181,true,true);

dimSizes = [20 10];
dimVarys = [true true];
image_id = cdflib.createVar(cdfid,'Image','cdf_int4',1,dimSizes,true,[true true]);

  3. Write data to the variables.

    % Write time data
cdflib.putVarRecordData(cdfid,time_id,0,int32(23));
cdflib.putVarRecordData(cdfid,time_id,1,int32(24));

% Write the latitude data
data = int16([-90:90]);
recspec = [0 1 1];
dimspec = { 0 181 1 };
cdflib.hyperPutVarData(cdfid,lat_id,recspec,dimspec,data);

% Write data for the image zVariable
recspec = [0 3 1];
dimspec = { [0 0], [20 10], [1 1] };
data = reshape(int32([0:599]), [20 10 3]);
cdflib.hyperPutVarData(cdfid,image_id,recspec,dimspec,data);

  4. Create a global attribute in the CDF file and write data to the attribute..

    titleAttrNum = cdflib.createAttr(cdfid,'TITLE','global_scope');

% Write the global attribute entries
cdflib.putAttrEntry(cdfid,titleAttrNum,0,'CDF_CHAR','cdf Title');
cdflib.putAttrEntry(cdfid,titleAttrNum,1,'CDF_CHAR','Author');

  5. Create attributes associated with variables in the CDF file and write data to the attribute.

    fieldAttrNum = cdflib.createAttr(cdfid,'FIELDNAM','variable_scope');
unitsAttrNum = cdflib.createAttr(cdfid,'UNITS','variable_scope');

% Write the time variable attributes
cdflib.putAttrEntry(cdfid,fieldAttrNum,time_id,'CDF_CHAR','Time of observation');
cdflib.putAttrEntry(cdfid,unitsAttrNum,time_id,'CDF_CHAR','Hours');

  6. Close the CDF file. 

    cdflib.close(cdfid);

Back to Top

Exporting to Network Common Data Form (NetCDF) Files

Network Common Data Form (NetCDF) is a set of software libraries and machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data. NetCDF is used by a wide range of engineering and scientific fields that want a standard way to store data so that it can be shared. For more information, read the NetCDF documentation available at the Unidata Web site.

MATLAB provides two methods to export data from the workspace into a NetCDF file:

Using the NetCDF High-Level Functions to Export Data

MATLAB includes several functions that you can use to export data from the file into the MATLAB workspace.

For details about how to use these functions, see their reference pages. These pages include examples. For information about importing (reading) data from a NetCDF file, see Using the MATLAB High-Level NetCDF Functions to Import Data. The following examples illustrate how to use these functions to perform several common scenarios:

Creating a New NetCDF File from an Existing File or Template.  This example describes how to create a new file based on an existing file (or template).

  1. Read the variable, dimension, and group definitions from the file using ncinfo. This information defines the file's schema.

    finfo = ncinfo('example.nc');

  2. Create a new NetCDF file that uses this schema, using ncwriteschema. 

    ncwriteschema('mynewfile.nc',finfo);

  3. View the existing file and the new file, using ncdisp. You can see how the new file contains the same set of dimensions, variables, and groups as the existing file.

      Note   A schema defines the structure of the file but does not contain any of the data that was in the original file.

    ncdisp('example.nc')
ncdisp('mynewfile.nc')

Converting Between NetCDF File Formats.  This example shows how to convert an existing file from one format to another.

  1. Create a new file containing one variable, using the nccreate function.

    nccreate('ex1.nc','myvar');

  2. Determine the format of the new file, using ncinfo.

    finfo = ncinfo('ex1.nc');
file_fmt = finfo.Format

file_fmt =

netcdf4_classic

  3. Change the value of the Format field in the finfo structure to another supported NetCDF format. You use the finfo structure to specify the new format. 

    finfo.Format = 'netcdf4';

  4. Create a new version of the file that uses the new format, using the ncwriteschema function.

    finfo = ncwriteschema('newfile.nc',finfo);
finfo = ncinfo('newfile.nc');
new_fmt = finfo.Format

file_fmt =

netcdf4

      Note   The new file contains the variable and dimension definitions of the original file, but does not contain the data. You must write the data to the file.

Merging Two NetCDF Files.  This example shows how to merge two NetCDF files.

  1. Create a file, define a variable in the file, and write data to the variable.

    nccreate('ex1.nc','myvar');
ncwrite('ex1.nc','myvar',55)
ncdisp('ex1.nc')

  2. Create a second file, with another variable, and write data to it.

    nccreate('ex2.nc','myvar2');
ncwrite('ex2.nc','myvar2',99)
ncdisp('ex2.nc')

  3. Get the schema of each of the newly created files, using ncinfo.

    finfo1 = ncinfo('ex1.nc')

finfo1 = 

      Filename: 'H:\file1.nc'
          Name: '/'
    Dimensions: []
     Variables: [1x1 struct]
    Attributes: []
        Groups: []
        Format: 'netcdf4_classic'

finfo2 = ncinfo('file2.nc')

finfo2 = 

      Filename: 'H:\file2.nc'
          Name: '/'
    Dimensions: []
     Variables: [1x1 struct]
    Attributes: []
        Groups: []
        Format: 'netcdf4_classic'

  4. Create a new NetCDF file that uses the schema of the first example file, using ncwriteschema.

    ncwriteschema('combined_file.nc',finfo1);

ncdisp('combined_file.nc')
Source:
           H:\combined_file.nc
Format:
           netcdf4_classic
Variables:
    myvar1
           Size:       1x1
           Dimensions: 
           Datatype:   double
           Attributes:
                       _FillValue = 9.97e+036

  5. Add the schema from the second example file to the newly created file, using ncwriteschema. When you view the contents, notice how the file now contains the variable defined in the first example file and the variable defined in the second file.

    ncwriteschema('combined_file.nc',finfo2);

ncdisp('combined_file.nc')
Source:
           H:\combined_file.nc
Format:
           netcdf4_classic
Variables:
    myvar1
           Size:       1x1
           Dimensions: 
           Datatype:   double
           Attributes:
                       _FillValue = 9.97e+036
    myvar2
           Size:       1x1
           Dimensions: 
           Datatype:   double
           Attributes:
                       _FillValue = 9.97e+036

Using the NetCDF Low-Level Functions to Export Data

MATLAB provides access to the routines in the NetCDF C library that you can use to read data from NetCDF files and write data to NetCDF files. MATLAB provides this access through a set of MATLAB functions that correspond to the functions in the NetCDF C library. MATLAB groups the functions into a package, called netcdf. To call one of the functions in the package, you must specify the package name. For a complete list of all the functions, see netcdf.

This section does not describe all features of the NetCDF library or explain basic NetCDF programming concepts. To use the MATLAB NetCDF functions effectively, you should be familiar with the information about NetCDF contained in the NetCDF C Interface Guide.

Exporting (Writing) Data to a NetCDF File.  To store data in a NetCDF file, you can use the MATLAB NetCDF functions to create a file, define dimensions in the file, create a variable in the file, and write data to the variable. Note that you must define dimensions in the file before you can create variables. To run the following example, you must have write permission in your current folder.

  1. Create a variable in the MATLAB workspace. This example creates a 50-element vector of numeric values named my_data. The vector is of class double.

    my_data = linspace(0,49,50);

  2. Create a NetCDF file (or open an existing file). The example uses the netcdf.create function to create a new file, named my_file.nc. The NOCLOBBER parameter is a NetCDF file access constant that indicates that you do not want to overwrite an existing file with the same name. See netcdf.create for more information about these file access constants.

    ncid = netcdf.create('my_file.nc','NOCLOBBER');

    When you create a NetCDF file, the file opens in define mode. You must be in define mode to define dimensions and variables.

  3. Define a dimension in the file, using the netcdf.defDim function. You must define dimensions in the file before you can define variables and write data to the file. When you define a dimension, you give it a name and a length. To create an unlimited dimension, i.e., a dimension that can grow, specify the constant NC_UNLIMITED in place of the dimension length.

    dimid = netcdf.defDim(ncid,'my_dim',50);

  4. Define a variable on the dimension, using the netcdf.defVar function. When you define a variable, you give it a name, data type, and a dimension ID.

    varid = netcdf.defVar(ncid,'my_var','NC_BYTE',dimid);

    You must use one of the NetCDF constants to specify the data type, listed in the following table.

    MATLAB ClassNetCDF Data Type
    int8NC_BYTE[a]
    uint8NC_BYTE[b]
    charNC_CHAR
    int16NC_SHORT
    uint16No equivalent
    int32NC_INT
    uint32No equivalent
    int64No equivalent
    uint64No equivalent
    singleNC_FLOAT
    doubleNC_DOUBLE

    [a] NetCDF interprets byte data as either signed or unsigned.

    [b] NetCDF interprets byte data as either signed or unsigned.

  5. Take the NetCDF file out of define mode. To write data to a file, you must be in data mode.

    netcdf.endDef(ncid);

  6. Write the data from the MATLAB workspace into the variable in the NetCDF file, using the netcdf.putVar function. Note that the data in the workspace is of class double but the variable in the NetCDF file is of type NC_BYTE. The MATLAB NetCDF functions automatically do the conversion.

    netcdf.putVar(ncid,varid,my_data);

  7. Close the file, using the netcdf.close function.

    netcdf.close(ncid);

  8. Verify that the data was written to the file by opening the file and reading the data from the variable into a new variable in the MATLAB workspace. Because the variable is the first variable in the file (and the only one), you can specify 0 (zero) for the variable ID—identifiers are zero-based indexes.

    ncid2 = netcdf.open('my_file.nc','NC_NOWRITE');

data_in_file = netcdf.getVar(ncid2,0)

data_in_file =

    0
    1
    2
    3
    4
    5
    6
    7
    8
    9
    .
    .
    .

    Because you stored the data in the file as NC_BYTE, MATLAB reads the data from the variable into the workspace as class int8.

Back to Top

Exporting to Hierarchical Data Format (HDF5) Files

Hierarchical Data Format, Version 5, (HDF5) is a general-purpose, machine-independent standard for storing scientific data in files, developed by the National Center for Supercomputing Applications (NCSA). HDF5 is used by a wide range of engineering and scientific fields that want a standard way to store data so that it can be shared. For more information about the HDF5 file format, read the HDF5 documentation available at the HDF Web site (http://www.hdfgroup.org).

MATLAB provides two methods to export data to an HDF5 file:

Using the MATLAB High-Level HDF5 Functions to Export Data

The easiest way to write data or metadata from the MATLAB workspace to an HDF5 file is to use these MATLAB high-level functions.

For details about how to use these functions, see their reference pages, which include examples. The following sections illustrate some common usage scenarios.

Writing a Numeric Array to an HDF5 Dataset.  This example creates an array and then writes the array to an HDF5 file.

  1. Create a MATLAB variable in the workspace. This example creates a 5-by-5 array of uint8 values.

    testdata = uint8(magic(5))

  2. Create the HDF5 file and the dataset, using h5create.

    h5create('my_example_file.h5', '/dataset1', size(testdata))

  3. Write the data to the HDF5 file.

    h5write('my_example_file.h5', '/dataset1', testdata)

Using the MATLAB Low-Level HDF5 Functions to Export Data

MATLAB provides direct access to dozens of functions in the HDF5 library with low-level functions that correspond to the functions in the HDF5 library. In this way, you can access the features of the HDF5 library from MATLAB, such as reading and writing complex data types and using the HDF5 subsetting capabilities. For more information, see Using the MATLAB Low-Level HDF5 Functions to Export Data.

The HDF5 library organizes the library functions into collections, called interfaces. For example, all the routines related to working with files, such as opening and closing, are in the H5F interface, where F stands for file. MATLAB organizes the low-level HDF5 functions into classes that correspond to each HDF5 interface. For example, the MATLAB functions that correspond to the HDF5 file interface (H5F) are in the @H5F class folder. For a complete list of the HDF5 interfaces and the corresponding MATLAB class folders, see hdf5.

The following sections provide more detail about how to use the MATLAB HDF5 low-level functions.

Mapping HDF5 Function Syntax to MATLAB Function Syntax.  In most cases, the syntax of the MATLAB low-level HDF5 functions matches the syntax of the corresponding HDF5 library functions. For example, the following is the function signature of the H5Fopen function in the HDF5 library. In the HDF5 function signatures, hid_t and herr_t are HDF5 types that return numeric values that represent object identifiers or error status values.

hid_t H5Fopen(const char *name, unsigned flags, hid_t access_id) /* C syntax */

In MATLAB, each function in an HDF5 interface is a method of a MATLAB class. To view the function signature for a function, specify the class folder name and then the function name, as in the following.

help @H5F/open

The following shows the signature of the corresponding MATLAB function. First note that, because it's a method of a class, you must use the dot notation to call the MATLAB function: H5F.open. This MATLAB function accepts the same three arguments as the HDF5 function: a text string for the name, an HDF5-defined constant for the flags argument, and an HDF5 property list ID. You use property lists to specify characteristics of many different HDF5 objects. In this case, it's a file access property list. Refer to the HDF5 documentation to see which constants can be used with a particular function and note that, in MATLAB, constants are passed as text strings.

file_id = H5F.open(name, flags, plist_id)

There are, however, some functions where the MATLAB function signature is different than the corresponding HDF5 library function. The following describes some general differences that you should keep in mind when using the MATLAB low-level HDF5 functions.

Mapping Between HDF5 Data Types and MATLAB Data Types.  When the HDF5 low-level functions read data from an HDF5 file or write data to an HDF5 file, the functions map HDF5 data types to MATLAB data types automatically.

For atomic data types, such as commonly used binary formats for numbers (integers and floating point) and characters (ASCII), the mapping is typically straightforward because MATLAB supports similar types. See the table Mapping Between HDF5 Atomic Data Types and MATLAB Data Types for a list of these mappings.

Mapping Between HDF5 Atomic Data Types and MATLAB Data Types

HDF5 Atomic Data TypeMATLAB Data Type
Bit-fieldArray of packed 8-bit integers
FloatMATLAB single and double types, provided that they occupy 64 bits or fewer
Integer types, signed and unsignedEquivalent MATLAB integer types, signed and unsigned
OpaqueArray of uint8 values
ReferenceArray of uint8 values
StringMATLAB character arrays

For composite data types, such as aggregations of one or more atomic data types into structures, multidimensional arrays, and variable-length data types (one-dimensional arrays), the mapping is sometimes ambiguous with reference to the HDF5 data type. In HDF5, a 5-by-5 data set containing a single uint8 value in each element is distinct from a 1-by-1 data set containing a 5-by-5 array of uint8 values. In the first case, the data set contains 25 observations of a single value. In the second case, the data set contains a single observation with 25 values. In MATLAB both of these data sets are represented by a 5-by-5 matrix.

If your data is a complex data set, you might need to create HDF5 data types directly to make sure you have the mapping you intend. See the table Mapping Between HDF5 Composite Data Types and MATLAB Data Types for a list of the default mappings. You can specify the data type when you write data to the file using the H5Dwrite function. See the HDF5 data type interface documentation for more information.

Mapping Between HDF5 Composite Data Types and MATLAB Data Types

HDF5 Composite Data TypeMATLAB Data Type
ArrayExtends the dimensionality of the data type which it contains. For example, an array of an array of integers in HDF5 would map onto a two dimensional array of integers in MATLAB.
CompoundMATLAB structure. Note: All structures representing HDF5 data in MATLAB are scalar.
EnumerationArray of integers which each have an associated name
Variable LengthMATLAB 1-D cell arrays

Reporting Data Set Dimensions.  The MATLAB low-level HDF5 functions report data set dimensions and the shape of data sets differently than the MATLAB high-level functions. For ease of use, the MATLAB high-level functions report data set dimensions consistent with MATLAB column-major indexing. To be consistent with the HDF5 library, and to support the possibility of nested data sets and complicated data types, the MATLAB low-level functions report array dimensions using the C row-major orientation.

Writing Data to an HDF5 Data Set Using the MATLAB Low-Level Functions.  This example shows how to use the MATLAB HDF5 low-level functions to write a data set to an HDF5 file and then read the data set from the file.

  1. Create the MATLAB variable that you want to write to the HDF5 file. The examples creates a two-dimensional array of uint8 data.

    testdata = [1 3 5; 2 4 6];

  2. Create the HDF5 file or open an existing file. The example creates a new HDF5 file, named my_file.h5, in the system temp folder.

    filename = fullfile(tempdir,'my_file.h5');

fileID = H5F.create(filename,'H5F_ACC_TRUNC','H5P_DEFAULT','H5P_DEFAULT');

    In HDF5, use the H5Fcreate function to create a file. The example uses the MATLAB equivalent, H5F.create. As arguments, specify the name you want to assign to the file, the type of access you want to the file ('H5F_ACC_TRUNC' in the example), and optional additional characteristics specified by a file creation property list and a file access property list. This example uses default values for these property lists ('H5P_DEFAULT'). In the example, note how the C constants are passed to the MATLAB functions as strings. The function returns an ID to the HDF5 file.

  3. Create the data set in the file to hold the MATLAB variable. In the HDF5 programming model, you must define the data type and dimensionality (data space) of the data set as separate entities.

    1. Specify the data type used by the data set. In HDF5, use the H5Tcopy function to create integer or floating-point data types. The example uses the corresponding MATLAB function, H5T.copy, to create a double data type because the MATLAB data is double. The function returns a data type ID.

      datatypeID = H5T.copy('H5T_NATIVE_DOUBLE');

    2. Specify the dimensions of the data set. In HDF5, use the H5Screate_simple routine to create a data space. The example uses the corresponding MATLAB function, H5S.create_simple, to specify the dimensions. The function returns a data space ID.

      Because HDF5 stores data in row-major order and the MATLAB array is organized in column-major order, you should reverse the ordering of the dimension extents before using H5Screate_simple to preserve the layout of the data. You can use fliplr for this purpose. For a list of other HDF5 functions that require dimension flipping, see Preserving the Correct Layout of Your Data.

      dims = size(testdata);
dataspaceID = H5S.create_simple(2, fliplr(dims), []);

      Other software programs that use row-major ordering (such as H5DUMP from the HDF Group) may report the size of the dataset to be 3-by-2 instead of 2-by-3.

    3. Create the data set. In HDF5, you use the H5Dcreate routine to create a data set. The example uses the corresponding MATLAB function, H5D.create, specifying the file ID, the name you want to assign to the data set, data type ID, the data space ID, and a data set creation property list ID as arguments. The example uses the defaults for the property lists. The function returns a data set ID.

      dsetname = 'my_dataset';  
datasetID = H5D.create(fileID,dsetname,datatypeID,dataspaceID,'H5P_DEFAULT');

        Note   To write a large data set, you must use the chunking capability of the HDF5 library. To do this, create a property list and use the H5P.set_chunk function to set the chunk size in the property list. In the following example, the dimensions of the data set are dims = [2^16 2^16] and the chunk size is 1024-by-1024. You then pass the property list as the last argument to the data set creation function, H5D.create, instead of using the H5P_DEFAULT value.

        plistID = H5P.create('H5P_DATASET_CREATE'); % create property list

chunk_size = min([1024 1024], dims); % define chunk size 
H5P.set_chunk(plistID, chunk_size); % set chunk size in property list

datasetID = H5D.create(fileID, dsetname, datatypeID, dataspaceID, plistID);

  4. Write the data to the data set. In HDF5, use the H5Dwrite routine to write data to a data set. The example uses the corresponding MATLAB function, H5D.write, specifying as arguments the data set ID, the memory data type ID, the memory space ID, the data space ID, the transfer property list ID and the name of the MATLAB variable to be written to the data set.

    You can use the memory data type to specify the data type used to represent the data in the file. The example uses the constant 'H5ML_DEFAULT' which lets the MATLAB function do an automatic mapping to HDF5 data types. The memory data space ID and the data set's data space ID specify to write subsets of the data set to the file. The example uses the constant 'H5S_ALL' to write all the data to the file and uses the default property list. 

    H5D.write(datasetID,'H5ML_DEFAULT','H5S_ALL','H5S_ALL', ...
          'H5P_DEFAULT', testdata);

    If you had not reversed the ordering of the dimension extents in step 3b above, you would have been required to permute the MATLAB array before using H5D.write, which could result in an enormous performance penalty.

  5. Close the data set, data space, data type, and file objects. If used inside a MATLAB function, these identifiers are closed automatically when they go out of scope.

    H5D.close(datasetID);
H5S.close(dataspaceID);
H5T.close(datatypeID);
H5F.close(fileID);

  6. To read the data set you wrote to the file, you must open the file. In HDF5, you use the H5Fopen routine to open an HDF5 file, specifying the name of the file, the access mode, and a property list as arguments. The example uses the corresponding MATLAB function, H5F.open, opening the file for read-only access.

    fileID = H5F.open(filename,'H5F_ACC_RDONLY','H5P_DEFAULT');

  7. After opening the file, you must open the data set. In HDF5, you use the H5Dopen function to open a data set. The example uses the corresponding MATLAB function, H5D.open, specifying as arguments the file ID and the name of the data set, defined earlier in the example.

    datasetID = H5D.open(fileID, dsetname);

  8. After opening the data set, you can read the data into the MATLAB workspace. In HDF5, you use the H5Dread function to read an HDF5 file. The example uses the corresponding MATLAB function, H5D.read, specifying as arguments the data set ID, the memory data type ID, the memory space ID, the data space ID, and the transfer property list ID.

    returned_data = H5D.read(datasetID,'H5ML_DEFAULT',...
                        'H5S_ALL','H5S_ALL','H5P_DEFAULT');

    You can compare the original MATLAB variable, testdata, with the variable just created, data, to see if they are the same.

Preserving the Correct Layout of Your Data.  When you use any of the following functions that deal with dataspaces, you should flip dimension extents to preserve the correct layout of the data, as illustrated in step 3b in Writing Data to an HDF5 Data Set Using the MATLAB Low-Level Functions.

Back to Top

Exporting to Hierarchical Data Format (HDF4) Files

Hierarchical Data Format (HDF4) is a general-purpose, machine-independent standard for storing scientific data in files, developed by the National Center for Supercomputing Applications (NCSA). For more information about these file formats, read the HDF documentation at the HDF Web site (www.hdfgroup.org).

HDF-EOS is an extension of HDF4 that was developed by the National Aeronautics and Space Administration (NASA) for storage of data returned from the Earth Observing System (EOS). For more information about this extension to HDF4, see the HDF-EOS documentation at the NASA Web site (www.hdfeos.org).

This section describes how to use MATLAB functions to access the HDF4 Application Programming Interfaces (APIs). These APIs are libraries of C routines. To import or export data, you must use the functions in the HDF4 API associated with the particular HDF4 data type you are working with. Each API has a particular programming model, that is, a prescribed way to use the routines to write data sets to the file. To illustrate this concept, this section describes the programming model of one particular HDF4 API: the HDF4 Scientific Data (SD) API. For a complete list of the HDF4 APIs supported by MATLAB and the functions you use to access each one, see the hdf reference page.

Mapping HDF4 to MATLAB Syntax

Each HDF4 API includes many individual routines that you use to read data from files, write data to files, and perform other related functions. For example, the HDF4 Scientific Data (SD) API includes separate C routines to open (SDopen), close (SDend), and read data (SDreaddata).

Instead of supporting each routine in the HDF4 APIs, MATLAB provides a single function that serves as a gateway to all the routines in a particular HDF4 API. For example, the HDF Scientific Data (SD) API includes the C routine SDend to close an HDF4 file:

status = SDend(sd_id); /* C code */

To call this routine from MATLAB, use the MATLAB function associated with the SD API, hdfsd. You must specify the name of the routine, minus the API acronym, as the first argument and pass any other required arguments to the routine in the order they are expected. For example,

status = hdfsd('end',sd_id); % MATLAB code

Some HDF4 API routines use output arguments to return data. Because MATLAB does not support output arguments, you must specify these arguments as return values.

For example, the SDfileinfo routine returns data about an HDF4 file in two output arguments, ndatasets and nglobal_atts. Here is the C code:

status = SDfileinfo(sd_id, ndatasets, nglobal_atts);

To call this routine from MATLAB, change the output arguments into return values:

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

Specify the return values in the same order as they appear as output arguments. The function status return value is always specified as the last return value.

Step 1: Creating an HDF4 File

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

For example, this code creates an HDF4 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 HDF4 SD multifile interface, returning an HDF4 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 HDF4 file, you must use HDF4 read or write modes. For information about using SDstart in these modes, see Step 1: Opening the HDF4 File.

Step 2: Creating an HDF4 Data Set

After creating the HDF4 file, or opening an existing one, you must create a data set in the file for each MATLAB array you want to export. If you are writing data to an existing data set, you can skip ahead to the next step.

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

Once you create a data set, you cannot change its name, data type, or dimensions.

For example, to create a data set in which you can write 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 call hdfsd, specifying as arguments 'create' and a valid HDF file identifier, sd_id. In addition, set the values of the other 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 HDF4 SD data set identifier, (sds_id). Otherwise, SDcreate returns -1.

In this example, note the following:

Step 3: Writing MATLAB Data to an HDF4 File

After creating an HDF4 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 HDF4 SD API, you use the SDwritedata routine. In MATLAB, use the hdfsd function, specifying as arguments:

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

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 HDF4 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 HDF4 File

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

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

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

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

The SD interface supports predefined attributes that have reserved names and, in some cases, data types. Predefined attributes are identical to user-defined attributes except that the HDF4 SD API has already defined their names and data types. For example, the HDF4 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 HDF4 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 HDF4 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 HDF4 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.

You can associate multiple attributes with a single HDF4 object. HDF4 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 HDF4 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.

Step 5: Closing HDF4 Data Sets

After writing data to a data set in an HDF4 file, you must close access to the data set. In the HDF4 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 HDF4 SD data set identifier, sds_id in this example:

stat = hdfsd('endaccess',sds_id);

Step 6: Closing an HDF4 File

After writing data to a data set and closing the data set, you must also close the HDF4 file. In the HDF4 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 HDF4 SD file identifier, sd_id in this example:

stat = hdfsd('end',sd_id);

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

Using the MATLAB HDF4 Utility API

In addition to the standard HDF4 APIs, listed in the hdfreference page, MATLAB supports utility functions that are designed to make it easier to use HDF4 in the MATLAB environment.

For example, using the gateway function to the MATLAB HDF4 utility API, hdfml, and specifying the name of the listinfo routine as an argument, you can view all the currently open HDF4 identifiers. MATLAB updates this list whenever HDF identifiers are created or closed. In the following example only two identifiers are open. 

hdfml('listinfo')
No open RI identifiers
No open GR identifiers
No open grid identifiers
No open grid file identifiers
No open annotation identifiers
No open AN identifiers
Open scientific dataset identifiers:
	262144
Open scientific data file identifiers:
	393216
No open Vdata identifiers
No open Vgroup identifiers
No open Vfile identifiers
No open point identifiers
No open point file identifiers
No open swath identifiers
No open swath file identifiers
No open access identifiers
No open file identifiers

Closing All Open HDF4 Identifiers.  To close all the currently open HDF4 identifiers in a single call, use the gateway function to the MATLAB HDF4 utility API, hdfml, specifying the name of the closeall routine as an argument. The following example closes all the currently open HDF4 identifiers.

hdfml('closeall')

[a] NetCDF interprets byte data as either signed or unsigned.

[b] NetCDF interprets byte data as either signed or unsigned.

Back to Top

  

Exporting to Excel SpreadsheetsExporting to Excel Spreadsheets Exporting to ImagesExporting to Images

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit

 © 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS