and <a href="https://support.hdfgroup.org/ftp/HDF5/examples/files/tutorial/SVM09_npp_d20120229_t0849107_e0854511_b01759_c20120229145452682127_noaa_ops.h5.gz">SVM09_npp.. (gzipped)</a>
\subsubsection subsubsecViewToolsViewContent_h5lsEx3 Example 3
The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset:
\code
h5ls -r OMI-Aura.he5
\endcode
The output is shown below:
\code
/ Group
/HDFEOS Group
/HDFEOS/ADDITIONAL Group
/HDFEOS/ADDITIONAL/FILE_ATTRIBUTES Group
/HDFEOS/GRIDS Group
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3 Group
/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group
<td>Displays any object or attribute that matches path P
</td>
<td>See @ref subsubsecViewToolsViewAttr_h5dumpEx6
</td>
</tr>
</table>
\subsubsection subsubsecViewToolsViewDset_h5dumpEx4 Example 4
A specific dataset can be viewed with <code style="background-color:whitesmoke;">h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire
path and name of the dataset for <code style="background-color:whitesmoke;">D</code>. The path is important in identifying the correct dataset,
as there can be multiple datasets with the same name. The path can be determined by looking at
the objects in the file with <code style="background-color:whitesmoke;">h5dump -n</code>.
The following example uses the <code style="background-color:whitesmoke;">groups.h5</code> file that is created by the
\ref LBExamples
example <code style="background-color:whitesmoke;">h5_crtgrpar.c</code>. To display <code style="background-color:whitesmoke;">dset1</code> in the <code style="background-color:whitesmoke;">groups.h5</code> file below, specify dataset
<code style="background-color:whitesmoke;">/MyGroup/dset1</code>. The <code style="background-color:whitesmoke;">-H</code> option is used to suppress printing of the data values:
<em>Contents of groups.h5</em>
\code
$ h5dump -n groups.h5
HDF5 "groups.h5" {
FILE_CONTENTS {
group /
group /MyGroup
group /MyGroup/Group_A
dataset /MyGroup/Group_A/dset2
group /MyGroup/Group_B
dataset /MyGroup/dset1
}
}
\endcode
<em>Display dataset "dset1"</em>
\code
$ h5dump -d "/MyGroup/dset1" -H groups.h5
HDF5 "groups.h5" {
DATASET "/MyGroup/dset1" {
DATATYPE H5T_STD_I32BE
DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) }
}
}
\endcode
\subsubsection subsubsecViewToolsViewDset_h5dumpEx5 Example 5
The <code style="background-color:whitesmoke;">-p</code> option is used to examine the dataset filters, storage layout, and fill value properties of a dataset.
This option can be useful for checking how well compression works, or even for analyzing performance
and dataset size issues related to chunking. (The smaller the chunk size, the more chunks that HDF5
has to keep track of, which increases the size of the file and potentially affects performance.)
In the file shown below the dataset <code style="background-color:whitesmoke;">/DS1</code> is both chunked and compressed:
\code
$ h5dump -H -p -d "/DS1" h5ex_d_gzip.h5
HDF5 "h5ex_d_gzip.h5" {
DATASET "/DS1" {
DATATYPE H5T_STD_I32LE
DATASPACE SIMPLE { ( 32, 64 ) / ( 32, 64 ) }
STORAGE_LAYOUT {
CHUNKED ( 4, 8 )
SIZE 5278 (1.552:1 COMPRESSION)
}
FILTERS {
COMPRESSION DEFLATE { LEVEL 9 }
}
FILLVALUE {
FILL_TIME H5D_FILL_TIME_IFSET
VALUE 0
}
ALLOCATION_TIME {
H5D_ALLOC_TIME_INCR
}
}
}
\endcode
You can obtain the <code style="background-color:whitesmoke;">h5ex_d_gzip.c</code> program that created this file, as well as the file created,
from the <a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page.
\subsection subsecViewToolsViewDset_h5ls h5ls
Specific datasets can be specified with <code style="background-color:whitesmoke;">h5ls</code> by simply adding the dataset path and dataset after the
file name. As an example, this command displays dataset <code style="background-color:whitesmoke;">dset2</code> in the <code style="background-color:whitesmoke;">groups.h5</code>
file used in @ref subsubsecViewToolsViewDset_h5dumpEx4 :
\code
h5ls groups.h5/MyGroup/Group_A/dset2
\endcode
Just the dataspace information gets displayed:
\code
dset2 Dataset {2, 10}
\endcode
The following options can be used to see detailed information about a dataset.
Both h5dump and h5ls can be used to view specific groups in a file.
<ul>
<li>\ref subsecViewToolsViewGrps_h5dump</li>
<li>\ref subsecViewToolsViewGrps_h5ls</li>
</ul>
\subsection subsecViewToolsViewGrps_h5dump h5dump
The <code style="background-color:whitesmoke;">h5dump</code> options that are useful for examining groups are:
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td>-g G, --group=G
</td>
<td>Displays group G and its members
</td>
</tr>
<tr>
<td>-H, --header
</td>
<td>Displays header information only
</td>
</tr>
<tr>
<td>-A 0, --onlyattr=0
</td>
<td>Suppresses the display of attributes
</td>
</tr>
</table>
To view the contents of the <code style="background-color:whitesmoke;">HDFEOS</code> group in the OMI file mentioned previously, you can specify the path and name of the group as follows:
\code
h5dump -g "/HDFEOS" -H -A 0 OMI-Aura.he5
\endcode
The <code style="background-color:whitesmoke;">-A 0</code> option suppresses attributes and <code style="background-color:whitesmoke;">-H</code> suppresses printing of data values:
You can view the contents of a group with <code style="background-color:whitesmoke;">h5ls</code>/ by specifying the group after the file name.
To use <code style="background-color:whitesmoke;">h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
If you specify the <code style="background-color:whitesmoke;">-v</code> option, you can also see the attributes and properties of the datasets.
\section secViewToolsViewAttr Attributes
\subsection subsecViewToolsViewAttr_h5dump h5dump
Attributes are displayed by default if using <code style="background-color:whitesmoke;">h5dump</code>. Some files contain many attributes, which
can make it difficult to examine the objects in the file. Shown below are options that can help
when using <code style="background-color:whitesmoke;">h5dump</code> to work with files that have attributes.
\subsubsection subsubsecViewToolsViewAttr_h5dumpEx6 Example 6
The <code style="background-color:whitesmoke;">-a</code> A option will display an attribute. However, the path to the attribute must be included
when specifying this option. For example, to see the <code style="background-color:whitesmoke;">ScaleFactor</code> attribute in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type:
\code
h5dump -a "/HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle/ScaleFactor" OMI-Aura.he5
\endcode
This command displays:
\code
HDF5 "OMI-Aura.he5" {
ATTRIBUTE "ScaleFactor" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 1
}
}
}
\endcode
How can you determine the path to the attribute? This can be done by looking at the file contents with the <code style="background-color:whitesmoke;">-n 1</code> option:
\code
h5dump -n 1 OMI-Aura.he5
\endcode
Below is a portion of the output for this command:
There can be multiple objects or attributes with the same name in a file. How can you make sure
you are finding the correct object or attribute? You can first determine how many attributes
there are with a specified name, and then examine the paths to them.
The <code style="background-color:whitesmoke;">-N</code> option can be used to display all objects or attributes with a given name.
For example, there are four attributes with the name <code style="background-color:whitesmoke;">ScaleFactor</code> in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file,
as can be seen below with the <code style="background-color:whitesmoke;">-N</code> option:
\code
h5dump -N ScaleFactor OMI-Aura.he5
\endcode
It outputs:
\code
HDF5 "OMI-Aura.he5" {
ATTRIBUTE "ScaleFactor" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 1
}
}
ATTRIBUTE "ScaleFactor" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 1
}
}
ATTRIBUTE "ScaleFactor" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 1
}
}
ATTRIBUTE "ScaleFactor" {
DATATYPE H5T_IEEE_F64LE
DATASPACE SIMPLE { ( 1 ) / ( 1 ) }
DATA {
(0): 1
}
}
}
\endcode
\subsection subsecViewToolsViewAttr_h5ls h5ls
If you include the <code style="background-color:whitesmoke;">-v</code> (verbose) option for <code style="background-color:whitesmoke;">h5ls</code>, you will see all of the attributes for the
specified file, dataset or group. You cannot display individual attributes.
\section secViewToolsViewSub Dataset Subset
\subsection subsecViewToolsViewSub_h5dump h5dump
If you have a very large dataset, you may wish to subset or see just a portion of the dataset.
This can be done with the following <code style="background-color:whitesmoke;">h5dump</code> options.
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td>-d D, --dataset=D
</td>
<td>Dataset D
</td>
</tr>
<tr>
<td>-s START, --start=START
</td>
<td>Offset or start of subsetting selection
</td>
</tr>
<tr>
<td>-S STRIDE, --stride=STRIDE
</td>
<td>Stride (sampling along a dimension). The default (unspecified, or 1) selects
every element along a dimension, a value of 2 selects every other element,
a value of 3 selects every third element, ...
</td>
</tr>
<tr>
<td>-c COUNT, --count=COUNT
</td>
<td>Number of blocks to include in the selection
</td>
</tr>
<tr>
<td>-k BLOCK, --block=BLOCK
</td>
<td>Size of the block in a hyperslab. The default (unspecified, or 1) is for
the block size to be the size of a single element.
</td>
</tr>
</table>
The <code style="background-color:whitesmoke;">START (s)</code>, <code style="background-color:whitesmoke;">STRIDE (S)</code>, <code style="background-color:whitesmoke;">COUNT (c)</code>, and <code style="background-color:whitesmoke;">BLOCK (k)</code> options
define the shape and size of the selection. They are arrays with the same number of dimensions as the rank
of the dataset's dataspace, and they all work together to define the selection. A change to one of
these arrays can affect the others.
When specifying these h5dump options, a comma is used as the delimiter for each dimension in the
option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W",
where H is the height and W is the width. If the offset is 0 for both dimensions, then
<code style="background-color:whitesmoke;">START</code> would be specified as follows:
\code
-s "0,0"
\endcode
There is also a shorthand way to specify these options with brackets at the end of the dataset name:
\code
-d DATASETNAME[s;S;c;k]
\endcode
Multiple dimensions are separated by commas. For example, a subset for a 2-dimensional dataset would be specified as follows:
\code
-d DATASETNAME[s,s;S,S;c,c;k,k]
\endcode
For a detailed understanding of how selections works, see the #H5Sselect_hyperslab API in the \ref RM.
The dataset SolarZenithAngle in the OMI-Aura.he5 file can be used to illustrate these options. This
dataset is a 2-dimensional dataset of size 720 (height) x 1440 (width). Too much data will be displayed
by simply viewing the specified dataset with the <code style="background-color:whitesmoke;">-d</code> option:
Users have been confused by the difference between an Array datatype (#H5T_ARRAY) and a dataset that
(has a dataspace that) is an array.
Typically, these users want a dataset that has a simple datatype (like integer or float) that is an
array, like the following dataset <code style="background-color:whitesmoke;">/DS1</code>. It has a datatype of #H5T_STD_I32LE (32-bit Little-Endian Integer)
and is a 4 by 7 array:
\code
$ h5dump h5ex_d_rdwr.h5
HDF5 "h5ex_d_rdwr.h5" {
GROUP "/" {
DATASET "DS1" {
DATATYPE H5T_STD_I32LE
DATASPACE SIMPLE { ( 4, 7 ) / ( 4, 7 ) }
DATA {
(0,0): 0, -1, -2, -3, -4, -5, -6,
(1,0): 0, 0, 0, 0, 0, 0, 0,
(2,0): 0, 1, 2, 3, 4, 5, 6,
(3,0): 0, 2, 4, 6, 8, 10, 12
}
}
}
}
\endcode
Contrast that with the following dataset that has both an Array datatype and is an array:
\code
$ h5dump h5ex_t_array.h5
HDF5 "h5ex_t_array.h5" {
GROUP "/" {
DATASET "DS1" {
DATATYPE H5T_ARRAY { [3][5] H5T_STD_I64LE }
DATASPACE SIMPLE { ( 4 ) / ( 4 ) }
DATA {
(0): [ 0, 0, 0, 0, 0,
0, -1, -2, -3, -4,
0, -2, -4, -6, -8 ],
(1): [ 0, 1, 2, 3, 4,
1, 1, 1, 1, 1,
2, 1, 0, -1, -2 ],
(2): [ 0, 2, 4, 6, 8,
2, 3, 4, 5, 6,
4, 4, 4, 4, 4 ],
(3): [ 0, 3, 6, 9, 12,
3, 5, 7, 9, 11,
6, 7, 8, 9, 10 ]
}
}
}
}
\endcode
In this file, dataset <code style="background-color:whitesmoke;">/DS1</code> has a datatype of
\code
H5T_ARRAY { [3][5] H5T_STD_I64LE }
\endcode
and it also has a dataspace of
\code
SIMPLE { ( 4 ) / ( 4 ) }
\endcode
In other words, it is an array of four elements, in which each element is a 3 by 5 array of #H5T_STD_I64LE.
This dataset is much more complex. Also note that subsetting cannot be done on Array datatypes.
See this <a href="https://portal.hdfgroup.org/display/knowledge/H5T_ARRAY+Datatype">FAQ</a> for more information on the Array datatype.
An Object Reference is a reference to an entire object (dataset, group, or named datatype).
A dataset with an Object Reference datatype consists of one or more Object References.
An Object Reference dataset can be used as an index to an HDF5 file.
The <code style="background-color:whitesmoke;">/DS1</code> dataset in the following file (<code style="background-color:whitesmoke;">h5ex_t_objref.h5</code>) is an Object Reference dataset.
It contains two references, one to group <code style="background-color:whitesmoke;">/G1</code> and the other to dataset <code style="background-color:whitesmoke;">/DS2</code>:
\code
$ h5dump h5ex_t_objref.h5
HDF5 "h5ex_t_objref.h5" {
GROUP "/" {
DATASET "DS1" {
DATATYPE H5T_REFERENCE { H5T_STD_REF_OBJECT }
DATASPACE SIMPLE { ( 2 ) / ( 2 ) }
DATA {
(0): GROUP 1400 /G1 , DATASET 800 /DS2
}
}
DATASET "DS2" {
DATATYPE H5T_STD_I32LE
DATASPACE NULL
DATA {
}
}
GROUP "G1" {
}
}
}
\endcode
\subsubsection subsubsecViewToolsViewDtypes_regref Region Reference
A Region Reference is a reference to a selection within a dataset. A selection can be either
individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with
the elements or slab that is selected. A dataset with a Region Reference datatype consists of
one or more Region References.
An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the
<a href="https://portal.hdfgroup.org/display/HDF5/Examples+by+API">Examples by API</a> page,
under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a
Region Reference dataset as indicated by its datatype, highlighted in bold below:
\li A selection of four individual elements in dataset <code style="background-color:whitesmoke;">/DS2 : (0,1), (2,11), (1,0), (2,4)</code>
See the #H5Sselect_elements API in the \ref UG for information on selecting individual elements.
\li A selection of these blocks in dataset <code style="background-color:whitesmoke;">/DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)</code>
See the #H5Sselect_hyperslab API in the \ref UG for how to do hyperslab selection.
If you look at the code that creates the dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.c</code>) you will see that the
first reference is created with these calls:
\code
status = H5Sselect_elements (space, H5S_SELECT_SET, 4, coords[0]);
status = H5Rcreate (&wdata[0], file, DATASET2, H5R_DATASET_REGION, space);
\endcode
where the buffer containing the coordinates to select is:
\code
coords[4][2] = { {0, 1},
{2, 11},
{1, 0},
{2, 4} },
\endcode
The second reference is created by calling,
\code
status = H5Sselect_hyperslab (space, H5S_SELECT_SET, start, stride, count, block);
status = H5Rcreate (&wdata[1], file, DATASET2, H5R_DATASET_REGION, space);
\endcode
where start, stride, count, and block have these values:
\code
start[2] = {0, 0},
stride[2] = {2, 11},
count[2] = {2, 2},
block[2] = {1, 3};
\endcode
These start, stride, count, and block values will select the elements shown in bold in the dataset:
If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset
<code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected:
