• LINKS
• What is HDF5?
• Downloads
• Documentation
• Software using HDF5
• HDF5 Users
• Sample HDF5 Files
• Acknowledgments
• Licenses

Contents:

• Reading from or Writing to a Subset of a Dataset
• Programming Example
  • Description
  • Remarks

Reading from or Writing to a Subset of a Dataset

HDF5 allows you to read from or write to a portion or subset of a dataset. This is done by selecting a subset of the dataspace of the dataset, and then using that selection to read from or write to the dataset. There are two types of selections in HDF5, hyperslab selections and element selections, specified with the H5Sselect_hyperslab / h5sselect_hyperslab_f and H5Sselect_elements /h5sselect_elements_f calls, respectively:

• The H5Sselect_hyperslab / h5sselect_hyperslab_f call selects a logically contiguous collection of points in a dataspace, or a regular pattern of points or blocks in a dataspace.

• The H5Sselect_elements /h5sselect_elements_f call selects elements in an array.

This tutorial topic shows how to write to a simple subset of data in a dataset and describes how to experiment with different shapes and sizes of subsets to write. It also includes an example of reading blocks of data from the dataset.

See the Advanced Tutorial topics for a more complex example and an example of using element selection.

Programming Example

Description

This example creates an 8 x 10 integer dataset in an HDF5 file. It then selects and writes to a 3 x 4 subset of the dataset created with Dimension 0 offset by 1 and Dimension 1 offset by 2. (In this discussion, Dimension 0 is vertical, and Dimension 1 is horizontal.) The following table shows the dataset that gets written originally, and the subset of data that gets modified afterwards.

  1 1 1 1 1 2 2 2 2 2   
  1 1 1 1 1 2 2 2 2 2
  1 1 1 1 1 2 2 2 2 2
  1 1 1 1 1 2 2 2 2 2
  1 1 1 1 1 2 2 2 2 2
  1 1 1 1 1 2 2 2 2 2
  1 1 1 1 1 2 2 2 2 2
  1 1 1 1 1 2 2 2 2 2

 1 1 1 1 1 2 2 2 2 2  
 1 1 5 5 5 5 2 2 2 2
 1 1 5 5 5 5 2 2 2 2
 1 1 5 5 5 5 2 2 2 2
 1 1 1 1 1 2 2 2 2 2
 1 1 1 1 1 2 2 2 2 2
 1 1 1 1 1 2 2 2 2 2
 1 1 1 1 1 2 2 2 2 2

To obtain the example, download:

[ C example ] - h5_hype.c
[ F90 example ] - h5_hypef.f90

For details on compiling an HDF5 application, click here.

The offset, count, stride and block parameters to H5Sselect_hyperslab / h5sselect_hyperslab_f define the shape and size of the selection. They must be arrays with the same number of dimensions as the rank of the dataset's dataspace. These arrays ALL work together to define a selection. A change to one of these arrays can affect the others.

Try changing the offset, count, and stride parameters in the example above to see what happens. For example, the following table shows how to select a 2 x 2 array (count of 2 for each dimension), in which every other element along Dimension 0 (stride of 2) is sampled:

2 x 2 Subset Written with  stride=2 for Dimension 0

1 1 1 1 1 2 2 2 2 2   1 1 5 5 1 2 2 2 2 2 1 1 1 1 1 2 2 2 2 2 1 1 5 5 1 2 2 2 2 2 1 1 1 1 1 2 2 2 2 2 1 1 1 1 1 2 2 2 2 2 1 1 1 1 1 2 2 2 2 2 1 1 1 1 1 2 2 2 2 2

The above example does not modify the block parameter. See the following example on modifying the block parameter. It shows how to read specific blocks back from the file and dataset that was created in the previous example program. Notice that in this example, the entire dataset's dataspace is selected for the memory dataspace in the H5Dread / h5dread_f call.

[ C example ] - h5_hypeb.c

For details on compiling an HDF5 application, click here.

Remarks

• In addition to H5Sselect_hyperslab / h5sselect_hyperslab_f, this example introduces the H5Dget_space / h5dget_space_f call to obtain the dataspace of a dataset.

• If using the default values for the stride and block parameters of H5Sselect_hyperslab / h5sselect_hyperslab_f, then, for C you can specify NULL for these parameters, rather than passing in an array for each, and for Fortran 90 you can omit these parameters.

---

- - Last modified:December 14th 2011