<!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>Homogenous storage classes — PyTables 3.0.0 documentation</title>
<link rel="stylesheet" href="../../_static/cloud.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '3.0.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<script type="text/javascript" src="../../_static/jquery.cookie.js"></script>
<script type="text/javascript" src="../../_static/toggle_sections.js"></script>
<script type="text/javascript" src="../../_static/toggle_sidebar.js"></script>
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="top" title="PyTables 3.0.0 documentation" href="../../index.html" />
<link rel="up" title="Library Reference" href="../libref.html" />
<link rel="next" title="Link classes" href="link_classes.html" />
<link rel="prev" title="Structured storage classes" href="structured_storage.html" />
</head>
<body>
<div class="relbar-top">
<div class="related">
<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="../../py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="../../np-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="link_classes.html" title="Link classes"
accesskey="N">next</a> </li>
<li class="right" >
<a href="structured_storage.html" title="Structured storage classes"
accesskey="P">previous</a> </li>
<li><a href="../../index.html">PyTables 3.0.0 documentation</a> »</li>
<li><a href="../index.html" >PyTables User’s Guide</a> »</li>
<li><a href="../libref.html" accesskey="U">Library Reference</a> »</li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="homogenous-storage-classes">
<h1>Homogenous storage classes<a class="headerlink" href="#homogenous-storage-classes" title="Permalink to this headline">¶</a></h1>
<div class="section" id="the-array-class">
<span id="arrayclassdescr"></span><h2>The Array class<a class="headerlink" href="#the-array-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="tables.Array">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">Array</tt><big>(</big><em>parentnode</em>, <em>name</em>, <em>obj=None</em>, <em>title=''</em>, <em>byteorder=None</em>, <em>_log=True</em>, <em>_atom=None</em><big>)</big><a class="headerlink" href="#tables.Array" title="Permalink to this definition">¶</a></dt>
<dd><p>This class represents homogeneous datasets in an HDF5 file.</p>
<p>This class provides methods to write or read data to or from array objects
in the file. This class does not allow you neither to enlarge nor compress
the datasets on disk; use the EArray class (see <a class="reference internal" href="#earrayclassdescr"><em>The EArray class</em></a>) if
you want enlargeable dataset support or compression features, or CArray
(see <a class="reference internal" href="#carrayclassdescr"><em>The CArray class</em></a>) if you just want compression.</p>
<p>An interesting property of the Array class is that it remembers the
<em>flavor</em> of the object that has been saved so that if you saved, for
example, a list, you will get a list during readings afterwards; if you
saved a NumPy array, you will get a NumPy object, and so forth.</p>
<p>Note that this class inherits all the public attributes and methods that
Leaf (see <a class="reference internal" href="hierarchy_classes.html#leafclassdescr"><em>The Leaf class</em></a>) already provides. However, as Array
instances have no internal I/O buffers, it is not necessary to use the
flush() method they inherit from Leaf in order to save their internal state
to disk. When a writing method call returns, all the data is already on
disk.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters :</th><td class="field-body"><p class="first"><strong>parentnode</strong> :</p>
<blockquote>
<div><p>The parent <a class="reference internal" href="hierarchy_classes.html#tables.Group" title="tables.Group"><tt class="xref py py-class docutils literal"><span class="pre">Group</span></tt></a> object.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Renamed from <em>parentNode</em> to <em>parentnode</em></p>
</div></blockquote>
<p><strong>name</strong> : str</p>
<blockquote>
<div><p>The name of this node in its parent group.</p>
</div></blockquote>
<p><strong>obj</strong> :</p>
<blockquote>
<div><p>The array or scalar to be saved. Accepted types are NumPy
arrays and scalars as well as native Python sequences and
scalars, provided that values are regular (i.e. they are not
like <tt class="docutils literal"><span class="pre">[[1,2],2]</span></tt>) and homogeneous (i.e. all the elements are
of the same type).</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Renamed form <em>object</em> into <em>obj</em>.</p>
</div></blockquote>
<p><strong>title</strong> :</p>
<blockquote>
<div><p>A description for this node (it sets the <tt class="docutils literal"><span class="pre">TITLE</span></tt> HDF5 attribute on
disk).</p>
</div></blockquote>
<p><strong>byteorder</strong> :</p>
<blockquote class="last">
<div><p>The byteorder of the data <em>on disk</em>, specified as ‘little’ or ‘big’.
If this is not specified, the byteorder is that of the given <cite>object</cite>.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<div class="section" id="array-instance-variables">
<h3>Array instance variables<a class="headerlink" href="#array-instance-variables" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="tables.Array.atom">
<tt class="descclassname">Array.</tt><tt class="descname">atom</tt><a class="headerlink" href="#tables.Array.atom" title="Permalink to this definition">¶</a></dt>
<dd><p>An Atom (see <a class="reference internal" href="declarative_classes.html#atomclassdescr"><em>The Atom class and its descendants</em></a>) instance representing the <em>type</em>
and <em>shape</em> of the atomic objects to be saved.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Array.rowsize">
<tt class="descclassname">Array.</tt><tt class="descname">rowsize</tt><a class="headerlink" href="#tables.Array.rowsize" title="Permalink to this definition">¶</a></dt>
<dd><p>The size of the rows in bytes in dimensions orthogonal to <em>maindim</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Array.nrow">
<tt class="descclassname">Array.</tt><tt class="descname">nrow</tt><a class="headerlink" href="#tables.Array.nrow" title="Permalink to this definition">¶</a></dt>
<dd><p>On iterators, this is the index of the current row.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Array.nrows">
<tt class="descclassname">Array.</tt><tt class="descname">nrows</tt><a class="headerlink" href="#tables.Array.nrows" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of rows in the array.</p>
</dd></dl>
</div>
<div class="section" id="array-methods">
<h3>Array methods<a class="headerlink" href="#array-methods" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.Array.get_enum">
<tt class="descclassname">Array.</tt><tt class="descname">get_enum</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Array.get_enum" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the enumerated type associated with this array.</p>
<p>If this array is of an enumerated type, the corresponding Enum instance
(see <a class="reference internal" href="helper_classes.html#enumclassdescr"><em>The Enum class</em></a>) is returned. If it is not of an enumerated
type, a TypeError is raised.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Array.iterrows">
<tt class="descclassname">Array.</tt><tt class="descname">iterrows</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Array.iterrows" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over the rows of the array.</p>
<p>This method returns an iterator yielding an object of the current
flavor for each selected row in the array. The returned rows are taken
from the <em>main dimension</em>.</p>
<p>If a range is not supplied, <em>all the rows</em> in the array are iterated
upon - you can also use the <a class="reference internal" href="#tables.Array.__iter__" title="tables.Array.__iter__"><tt class="xref py py-meth docutils literal"><span class="pre">Array.__iter__()</span></tt></a> special method for
that purpose. If you only want to iterate over a given <em>range of rows</em>
in the array, you may use the start, stop and step parameters.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">arrayInstance</span><span class="o">.</span><span class="n">iterrows</span><span class="p">(</span><span class="n">step</span><span class="o">=</span><span class="mi">4</span><span class="p">)]</span>
</pre></div>
</div>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>If the <em>start</em> parameter is provided and <em>stop</em> is None then the
array is iterated from <em>start</em> to the last line.
In PyTables < 3.0 only one element was returned.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Array.next">
<tt class="descclassname">Array.</tt><tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Array.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the next element of the array during an iteration.</p>
<p>The element is returned as an object of the current flavor.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Array.read">
<tt class="descclassname">Array.</tt><tt class="descname">read</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em>, <em>out=None</em><big>)</big><a class="headerlink" href="#tables.Array.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Get data in the array as an object of the current flavor.</p>
<p>The start, stop and step parameters can be used to select only a
<em>range of rows</em> in the array. Their meanings are the same as in
the built-in range() Python function, except that negative values
of step are not allowed yet. Moreover, if only start is specified,
then stop will be set to start + 1. If you do not specify neither
start nor stop, then <em>all the rows</em> in the array are selected.</p>
<p>The out parameter may be used to specify a NumPy array to receive
the output data. Note that the array must have the same size as
the data selected with the other parameters. Note that the array’s
datatype is not checked and no type casting is performed, so if it
does not match the datatype on disk, the output will not be correct.
Also, this parameter is only valid when the array’s flavor is set
to ‘numpy’. Otherwise, a TypeError will be raised.</p>
<p>When data is read from disk in NumPy format, the output will be
in the current system’s byteorder, regardless of how it is stored
on disk.
The exception is when an output buffer is supplied, in which case
the output will be in the byteorder of that output buffer.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Added the <em>out</em> parameter.</p>
</dd></dl>
</div>
<div class="section" id="array-special-methods">
<h3>Array special methods<a class="headerlink" href="#array-special-methods" title="Permalink to this headline">¶</a></h3>
<p>The following methods automatically trigger actions when an <a class="reference internal" href="#tables.Array" title="tables.Array"><tt class="xref py py-class docutils literal"><span class="pre">Array</span></tt></a>
instance is accessed in a special way (e.g. <tt class="docutils literal"><span class="pre">array[2:3,...,::2]</span></tt> will be
equivalent to a call to
<tt class="docutils literal"><span class="pre">array.__getitem__((slice(2,</span> <span class="pre">3,</span> <span class="pre">None),</span> <span class="pre">Ellipsis,</span> <span class="pre">slice(None,</span> <span class="pre">None,</span> <span class="pre">2))))</span></tt>.</p>
<dl class="method">
<dt id="tables.Array.__getitem__">
<tt class="descclassname">Array.</tt><tt class="descname">__getitem__</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#tables.Array.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a row, a range of rows or a slice from the array.</p>
<p>The set of tokens allowed for the key is the same as that for extended
slicing in Python (including the Ellipsis or ... token). The result is
an object of the current flavor; its shape depends on the kind of slice
used as key and the shape of the array itself.</p>
<p>Furthermore, NumPy-style fancy indexing, where a list of indices in a
certain axis is specified, is also supported. Note that only one list
per selection is supported right now. Finally, NumPy-style point and
boolean selections are supported as well.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">array1</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="c"># simple selection</span>
<span class="n">array2</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">1000</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span> <span class="c"># slice selection</span>
<span class="n">array3</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="p">::</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span><span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">:]</span> <span class="c"># general slice selection</span>
<span class="n">array4</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">10</span><span class="p">],</span> <span class="o">...</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="c"># fancy selection</span>
<span class="n">array5</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">array</span><span class="p">[:]</span> <span class="o">></span> <span class="mi">4</span><span class="p">)]</span> <span class="c"># point selection</span>
<span class="n">array6</span> <span class="o">=</span> <span class="n">array</span><span class="p">[</span><span class="n">array</span><span class="p">[:]</span> <span class="o">></span> <span class="mi">4</span><span class="p">]</span> <span class="c"># boolean selection</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.Array.__iter__">
<tt class="descclassname">Array.</tt><tt class="descname">__iter__</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Array.__iter__" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over the rows of the array.</p>
<p>This is equivalent to calling <a class="reference internal" href="#tables.Array.iterrows" title="tables.Array.iterrows"><tt class="xref py py-meth docutils literal"><span class="pre">Array.iterrows()</span></tt></a> with default
arguments, i.e. it iterates over <em>all the rows</em> in the array.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">array</span><span class="p">]</span>
</pre></div>
</div>
<p>Which is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">array</span><span class="o">.</span><span class="n">iterrows</span><span class="p">()]</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.Array.__setitem__">
<tt class="descclassname">Array.</tt><tt class="descname">__setitem__</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#tables.Array.__setitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a row, a range of rows or a slice in the array.</p>
<p>It takes different actions depending on the type of the key parameter:
if it is an integer, the corresponding array row is set to value (the
value is broadcast when needed). If key is a slice, the row slice
determined by it is set to value (as usual, if the slice to be updated
exceeds the actual shape of the array, only the values in the existing
range are updated).</p>
<p>If value is a multidimensional object, then its shape must be
compatible with the shape determined by key, otherwise, a ValueError
will be raised.</p>
<p>Furthermore, NumPy-style fancy indexing, where a list of indices in a
certain axis is specified, is also supported. Note that only one list
per selection is supported right now. Finally, NumPy-style point and
boolean selections are supported as well.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a1</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="mi">333</span> <span class="c"># assign an integer to a Integer Array row</span>
<span class="n">a2</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="s">'b'</span> <span class="c"># assign a string to a string Array row</span>
<span class="n">a3</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="mi">5</span> <span class="c"># broadcast 5 to slice 1:4</span>
<span class="n">a4</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">4</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="s">'xXx'</span> <span class="c"># broadcast 'xXx' to slice 1:4:2</span>
<span class="c"># General slice update (a5.shape = (4,3,2,8,5,10).</span>
<span class="n">a5</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="p">::</span><span class="mi">2</span><span class="p">,</span> <span class="mi">1</span><span class="p">:</span><span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">:]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">1728</span><span class="p">,</span> <span class="n">shape</span><span class="o">=</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">6</span><span class="p">))</span>
<span class="n">a6</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mi">10</span><span class="p">],</span> <span class="o">...</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">arr</span> <span class="c"># fancy selection</span>
<span class="n">a7</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">a6</span><span class="p">[:]</span> <span class="o">></span> <span class="mi">4</span><span class="p">)]</span> <span class="o">=</span> <span class="mi">4</span> <span class="c"># point selection + broadcast</span>
<span class="n">a8</span><span class="p">[</span><span class="n">arr</span> <span class="o">></span> <span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="n">arr2</span> <span class="c"># boolean selection</span>
</pre></div>
</div>
</dd></dl>
</div>
</div>
<div class="section" id="the-carray-class">
<span id="carrayclassdescr"></span><h2>The CArray class<a class="headerlink" href="#the-carray-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="tables.CArray">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">CArray</tt><big>(</big><em>parentnode</em>, <em>name</em>, <em>atom=None</em>, <em>shape=None</em>, <em>title=''</em>, <em>filters=None</em>, <em>chunkshape=None</em>, <em>byteorder=None</em>, <em>_log=True</em><big>)</big><a class="headerlink" href="#tables.CArray" title="Permalink to this definition">¶</a></dt>
<dd><p>This class represents homogeneous datasets in an HDF5 file.</p>
<p>The difference between a CArray and a normal Array (see
<a class="reference internal" href="#arrayclassdescr"><em>The Array class</em></a>), from which it inherits, is that a CArray
has a chunked layout and, as a consequence, it supports compression.
You can use datasets of this class to easily save or load arrays to
or from disk, with compression support included.</p>
<p>CArray includes all the instance variables and methods of Array.
Only those with different behavior are mentioned here.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters :</th><td class="field-body"><p class="first"><strong>parentnode</strong> :</p>
<blockquote>
<div><p>The parent <a class="reference internal" href="hierarchy_classes.html#tables.Group" title="tables.Group"><tt class="xref py py-class docutils literal"><span class="pre">Group</span></tt></a> object.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Renamed from <em>parentNode</em> to <em>parentnode</em>.</p>
</div></blockquote>
<p><strong>name</strong> : str</p>
<blockquote>
<div><p>The name of this node in its parent group.</p>
</div></blockquote>
<p><strong>atom</strong> :</p>
<blockquote>
<div><p>An <cite>Atom</cite> instance representing the <em>type</em> and <em>shape</em> of
the atomic objects to be saved.</p>
</div></blockquote>
<p><strong>shape</strong> :</p>
<blockquote>
<div><p>The shape of the new array.</p>
</div></blockquote>
<p><strong>title</strong> :</p>
<blockquote>
<div><p>A description for this node (it sets the <tt class="docutils literal"><span class="pre">TITLE</span></tt> HDF5
attribute on disk).</p>
</div></blockquote>
<p><strong>filters</strong> :</p>
<blockquote>
<div><p>An instance of the <cite>Filters</cite> class that provides
information about the desired I/O filters to be applied
during the life of this object.</p>
</div></blockquote>
<p><strong>chunkshape</strong> :</p>
<blockquote>
<div><p>The shape of the data chunk to be read or written in a
single HDF5 I/O operation. Filters are applied to those
chunks of data. The dimensionality of <cite>chunkshape</cite> must
be the same as that of <cite>shape</cite>. If <tt class="docutils literal"><span class="pre">None</span></tt>, a sensible
value is calculated (which is recommended).</p>
</div></blockquote>
<p><strong>byteorder</strong> :</p>
<blockquote class="last">
<div><p>The byteorder of the data <em>on disk</em>, specified as ‘little’
or ‘big’. If this is not specified, the byteorder is that
of the platform.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Examples</p>
<p>See below a small example of the use of the <cite>CArray</cite> class.
The code is available in <tt class="docutils literal"><span class="pre">examples/carray1.py</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span>
<span class="kn">import</span> <span class="nn">tables</span>
<span class="n">fileName</span> <span class="o">=</span> <span class="s">'carray1.h5'</span>
<span class="n">shape</span> <span class="o">=</span> <span class="p">(</span><span class="mi">200</span><span class="p">,</span> <span class="mi">300</span><span class="p">)</span>
<span class="n">atom</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">UInt8Atom</span><span class="p">()</span>
<span class="n">filters</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">Filters</span><span class="p">(</span><span class="n">complevel</span><span class="o">=</span><span class="mi">5</span><span class="p">,</span> <span class="n">complib</span><span class="o">=</span><span class="s">'zlib'</span><span class="p">)</span>
<span class="n">h5f</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">open_file</span><span class="p">(</span><span class="n">fileName</span><span class="p">,</span> <span class="s">'w'</span><span class="p">)</span>
<span class="n">ca</span> <span class="o">=</span> <span class="n">h5f</span><span class="o">.</span><span class="n">create_carray</span><span class="p">(</span><span class="n">h5f</span><span class="o">.</span><span class="n">root</span><span class="p">,</span> <span class="s">'carray'</span><span class="p">,</span> <span class="n">atom</span><span class="p">,</span> <span class="n">shape</span><span class="p">,</span>
<span class="n">filters</span><span class="o">=</span><span class="n">filters</span><span class="p">)</span>
<span class="c"># Fill a hyperslab in ``ca``.</span>
<span class="n">ca</span><span class="p">[</span><span class="mi">10</span><span class="p">:</span><span class="mi">60</span><span class="p">,</span> <span class="mi">20</span><span class="p">:</span><span class="mi">70</span><span class="p">]</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">ones</span><span class="p">((</span><span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">))</span>
<span class="n">h5f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
<span class="c"># Re-open a read another hyperslab</span>
<span class="n">h5f</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">open_file</span><span class="p">(</span><span class="n">fileName</span><span class="p">)</span>
<span class="k">print</span> <span class="n">h5f</span>
<span class="k">print</span> <span class="n">h5f</span><span class="o">.</span><span class="n">root</span><span class="o">.</span><span class="n">carray</span><span class="p">[</span><span class="mi">8</span><span class="p">:</span><span class="mi">12</span><span class="p">,</span> <span class="mi">18</span><span class="p">:</span><span class="mi">22</span><span class="p">]</span>
<span class="n">h5f</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The output for the previous script is something like:</p>
<div class="highlight-python"><pre>carray1.h5 (File) ''
Last modif.: 'Thu Apr 12 10:15:38 2007'
Object Tree:
/ (RootGroup) ''
/carray (CArray(200, 300), shuffle, zlib(5)) ''
[[0 0 0 0]
[0 0 0 0]
[0 0 1 1]
[0 0 1 1]]</pre>
</div>
</dd></dl>
</div>
<div class="section" id="the-earray-class">
<span id="earrayclassdescr"></span><h2>The EArray class<a class="headerlink" href="#the-earray-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="tables.EArray">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">EArray</tt><big>(</big><em>parentnode</em>, <em>name</em>, <em>atom=None</em>, <em>shape=None</em>, <em>title=''</em>, <em>filters=None</em>, <em>expectedrows=None</em>, <em>chunkshape=None</em>, <em>byteorder=None</em>, <em>_log=True</em><big>)</big><a class="headerlink" href="#tables.EArray" title="Permalink to this definition">¶</a></dt>
<dd><p>This class represents extendable, homogeneous datasets in an HDF5 file.</p>
<p>The main difference between an EArray and a CArray (see
<a class="reference internal" href="#carrayclassdescr"><em>The CArray class</em></a>), from which it inherits, is that the former
can be enlarged along one of its dimensions, the <em>enlargeable
dimension</em>. That means that the <a class="reference internal" href="hierarchy_classes.html#tables.Leaf.extdim" title="tables.Leaf.extdim"><tt class="xref py py-attr docutils literal"><span class="pre">Leaf.extdim</span></tt></a> attribute (see
<a class="reference internal" href="hierarchy_classes.html#tables.Leaf" title="tables.Leaf"><tt class="xref py py-class docutils literal"><span class="pre">Leaf</span></tt></a>) of any EArray instance will always be non-negative.
Multiple enlargeable dimensions might be supported in the future.</p>
<p>New rows can be added to the end of an enlargeable array by using the
<a class="reference internal" href="#tables.EArray.append" title="tables.EArray.append"><tt class="xref py py-meth docutils literal"><span class="pre">EArray.append()</span></tt></a> method.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters :</th><td class="field-body"><p class="first"><strong>parentnode</strong> :</p>
<blockquote>
<div><p>The parent <a class="reference internal" href="hierarchy_classes.html#tables.Group" title="tables.Group"><tt class="xref py py-class docutils literal"><span class="pre">Group</span></tt></a> object.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Renamed from <em>parentNode</em> to <em>parentnode</em>.</p>
</div></blockquote>
<p><strong>name</strong> : str</p>
<blockquote>
<div><p>The name of this node in its parent group.</p>
</div></blockquote>
<p><strong>atom</strong> :</p>
<blockquote>
<div><p>An <cite>Atom</cite> instance representing the <em>type</em> and <em>shape</em>
of the atomic objects to be saved.</p>
</div></blockquote>
<p><strong>shape</strong> :</p>
<blockquote>
<div><p>The shape of the new array. One (and only one) of
the shape dimensions <em>must</em> be 0. The dimension being 0
means that the resulting <cite>EArray</cite> object can be extended
along it. Multiple enlargeable dimensions are not supported
right now.</p>
</div></blockquote>
<p><strong>title</strong> :</p>
<blockquote>
<div><p>A description for this node (it sets the <tt class="docutils literal"><span class="pre">TITLE</span></tt>
HDF5 attribute on disk).</p>
</div></blockquote>
<p><strong>filters</strong> :</p>
<blockquote>
<div><p>An instance of the <cite>Filters</cite> class that provides information
about the desired I/O filters to be applied during the life
of this object.</p>
</div></blockquote>
<p><strong>expectedrows</strong> :</p>
<blockquote>
<div><p>A user estimate about the number of row elements that will
be added to the growable dimension in the <cite>EArray</cite> node.
If not provided, the default value is <tt class="docutils literal"><span class="pre">EXPECTED_ROWS_EARRAY</span></tt>
(see <tt class="docutils literal"><span class="pre">tables/parameters.py</span></tt>). If you plan to create either
a much smaller or a much bigger <cite>EArray</cite> try providing a guess;
this will optimize the HDF5 B-Tree creation and management
process time and the amount of memory used.</p>
</div></blockquote>
<p><strong>chunkshape</strong> :</p>
<blockquote>
<div><p>The shape of the data chunk to be read or written in a single
HDF5 I/O operation. Filters are applied to those chunks of data.
The dimensionality of <cite>chunkshape</cite> must be the same as that of
<cite>shape</cite> (beware: no dimension should be 0 this time!).
If <tt class="docutils literal"><span class="pre">None</span></tt>, a sensible value is calculated based on the
<cite>expectedrows</cite> parameter (which is recommended).</p>
</div></blockquote>
<p><strong>byteorder</strong> :</p>
<blockquote class="last">
<div><p>The byteorder of the data <em>on disk</em>, specified as ‘little’ or
‘big’. If this is not specified, the byteorder is that of the
platform.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Examples</p>
<p>See below a small example of the use of the <cite>EArray</cite> class. The
code is available in <tt class="docutils literal"><span class="pre">examples/earray1.py</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">tables</span>
<span class="kn">import</span> <span class="nn">numpy</span>
<span class="n">fileh</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">open_file</span><span class="p">(</span><span class="s">'earray1.h5'</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s">'w'</span><span class="p">)</span>
<span class="n">a</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">StringAtom</span><span class="p">(</span><span class="n">itemsize</span><span class="o">=</span><span class="mi">8</span><span class="p">)</span>
<span class="c"># Use ``a`` as the object type for the enlargeable array.</span>
<span class="n">array_c</span> <span class="o">=</span> <span class="n">fileh</span><span class="o">.</span><span class="n">create_earray</span><span class="p">(</span><span class="n">fileh</span><span class="o">.</span><span class="n">root</span><span class="p">,</span> <span class="s">'array_c'</span><span class="p">,</span> <span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="mi">0</span><span class="p">,),</span>
<span class="s">"Chars"</span><span class="p">)</span>
<span class="n">array_c</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="s">'a'</span><span class="o">*</span><span class="mi">2</span><span class="p">,</span> <span class="s">'b'</span><span class="o">*</span><span class="mi">4</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="s">'S8'</span><span class="p">))</span>
<span class="n">array_c</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="s">'a'</span><span class="o">*</span><span class="mi">6</span><span class="p">,</span> <span class="s">'b'</span><span class="o">*</span><span class="mi">8</span><span class="p">,</span> <span class="s">'c'</span><span class="o">*</span><span class="mi">10</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="s">'S8'</span><span class="p">))</span>
<span class="c"># Read the string ``EArray`` we have created on disk.</span>
<span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">array_c</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'array_c[</span><span class="si">%s</span><span class="s">] => </span><span class="si">%r</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">array_c</span><span class="o">.</span><span class="n">nrow</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span>
<span class="c"># Close the file.</span>
<span class="n">fileh</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The output for the previous script is something like:</p>
<div class="highlight-python"><pre>array_c[0] => 'aa'
array_c[1] => 'bbbb'
array_c[2] => 'aaaaaa'
array_c[3] => 'bbbbbbbb'
array_c[4] => 'cccccccc'</pre>
</div>
</dd></dl>
<div class="section" id="earray-methods">
<span id="earraymethodsdescr"></span><h3>EArray methods<a class="headerlink" href="#earray-methods" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.EArray.append">
<tt class="descclassname">EArray.</tt><tt class="descname">append</tt><big>(</big><em>sequence</em><big>)</big><a class="headerlink" href="#tables.EArray.append" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a sequence of data to the end of the dataset.</p>
<p>The sequence must have the same type as the array; otherwise a
TypeError is raised. In the same way, the dimensions of the
sequence must conform to the shape of the array, that is, all
dimensions must match, with the exception of the enlargeable
dimension, which can be of any length (even 0!). If the shape
of the sequence is invalid, a ValueError is raised.</p>
</dd></dl>
</div>
</div>
<div class="section" id="the-vlarray-class">
<span id="vlarrayclassdescr"></span><h2>The VLArray class<a class="headerlink" href="#the-vlarray-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="tables.VLArray">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">VLArray</tt><big>(</big><em>parentnode</em>, <em>name</em>, <em>atom=None</em>, <em>title=''</em>, <em>filters=None</em>, <em>expectedrows=None</em>, <em>chunkshape=None</em>, <em>byteorder=None</em>, <em>_log=True</em><big>)</big><a class="headerlink" href="#tables.VLArray" title="Permalink to this definition">¶</a></dt>
<dd><p>This class represents variable length (ragged) arrays in an HDF5 file.</p>
<p>Instances of this class represent array objects in the object tree
with the property that their rows can have a <em>variable</em> number of
homogeneous elements, called <em>atoms</em>. Like Table datasets (see
<a class="reference internal" href="structured_storage.html#tableclassdescr"><em>The Table class</em></a>), variable length arrays can have only one
dimension, and the elements (atoms) of their rows can be fully
multidimensional. VLArray objects do also support compression.</p>
<p>When reading a range of rows from a VLArray, you will <em>always</em> get
a Python list of objects of the current flavor (each of them for a
row), which may have different lengths.</p>
<p>This class provides methods to write or read data to or from
variable length array objects in the file. Note that it also
inherits all the public attributes and methods that Leaf (see
<a class="reference internal" href="hierarchy_classes.html#leafclassdescr"><em>The Leaf class</em></a>) already provides.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters :</th><td class="field-body"><p class="first"><strong>parentnode</strong> :</p>
<blockquote>
<div><p>The parent <a class="reference internal" href="hierarchy_classes.html#tables.Group" title="tables.Group"><tt class="xref py py-class docutils literal"><span class="pre">Group</span></tt></a> object.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Renamed from <em>parentNode</em> to <em>parentnode</em>.</p>
</div></blockquote>
<p><strong>name</strong> : str</p>
<blockquote>
<div><p>The name of this node in its parent group.</p>
</div></blockquote>
<p><strong>atom</strong> :</p>
<blockquote>
<div><p>An <cite>Atom</cite> instance representing the <em>type</em> and <em>shape</em> of the atomic
objects to be saved.</p>
</div></blockquote>
<p><strong>title</strong> :</p>
<blockquote>
<div><p>A description for this node (it sets the <tt class="docutils literal"><span class="pre">TITLE</span></tt> HDF5 attribute on
disk).</p>
</div></blockquote>
<p><strong>filters</strong> :</p>
<blockquote>
<div><p>An instance of the <cite>Filters</cite> class that provides information about the
desired I/O filters to be applied during the life of this object.</p>
</div></blockquote>
<p><strong>expectedrows</strong> :</p>
<blockquote>
<div><p>A user estimate about the number of row elements that will
be added to the growable dimension in the <cite>VLArray</cite> node.
If not provided, the default value is <tt class="docutils literal"><span class="pre">EXPECTED_ROWS_VLARRAY</span></tt>
(see <tt class="docutils literal"><span class="pre">tables/parameters.py</span></tt>). If you plan to create either
a much smaller or a much bigger <cite>VLArray</cite> try providing a guess;
this will optimize the HDF5 B-Tree creation and management
process time and the amount of memory used.</p>
<p class="versionadded">
<span class="versionmodified">New in version 3.0.</span></p>
</div></blockquote>
<p><strong>chunkshape</strong> :</p>
<blockquote>
<div><p>The shape of the data chunk to be read or written in a single HDF5 I/O
operation. Filters are applied to those chunks of data. The
dimensionality of <cite>chunkshape</cite> must be 1. If <tt class="docutils literal"><span class="pre">None</span></tt>, a sensible
value is calculated (which is recommended).</p>
</div></blockquote>
<p><strong>byteorder</strong> :</p>
<blockquote>
<div><p>The byteorder of the data <em>on disk</em>, specified as ‘little’ or ‘big’.
If this is not specified, the byteorder is that of the platform.</p>
</div></blockquote>
<p><strong>.. versionchanged:: 3.0</strong> :</p>
<blockquote class="last">
<div><p>The <em>expectedsizeinMB</em> parameter has been replaced by <em>expectedrows</em>.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Examples</p>
<p>See below a small example of the use of the VLArray class. The code is
available in <tt class="file docutils literal"><span class="pre">examples/vlarray1.py</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">tables</span>
<span class="kn">from</span> <span class="nn">numpy</span> <span class="kn">import</span> <span class="o">*</span>
<span class="c"># Create a VLArray:</span>
<span class="n">fileh</span> <span class="o">=</span> <span class="n">tables</span><span class="o">.</span><span class="n">open_file</span><span class="p">(</span><span class="s">'vlarray1.h5'</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s">'w'</span><span class="p">)</span>
<span class="n">vlarray</span> <span class="o">=</span> <span class="n">fileh</span><span class="o">.</span><span class="n">create_vlarray</span><span class="p">(</span><span class="n">fileh</span><span class="o">.</span><span class="n">root</span><span class="p">,</span> <span class="s">'vlarray1'</span><span class="p">,</span>
<span class="n">tables</span><span class="o">.</span><span class="n">Int32Atom</span><span class="p">(</span><span class="n">shape</span><span class="o">=</span><span class="p">()),</span>
<span class="s">"ragged array of ints"</span><span class="p">,</span>
<span class="n">filters</span><span class="o">=</span><span class="n">tables</span><span class="o">.</span><span class="n">Filters</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>
<span class="c"># Append some (variable length) rows:</span>
<span class="n">vlarray</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">array</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">]))</span>
<span class="n">vlarray</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">array</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">]))</span>
<span class="n">vlarray</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">8</span><span class="p">])</span>
<span class="c"># Now, read it through an iterator:</span>
<span class="k">print</span> <span class="s">'-->'</span><span class="p">,</span> <span class="n">vlarray</span><span class="o">.</span><span class="n">title</span>
<span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">vlarray</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">[</span><span class="si">%d</span><span class="s">]--> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">vlarray</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">vlarray</span><span class="o">.</span><span class="n">nrow</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
<span class="c"># Now, do the same with native Python strings.</span>
<span class="n">vlarray2</span> <span class="o">=</span> <span class="n">fileh</span><span class="o">.</span><span class="n">create_vlarray</span><span class="p">(</span><span class="n">fileh</span><span class="o">.</span><span class="n">root</span><span class="p">,</span> <span class="s">'vlarray2'</span><span class="p">,</span>
<span class="n">tables</span><span class="o">.</span><span class="n">StringAtom</span><span class="p">(</span><span class="n">itemsize</span><span class="o">=</span><span class="mi">2</span><span class="p">),</span>
<span class="s">"ragged array of strings"</span><span class="p">,</span>
<span class="n">filters</span><span class="o">=</span><span class="n">tables</span><span class="o">.</span><span class="n">Filters</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>
<span class="n">vlarray2</span><span class="o">.</span><span class="n">flavor</span> <span class="o">=</span> <span class="s">'python'</span>
<span class="c"># Append some (variable length) rows:</span>
<span class="k">print</span> <span class="s">'-->'</span><span class="p">,</span> <span class="n">vlarray2</span><span class="o">.</span><span class="n">title</span>
<span class="n">vlarray2</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">'5'</span><span class="p">,</span> <span class="s">'66'</span><span class="p">])</span>
<span class="n">vlarray2</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">'5'</span><span class="p">,</span> <span class="s">'6'</span><span class="p">,</span> <span class="s">'77'</span><span class="p">])</span>
<span class="n">vlarray2</span><span class="o">.</span><span class="n">append</span><span class="p">([</span><span class="s">'5'</span><span class="p">,</span> <span class="s">'6'</span><span class="p">,</span> <span class="s">'9'</span><span class="p">,</span> <span class="s">'88'</span><span class="p">])</span>
<span class="c"># Now, read it through an iterator:</span>
<span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">vlarray2</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">[</span><span class="si">%d</span><span class="s">]--> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">vlarray2</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">vlarray2</span><span class="o">.</span><span class="n">nrow</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span>
<span class="c"># Close the file.</span>
<span class="n">fileh</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The output for the previous script is something like:</p>
<div class="highlight-python"><pre>--> ragged array of ints
vlarray1[0]--> [5 6]
vlarray1[1]--> [5 6 7]
vlarray1[2]--> [5 6 9 8]
--> ragged array of strings
vlarray2[0]--> ['5', '66']
vlarray2[1]--> ['5', '6', '77']
vlarray2[2]--> ['5', '6', '9', '88']</pre>
</div>
<p class="rubric">VLArray attributes</p>
<p>The instance variables below are provided in addition to those in
Leaf (see <a class="reference internal" href="hierarchy_classes.html#leafclassdescr"><em>The Leaf class</em></a>).</p>
<dl class="attribute">
<dt id="tables.VLArray.atom">
<tt class="descname">atom</tt><a class="headerlink" href="#tables.VLArray.atom" title="Permalink to this definition">¶</a></dt>
<dd><p>An Atom (see <a class="reference internal" href="declarative_classes.html#atomclassdescr"><em>The Atom class and its descendants</em></a>)
instance representing the <em>type</em> and
<em>shape</em> of the atomic objects to be
saved. You may use a <em>pseudo-atom</em> for
storing a serialized object or variable length string per row.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.VLArray.flavor">
<tt class="descname">flavor</tt><a class="headerlink" href="#tables.VLArray.flavor" title="Permalink to this definition">¶</a></dt>
<dd><p>The type of data object read from this leaf.</p>
<p>Please note that when reading several rows of VLArray data,
the flavor only applies to the <em>components</em> of the returned
Python list, not to the list itself.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.VLArray.nrow">
<tt class="descname">nrow</tt><a class="headerlink" href="#tables.VLArray.nrow" title="Permalink to this definition">¶</a></dt>
<dd><p>On iterators, this is the index of the current row.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.VLArray.nrows">
<tt class="descname">nrows</tt><a class="headerlink" href="#tables.VLArray.nrows" title="Permalink to this definition">¶</a></dt>
<dd><p>The current number of rows in the array.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.VLArray.extdim">
<tt class="descname">extdim</tt><a class="headerlink" href="#tables.VLArray.extdim" title="Permalink to this definition">¶</a></dt>
<dd><p>The index of the enlargeable dimension (always 0 for vlarrays).</p>
</dd></dl>
</dd></dl>
<div class="section" id="vlarray-properties">
<h3>VLArray properties<a class="headerlink" href="#vlarray-properties" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="tables.VLArray.size_on_disk">
<tt class="descclassname">VLArray.</tt><tt class="descname">size_on_disk</tt><a class="headerlink" href="#tables.VLArray.size_on_disk" title="Permalink to this definition">¶</a></dt>
<dd><p>The HDF5 library does not include a function to determine size_on_disk
for variable-length arrays. Accessing this attribute will raise a
NotImplementedError.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.VLArray.size_in_memory">
<tt class="descclassname">VLArray.</tt><tt class="descname">size_in_memory</tt><a class="headerlink" href="#tables.VLArray.size_in_memory" title="Permalink to this definition">¶</a></dt>
<dd><p>The size of this array’s data in bytes when it is fully loaded
into memory.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When data is stored in a VLArray using the ObjectAtom type,
it is first serialized using pickle, and then converted to
a NumPy array suitable for storage in an HDF5 file.
This attribute will return the size of that NumPy
representation. If you wish to know the size of the Python
objects after they are loaded from disk, you can use this
<a class="reference external" href="http://code.activestate.com/recipes/577504/">ActiveState recipe</a>.</p>
</div>
</dd></dl>
</div>
<div class="section" id="vlarray-methods">
<h3>VLArray methods<a class="headerlink" href="#vlarray-methods" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.VLArray.append">
<tt class="descclassname">VLArray.</tt><tt class="descname">append</tt><big>(</big><em>sequence</em><big>)</big><a class="headerlink" href="#tables.VLArray.append" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a sequence of data to the end of the dataset.</p>
<p>This method appends the objects in the sequence to a <em>single row</em> in
this array. The type and shape of individual objects must be compliant
with the atoms in the array. In the case of serialized objects and
variable length strings, the object or string to append is itself the
sequence.</p>
</dd></dl>
<dl class="method">
<dt id="tables.VLArray.get_enum">
<tt class="descclassname">VLArray.</tt><tt class="descname">get_enum</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.VLArray.get_enum" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the enumerated type associated with this array.</p>
<p>If this array is of an enumerated type, the corresponding Enum instance
(see <a class="reference internal" href="helper_classes.html#enumclassdescr"><em>The Enum class</em></a>) is returned. If it is not of an enumerated
type, a TypeError is raised.</p>
</dd></dl>
<dl class="method">
<dt id="tables.VLArray.iterrows">
<tt class="descclassname">VLArray.</tt><tt class="descname">iterrows</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.VLArray.iterrows" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over the rows of the array.</p>
<p>This method returns an iterator yielding an object of the current
flavor for each selected row in the array.</p>
<p>If a range is not supplied, <em>all the rows</em> in the array are iterated
upon. You can also use the <a class="reference internal" href="#tables.VLArray.__iter__" title="tables.VLArray.__iter__"><tt class="xref py py-meth docutils literal"><span class="pre">VLArray.__iter__()</span></tt></a> special method for
that purpose. If you only want to iterate over a given <em>range of rows</em>
in the array, you may use the start, stop and step parameters.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">vlarray</span><span class="o">.</span><span class="n">iterrows</span><span class="p">(</span><span class="n">step</span><span class="o">=</span><span class="mi">4</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">[</span><span class="si">%d</span><span class="s">]--> </span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">vlarray</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">vlarray</span><span class="o">.</span><span class="n">nrow</span><span class="p">,</span> <span class="n">row</span><span class="p">)</span>
</pre></div>
</div>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>If the <em>start</em> parameter is provided and <em>stop</em> is None then the
array is iterated from <em>start</em> to the last line.
In PyTables < 3.0 only one element was returned.</p>
</dd></dl>
<dl class="method">
<dt id="tables.VLArray.next">
<tt class="descclassname">VLArray.</tt><tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.VLArray.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the next element of the array during an iteration.</p>
<p>The element is returned as a list of objects of the current flavor.</p>
</dd></dl>
<dl class="method">
<dt id="tables.VLArray.read">
<tt class="descclassname">VLArray.</tt><tt class="descname">read</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=1</em><big>)</big><a class="headerlink" href="#tables.VLArray.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Get data in the array as a list of objects of the current flavor.</p>
<p>Please note that, as the lengths of the different rows are variable,
the returned value is a <em>Python list</em> (not an array of the current
flavor), with as many entries as specified rows in the range
parameters.</p>
<p>The start, stop and step parameters can be used to select only a
<em>range of rows</em> in the array. Their meanings are the same as in
the built-in range() Python function, except that negative values
of step are not allowed yet. Moreover, if only start is specified,
then stop will be set to start + 1. If you do not specify neither
start nor stop, then <em>all the rows</em> in the array are selected.</p>
</dd></dl>
</div>
<div class="section" id="vlarray-special-methods">
<h3>VLArray special methods<a class="headerlink" href="#vlarray-special-methods" title="Permalink to this headline">¶</a></h3>
<p>The following methods automatically trigger actions when a <a class="reference internal" href="#tables.VLArray" title="tables.VLArray"><tt class="xref py py-class docutils literal"><span class="pre">VLArray</span></tt></a>
instance is accessed in a special way (e.g., vlarray[2:5] will be equivalent
to a call to vlarray.__getitem__(slice(2, 5, None)).</p>
<dl class="method">
<dt id="tables.VLArray.__getitem__">
<tt class="descclassname">VLArray.</tt><tt class="descname">__getitem__</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#tables.VLArray.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a row or a range of rows from the array.</p>
<p>If key argument is an integer, the corresponding array row is returned
as an object of the current flavor. If key is a slice, the range of
rows determined by it is returned as a list of objects of the current
flavor.</p>
<p>In addition, NumPy-style point selections are supported. In
particular, if key is a list of row coordinates, the set of rows
determined by it is returned. Furthermore, if key is an array of
boolean values, only the coordinates where key is True are returned.
Note that for the latter to work it is necessary that key list would
contain exactly as many rows as the array has.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a_row</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span>
<span class="n">a_list</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[</span><span class="mi">4</span><span class="p">:</span><span class="mi">1000</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span>
<span class="n">a_list2</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[[</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">]]</span> <span class="c"># get list of coords</span>
<span class="n">a_list3</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[[</span><span class="mi">0</span><span class="p">,</span><span class="o">-</span><span class="mi">2</span><span class="p">]]</span> <span class="c"># negative values accepted</span>
<span class="n">a_list4</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[</span><span class="n">numpy</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="bp">True</span><span class="p">,</span><span class="o">...</span><span class="p">,</span><span class="bp">False</span><span class="p">])]</span> <span class="c"># array of bools</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.VLArray.__iter__">
<tt class="descclassname">VLArray.</tt><tt class="descname">__iter__</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.VLArray.__iter__" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over the rows of the array.</p>
<p>This is equivalent to calling <a class="reference internal" href="#tables.VLArray.iterrows" title="tables.VLArray.iterrows"><tt class="xref py py-meth docutils literal"><span class="pre">VLArray.iterrows()</span></tt></a> with default
arguments, i.e. it iterates over <em>all the rows</em> in the array.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">vlarray</span><span class="p">]</span>
</pre></div>
</div>
<p>Which is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">result</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">vlarray</span><span class="o">.</span><span class="n">iterrows</span><span class="p">()]</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.VLArray.__setitem__">
<tt class="descclassname">VLArray.</tt><tt class="descname">__setitem__</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#tables.VLArray.__setitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a row, or set of rows, in the array.</p>
<p>It takes different actions depending on the type of the <em>key</em>
parameter: if it is an integer, the corresponding table row is
set to <em>value</em> (a record or sequence capable of being converted
to the table structure). If <em>key</em> is a slice, the row slice
determined by it is set to <em>value</em> (a record array or sequence
of rows capable of being converted to the table structure).</p>
<p>In addition, NumPy-style point selections are supported. In
particular, if key is a list of row coordinates, the set of rows
determined by it is set to value. Furthermore, if key is an array of
boolean values, only the coordinates where key is True are set to
values from value. Note that for the latter to work it is necessary
that key list would contain exactly as many rows as the table has.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When updating the rows of a VLArray object which uses a
pseudo-atom, there is a problem: you can only update values
with <em>exactly</em> the same size in bytes than the original row.
This is very difficult to meet with object pseudo-atoms,
because <tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt> applied on a Python object does not
guarantee to return the same number of bytes than over another
object, even if they are of the same class.
This effectively limits the kinds of objects than can be
updated in variable-length arrays.</p>
</div>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">vlarray</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">*</span> <span class="mi">2</span> <span class="o">+</span> <span class="mi">3</span>
<span class="n">vlarray</span><span class="p">[</span><span class="mi">99</span><span class="p">]</span> <span class="o">=</span> <span class="n">arange</span><span class="p">(</span><span class="mi">96</span><span class="p">)</span> <span class="o">*</span> <span class="mi">2</span> <span class="o">+</span> <span class="mi">3</span>
<span class="c"># Negative values for the index are supported.</span>
<span class="n">vlarray</span><span class="p">[</span><span class="o">-</span><span class="mi">99</span><span class="p">]</span> <span class="o">=</span> <span class="n">vlarray</span><span class="p">[</span><span class="mi">5</span><span class="p">]</span> <span class="o">*</span> <span class="mi">2</span> <span class="o">+</span> <span class="mi">3</span>
<span class="n">vlarray</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">30</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">list_of_rows</span>
<span class="n">vlarray</span><span class="p">[[</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">]]</span> <span class="o">=</span> <span class="n">new_1_and_3_rows</span>
</pre></div>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo-pytables-small.png" alt="Logo"/>
</a></p>
<h3><a href="../../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Homogenous storage classes</a><ul>
<li><a class="reference internal" href="#the-array-class">The Array class</a><ul>
<li><a class="reference internal" href="#array-instance-variables">Array instance variables</a></li>
<li><a class="reference internal" href="#array-methods">Array methods</a></li>
<li><a class="reference internal" href="#array-special-methods">Array special methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-carray-class">The CArray class</a></li>
<li><a class="reference internal" href="#the-earray-class">The EArray class</a><ul>
<li><a class="reference internal" href="#earray-methods">EArray methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-vlarray-class">The VLArray class</a><ul>
<li><a class="reference internal" href="#vlarray-properties">VLArray properties</a></li>
<li><a class="reference internal" href="#vlarray-methods">VLArray methods</a></li>
<li><a class="reference internal" href="#vlarray-special-methods">VLArray special methods</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="structured_storage.html"
title="previous chapter">Structured storage classes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="link_classes.html"
title="next chapter">Link classes</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/usersguide/libref/homogenous_storage.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="relbar-bottom">
<div class="related">
<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="../../py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="../../np-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="link_classes.html" title="Link classes"
>next</a> </li>
<li class="right" >
<a href="structured_storage.html" title="Structured storage classes"
>previous</a> </li>
<li><a href="../../index.html">PyTables 3.0.0 documentation</a> »</li>
<li><a href="../index.html" >PyTables User’s Guide</a> »</li>
<li><a href="../libref.html" >Library Reference</a> »</li>
</ul>
</div>
</div>
<div class="footer">
© Copyright 2011-2013, PyTables maintainers.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
<!-- cloud_sptheme 1.3 -->
</body>
</html>
