diff options
| author | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
|---|---|---|
| committer | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
| commit | 4f20d880c97be1249f8d89ced95f72836dbf3ee0 (patch) | |
| tree | 30d8dcb282134b7126b092796f2be00d2d97bd3c /develop/_intro_h_d_f5.html | |
| parent | 4e7e457497c948b41c8b0065225875bf10cdf9d4 (diff) | |
| download | hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.zip hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.gz hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.bz2 | |
deploy: ef39882fa1e13740d2530c7a0637bd1f1a822b68
Diffstat (limited to 'develop/_intro_h_d_f5.html')
| -rw-r--r-- | develop/_intro_h_d_f5.html | 564 |
1 files changed, 564 insertions, 0 deletions
diff --git a/develop/_intro_h_d_f5.html b/develop/_intro_h_d_f5.html new file mode 100644 index 0000000..f225db1 --- /dev/null +++ b/develop/_intro_h_d_f5.html @@ -0,0 +1,564 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen 1.9.1"/> +<meta name="viewport" content="width=device-width, initial-scale=1"/> +<title>HDF5: Introduction to HDF5</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtreedata.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(function() { init_search(); }); +/* @license-end */ +</script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="hdf5doxy.css" rel="stylesheet" type="text/css"> +<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/> + --> +<script type="text/javascript" src="hdf5_navtree_hacks.js"></script> +</head> +<body> +<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td> + <td id="projectalign" style="padding-left: 0.5em;"> + <div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a> +  <span id="projectnumber">1.15.0.ef39882</span> + </div> + <div id="projectbrief">API Reference</div> + </td> + <td> <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.svg" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a> + </span> + </div> +</td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.9.1 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); +/* @license-end */ +</script> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('_intro_h_d_f5.html',''); initResizable(); }); +/* @license-end */ +</script> +<div id="doc-content"> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +</div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +<div class="PageDoc"><div class="header"> + <div class="headertitle"> +<div class="title">Introduction to HDF5 </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> </p><hr /> +<h1><a class="anchor" id="sec_intro_desc"></a> +HDF5 Description</h1> +<p>HDF5 consists of a file format for storing HDF5 data, a data model for logically organizing and accessing HDF5 data from an application, and the software (libraries, language interfaces, and tools) for working with this format.</p> +<h2><a class="anchor" id="subsec_intro_desc_file"></a> +File Format</h2> +<p>HDF5 consists of a file format for storing HDF5 data, a data model for logically organizing and accessing HDF5 data from an application, and the software (libraries, language interfaces, and tools) for working with this format.</p> +<h2><a class="anchor" id="subsec_intro_desc_dm"></a> +Data Model</h2> +<p>The HDF5 Data Model, also known as the HDF5 Abstract (or Logical) Data Model consists of the building blocks for data organization and specification in HDF5.</p> +<p>An HDF5 file (an object in itself) can be thought of as a container (or group) that holds a variety of heterogeneous data objects (or datasets). The datasets can be images, tables, graphs, and even documents, such as PDF or Excel:</p> +<table class="doxtable"> +<tr> +<td><div class="image"> +<img src="fileobj.png" alt=""/> +</div> + </td></tr> +</table> +<p>The two primary objects in the HDF5 Data Model are groups and datasets.</p> +<p>There are also a variety of other objects in the HDF5 Data Model that support groups and datasets, including datatypes, dataspaces, properties and attributes.</p> +<h3><a class="anchor" id="subsec_intro_desc_dm_group"></a> +Groups</h3> +<p>HDF5 groups (and links) organize data objects. Every HDF5 file contains a root group that can contain other groups or be linked to objects in other files.</p> +<table class="doxtable"> +<caption>There are two groups in the HDF5 file depicted above: Viz and SimOut. Under the Viz group are a variety of images and a table that is shared with the SimOut group. The SimOut group contains a 3-dimensional array, a 2-dimensional array and a link to a 2-dimensional array in another HDF5 file.</caption> +<tr> +<td><div class="image"> +<img src="group.png" alt=""/> +</div> + </td></tr> +</table> +<p>Working with groups and group members is similar in many ways to working with directories and files in UNIX. As with UNIX directories and files, objects in an HDF5 file are often described by giving their full (or absolute) path names. </p><ul> +<li>/ signifies the root group. </li> +<li>/foo signifies a member of the root group called foo. </li> +<li>/foo/zoo signifies a member of the group foo, which in turn is a member of the root group.</li> +</ul> +<h3><a class="anchor" id="subsec_intro_desc_dm_dset"></a> +Datasets</h3> +<p>HDF5 datasets organize and contain the “raw” data values. A dataset consists of metadata that describes the data, in addition to the data itself:</p> +<table class="doxtable"> +<caption>In this picture, the data is stored as a three dimensional dataset of size 4 x 5 x 6 with an integer datatype. It contains attributes, Time and Pressure, and the dataset is chunked and compressed.</caption> +<tr> +<td><div class="image"> +<img src="dataset.png" alt=""/> +</div> + </td></tr> +</table> +<p>Datatypes, dataspaces, properties and (optional) attributes are HDF5 objects that describe a dataset. The datatype describes the individual data elements.</p> +<h2><a class="anchor" id="subsec_intro_desc_props"></a> +Datatypes, Dataspaces, Properties and Attributes</h2> +<h3><a class="anchor" id="subsec_intro_desc_prop_dtype"></a> +Datatypes</h3> +<p>The datatype describes the individual data elements in a dataset. It provides complete information for data conversion to or from that datatype.</p> +<table class="doxtable"> +<caption>In the dataset depicted, each element of the dataset is a 32-bit integer.</caption> +<tr> +<td><div class="image"> +<img src="datatype.png" alt=""/> +</div> + </td></tr> +</table> +<p>Datatypes in HDF5 can be grouped into: </p><ul> +<li> +<b>Pre-Defined Datatypes</b>: These are datatypes that are created by HDF5. They are actually opened (and closed) by HDF5 and can have different values from one HDF5 session to the next. There are two types of pre-defined datatypes: <ul> +<li> +Standard datatypes are the same on all platforms and are what you see in an HDF5 file. Their names are of the form H5T_ARCH_BASE where ARCH is an architecture name and BASE is a programming type name. For example, <a class="el" href="group___p_d_t_i_e_e_e.html#ga71d24a7d4c373ed9a003d7a0d8133f1e">H5T_IEEE_F32BE</a> indicates a standard Big Endian floating point type. </li> +<li> +Native datatypes are used to simplify memory operations (reading, writing) and are NOT the same on different platforms. For example, <a class="el" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a> indicates an int (C). </li> +</ul> +</li> +<li> +<b>Derived Datatypes</b>: These are datatypes that are created or derived from the pre-defined datatypes. An example of a commonly used derived datatype is a string of more than one character. Compound datatypes are also derived types. A compound datatype can be used to create a simple table, and can also be nested, in which it includes one more other compound datatypes. <table class="doxtable"> +<caption>This is an example of a dataset with a compound datatype. Each element in the dataset consists of a 16-bit integer, a character, a 32-bit integer, and a 2x3x2 array of 32-bit floats (the datatype). It is a 2-dimensional 5 x 3 array (the dataspace). The datatype should not be confused with the dataspace. </caption> +<tr> +<td><div class="image"> +<img src="cmpnddtype.png" alt=""/> +</div> + </td></tr> +</table> +</li> +</ul> +<h3><a class="anchor" id="subsec_intro_desc_prop_dspace"></a> +Dataspaces</h3> +<p>A dataspace describes the layout of a dataset's data elements. It can consist of no elements (NULL), a single element (scalar), or a simple array.</p> +<table class="doxtable"> +<caption>This image illustrates a dataspace that is an array with dimensions of 5 x 3 and a rank (number of dimensions) of 2.</caption> +<tr> +<td><div class="image"> +<img src="dataspace1.png" alt=""/> +</div> + </td></tr> +</table> +<p>A dataspace can have dimensions that are fixed (unchanging) or unlimited, which means they can grow in size (i.e. they are extendible).</p> +<p>There are two roles of a dataspace: </p><ul> +<li>It contains the spatial information (logical layout) of a dataset stored in a file. This includes the rank and dimensions of a dataset, which are a permanent part of the dataset definition. </li> +<li>It describes an application's data buffers and data elements participating in I/O. In other words, it can be used to select a portion or subset of a dataset.</li> +</ul> +<table class="doxtable"> +<caption>The dataspace is used to describe both the logical layout of a dataset and a subset of a dataset.</caption> +<tr> +<td><div class="image"> +<img src="dataspace.png" alt=""/> +</div> + </td></tr> +</table> +<h3><a class="anchor" id="subsec_intro_desc_prop_property"></a> +Properties</h3> +<p>A property is a characteristic or feature of an HDF5 object. There are default properties which handle the most common needs. These default properties can be modified using the HDF5 Property List API to take advantage of more powerful or unusual features of HDF5 objects.</p> +<table class="doxtable"> +<tr> +<td><div class="image"> +<img src="properties.png" alt=""/> +</div> + </td></tr> +</table> +<p>For example, the data storage layout property of a dataset is contiguous by default. For better performance, the layout can be modified to be chunked or chunked and compressed:</p> +<h3><a class="anchor" id="subsec_intro_desc_prop_attr"></a> +Attributes</h3> +<p>Attributes can optionally be associated with HDF5 objects. They have two parts: a name and a value. Attributes are accessed by opening the object that they are attached to so are not independent objects. Typically an attribute is small in size and contains user metadata about the object that it is attached to.</p> +<p>Attributes look similar to HDF5 datasets in that they have a datatype and dataspace. However, they do not support partial I/O operations, and they cannot be compressed or extended.</p> +<h2><a class="anchor" id="subsec_intro_desc_soft"></a> +HDF5 Software</h2> +<p>The HDF5 software is written in C and includes optional wrappers for C++, FORTRAN (90 and F2003), and Java. The HDF5 binary distribution consists of the HDF5 libraries, include files, command-line utilities, scripts for compiling applications, and example programs.</p> +<h3><a class="anchor" id="subsec_intro_desc_soft_apis"></a> +HDF5 APIs and Libraries</h3> +<p>There are APIs for each type of object in HDF5. For example, all C routines in the HDF5 library begin with a prefix of the form H5*, where * is one or two uppercase letters indicating the type of object on which the function operates: </p><ul> +<li><a class="el" href="group___h5_a.html">Attributes (H5A)</a> <b>A</b>ttribute Interface </li> +<li><a class="el" href="group___h5_d.html">Datasets (H5D)</a> <b>D</b>ataset Interface </li> +<li><a class="el" href="group___h5_f.html">Files (H5F)</a> <b>F</b>ile Interface</li> +</ul> +<p>The HDF5 High Level APIs simplify many of the steps required to create and access objects, as well as providing templates for storing objects. Following is a list of the High Level APIs: </p><ul> +<li><a class="el" href="group___h5_l_t.html">HDF5 Lite APIs (H5LT,H5LD)</a> – simplifies steps in creating datasets and attributes </li> +<li><a class="el" href="group___h5_i_m.html">HDF5 Images API (H5IM)</a> – defines a standard for storing images in HDF5 </li> +<li><a class="el" href="group___h5_t_b.html">HDF5 Table APIs (H5TB)</a> – condenses the steps required to create tables </li> +<li><a class="el" href="group___h5_d_s.html">HDF5 Dimension Scales APIs (H5DS)</a> – provides a standard for dimension scale storage </li> +<li><a class="el" href="group___h5_p_t.html">HDF5 Packet Table APIs (H5PT)</a> – provides a standard for storing packet data</li> +</ul> +<h3><a class="anchor" id="subsec_intro_desc_soft_tools"></a> +Tools</h3> +<p>Useful tools for working with HDF5 files include: </p><ul> +<li>h5dump: A utility to dump or display the contents of an HDF5 File </li> +<li>h5cc, h5c++, h5fc: Unix scripts for compiling applications </li> +<li>HDFView: A java browser to view HDF (HDF4 and HDF5) files</li> +</ul> +<h4>h5dump</h4> +<p>The h5dump utility displays the contents of an HDF5 file in Data Description Language (<a class="el" href="_d_d_l_b_n_f110.html">DDL in BNF through HDF5 1.10</a>). Below is an example of h5dump output for an HDF5 file that contains no objects: </p><div class="fragment"><div class="line">$ h5dump file.h5</div> +<div class="line"> HDF5 <span class="stringliteral">"file.h5"</span> {</div> +<div class="line"> GROUP <span class="stringliteral">"/"</span> {</div> +<div class="line"> }</div> +<div class="line"> }</div> +</div><!-- fragment --><p>With large files and datasets the output from h5dump can be overwhelming. There are options that can be used to examine specific parts of an HDF5 file. Some useful h5dump options are included below: </p><div class="fragment"><div class="line">-H, --header Display header information only (no data)</div> +<div class="line">-d <name> Display a dataset with a specified path and name</div> +<div class="line">-p Display properties</div> +<div class="line">-n Display the contents of the file</div> +</div><!-- fragment --><h4>h5cc, h5fc, h5c++</h4> +<p>The built HDF5 binaries include the h5cc, h5fc, h5c++ compile scripts for compiling applications. When using these scripts there is no need to specify the HDF5 libraries and include files. Compiler options can be passed to the scripts.</p> +<h4>HDFView</h4> +<p>The HDFView tool allows browsing of data in HDF (HDF4 and HDF5) files.</p> +<h1><a class="anchor" id="sec_intro_pm"></a> +Introduction to the HDF5 Programming Model and APIs</h1> +<p>The HDF5 Application Programming Interface is extensive, but a few functions do most of the work.</p> +<p>To introduce the programming model, examples in Python and C are included below. The Python examples use the HDF5 Python APIs (h5py). See the Examples from "Learning the Basics" page for complete examples that can be downloaded and run for C, FORTRAN, C++, Java and Python.</p> +<p>The general paradigm for working with objects in HDF5 is to: </p><ul> +<li>Open the object. </li> +<li>Access the object. </li> +<li>Close the object.</li> +</ul> +<p>The library imposes an order on the operations by argument dependencies. For example, a file must be opened before a dataset because the dataset open call requires a file handle as an argument. Objects can be closed in any order. However, once an object is closed it no longer can be accessed.</p> +<p>Keep the following in mind when looking at the example programs included in this section: </p><ul> +<li> +<ul> +<li> +C routines begin with the prefix “H5*” where * is a single letter indicating the object on which the operation is to be performed. </li> +<li> +FORTRAN routines are similar; they begin with “h5*” and end with “_f”. </li> +<li> +Java routines are similar; the routine names begin with “H5*” and are prefixed with “H5.” as the class. Constants are in the HDF5Constants class and are prefixed with "HDF5Constants.". The function arguments are usually similar, <dl class="section see"><dt>See also</dt><dd><a class="el" href="_h_d_f5_l_i_b.html">HDF5 Java API Package</a> </dd></dl> +</li> +</ul> +For example: <ul> +<li> +File Interface:<ul> +<li> +<a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> (C)</li> +<li> +h5fopen_f (FORTRAN)</li> +<li> +H5.H5Fopen (Java)</li> +</ul> +</li> +<li> +Dataset Interface:<ul> +<li> +<a class="el" href="_h5version_8h.html#a7dba2e5b2045f31c0932123ffb54f7a3">H5Dopen</a> (C)</li> +<li> +h5dopen_f (FORTRAN)</li> +<li> +H5.H5Dopen (Java)</li> +</ul> +</li> +<li> +Dataspace interface:<ul> +<li> +<a class="el" href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1" title="Releases and terminates access to a dataspace.">H5Sclose</a> (C)</li> +<li> +h5sclose_f (FORTRAN)</li> +<li> +H5.H5Sclose (Java)</li> +</ul> +</li> +</ul> +The HDF5 Python APIs use methods associated with specific objects. </li> +<li> +For portability, the HDF5 library has its own defined types. Some common types that you will see in the example code are: <ul> +<li> +<a class="el" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> is used for object handles </li> +<li> +hsize_t is used for dimensions </li> +<li> +<a class="el" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> is used for many return values </li> +</ul> +</li> +<li> +Language specific files must be included in applications: <ul> +<li> +Python: Add <code>"import h5py / import numpy"</code> </li> +<li> +C: Add <code>"#include hdf5.h"</code> </li> +<li> +FORTRAN: Add <code>"USE HDF5"</code> and call h5open_f and h5close_f to initialize and close the HDF5 FORTRAN interface </li> +<li> +Java: Add <code>"import hdf.hdf5lib.H5; + import hdf.hdf5lib.HDF5Constants;"</code> </li> +</ul> +</li> +</ul> +<h2><a class="anchor" id="subsec_intro_pm_file"></a> +Steps to create a file</h2> +<p>To create an HDF5 file you must: </p><ul> +<li>Specify property lists (or use the defaults). </li> +<li>Create the file. </li> +<li>Close the file (and property lists if needed).</li> +</ul> +<p>Example: </p><table class="doxtable"> +<caption>The following Python and C examples create a file, file.h5, and then close it. The resulting HDF5 file will only contain a root group:</caption> +<tr> +<td><div class="image"> +<img src="crtf-pic.png" alt=""/> +</div> + </td></tr> +</table> +<p>Calling h5py.File with ‘w’ for the file access flag will create a new HDF5 file and overwrite an existing file with the same name. “file” is the file handle returned from opening the file. When finished with the file, it must be closed. When not specifying property lists, the default property lists are used:</p> +<table class="doxtable"> +<tr> +<td><em>Python</em> <div class="fragment"><div class="line"><span class="keyword">import</span> h5py</div> +<div class="line">file = h5py.File (‘file.h5’, ‘w’)</div> +<div class="line">file.close ()</div> +</div><!-- fragment --> </td></tr> +</table> +<p>The H5Fcreate function creates an HDF5 file. <a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> is the file access flag to create a new file and overwrite an existing file with the same name, and <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> is the value specified to use a default property list.</p> +<table class="doxtable"> +<tr> +<td><em>C</em> <div class="fragment"><div class="line"><span class="preprocessor">#include “hdf5.h”</span></div> +<div class="line"> </div> +<div class="line"><span class="keywordtype">int</span> main() {</div> +<div class="line"> <a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id;</div> +<div class="line"> <a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> status;</div> +<div class="line"> </div> +<div class="line"> file_id = <a class="code" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a> (<span class="stringliteral">"file.h5"</span>, <a class="code" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>); </div> +<div class="line"> status = <a class="code" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a> (file_id);</div> +<div class="line">}</div> +<div class="ttc" id="a_h5_fpublic_8h_html_a5a2d6726f9ad8d2bca8df2b817e5ad6a"><div class="ttname"><a href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a></div><div class="ttdeci">#define H5F_ACC_TRUNC</div><div class="ttdef"><b>Definition:</b> H5Fpublic.h:50</div></div> +<div class="ttc" id="a_h5_ipublic_8h_html_a0045db7ff9c22ad35db6ae91662e1943"><div class="ttname"><a href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a></div><div class="ttdeci">int64_t hid_t</div><div class="ttdef"><b>Definition:</b> H5Ipublic.h:60</div></div> +<div class="ttc" id="a_h5_ppublic_8h_html_afa85e97bfbf9bf1c58e39263846c568f"><div class="ttname"><a href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a></div><div class="ttdeci">#define H5P_DEFAULT</div><div class="ttdef"><b>Definition:</b> H5Ppublic.h:102</div></div> +<div class="ttc" id="a_h5public_8h_html_a3b079ecf932a5c599499cf7e298af160"><div class="ttname"><a href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div><div class="ttdeci">int herr_t</div><div class="ttdef"><b>Definition:</b> H5public.h:235</div></div> +<div class="ttc" id="agroup___h5_f_html_gac55cd91d80822e4f8c2a7f04ea71b124"><div class="ttname"><a href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a></div><div class="ttdeci">herr_t H5Fclose(hid_t file_id)</div><div class="ttdoc">Terminates access to an HDF5 file.</div></div> +<div class="ttc" id="agroup___h5_f_html_gae64b51ee9ac0781bc4ccc599d98387f4"><div class="ttname"><a href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a></div><div class="ttdeci">hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)</div><div class="ttdoc">Creates an HDF5 file.</div></div> +</div><!-- fragment --> </td></tr> +</table> +<h2><a class="anchor" id="subsec_intro_pm_dataset"></a> +Steps to create a dataset</h2> +<p>As described previously, an HDF5 dataset consists of the raw data, as well as the metadata that describes the data (datatype, spatial information, and properties). To create a dataset you must: </p><ul> +<li>Define the dataset characteristics (datatype, dataspace, properties). </li> +<li>Decide which group to attach the dataset to. </li> +<li>Create the dataset. </li> +<li>Close the dataset handle from step 3.</li> +</ul> +<p>Example: </p><table class="doxtable"> +<caption>The code excerpts below show the calls that need to be made to create a 4 x 6 integer dataset dset in a file dset.h5. The dataset will be located in the root group:</caption> +<tr> +<td><div class="image"> +<img src="crtdset.png" alt=""/> +</div> + </td></tr> +</table> +<p>With Python, the creation of the dataspace is included as a parameter in the dataset creation method. Just one call will create a 4 x 6 integer dataset dset. A pre-defined Big Endian 32-bit integer datatype is specified. The create_dataset method creates the dataset in the root group (the file object). The dataset is close by the Python interface.</p> +<table class="doxtable"> +<tr> +<td><em>Python</em> <div class="fragment"><div class="line">dataset = file.create_dataset(<span class="stringliteral">"dset"</span>,(4, 6), h5py.h5t.STD_I32BE)</div> +</div><!-- fragment --> </td></tr> +</table> +<p>To create the same dataset in C, you must specify the dataspace with the <a class="el" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae" title="Creates a new simple dataspace and opens it for access.">H5Screate_simple</a> function, create the dataset by calling <a class="el" href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a>, and then close the dataspace and dataset with calls to <a class="el" href="group___h5_d.html#gae47c3f38db49db127faf221624c30609" title="Closes the specified dataset.">H5Dclose</a> and <a class="el" href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1" title="Releases and terminates access to a dataspace.">H5Sclose</a>. <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a> is specified to use a default property list. Note that the file identifier (file_id) is passed in as the first parameter to <a class="el" href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a>, which creates the dataset in the root group.</p> +<table class="doxtable"> +<tr> +<td><em>C</em> <div class="fragment"><div class="line"><span class="comment">// Create the dataspace for the dataset.</span></div> +<div class="line">dims[0] = 4;</div> +<div class="line">dims[1] = 6;</div> +<div class="line"> </div> +<div class="line">dataspace_id = <a class="code" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a>(2, dims, NULL);</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Create the dataset.</span></div> +<div class="line">dataset_id = <a class="code" href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a> (file_id, <span class="stringliteral">"/dset"</span>, <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>, dataspace_id, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>);</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Close the dataset and dataspace</span></div> +<div class="line">status = <a class="code" href="group___h5_d.html#gae47c3f38db49db127faf221624c30609">H5Dclose</a>(dataset_id);</div> +<div class="line">status = <a class="code" href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1">H5Sclose</a>(dataspace_id);</div> +<div class="ttc" id="agroup___h5_d_html_ga0647ba4bbd26d5230cc07f3a5685b2cf"><div class="ttname"><a href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a></div><div class="ttdeci">#define H5Dcreate</div><div class="ttdef"><b>Definition:</b> H5version.h:892</div></div> +<div class="ttc" id="agroup___h5_d_html_gae47c3f38db49db127faf221624c30609"><div class="ttname"><a href="group___h5_d.html#gae47c3f38db49db127faf221624c30609">H5Dclose</a></div><div class="ttdeci">herr_t H5Dclose(hid_t dset_id)</div><div class="ttdoc">Closes the specified dataset.</div></div> +<div class="ttc" id="agroup___h5_s_html_ga2b53128a39c8f104c1c9c2a91590fcc1"><div class="ttname"><a href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1">H5Sclose</a></div><div class="ttdeci">herr_t H5Sclose(hid_t space_id)</div><div class="ttdoc">Releases and terminates access to a dataspace.</div></div> +<div class="ttc" id="agroup___h5_s_html_ga8e35eea5738b4805856eac7d595254ae"><div class="ttname"><a href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a></div><div class="ttdeci">hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[])</div><div class="ttdoc">Creates a new simple dataspace and opens it for access.</div></div> +<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga37e8a6be7ee64587c2a282b965019bb8"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div><div class="ttdeci">#define H5T_STD_I32BE</div><div class="ttdef"><b>Definition:</b> H5Tpublic.h:305</div></div> +</div><!-- fragment --> </td></tr> +</table> +<h2><a class="anchor" id="subsec_intro_pm_write"></a> +Writing to or reading from a dataset</h2> +<p>Once you have created or opened a dataset you can write to it:</p> +<table class="doxtable"> +<tr> +<td><em>Python</em> <div class="fragment"><div class="line">data = np.zeros((4,6))</div> +<div class="line"><span class="keywordflow">for</span> i in range(4):</div> +<div class="line"> for j in range(6):</div> +<div class="line"> data[i][j]= i*6+j+1</div> +<div class="line"> </div> +<div class="line">dataset[...] = data <-- Write data to dataset</div> +<div class="line">data_read = dataset[...] <-- Read data from dataset</div> +</div><!-- fragment --> </td></tr> +</table> +<p><a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> is passed in for the memory and file dataspace parameters to indicate that the entire dataspace of the dataset is specified. These two parameters can be modified to allow subsetting of a dataset. The native predefined datatype, <a class="el" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, is used for reading and writing so that HDF5 will do any necessary integer conversions:</p> +<table class="doxtable"> +<tr> +<td><em>C</em> <div class="fragment"><div class="line">status = <a class="code" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a> (dataset_id, <a class="code" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, <a class="code" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>, <a class="code" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, dset_data);</div> +<div class="line">status = <a class="code" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a> (dataset_id, <a class="code" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, <a class="code" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>, <a class="code" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, dset_data);</div> +<div class="ttc" id="a_h5_spublic_8h_html_a5f96eeee84b987f18470737f85af0484"><div class="ttname"><a href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a></div><div class="ttdeci">#define H5S_ALL</div><div class="ttdef"><b>Definition:</b> H5Spublic.h:32</div></div> +<div class="ttc" id="agroup___h5_d_html_ga8287d5a7be7b8e55ffeff68f7d26811c"><div class="ttname"><a href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a></div><div class="ttdeci">herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf)</div><div class="ttdoc">Reads raw data from a dataset into a provided buffer.</div></div> +<div class="ttc" id="agroup___h5_d_html_ga98f44998b67587662af8b0d8a0a75906"><div class="ttname"><a href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a></div><div class="ttdeci">herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf)</div><div class="ttdoc">Writes raw data from a buffer to a dataset.</div></div> +<div class="ttc" id="agroup___p_d_t_n_a_t_html_ga3cf93ffc6782be68070ef8e00f219ec2"><div class="ttname"><a href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a></div><div class="ttdeci">#define H5T_NATIVE_INT</div><div class="ttdef"><b>Definition:</b> H5Tpublic.h:767</div></div> +</div><!-- fragment --> </td></tr> +</table> +<h2><a class="anchor" id="subsec_intro_pm_group"></a> +Steps to create a group</h2> +<p>An HDF5 group is a structure containing zero or more HDF5 objects. Before you can create a group you must obtain the location identifier of where the group is to be created. Following are the steps that are required: </p><ul> +<li>Decide where to put the group – in the “root group” (or file identifier) or in another group. Open the group if it is not already open. </li> +<li>Define properties or use the default. </li> +<li>Create the group. </li> +<li>Close the group.</li> +</ul> +<table class="doxtable"> +<caption>Creates attributes that are attached to the dataset dset</caption> +<tr> +<td><div class="image"> +<img src="crtgrp.png" alt=""/> +</div> + </td></tr> +</table> +<p>The code below opens the dataset dset.h5 with read/write permission and creates a group MyGroup in the root group. Properties are not specified so the defaults are used:</p> +<table class="doxtable"> +<tr> +<td><em>Python</em> <div class="fragment"><div class="line"><span class="keyword">import</span> h5py</div> +<div class="line">file = h5py.File(<span class="stringliteral">'dset.h5'</span>, <span class="stringliteral">'r+'</span>) </div> +<div class="line">group = file.create_group (<span class="stringliteral">'MyGroup'</span>)</div> +<div class="line">file.close()</div> +</div><!-- fragment --> </td></tr> +</table> +<p>To create the group MyGroup in the root group, you must call <a class="el" href="group___h5_g.html#ga187cee27a9fc4f1a311eb19b0522c7b8">H5Gcreate</a>, passing in the file identifier returned from opening or creating the file. The default property lists are specified with <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>. The group is then closed:</p> +<table class="doxtable"> +<tr> +<td><em>C</em> <div class="fragment"><div class="line">group_id = <a class="code" href="group___h5_g.html#ga187cee27a9fc4f1a311eb19b0522c7b8">H5Gcreate</a> (file_id, <span class="stringliteral">"MyGroup"</span>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>);</div> +<div class="line">status = <a class="code" href="group___h5_g.html#ga8dbe20b390d2504f0bd3589ed8f4e221">H5Gclose</a> (group_id);</div> +<div class="ttc" id="agroup___h5_g_html_ga187cee27a9fc4f1a311eb19b0522c7b8"><div class="ttname"><a href="group___h5_g.html#ga187cee27a9fc4f1a311eb19b0522c7b8">H5Gcreate</a></div><div class="ttdeci">#define H5Gcreate</div><div class="ttdef"><b>Definition:</b> H5version.h:997</div></div> +<div class="ttc" id="agroup___h5_g_html_ga8dbe20b390d2504f0bd3589ed8f4e221"><div class="ttname"><a href="group___h5_g.html#ga8dbe20b390d2504f0bd3589ed8f4e221">H5Gclose</a></div><div class="ttdeci">herr_t H5Gclose(hid_t group_id)</div><div class="ttdoc">Closes the specified group.</div></div> +</div><!-- fragment --> </td></tr> +</table> +<h2><a class="anchor" id="subsec_intro_pm_attr"></a> +Steps to create and write to an attribute</h2> +<p>To create an attribute you must open the object that you wish to attach the attribute to. Then you can create, access, and close the attribute as needed: </p><ul> +<li>Open the object that you wish to add an attribute to. </li> +<li>Create the attribute </li> +<li>Write to the attribute </li> +<li>Close the attribute and the object it is attached to.</li> +</ul> +<table class="doxtable"> +<caption>Creates attributes that are attached to the dataset dset</caption> +<tr> +<td><div class="image"> +<img src="crtatt.png" alt=""/> +</div> + </td></tr> +</table> +<p>The dataspace, datatype, and data are specified in the call to create an attribute in Python:</p> +<table class="doxtable"> +<tr> +<td><em>Python</em> <div class="fragment"><div class="line">dataset.attrs[<span class="stringliteral">"Units"</span>] = “Meters per second” <-- Create <span class="keywordtype">string</span></div> +<div class="line">attr_data = np.zeros((2,))</div> +<div class="line">attr_data[0] = 100</div> +<div class="line">attr_data[1] = 200</div> +<div class="line">dataset.attrs.create(<span class="stringliteral">"Speed"</span>, attr_data, (2,), “i”) <-- Create Integer</div> +</div><!-- fragment --> </td></tr> +</table> +<p>To create an integer attribute in C, you must create the dataspace, create the attribute, write to it and then close it in separate steps:</p> +<table class="doxtable"> +<tr> +<td><em>C</em> <div class="fragment"><div class="line"><a class="code" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attribute_id, dataspace_id; <span class="comment">// identifiers</span></div> +<div class="line"><a class="code" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> dims;</div> +<div class="line"><span class="keywordtype">int</span> attr_data[2];</div> +<div class="line"><a class="code" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> status;</div> +<div class="line"> </div> +<div class="line"> ...</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Initialize the attribute data.</span></div> +<div class="line">attr_data[0] = 100;</div> +<div class="line">attr_data[1] = 200;</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Create the data space for the attribute.</span></div> +<div class="line">dims = 2;</div> +<div class="line">dataspace_id = <a class="code" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a>(1, &dims, NULL);</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Create a dataset attribute.</span></div> +<div class="line">attribute_id = <a class="code" href="group___h5_a.html#ga4f4e5248c09f689633079ed8afc0b308">H5Acreate2</a> (dataset_id, <span class="stringliteral">"Units"</span>, <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>,</div> +<div class="line"> dataspace_id, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>);</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Write the attribute data.</span></div> +<div class="line">status = <a class="code" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a>(attribute_id, <a class="code" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, attr_data);</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Close the attribute.</span></div> +<div class="line">status = <a class="code" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a>(attribute_id);</div> +<div class="line"> </div> +<div class="line"><span class="comment">// Close the dataspace.</span></div> +<div class="line">status = <a class="code" href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1">H5Sclose</a>(dataspace_id);</div> +<div class="ttc" id="a_h5public_8h_html_a7f81cce70fb546af88da24d9285d3c1c"><div class="ttname"><a href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a></div><div class="ttdeci">uint64_t hsize_t</div><div class="ttdef"><b>Definition:</b> H5public.h:297</div></div> +<div class="ttc" id="agroup___h5_a_html_ga4f4e5248c09f689633079ed8afc0b308"><div class="ttname"><a href="group___h5_a.html#ga4f4e5248c09f689633079ed8afc0b308">H5Acreate2</a></div><div class="ttdeci">hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id)</div><div class="ttdoc">Creates an attribute attached to a specified object.</div></div> +<div class="ttc" id="agroup___h5_a_html_gab70871e205d57450c83efd9912be2b5c"><div class="ttname"><a href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a></div><div class="ttdeci">herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf)</div><div class="ttdoc">Writes data to an attribute.</div></div> +<div class="ttc" id="agroup___h5_a_html_gaef4394b661e2c930879e9868e122bdda"><div class="ttname"><a href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a></div><div class="ttdeci">herr_t H5Aclose(hid_t attr_id)</div><div class="ttdoc">Closes the specified attribute.</div></div> +</div><!-- fragment --> </td></tr> +</table> +<hr /> +<p> Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> </p> +</div></div><!-- contents --> +</div><!-- PageDoc --> +</div><!-- doc-content --> +<!-- start footer part --> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + <li class="footer">Generated by + <a href="http://www.doxygen.org/index.html"> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li> + </ul> +</div> +</body> +</html> |