/usr/share/doc/python-h5py-doc/html/refs.html is in python-h5py-doc 2.7.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 | <!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/html; charset=utf-8" />
<title>Object and Region References — h5py 2.7.1 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.7.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Parallel HDF5" href="mpi.html" />
<link rel="prev" title="Strings in HDF5" href="strings.html" />
</head>
<body role="document">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="mpi.html" title="Parallel HDF5"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="strings.html" title="Strings in HDF5"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">h5py 2.7.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="object-and-region-references">
<span id="refs"></span><h1>Object and Region References<a class="headerlink" href="#object-and-region-references" title="Permalink to this headline">¶</a></h1>
<p>In addition to soft and external links, HDF5 supplies one more mechanism to
refer to objects and data in a file. HDF5 <em>references</em> are low-level pointers
to other objects. The great advantage of references is that they can be
stored and retrieved as data; you can create an attribute or an entire dataset
of reference type.</p>
<p>References come in two flavors, object references and region references.
As the name suggests, object references point to a particular object in a file,
either a dataset, group or named datatype. Region references always point to
a dataset, and additionally contain information about a certain selection
(<em>dataset region</em>) on that dataset. For example, if you have a dataset
representing an image, you could specify a region of interest, and store it
as an attribute on the dataset.</p>
<div class="section" id="using-object-references">
<span id="refs-object"></span><h2>Using object references<a class="headerlink" href="#using-object-references" title="Permalink to this headline">¶</a></h2>
<p>It’s trivial to create a new object reference; every high-level object
in h5py has a read-only property “ref”, which when accessed returns a new
object reference:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">myfile</span> <span class="o">=</span> <span class="n">h5py</span><span class="o">.</span><span class="n">File</span><span class="p">(</span><span class="s1">'myfile.hdf5'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">mygroup</span> <span class="o">=</span> <span class="n">myfile</span><span class="p">[</span><span class="s1">'/some/group'</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">ref</span> <span class="o">=</span> <span class="n">mygroup</span><span class="o">.</span><span class="n">ref</span>
<span class="gp">>>> </span><span class="nb">print</span> <span class="n">ref</span>
<span class="go"><HDF5 object reference></span>
</pre></div>
</div>
<p>“Dereferencing” these objects is straightforward; use the same syntax as when
opening any other object:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">mygroup2</span> <span class="o">=</span> <span class="n">myfile</span><span class="p">[</span><span class="n">ref</span><span class="p">]</span>
<span class="gp">>>> </span><span class="nb">print</span> <span class="n">mygroup2</span>
<span class="go"><HDF5 group "/some/group" (0 members)></span>
</pre></div>
</div>
</div>
<div class="section" id="using-region-references">
<span id="refs-region"></span><h2>Using region references<a class="headerlink" href="#using-region-references" title="Permalink to this headline">¶</a></h2>
<p>Region references always contain a selection. You create them using the
dataset property “regionref” and standard NumPy slicing syntax:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">myds</span> <span class="o">=</span> <span class="n">myfile</span><span class="o">.</span><span class="n">create_dataset</span><span class="p">(</span><span class="s1">'dset'</span><span class="p">,</span> <span class="p">(</span><span class="mi">200</span><span class="p">,</span><span class="mi">200</span><span class="p">))</span>
<span class="gp">>>> </span><span class="n">regref</span> <span class="o">=</span> <span class="n">myds</span><span class="o">.</span><span class="n">regionref</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">10</span><span class="p">,</span> <span class="mi">0</span><span class="p">:</span><span class="mi">5</span><span class="p">]</span>
<span class="gp">>>> </span><span class="nb">print</span> <span class="n">regref</span>
<span class="go"><HDF5 region reference></span>
</pre></div>
</div>
<p>The reference itself can now be used in place of slicing arguments to the
dataset:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">subset</span> <span class="o">=</span> <span class="n">myds</span><span class="p">[</span><span class="n">regref</span><span class="p">]</span>
</pre></div>
</div>
<p>There is one complication; since HDF5 region references don’t express shapes
the same way as NumPy does, the data returned will be “flattened” into a
1-D array:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">subset</span><span class="o">.</span><span class="n">shape</span>
<span class="go">(50,)</span>
</pre></div>
</div>
<p>This is similar to the behavior of NumPy’s fancy indexing, which returns
a 1D array for selections which don’t conform to a regular grid.</p>
<p>In addition to storing a selection, region references inherit from object
references, and can be used anywhere an object reference is accepted. In this
case the object they point to is the dataset used to create them.</p>
</div>
<div class="section" id="storing-references-in-a-dataset">
<h2>Storing references in a dataset<a class="headerlink" href="#storing-references-in-a-dataset" title="Permalink to this headline">¶</a></h2>
<p>HDF5 treats object and region references as data. Consequently, there is a
special HDF5 type to represent them. However, NumPy has no equivalent type.
Rather than implement a special “reference type” for NumPy, references are
handled at the Python layer as plain, ordinary python objects. To NumPy they
are represented with the “object” dtype (kind ‘O’). A small amount of
metadata attached to the dtype tells h5py to interpret the data as containing
reference objects.</p>
<p>H5py contains a convenience function to create these “hinted dtypes” for you:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ref_dtype</span> <span class="o">=</span> <span class="n">h5py</span><span class="o">.</span><span class="n">special_dtype</span><span class="p">(</span><span class="n">ref</span><span class="o">=</span><span class="n">h5py</span><span class="o">.</span><span class="n">Reference</span><span class="p">)</span>
<span class="gp">>>> </span><span class="nb">type</span><span class="p">(</span><span class="n">ref_dtype</span><span class="p">)</span>
<span class="go"><type 'numpy.dtype'></span>
<span class="gp">>>> </span><span class="n">ref_dtype</span><span class="o">.</span><span class="n">kind</span>
<span class="go">'O'</span>
</pre></div>
</div>
<p>The types accepted by this “ref=” keyword argument are h5py.Reference (for
object references) and h5py.RegionReference (for region references).</p>
<p>To create an array of references, use this dtype as you normally would:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ref_dataset</span> <span class="o">=</span> <span class="n">myfile</span><span class="o">.</span><span class="n">create_dataset</span><span class="p">(</span><span class="s2">"MyRefs"</span><span class="p">,</span> <span class="p">(</span><span class="mi">100</span><span class="p">,),</span> <span class="n">dtype</span><span class="o">=</span><span class="n">ref_dtype</span><span class="p">)</span>
</pre></div>
</div>
<p>You can read from and write to the array as normal:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ref_dataset</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">myfile</span><span class="o">.</span><span class="n">ref</span>
<span class="gp">>>> </span><span class="nb">print</span> <span class="n">ref_dataset</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="go"><HDF5 object reference></span>
</pre></div>
</div>
</div>
<div class="section" id="storing-references-in-an-attribute">
<h2>Storing references in an attribute<a class="headerlink" href="#storing-references-in-an-attribute" title="Permalink to this headline">¶</a></h2>
<p>Simply assign the reference to a name; h5py will figure it out and store it
with the correct type:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">myref</span> <span class="o">=</span> <span class="n">myfile</span><span class="o">.</span><span class="n">ref</span>
<span class="gp">>>> </span><span class="n">myfile</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s2">"Root group reference"</span><span class="p">]</span> <span class="o">=</span> <span class="n">myref</span>
</pre></div>
</div>
</div>
<div class="section" id="null-references">
<h2>Null references<a class="headerlink" href="#null-references" title="Permalink to this headline">¶</a></h2>
<p>When you create a dataset of reference type, the uninitialized elements are
“null” references. H5py uses the truth value of a reference object to
indicate whether or not it is null:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span> <span class="nb">bool</span><span class="p">(</span><span class="n">myfile</span><span class="o">.</span><span class="n">ref</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">nullref</span> <span class="o">=</span> <span class="n">ref_dataset</span><span class="p">[</span><span class="mi">50</span><span class="p">]</span>
<span class="gp">>>> </span><span class="nb">print</span> <span class="nb">bool</span><span class="p">(</span><span class="n">nullref</span><span class="p">)</span>
<span class="go">False</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Object and Region References</a><ul>
<li><a class="reference internal" href="#using-object-references">Using object references</a></li>
<li><a class="reference internal" href="#using-region-references">Using region references</a></li>
<li><a class="reference internal" href="#storing-references-in-a-dataset">Storing references in a dataset</a></li>
<li><a class="reference internal" href="#storing-references-in-an-attribute">Storing references in an attribute</a></li>
<li><a class="reference internal" href="#null-references">Null references</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="strings.html"
title="previous chapter">Strings in HDF5</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="mpi.html"
title="next chapter">Parallel HDF5</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/refs.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="mpi.html" title="Parallel HDF5"
>next</a> |</li>
<li class="right" >
<a href="strings.html" title="Strings in HDF5"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">h5py 2.7.1 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2017, Andrew Collette and contributors.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
</div>
</body>
</html>
|