<!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>Structured 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="Homogenous storage classes" href="homogenous_storage.html" />
<link rel="prev" title="Hierarchy definition classes" href="hierarchy_classes.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="homogenous_storage.html" title="Homogenous storage classes"
accesskey="N">next</a> </li>
<li class="right" >
<a href="hierarchy_classes.html" title="Hierarchy definition 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="structured-storage-classes">
<h1>Structured storage classes<a class="headerlink" href="#structured-storage-classes" title="Permalink to this headline">¶</a></h1>
<div class="section" id="the-table-class">
<span id="tableclassdescr"></span><h2>The Table class<a class="headerlink" href="#the-table-class" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="tables.Table">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">Table</tt><big>(</big><em>parentnode</em>, <em>name</em>, <em>description=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.Table" title="Permalink to this definition">¶</a></dt>
<dd><p>This class represents heterogeneous datasets in an HDF5 file.</p>
<p>Tables are leaves (see the Leaf class in <a class="reference internal" href="hierarchy_classes.html#leafclassdescr"><em>The Leaf class</em></a>) whose data
consists of a unidimensional sequence of <em>rows</em>, where each row contains
one or more <em>fields</em>. Fields have an associated unique <em>name</em> and
<em>position</em>, with the first field having position 0. All rows have the same
fields, which are arranged in <em>columns</em>.</p>
<p>Fields can have any type supported by the Col class (see
<a class="reference internal" href="declarative_classes.html#colclassdescr"><em>The Col class and its descendants</em></a>) and its descendants, which support multidimensional
data. Moreover, a field can be <em>nested</em> (to an arbitrary depth), meaning
that it includes further fields inside. A field named x inside a nested
field a in a table can be accessed as the field a/x (its <em>path name</em>) from
the table.</p>
<p>The structure of a table is declared by its description, which is made
available in the Table.description attribute (see <a class="reference internal" href="#tables.Table" title="tables.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>).</p>
<p>This class provides new methods to read, write and search table data
efficiently. It also provides special Python methods to allow accessing
the table as a normal sequence or array (with extended slicing supported).</p>
<p>PyTables supports <em>in-kernel</em> searches working simultaneously on several
columns using complex conditions. These are faster than selections using
Python expressions. See the <a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> method for more
information on in-kernel searches.</p>
<p>Non-nested columns can be <em>indexed</em>. Searching an indexed column can be
several times faster than searching a non-nested one. Search methods
automatically take advantage of indexing where available.</p>
<p>When iterating a table, an object from the Row (see <a class="reference internal" href="#rowclassdescr"><em>The Row class</em></a>)
class is used. This object allows to read and write data one row at a
time, as well as to perform queries which are not supported by in-kernel
syntax (at a much lower speed, of course).</p>
<p>Objects of this class support access to individual columns via <em>natural
naming</em> through the <a class="reference internal" href="#tables.Table.cols" title="tables.Table.cols"><tt class="xref py py-attr docutils literal"><span class="pre">Table.cols</span></tt></a> accessor. Nested columns are
mapped to Cols instances, and non-nested ones to Column instances.
See the Column class in <a class="reference internal" href="#columnclassdescr"><em>The Column class</em></a> for examples of this
feature.</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>description</strong> :</p>
<blockquote>
<div><p>An IsDescription subclass or a dictionary where the keys are the field
names, and the values the type definitions. In addition, a pure NumPy
dtype is accepted. If None, the table metadata is read from disk,
else, it’s taken from previous parameters.</p>
</div></blockquote>
<p><strong>title</strong> :</p>
<blockquote>
<div><p>Sets a TITLE attribute on the HDF5 table entity.</p>
</div></blockquote>
<p><strong>filters</strong> : Filters</p>
<blockquote>
<div><p>An instance of the Filters 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 rows that will be on table. If not
provided, the default value is <tt class="docutils literal"><span class="pre">EXPECTED_ROWS_TABLE</span></tt> (see
<tt class="docutils literal"><span class="pre">tables/parameters.py</span></tt>). If you plan to save bigger tables, try
providing a guess; this will optimize the HDF5 B-Tree creation and
management process time and memory used.</p>
</div></blockquote>
<p><strong>chunkshape</strong> :</p>
<blockquote>
<div><p>The shape of the data chunk to be read or written as a single HDF5 I/O
operation. The filters are applied to those chunks of data. Its rank
for tables has to be 1. 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, unless
you passed a recarray as the <cite>description</cite>, in which case the recarray
byteorder will be chosen.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Notes</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>). Please note that there are several
col* dictionaries to ease retrieving information about a column
directly by its path name, avoiding the need to walk through
Table.description or Table.cols.</p>
<p class="rubric">Table attributes</p>
<dl class="attribute">
<dt id="tables.Table.coldescrs">
<tt class="descname">coldescrs</tt><a class="headerlink" href="#tables.Table.coldescrs" title="Permalink to this definition">¶</a></dt>
<dd><p>Maps the name of a column to its Col description (see
<a class="reference internal" href="declarative_classes.html#colclassdescr"><em>The Col class and its descendants</em></a>).</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.coldflts">
<tt class="descname">coldflts</tt><a class="headerlink" href="#tables.Table.coldflts" title="Permalink to this definition">¶</a></dt>
<dd><p>Maps the name of a column to its default value.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.coldtypes">
<tt class="descname">coldtypes</tt><a class="headerlink" href="#tables.Table.coldtypes" title="Permalink to this definition">¶</a></dt>
<dd><p>Maps the name of a column to its NumPy data type.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.colindexed">
<tt class="descname">colindexed</tt><a class="headerlink" href="#tables.Table.colindexed" title="Permalink to this definition">¶</a></dt>
<dd><p>Is the column which name is used as a key indexed?</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.colinstances">
<tt class="descname">colinstances</tt><a class="headerlink" href="#tables.Table.colinstances" title="Permalink to this definition">¶</a></dt>
<dd><p>Maps the name of a column to its Column (see
<a class="reference internal" href="#columnclassdescr"><em>The Column class</em></a>) or Cols (see <a class="reference internal" href="#colsclassdescr"><em>The Cols class</em></a>)
instance.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.colnames">
<tt class="descname">colnames</tt><a class="headerlink" href="#tables.Table.colnames" title="Permalink to this definition">¶</a></dt>
<dd><p>A list containing the names of <em>top-level</em> columns in the table.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.colpathnames">
<tt class="descname">colpathnames</tt><a class="headerlink" href="#tables.Table.colpathnames" title="Permalink to this definition">¶</a></dt>
<dd><p>A list containing the pathnames of <em>bottom-level</em> columns in
the table.</p>
<p>These are the leaf columns obtained when walking the table
description left-to-right, bottom-first. Columns inside a
nested column have slashes (/) separating name components in
their pathname.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.cols">
<tt class="descname">cols</tt><a class="headerlink" href="#tables.Table.cols" title="Permalink to this definition">¶</a></dt>
<dd><p>A Cols instance that provides <em>natural naming</em> access to
non-nested (Column, see <a class="reference internal" href="#columnclassdescr"><em>The Column class</em></a>) and nested
(Cols, see <a class="reference internal" href="#colsclassdescr"><em>The Cols class</em></a>) columns.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.coltypes">
<tt class="descname">coltypes</tt><a class="headerlink" href="#tables.Table.coltypes" title="Permalink to this definition">¶</a></dt>
<dd><p>Maps the name of a column to its PyTables data type.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.description">
<tt class="descname">description</tt><a class="headerlink" href="#tables.Table.description" title="Permalink to this definition">¶</a></dt>
<dd><p>A Description instance (see <a class="reference internal" href="#descriptionclassdescr"><em>The Description class</em></a>)
reflecting the structure of the table.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.extdim">
<tt class="descname">extdim</tt><a class="headerlink" href="#tables.Table.extdim" title="Permalink to this definition">¶</a></dt>
<dd><p>The index of the enlargeable dimension (always 0 for tables).</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.indexed">
<tt class="descname">indexed</tt><a class="headerlink" href="#tables.Table.indexed" title="Permalink to this definition">¶</a></dt>
<dd><p>Does this table have any indexed columns?</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.nrows">
<tt class="descname">nrows</tt><a class="headerlink" href="#tables.Table.nrows" title="Permalink to this definition">¶</a></dt>
<dd><p>The current number of rows in the table.</p>
</dd></dl>
</dd></dl>
<div class="section" id="table-properties">
<h3>Table properties<a class="headerlink" href="#table-properties" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="tables.Table.autoindex">
<tt class="descclassname">Table.</tt><tt class="descname">autoindex</tt><a class="headerlink" href="#tables.Table.autoindex" title="Permalink to this definition">¶</a></dt>
<dd><p>Automatically keep column indexes up to date?</p>
<p>Setting this value states whether existing indexes should be automatically
updated after an append operation or recomputed after an index-invalidating
operation (i.e. removal and modification of rows). The default is true.</p>
<p>This value gets into effect whenever a column is altered. If you don’t have
automatic indexing activated and you want to do an immediate update use
<a class="reference internal" href="#tables.Table.flush_rows_to_index" title="tables.Table.flush_rows_to_index"><tt class="xref py py-meth docutils literal"><span class="pre">Table.flush_rows_to_index()</span></tt></a>; for immediate reindexing of invalidated
indexes, use <a class="reference internal" href="#tables.Table.reindex_dirty" title="tables.Table.reindex_dirty"><tt class="xref py py-meth docutils literal"><span class="pre">Table.reindex_dirty()</span></tt></a>.</p>
<p>This value is persistent.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>The <em>autoIndex</em> property has been renamed into <em>autoindex</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.colindexes">
<tt class="descclassname">Table.</tt><tt class="descname">colindexes</tt><a class="headerlink" href="#tables.Table.colindexes" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary with the indexes of the indexed columns.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.indexedcolpathnames">
<tt class="descclassname">Table.</tt><tt class="descname">indexedcolpathnames</tt><a class="headerlink" href="#tables.Table.indexedcolpathnames" title="Permalink to this definition">¶</a></dt>
<dd><p>List of pathnames of indexed columns in the table.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.row">
<tt class="descclassname">Table.</tt><tt class="descname">row</tt><a class="headerlink" href="#tables.Table.row" title="Permalink to this definition">¶</a></dt>
<dd><p>The associated Row instance (see <a class="reference internal" href="#rowclassdescr"><em>The Row class</em></a>).</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Table.rowsize">
<tt class="descclassname">Table.</tt><tt class="descname">rowsize</tt><a class="headerlink" href="#tables.Table.rowsize" title="Permalink to this definition">¶</a></dt>
<dd><p>The size in bytes of each row in the table.</p>
</dd></dl>
</div>
<div class="section" id="table-methods-reading">
<h3>Table methods - reading<a class="headerlink" href="#table-methods-reading" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.Table.col">
<tt class="descclassname">Table.</tt><tt class="descname">col</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#tables.Table.col" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a column from the table.</p>
<p>If a column called name exists in the table, it is read and returned as
a NumPy object. If it does not exist, a KeyError is raised.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">narray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">col</span><span class="p">(</span><span class="s">'var2'</span><span class="p">)</span>
</pre></div>
</div>
<p>That statement is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">narray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">field</span><span class="o">=</span><span class="s">'var2'</span><span class="p">)</span>
</pre></div>
</div>
<p>Here you can see how this method can be used as a shorthand for the
<a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.iterrows">
<tt class="descclassname">Table.</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.Table.iterrows" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over the table using a Row instance.</p>
<p>If a range is not supplied, <em>all the rows</em> in the table are iterated
upon - you can also use the <a class="reference internal" href="#tables.Table.__iter__" title="tables.Table.__iter__"><tt class="xref py py-meth docutils literal"><span class="pre">Table.__iter__()</span></tt></a> special method for
that purpose. If you want to iterate over a given <em>range of rows</em> in
the table, you may use the start, stop and step parameters.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When in the middle of a table row iterator, you should not
use methods that can change the number of rows in the table
(like <a class="reference internal" href="#tables.Table.append" title="tables.Table.append"><tt class="xref py py-meth docutils literal"><span class="pre">Table.append()</span></tt></a> or <a class="reference internal" href="#tables.Table.remove_rows" title="tables.Table.remove_rows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.remove_rows()</span></tt></a>) or
unexpected errors will happen.</p>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="#tables.tableextension.Row" title="tables.tableextension.Row"><tt class="xref py py-obj docutils literal"><span class="pre">tableextension.Row</span></tt></a></dt>
<dd>the table row iterator and field accessor</dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>This iterator can be nested (see <a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> for an example).</p>
<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
table is iterated from <em>start</em> to the last line.
In PyTables < 3.0 only one element was returned.</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="s">'var2'</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</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">5</span><span class="p">)</span>
<span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="s">'var1'</span><span class="p">]</span> <span class="o"><=</span> <span class="mi">20</span> <span class="p">]</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.Table.itersequence">
<tt class="descclassname">Table.</tt><tt class="descname">itersequence</tt><big>(</big><em>sequence</em><big>)</big><a class="headerlink" href="#tables.Table.itersequence" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over a sequence of row coordinates.</p>
<p class="rubric">Notes</p>
<p>This iterator can be nested (see <a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> for an example).</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.itersorted">
<tt class="descclassname">Table.</tt><tt class="descname">itersorted</tt><big>(</big><em>sortby</em>, <em>checkCSI=False</em>, <em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.itersorted" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate table data following the order of the index of sortby
column.</p>
<p>The sortby column must have associated a full index. If you want to
ensure a fully sorted order, the index must be a CSI one. You may want
to use the checkCSI argument in order to explicitly check for the
existence of a CSI index.</p>
<p>The meaning of the start, stop and step arguments is the same as in
<a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a>.</p>
<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
table 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.Table.read">
<tt class="descclassname">Table.</tt><tt class="descname">read</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em>, <em>field=None</em>, <em>out=None</em><big>)</big><a class="headerlink" href="#tables.Table.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Get data in the table as a (record) array.</p>
<p>The start, stop and step parameters can be used to select only
a <em>range of rows</em> in the table. Their meanings are the same as
in the built-in Python slices.</p>
<p>If field is supplied only the named column will be selected.
If the column is not nested, an <em>array</em> of the current flavor
will be returned; if it is, a <em>structured array</em> will be used
instead. If no field is specified, all the columns will be
returned in a structured array of the current flavor.</p>
<p>Columns under a nested column can be specified in the field
parameter by using a slash character (/) as a separator (e.g.
‘position/x’).</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.</p>
<p>When specifying a single nested column with the field parameter,
and supplying an output buffer with the out parameter, the
output buffer must contain all columns in the table.
The data in all columns will be read into the output buffer.
However, only the specified nested column will be returned from
the method call.</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. If the out parameter is specified, the output
array also must be in the current system’s byteorder.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>Added the <em>out</em> parameter. Also the start, stop and step
parameters now behave like in slice.</p>
<p class="rubric">Examples</p>
<p>Reading the entire table:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
</pre></div>
</div>
<p>Reading record n. 6:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">)</span>
</pre></div>
</div>
<p>Reading from record n. 6 to the end of the table:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">6</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.Table.read_coordinates">
<tt class="descclassname">Table.</tt><tt class="descname">read_coordinates</tt><big>(</big><em>coords</em>, <em>field=None</em><big>)</big><a class="headerlink" href="#tables.Table.read_coordinates" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a set of rows given their indexes as a (record) array.</p>
<p>This method works much like the <a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a> method, but it uses
a sequence (coords) of row indexes to select the wanted columns,
instead of a column range.</p>
<p>The selected rows are returned in an array or structured array of the
current flavor.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.read_sorted">
<tt class="descclassname">Table.</tt><tt class="descname">read_sorted</tt><big>(</big><em>sortby</em>, <em>checkCSI=False</em>, <em>field=None</em>, <em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.read_sorted" title="Permalink to this definition">¶</a></dt>
<dd><p>Read table data following the order of the index of sortby column.</p>
<p>The sortby column must have associated a full index. If you want to
ensure a fully sorted order, the index must be a CSI one. You may want
to use the checkCSI argument in order to explicitly check for the
existence of a CSI index.</p>
<p>If field is supplied only the named column will be selected. If the
column is not nested, an <em>array</em> of the current flavor will be
returned; if it is, a <em>structured array</em> will be used instead. If no
field is specified, all the columns will be returned in a structured
array of the current flavor.</p>
<p>The meaning of the start, stop and step arguments is the same as in
<a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a>.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0.</span></p>
<p>The start, stop and step parameters now behave like in slice.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.__getitem__">
<tt class="descclassname">Table.</tt><tt class="descname">__getitem__</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#tables.Table.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a row or a range of rows from the table.</p>
<p>If key argument is an integer, the corresponding table row is returned
as a record of the current flavor. If key is a slice, the range of rows
determined by it is returned as a structured array 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 table has.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">record</span> <span class="o">=</span> <span class="n">table</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span>
<span class="n">recarray</span> <span class="o">=</span> <span class="n">table</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">recarray</span> <span class="o">=</span> <span class="n">table</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="c"># only retrieves rows 4 and 1000</span>
<span class="n">recarray</span> <span class="o">=</span> <span class="n">table</span><span class="p">[[</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="bp">True</span><span class="p">]]</span>
</pre></div>
</div>
<p>Those statements are equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">record</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">4</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">recarray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">stop</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="n">recarray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read_coordinates</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="n">recarray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read_coordinates</span><span class="p">([</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="bp">True</span><span class="p">])</span>
</pre></div>
</div>
<p>Here, you can see how indexing can be used as a shorthand for the
<a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a> and <a class="reference internal" href="#tables.Table.read_coordinates" title="tables.Table.read_coordinates"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read_coordinates()</span></tt></a> methods.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.__iter__">
<tt class="descclassname">Table.</tt><tt class="descname">__iter__</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Table.__iter__" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over the table using a Row instance.</p>
<p>This is equivalent to calling <a class="reference internal" href="#tables.Table.iterrows" title="tables.Table.iterrows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.iterrows()</span></tt></a> with default
arguments, i.e. it iterates over <em>all the rows</em> in the table.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="#tables.tableextension.Row" title="tables.tableextension.Row"><tt class="xref py py-obj docutils literal"><span class="pre">tableextension.Row</span></tt></a></dt>
<dd>the table row iterator and field accessor</dd>
</dl>
</div>
<p class="rubric">Notes</p>
<p>This iterator can be nested (see <a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> for an example).</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="s">'var2'</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</span> <span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="s">'var1'</span><span class="p">]</span> <span class="o"><=</span> <span class="mi">20</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="s">'var2'</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</span><span class="o">.</span><span class="n">iterrows</span><span class="p">()</span>
<span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="s">'var1'</span><span class="p">]</span> <span class="o"><=</span> <span class="mi">20</span> <span class="p">]</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="table-methods-writing">
<h3>Table methods - writing<a class="headerlink" href="#table-methods-writing" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.Table.append">
<tt class="descclassname">Table.</tt><tt class="descname">append</tt><big>(</big><em>rows</em><big>)</big><a class="headerlink" href="#tables.Table.append" title="Permalink to this definition">¶</a></dt>
<dd><p>Append a sequence of rows to the end of the table.</p>
<p>The rows argument may be any object which can be converted to
a structured array compliant with the table structure
(otherwise, a ValueError is raised). This includes NumPy
structured arrays, lists of tuples or array records, and a
string or Python buffer.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">tables</span> <span class="kn">import</span> <span class="o">*</span>
<span class="k">class</span> <span class="nc">Particle</span><span class="p">(</span><span class="n">IsDescription</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="n">StringCol</span><span class="p">(</span><span class="mi">16</span><span class="p">,</span> <span class="n">pos</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span> <span class="c"># 16-character String</span>
<span class="n">lati</span> <span class="o">=</span> <span class="n">IntCol</span><span class="p">(</span><span class="n">pos</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span> <span class="c"># integer</span>
<span class="n">longi</span> <span class="o">=</span> <span class="n">IntCol</span><span class="p">(</span><span class="n">pos</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span> <span class="c"># integer</span>
<span class="n">pressure</span> <span class="o">=</span> <span class="n">Float32Col</span><span class="p">(</span><span class="n">pos</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span> <span class="c"># float (single-precision)</span>
<span class="n">temperature</span> <span class="o">=</span> <span class="n">FloatCol</span><span class="p">(</span><span class="n">pos</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span> <span class="c"># double (double-precision)</span>
<span class="n">fileh</span> <span class="o">=</span> <span class="n">open_file</span><span class="p">(</span><span class="s">'test4.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">table</span> <span class="o">=</span> <span class="n">fileh</span><span class="o">.</span><span class="n">create_table</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">'table'</span><span class="p">,</span> <span class="n">Particle</span><span class="p">,</span>
<span class="s">"A table"</span><span class="p">)</span>
<span class="c"># Append several rows in only one call</span>
<span class="n">table</span><span class="o">.</span><span class="n">append</span><span class="p">([(</span><span class="s">"Particle: 10"</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">10</span> <span class="o">*</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">10</span><span class="o">**</span><span class="mi">2</span><span class="p">),</span>
<span class="p">(</span><span class="s">"Particle: 11"</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">11</span> <span class="o">*</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">11</span><span class="o">**</span><span class="mi">2</span><span class="p">),</span>
<span class="p">(</span><span class="s">"Particle: 12"</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="p">,</span> <span class="mi">12</span> <span class="o">*</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">12</span><span class="o">**</span><span class="mi">2</span><span class="p">)])</span>
<span class="n">fileh</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.Table.modify_column">
<tt class="descclassname">Table.</tt><tt class="descname">modify_column</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em>, <em>column=None</em>, <em>colname=None</em><big>)</big><a class="headerlink" href="#tables.Table.modify_column" title="Permalink to this definition">¶</a></dt>
<dd><p>Modify one single column in the row slice [start:stop:step].</p>
<p>The colname argument specifies the name of the column in the
table to be modified with the data given in column. This
method returns the number of rows modified. Should the
modification exceed the length of the table, an IndexError is
raised before changing data.</p>
<p>The <em>column</em> argument may be any object which can be converted
to a (record) array compliant with the structure of the column
to be modified (otherwise, a ValueError is raised). This
includes NumPy (record) arrays, lists of scalars, tuples or
array records, and a string or Python buffer.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.modify_columns">
<tt class="descclassname">Table.</tt><tt class="descname">modify_columns</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em>, <em>columns=None</em>, <em>names=None</em><big>)</big><a class="headerlink" href="#tables.Table.modify_columns" title="Permalink to this definition">¶</a></dt>
<dd><p>Modify a series of columns in the row slice [start:stop:step].</p>
<p>The names argument specifies the names of the columns in the
table to be modified with the data given in columns. This
method returns the number of rows modified. Should the
modification exceed the length of the table, an IndexError
is raised before changing data.</p>
<p>The columns argument may be any object which can be converted
to a structured array compliant with the structure of the
columns to be modified (otherwise, a ValueError is raised).
This includes NumPy structured arrays, lists of tuples or array
records, and a string or Python buffer.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.modify_coordinates">
<tt class="descclassname">Table.</tt><tt class="descname">modify_coordinates</tt><big>(</big><em>coords</em>, <em>rows</em><big>)</big><a class="headerlink" href="#tables.Table.modify_coordinates" title="Permalink to this definition">¶</a></dt>
<dd><p>Modify a series of rows in positions specified in coords</p>
<p>The values in the selected rows will be modified with the data given in
rows. This method returns the number of rows modified.</p>
<p>The possible values for the rows argument are the same as in
<a class="reference internal" href="#tables.Table.append" title="tables.Table.append"><tt class="xref py py-meth docutils literal"><span class="pre">Table.append()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.modify_rows">
<tt class="descclassname">Table.</tt><tt class="descname">modify_rows</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em>, <em>rows=None</em><big>)</big><a class="headerlink" href="#tables.Table.modify_rows" title="Permalink to this definition">¶</a></dt>
<dd><p>Modify a series of rows in the slice [start:stop:step].</p>
<p>The values in the selected rows will be modified with the data given in
rows. This method returns the number of rows modified. Should the
modification exceed the length of the table, an IndexError is raised
before changing data.</p>
<p>The possible values for the rows argument are the same as in
<a class="reference internal" href="#tables.Table.append" title="tables.Table.append"><tt class="xref py py-meth docutils literal"><span class="pre">Table.append()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.remove_rows">
<tt class="descclassname">Table.</tt><tt class="descname">remove_rows</tt><big>(</big><em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.remove_rows" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove a range of rows in the table.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0.</span></p>
<p>The start, stop and step parameters now behave like in slice.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">remove_row()</p>
</div>
<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>start</strong> : int</p>
<blockquote>
<div><p>Sets the starting row to be removed. It accepts negative values
meaning that the count starts from the end. A value of 0 means the
first row.</p>
</div></blockquote>
<p><strong>stop</strong> : int</p>
<blockquote>
<div><p>Sets the last row to be removed to stop-1, i.e. the end point is
omitted (in the Python range() tradition). Negative values are also
accepted.</p>
</div></blockquote>
<p><strong>step</strong> : int</p>
<blockquote class="last">
<div><p>The step size between rows to remove.</p>
<p class="versionadded">
<span class="versionmodified">New in version 3.0.</span></p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Examples</p>
<p>Removing rows from 5 to 10 (excluded):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span><span class="o">.</span><span class="n">remove_rows</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<p>Removing all rows starting drom the 10th:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span><span class="o">.</span><span class="n">remove_rows</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<p>Removing the 6th row:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">t</span><span class="o">.</span><span class="n">remove_rows</span><span class="p">(</span><span class="mi">6</span><span class="p">,</span> <span class="mi">7</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">removing a single row can be done using the specific
<tt class="xref py py-meth docutils literal"><span class="pre">remove_row()</span></tt> method.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.Table.__setitem__">
<tt class="descclassname">Table.</tt><tt class="descname">__setitem__</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#tables.Table.__setitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a row or a range of rows in the table.</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
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>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Modify just one existing row</span>
<span class="n">table</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="mi">456</span><span class="p">,</span><span class="s">'db2'</span><span class="p">,</span><span class="mf">1.2</span><span class="p">]</span>
<span class="c"># Modify two existing rows</span>
<span class="n">rows</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">rec</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">457</span><span class="p">,</span><span class="s">'db1'</span><span class="p">,</span><span class="mf">1.2</span><span class="p">],[</span><span class="mi">6</span><span class="p">,</span><span class="s">'de2'</span><span class="p">,</span><span class="mf">1.3</span><span class="p">]],</span>
<span class="n">formats</span><span class="o">=</span><span class="s">'i4,a3,f8'</span><span class="p">)</span>
<span class="n">table</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">rows</span> <span class="c"># modify a table slice</span>
<span class="n">table</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">rows</span> <span class="c"># only modifies rows 1 and 3</span>
<span class="n">table</span><span class="p">[[</span><span class="bp">True</span><span class="p">,</span><span class="bp">False</span><span class="p">,</span><span class="bp">True</span><span class="p">]]</span> <span class="o">=</span> <span class="n">rows</span> <span class="c"># only modifies rows 0 and 2</span>
</pre></div>
</div>
<p>Which is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span><span class="o">.</span><span class="n">modify_rows</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">rows</span><span class="o">=</span><span class="p">[</span><span class="mi">456</span><span class="p">,</span><span class="s">'db2'</span><span class="p">,</span><span class="mf">1.2</span><span class="p">])</span>
<span class="n">rows</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">rec</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">457</span><span class="p">,</span><span class="s">'db1'</span><span class="p">,</span><span class="mf">1.2</span><span class="p">],[</span><span class="mi">6</span><span class="p">,</span><span class="s">'de2'</span><span class="p">,</span><span class="mf">1.3</span><span class="p">]],</span>
<span class="n">formats</span><span class="o">=</span><span class="s">'i4,a3,f8'</span><span class="p">)</span>
<span class="n">table</span><span class="o">.</span><span class="n">modify_rows</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">stop</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">rows</span><span class="o">=</span><span class="n">rows</span><span class="p">)</span>
<span class="n">table</span><span class="o">.</span><span class="n">modify_coordinates</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="mi">2</span><span class="p">],</span> <span class="n">rows</span><span class="p">)</span>
<span class="n">table</span><span class="o">.</span><span class="n">modify_coordinates</span><span class="p">([</span><span class="bp">True</span><span class="p">,</span> <span class="bp">False</span><span class="p">,</span> <span class="bp">True</span><span class="p">],</span> <span class="n">rows</span><span class="p">)</span>
</pre></div>
</div>
<p>Here, you can see how indexing can be used as a shorthand for the
<a class="reference internal" href="#tables.Table.modify_rows" title="tables.Table.modify_rows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.modify_rows()</span></tt></a> and <a class="reference internal" href="#tables.Table.modify_coordinates" title="tables.Table.modify_coordinates"><tt class="xref py py-meth docutils literal"><span class="pre">Table.modify_coordinates()</span></tt></a>
methods.</p>
</dd></dl>
</div>
<div class="section" id="table-methods-querying">
<span id="tablemethods-querying"></span><h3>Table methods - querying<a class="headerlink" href="#table-methods-querying" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.Table.get_where_list">
<tt class="descclassname">Table.</tt><tt class="descname">get_where_list</tt><big>(</big><em>condition</em>, <em>condvars=None</em>, <em>sort=False</em>, <em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.get_where_list" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the row coordinates fulfilling the given condition.</p>
<p>The coordinates are returned as a list of the current flavor. sort
means that you want to retrieve the coordinates ordered. The default is
to not sort them.</p>
<p>The meaning of the other arguments is the same as in the
<a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.read_where">
<tt class="descclassname">Table.</tt><tt class="descname">read_where</tt><big>(</big><em>condition</em>, <em>condvars=None</em>, <em>field=None</em>, <em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.read_where" title="Permalink to this definition">¶</a></dt>
<dd><p>Read table data fulfilling the given <em>condition</em>.</p>
<p>This method is similar to <a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a>, having their common
arguments and return values the same meanings. However, only the rows
fulfilling the <em>condition</em> are included in the result.</p>
<p>The meaning of the other arguments is the same as in the
<a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.where">
<tt class="descclassname">Table.</tt><tt class="descname">where</tt><big>(</big><em>condition</em>, <em>condvars=None</em>, <em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.where" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over values fulfilling a condition.</p>
<p>This method returns a Row iterator (see <a class="reference internal" href="#rowclassdescr"><em>The Row class</em></a>) which
only selects rows in the table that satisfy the given condition (an
expression-like string).</p>
<p>The condvars mapping may be used to define the variable names appearing
in the condition. condvars should consist of identifier-like strings
pointing to Column (see <a class="reference internal" href="#columnclassdescr"><em>The Column class</em></a>) instances <em>of this
table</em>, or to other values (which will be converted to arrays). A
default set of condition variables is provided where each top-level,
non-nested column with an identifier-like name appears. Variables in
condvars override the default ones.</p>
<p>When condvars is not provided or None, the current local and global
namespace is sought instead of condvars. The previous mechanism is
mostly intended for interactive usage. To disable it, just specify a
(maybe empty) mapping as condvars.</p>
<p>If a range is supplied (by setting some of the start, stop or step
parameters), only the rows in that range and fulfilling the condition
are used. The meaning of the start, stop and step parameters is the
same as for Python slices.</p>
<p>When possible, indexed columns participating in the condition will be
used to speed up the search. It is recommended that you place the
indexed columns as left and out in the condition as possible. Anyway,
this method has always better performance than regular Python
selections on the table.</p>
<p>You can mix this method with regular Python selections in order to
support even more complex queries. It is strongly recommended that you
pass the most restrictive condition as the parameter to this method if
you want to achieve maximum performance.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When in the middle of a table row iterator, you should not
use methods that can change the number of rows in the table
(like <a class="reference internal" href="#tables.Table.append" title="tables.Table.append"><tt class="xref py py-meth docutils literal"><span class="pre">Table.append()</span></tt></a> or <a class="reference internal" href="#tables.Table.remove_rows" title="tables.Table.remove_rows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.remove_rows()</span></tt></a>) or
unexpected errors will happen.</p>
</div>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">passvalues</span> <span class="o">=</span> <span class="p">[</span> <span class="n">row</span><span class="p">[</span><span class="s">'col3'</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span>
<span class="gp">... </span> <span class="n">table</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'(col1 > 0) & (col2 <= 20)'</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">... </span> <span class="k">if</span> <span class="n">your_function</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="s">'col2'</span><span class="p">])</span> <span class="p">]</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="s">"Values that pass the cuts:"</span><span class="p">,</span> <span class="n">passvalues</span>
</pre></div>
</div>
<p>Note that, from PyTables 1.1 on, you can nest several
iterators over the same table. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">rout</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'pressure < 16'</span><span class="p">):</span>
<span class="k">for</span> <span class="n">q</span> <span class="ow">in</span> <span class="n">rout</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'pressure < 9'</span><span class="p">):</span>
<span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="n">rout</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'energy < 10'</span><span class="p">):</span>
<span class="k">print</span> <span class="s">"pressure, energy:"</span><span class="p">,</span> <span class="n">p</span><span class="p">[</span><span class="s">'pressure'</span><span class="p">],</span> <span class="n">n</span><span class="p">[</span><span class="s">'energy'</span><span class="p">]</span>
</pre></div>
</div>
<p>In this example, iterators returned by <a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> have been
used, but you may as well use any of the other reading iterators that
Table objects offer. See the file <tt class="file docutils literal"><span class="pre">examples/nested-iter.py</span></tt> for
the full code.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0.</span></p>
<p>The start, stop and step parameters now behave like in slice.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.append_where">
<tt class="descclassname">Table.</tt><tt class="descname">append_where</tt><big>(</big><em>dstTable</em>, <em>condition</em>, <em>condvars=None</em>, <em>start=None</em>, <em>stop=None</em>, <em>step=None</em><big>)</big><a class="headerlink" href="#tables.Table.append_where" title="Permalink to this definition">¶</a></dt>
<dd><p>Append rows fulfilling the condition to the dstTable table.</p>
<p>dstTable must be capable of taking the rows resulting from the query,
i.e. it must have columns with the expected names and compatible
types. The meaning of the other arguments is the same as in the
<a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> method.</p>
<p>The number of rows appended to dstTable is returned as a result.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>The <em>whereAppend</em> method has been renamed into <em>append_where</em>.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.will_query_use_indexing">
<tt class="descclassname">Table.</tt><tt class="descname">will_query_use_indexing</tt><big>(</big><em>condition</em>, <em>condvars=None</em><big>)</big><a class="headerlink" href="#tables.Table.will_query_use_indexing" title="Permalink to this definition">¶</a></dt>
<dd><p>Will a query for the condition use indexing?</p>
<p>The meaning of the condition and <em>condvars</em> arguments is the same as in
the <a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> method. If condition can use indexing, this
method returns a frozenset with the path names of the columns whose
index is usable. Otherwise, it returns an empty list.</p>
<p>This method is mainly intended for testing. Keep in mind that changing
the set of indexed columns or their dirtiness may make this method
return different values for the same arguments at different times.</p>
</dd></dl>
</div>
<div class="section" id="table-methods-other">
<h3>Table methods - other<a class="headerlink" href="#table-methods-other" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="tables.Table.copy">
<tt class="descclassname">Table.</tt><tt class="descname">copy</tt><big>(</big><em>newparent=None</em>, <em>newname=None</em>, <em>overwrite=False</em>, <em>createparents=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#tables.Table.copy" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy this table and return the new one.</p>
<p>This method has the behavior and keywords described in
<a class="reference internal" href="hierarchy_classes.html#tables.Leaf.copy" title="tables.Leaf.copy"><tt class="xref py py-meth docutils literal"><span class="pre">Leaf.copy()</span></tt></a>. Moreover, it recognises the following additional
keyword arguments.</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>sortby</strong> :</p>
<blockquote>
<div><p>If specified, and sortby corresponds to a column with an index,
then the copy will be sorted by this index. If you want to ensure
a fully sorted order, the index must be a CSI one. A reverse
sorted copy can be achieved by specifying a negative value for the
step keyword. If sortby is omitted or None, the original table
order is used.</p>
</div></blockquote>
<p><strong>checkCSI</strong> :</p>
<blockquote>
<div><p>If true and a CSI index does not exist for the sortby column, an
error will be raised. If false (the default), it does nothing.
You can use this flag in order to explicitly check for the
existence of a CSI index.</p>
</div></blockquote>
<p><strong>propindexes</strong> :</p>
<blockquote class="last">
<div><p>If true, the existing indexes in the source table are propagated
(created) to the new one. If false (the default), the indexes are
not propagated.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="tables.Table.flush_rows_to_index">
<tt class="descclassname">Table.</tt><tt class="descname">flush_rows_to_index</tt><big>(</big><em>_lastrow=True</em><big>)</big><a class="headerlink" href="#tables.Table.flush_rows_to_index" title="Permalink to this definition">¶</a></dt>
<dd><p>Add remaining rows in buffers to non-dirty indexes.</p>
<p>This can be useful when you have chosen non-automatic indexing
for the table (see the <a class="reference internal" href="#tables.Table.autoindex" title="tables.Table.autoindex"><tt class="xref py py-attr docutils literal"><span class="pre">Table.autoindex</span></tt></a> property in
<a class="reference internal" href="#tables.Table" title="tables.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>) and you want to update the indexes on it.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.get_enum">
<tt class="descclassname">Table.</tt><tt class="descname">get_enum</tt><big>(</big><em>colname</em><big>)</big><a class="headerlink" href="#tables.Table.get_enum" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the enumerated type associated with the named column.</p>
<p>If the column named colname (a string) exists and 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. If
the column does not exist, a KeyError is raised.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.reindex">
<tt class="descclassname">Table.</tt><tt class="descname">reindex</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Table.reindex" title="Permalink to this definition">¶</a></dt>
<dd><p>Recompute all the existing indexes in the table.</p>
<p>This can be useful when you suspect that, for any reason, the index
information for columns is no longer valid and want to rebuild the
indexes on it.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Table.reindex_dirty">
<tt class="descclassname">Table.</tt><tt class="descname">reindex_dirty</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Table.reindex_dirty" title="Permalink to this definition">¶</a></dt>
<dd><p>Recompute the existing indexes in table, <em>if</em> they are dirty.</p>
<p>This can be useful when you have set <a class="reference internal" href="#tables.Table.autoindex" title="tables.Table.autoindex"><tt class="xref py py-attr docutils literal"><span class="pre">Table.autoindex</span></tt></a>
(see <a class="reference internal" href="#tables.Table" title="tables.Table"><tt class="xref py py-class docutils literal"><span class="pre">Table</span></tt></a>) to false for the table and you want to
update the indexes after a invalidating index operation
(<a class="reference internal" href="#tables.Table.remove_rows" title="tables.Table.remove_rows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.remove_rows()</span></tt></a>, for example).</p>
</dd></dl>
</div>
<div class="section" id="the-description-class">
<span id="descriptionclassdescr"></span><h3>The Description class<a class="headerlink" href="#the-description-class" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="tables.Description">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">Description</tt><big>(</big><em>classdict</em>, <em>nestedlvl=-1</em>, <em>validate=True</em><big>)</big><a class="headerlink" href="#tables.Description" title="Permalink to this definition">¶</a></dt>
<dd><p>This class represents descriptions of the structure of tables.</p>
<p>An instance of this class is automatically bound to Table (see
<a class="reference internal" href="#tableclassdescr"><em>The Table class</em></a>) objects when they are created. It provides a
browseable representation of the structure of the table, made of non-nested
(Col - see <a class="reference internal" href="declarative_classes.html#colclassdescr"><em>The Col class and its descendants</em></a>) and nested (Description) columns.</p>
<p>Column definitions under a description can be accessed as attributes of it
(<em>natural naming</em>). For instance, if table.description is a Description
instance with a column named col1 under it, the later can be accessed as
table.description.col1. If col1 is nested and contains a col2 column, this
can be accessed as table.description.col1.col2. Because of natural naming,
the names of members start with special prefixes, like in the Group class
(see <a class="reference internal" href="hierarchy_classes.html#groupclassdescr"><em>The Group class</em></a>).</p>
<p class="rubric">Description attributes</p>
<dl class="attribute">
<dt id="tables.Description._v_colobjects">
<tt class="descname">_v_colobjects</tt><a class="headerlink" href="#tables.Description._v_colobjects" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping the names of the columns hanging
directly from the associated table or nested column to their
respective descriptions (Col - see <a class="reference internal" href="declarative_classes.html#colclassdescr"><em>The Col class and its descendants</em></a> or
Description - see <a class="reference internal" href="#descriptionclassdescr"><em>The Description class</em></a> instances).</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>The <em>_v_colObjects</em> attobute has been renamed into
<em>_v_colobjects</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_dflts">
<tt class="descname">_v_dflts</tt><a class="headerlink" href="#tables.Description._v_dflts" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping the names of non-nested columns
hanging directly from the associated table or nested column
to their respective default values.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_dtype">
<tt class="descname">_v_dtype</tt><a class="headerlink" href="#tables.Description._v_dtype" title="Permalink to this definition">¶</a></dt>
<dd><p>The NumPy type which reflects the structure of this
table or nested column. You can use this as the
dtype argument of NumPy array factories.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_dtypes">
<tt class="descname">_v_dtypes</tt><a class="headerlink" href="#tables.Description._v_dtypes" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping the names of non-nested columns
hanging directly from the associated table or nested column
to their respective NumPy types.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_is_nested">
<tt class="descname">_v_is_nested</tt><a class="headerlink" href="#tables.Description._v_is_nested" title="Permalink to this definition">¶</a></dt>
<dd><p>Whether the associated table or nested column contains
further nested columns or not.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_itemsize">
<tt class="descname">_v_itemsize</tt><a class="headerlink" href="#tables.Description._v_itemsize" title="Permalink to this definition">¶</a></dt>
<dd><p>The size in bytes of an item in this table or nested column.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_name">
<tt class="descname">_v_name</tt><a class="headerlink" href="#tables.Description._v_name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of this description group. The name of the
root group is ‘/’.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_names">
<tt class="descname">_v_names</tt><a class="headerlink" href="#tables.Description._v_names" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of the names of the columns hanging directly
from the associated table or nested column. The order of the
names matches the order of their respective columns in the
containing table.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_nested_descr">
<tt class="descname">_v_nested_descr</tt><a class="headerlink" href="#tables.Description._v_nested_descr" title="Permalink to this definition">¶</a></dt>
<dd><p>A nested list of pairs of (name, format) tuples for all the columns
under this table or nested column. You can use this as the dtype and
descr arguments of NumPy array factories.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>The <em>_v_nestedDescr</em> attribute has been renamed into
<em>_v_nested_descr</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_nested_formats">
<tt class="descname">_v_nested_formats</tt><a class="headerlink" href="#tables.Description._v_nested_formats" title="Permalink to this definition">¶</a></dt>
<dd><p>A nested list of the NumPy string formats (and shapes) of all the
columns under this table or nested column. You can use this as the
formats argument of NumPy array factories.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>The <em>_v_nestedFormats</em> attribute has been renamed into
<em>_v_nested_formats</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_nestedlvl">
<tt class="descname">_v_nestedlvl</tt><a class="headerlink" href="#tables.Description._v_nestedlvl" title="Permalink to this definition">¶</a></dt>
<dd><p>The level of the associated table or nested column in the nested
datatype.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_nested_names">
<tt class="descname">_v_nested_names</tt><a class="headerlink" href="#tables.Description._v_nested_names" title="Permalink to this definition">¶</a></dt>
<dd><p>A nested list of the names of all the columns under this table or
nested column. You can use this as the names argument of NumPy array
factories.</p>
<p class="versionchanged">
<span class="versionmodified">Changed in version 3.0: </span>The <em>_v_nestedNames</em> attribute has been renamed into
<em>_v_nested_names</em>.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_pathname">
<tt class="descname">_v_pathname</tt><a class="headerlink" href="#tables.Description._v_pathname" title="Permalink to this definition">¶</a></dt>
<dd><p>Pathname of the table or nested column.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_pathnames">
<tt class="descname">_v_pathnames</tt><a class="headerlink" href="#tables.Description._v_pathnames" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of the pathnames of all the columns under this table or nested
column (in preorder). If it does not contain nested columns, this is
exactly the same as the <a class="reference internal" href="#tables.Description._v_names" title="tables.Description._v_names"><tt class="xref py py-attr docutils literal"><span class="pre">Description._v_names</span></tt></a> attribute.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Description._v_types">
<tt class="descname">_v_types</tt><a class="headerlink" href="#tables.Description._v_types" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary mapping the names of non-nested columns hanging directly
from the associated table or nested column to their respective PyTables
types.</p>
</dd></dl>
</dd></dl>
<div class="section" id="description-methods">
<h4>Description methods<a class="headerlink" href="#description-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="tables.Description._f_walk">
<tt class="descclassname">Description.</tt><tt class="descname">_f_walk</tt><big>(</big><em>type='All'</em><big>)</big><a class="headerlink" href="#tables.Description._f_walk" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over nested columns.</p>
<p>If type is ‘All’ (the default), all column description objects (Col and
Description instances) are yielded in top-to-bottom order (preorder).</p>
<p>If type is ‘Col’ or ‘Description’, only column descriptions of that
type are yielded.</p>
</dd></dl>
</div>
</div>
<div class="section" id="the-row-class">
<span id="rowclassdescr"></span><h3>The Row class<a class="headerlink" href="#the-row-class" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="tables.tableextension.Row">
<em class="property">class </em><tt class="descclassname">tables.tableextension.</tt><tt class="descname">Row</tt><a class="headerlink" href="#tables.tableextension.Row" title="Permalink to this definition">¶</a></dt>
<dd><p>Table row iterator and field accessor.</p>
<p>Instances of this class are used to fetch and set the values
of individual table fields. It works very much like a dictionary,
where keys are the pathnames or positions (extended slicing is
supported) of the fields in the associated table in a specific row.</p>
<p>This class provides an <em>iterator interface</em>
so that you can use the same Row instance to
access successive table rows one after the other. There are also
some important methods that are useful for accessing, adding and
modifying values in tables.</p>
<p class="rubric">Row attributes</p>
<dl class="attribute">
<dt id="tables.Row.nrow">
<tt class="descname">nrow</tt><a class="headerlink" href="#tables.Row.nrow" title="Permalink to this definition">¶</a></dt>
<dd><p>The current row number.</p>
<p>This property is useful for knowing which row is being dealt with in the
middle of a loop or iterator.</p>
</dd></dl>
</dd></dl>
<div class="section" id="row-methods">
<h4>Row methods<a class="headerlink" href="#row-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="tables.tableextension.Row.append">
<tt class="descclassname">Row.</tt><tt class="descname">append</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.tableextension.Row.append" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a new row of data to the end of the dataset.</p>
<p>Once you have filled the proper fields for the current
row, calling this method actually appends the new data to the
<em>output buffer</em> (which will eventually be
dumped to disk). If you have not set the value of a field, the
default value of the column will be used.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">After completion of the loop in which <tt class="xref py py-meth docutils literal"><span class="pre">Row.append()</span></tt> has
been called, it is always convenient to make a call to
<tt class="xref py py-meth docutils literal"><span class="pre">Table.flush()</span></tt> in order to avoid losing the last rows that
may still remain in internal buffers.</p>
</div>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">row</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">row</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">xrange</span><span class="p">(</span><span class="n">nrows</span><span class="p">):</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col1'</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="o">-</span><span class="mi">1</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col2'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'a'</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col3'</span><span class="p">]</span> <span class="o">=</span> <span class="o">-</span><span class="mf">1.0</span>
<span class="n">row</span><span class="o">.</span><span class="n">append</span><span class="p">()</span>
<span class="n">table</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="tables.tableextension.Row.fetch_all_fields">
<tt class="descclassname">Row.</tt><tt class="descname">fetch_all_fields</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.tableextension.Row.fetch_all_fields" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve all the fields in the current row.</p>
<p>Contrarily to row[:] (see <a class="reference internal" href="#rowspecialmethods"><em>Row special methods</em></a>), this returns row
data as a NumPy void scalar. For instance:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">row</span><span class="o">.</span><span class="n">fetch_all_fields</span><span class="p">()</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'col1 < 3'</span><span class="p">)]</span>
</pre></div>
</div>
<p>will select all the rows that fulfill the given condition
as a list of NumPy records.</p>
</dd></dl>
<dl class="method">
<dt id="tables.tableextension.Row.update">
<tt class="descclassname">Row.</tt><tt class="descname">update</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.tableextension.Row.update" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the data of the current row in the dataset.</p>
<p>This method allows you to modify values in a table when you are in the
middle of a table iterator like <a class="reference internal" href="#tables.Table.iterrows" title="tables.Table.iterrows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.iterrows()</span></tt></a> or
<a class="reference internal" href="#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a>.</p>
<p>Once you have filled the proper fields for the current row, calling
this method actually changes data in the <em>output buffer</em> (which will
eventually be dumped to disk). If you have not set the value of a
field, its original value will be used.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">After completion of the loop in which <tt class="xref py py-meth docutils literal"><span class="pre">Row.update()</span></tt> has
been called, it is always convenient to make a call to
<tt class="xref py py-meth docutils literal"><span class="pre">Table.flush()</span></tt> in order to avoid losing changed rows that
may still remain in internal buffers.</p>
</div>
<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">table</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">10</span><span class="p">):</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col1'</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="o">.</span><span class="n">nrow</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col2'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'b'</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col3'</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">row</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
<span class="n">table</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
</pre></div>
</div>
<p>which modifies every tenth row in table. Or:</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">table</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'col1 > 3'</span><span class="p">):</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col1'</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="o">.</span><span class="n">nrow</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col2'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'b'</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col3'</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">row</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
<span class="n">table</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
</pre></div>
</div>
<p>which just updates the rows with values bigger than 3 in the first
column.</p>
</dd></dl>
</div>
<div class="section" id="row-special-methods">
<span id="rowspecialmethods"></span><h4>Row special methods<a class="headerlink" href="#row-special-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="tables.tableextension.Row.__contains__">
<tt class="descclassname">Row.</tt><tt class="descname">__contains__</tt><big>(</big><em>item</em><big>)</big><a class="headerlink" href="#tables.tableextension.Row.__contains__" title="Permalink to this definition">¶</a></dt>
<dd><p>A true value is returned if item is found in current row, false
otherwise.</p>
</dd></dl>
<dl class="method">
<dt id="tables.tableextension.Row.__getitem__">
<tt class="descclassname">Row.</tt><tt class="descname">__getitem__</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#tables.tableextension.Row.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the row field specified by the <cite>key</cite>.</p>
<p>The key can be a string (the name of the field), an integer (the
position of the field) or a slice (the range of field positions). When
key is a slice, the returned value is a <em>tuple</em> containing the values
of the specified fields.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="s">'var3'</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="s">'var2 < 20'</span><span class="p">)]</span>
</pre></div>
</div>
<p>which selects the var3 field for all the rows that fulfil the
condition. Or:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</span> <span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o"><</span> <span class="mi">20</span><span class="p">]</span>
</pre></div>
</div>
<p>which selects the field in the <em>4th</em> position for all the rows that
fulfil the condition. Or:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span><span class="p">[:]</span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">table</span> <span class="k">if</span> <span class="n">row</span><span class="p">[</span><span class="s">'var2'</span><span class="p">]</span> <span class="o"><</span> <span class="mi">20</span><span class="p">]</span>
</pre></div>
</div>
<p>which selects the all the fields (in the form of a <em>tuple</em>) for all the
rows that fulfil the condition. Or:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">res</span> <span class="o">=</span> <span class="p">[</span><span class="n">row</span><span class="p">[</span><span class="mi">1</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">table</span><span class="o">.</span><span class="n">iterrows</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3000</span><span class="p">,</span> <span class="mi">3</span><span class="p">)]</span>
</pre></div>
</div>
<p>which selects all the fields in even positions (in the form of a
<em>tuple</em>) for all the rows in the slice [2:3000:3].</p>
</dd></dl>
<dl class="method">
<dt id="tables.tableextension.Row.__setitem__">
<tt class="descclassname">Row.</tt><tt class="descname">__setitem__</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#tables.tableextension.Row.__setitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the key row field to the specified value.</p>
<p>Differently from its __getitem__() counterpart, in this case key can
only be a string (the name of the field). The changes done via
__setitem__() will not take effect on the data on disk until any of the
<tt class="xref py py-meth docutils literal"><span class="pre">Row.append()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">Row.update()</span></tt> methods are called.</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">table</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">10</span><span class="p">):</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col1'</span><span class="p">]</span> <span class="o">=</span> <span class="n">row</span><span class="o">.</span><span class="n">nrow</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col2'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'b'</span>
<span class="n">row</span><span class="p">[</span><span class="s">'col3'</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">row</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
<span class="n">table</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
</pre></div>
</div>
<p>which modifies every tenth row in the table.</p>
</dd></dl>
</div>
</div>
<div class="section" id="the-cols-class">
<span id="colsclassdescr"></span><h3>The Cols class<a class="headerlink" href="#the-cols-class" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="tables.Cols">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">Cols</tt><big>(</big><em>table</em>, <em>desc</em><big>)</big><a class="headerlink" href="#tables.Cols" title="Permalink to this definition">¶</a></dt>
<dd><p>Container for columns in a table or nested column.</p>
<p>This class is used as an <em>accessor</em> to the columns in a table or nested
column. It supports the <em>natural naming</em> convention, so that you can
access the different columns as attributes which lead to Column instances
(for non-nested columns) or other Cols instances (for nested columns).</p>
<p>For instance, if table.cols is a Cols instance with a column named col1
under it, the later can be accessed as table.cols.col1. If col1 is nested
and contains a col2 column, this can be accessed as table.cols.col1.col2
and so on. Because of natural naming, the names of members start with
special prefixes, like in the Group class (see <a class="reference internal" href="hierarchy_classes.html#groupclassdescr"><em>The Group class</em></a>).</p>
<p>Like the Column class (see <a class="reference internal" href="#columnclassdescr"><em>The Column class</em></a>), Cols supports item
access to read and write ranges of values in the table or nested column.</p>
<p class="rubric">Cols attributes</p>
<dl class="attribute">
<dt id="tables.Cols._v_colnames">
<tt class="descname">_v_colnames</tt><a class="headerlink" href="#tables.Cols._v_colnames" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of the names of the columns hanging directly
from the associated table or nested column. The order of
the names matches the order of their respective columns in
the containing table.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Cols._v_colpathnames">
<tt class="descname">_v_colpathnames</tt><a class="headerlink" href="#tables.Cols._v_colpathnames" title="Permalink to this definition">¶</a></dt>
<dd><p>A list of the pathnames of all the columns under the
associated table or nested column (in preorder). If it does
not contain nested columns, this is exactly the same as the
<a class="reference internal" href="#tables.Cols._v_colnames" title="tables.Cols._v_colnames"><tt class="xref py py-attr docutils literal"><span class="pre">Cols._v_colnames</span></tt></a> attribute.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Cols._v_desc">
<tt class="descname">_v_desc</tt><a class="headerlink" href="#tables.Cols._v_desc" title="Permalink to this definition">¶</a></dt>
<dd><p>The associated Description instance (see
<a class="reference internal" href="#descriptionclassdescr"><em>The Description class</em></a>).</p>
</dd></dl>
</dd></dl>
<div class="section" id="cols-properties">
<h4>Cols properties<a class="headerlink" href="#cols-properties" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="tables.Cols._v_table">
<tt class="descclassname">Cols.</tt><tt class="descname">_v_table</tt><a class="headerlink" href="#tables.Cols._v_table" title="Permalink to this definition">¶</a></dt>
<dd><p>The parent Table instance (see <a class="reference internal" href="#tableclassdescr"><em>The Table class</em></a>).</p>
</dd></dl>
</div>
<div class="section" id="cols-methods">
<h4>Cols methods<a class="headerlink" href="#cols-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="tables.Cols._f_col">
<tt class="descclassname">Cols.</tt><tt class="descname">_f_col</tt><big>(</big><em>colname</em><big>)</big><a class="headerlink" href="#tables.Cols._f_col" title="Permalink to this definition">¶</a></dt>
<dd><p>Get an accessor to the column colname.</p>
<p>This method returns a Column instance (see <a class="reference internal" href="#columnclassdescr"><em>The Column class</em></a>) if
the requested column is not nested, and a Cols instance (see
<a class="reference internal" href="#colsclassdescr"><em>The Cols class</em></a>) if it is. You may use full column pathnames in
colname.</p>
<p>Calling cols._f_col(‘col1/col2’) is equivalent to using cols.col1.col2.
However, the first syntax is more intended for programmatic use. It is
also better if you want to access columns with names that are not valid
Python identifiers.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Cols.__getitem__">
<tt class="descclassname">Cols.</tt><tt class="descname">__getitem__</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#tables.Cols.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a row or a range of rows from a table or nested column.</p>
<p>If key argument is an integer, the corresponding nested type row is
returned as a record of the current flavor. If key is a slice, the
range of rows determined by it is returned as a structured array of the
current flavor.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">record</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">cols</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="c"># equivalent to table[4]</span>
<span class="n">recarray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">cols</span><span class="o">.</span><span class="n">Info</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>
</pre></div>
</div>
<p>Those statements are equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">nrecord</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">4</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">nrecarray</span> <span class="o">=</span> <span class="n">table</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span> <span class="n">stop</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span><span class="o">.</span><span class="n">field</span><span class="p">(</span><span class="s">'Info'</span><span class="p">)</span>
</pre></div>
</div>
<p>Here you can see how a mix of natural naming, indexing and slicing can
be used as shorthands for the <a class="reference internal" href="#tables.Table.read" title="tables.Table.read"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read()</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Cols.__len__">
<tt class="descclassname">Cols.</tt><tt class="descname">__len__</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Cols.__len__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the number of top level columns in table.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Cols.__setitem__">
<tt class="descclassname">Cols.</tt><tt class="descname">__setitem__</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#tables.Cols.__setitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a row or a range of rows in a table or nested column.</p>
<p>If key argument is an integer, the corresponding row is set to
value. If key is a slice, the range of rows determined by it is set to
value.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span><span class="o">.</span><span class="n">cols</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="n">record</span>
<span class="n">table</span><span class="o">.</span><span class="n">cols</span><span class="o">.</span><span class="n">Info</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="o">=</span> <span class="n">recarray</span>
</pre></div>
</div>
<p>Those statements are equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">table</span><span class="o">.</span><span class="n">modify_rows</span><span class="p">(</span><span class="mi">4</span><span class="p">,</span> <span class="n">rows</span><span class="o">=</span><span class="n">record</span><span class="p">)</span>
<span class="n">table</span><span class="o">.</span><span class="n">modify_column</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">colname</span><span class="o">=</span><span class="s">'Info'</span><span class="p">,</span> <span class="n">column</span><span class="o">=</span><span class="n">recarray</span><span class="p">)</span>
</pre></div>
</div>
<p>Here you can see how a mix of natural naming, indexing and slicing
can be used as shorthands for the <a class="reference internal" href="#tables.Table.modify_rows" title="tables.Table.modify_rows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.modify_rows()</span></tt></a> and
<a class="reference internal" href="#tables.Table.modify_column" title="tables.Table.modify_column"><tt class="xref py py-meth docutils literal"><span class="pre">Table.modify_column()</span></tt></a> methods.</p>
</dd></dl>
</div>
</div>
<div class="section" id="the-column-class">
<span id="columnclassdescr"></span><h3>The Column class<a class="headerlink" href="#the-column-class" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="tables.Column">
<em class="property">class </em><tt class="descclassname">tables.</tt><tt class="descname">Column</tt><big>(</big><em>table</em>, <em>name</em>, <em>descr</em><big>)</big><a class="headerlink" href="#tables.Column" title="Permalink to this definition">¶</a></dt>
<dd><p>Accessor for a non-nested column in a table.</p>
<p>Each instance of this class is associated with one <em>non-nested</em> column of a
table. These instances are mainly used to read and write data from the
table columns using item access (like the Cols class - see
<a class="reference internal" href="#colsclassdescr"><em>The Cols class</em></a>), but there are a few other associated methods to
deal with indexes.</p>
<p class="rubric">Column attributes</p>
<dl class="attribute">
<dt id="tables.Column.descr">
<tt class="descname">descr</tt><a class="headerlink" href="#tables.Column.descr" title="Permalink to this definition">¶</a></dt>
<dd><p>The Description (see <a class="reference internal" href="#descriptionclassdescr"><em>The Description class</em></a>) instance of the
parent table or nested column.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.name">
<tt class="descname">name</tt><a class="headerlink" href="#tables.Column.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the associated column.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.pathname">
<tt class="descname">pathname</tt><a class="headerlink" href="#tables.Column.pathname" title="Permalink to this definition">¶</a></dt>
<dd><p>The complete pathname of the associated column (the same as
Column.name if the column is not inside a nested column).</p>
</dd></dl>
<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>table</strong> :</p>
<blockquote>
<div><p>The parent table instance</p>
</div></blockquote>
<p><strong>name</strong> :</p>
<blockquote>
<div><p>The name of the column that is associated with this object</p>
</div></blockquote>
<p><strong>descr</strong> :</p>
<blockquote class="last">
<div><p>The parent description object</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<div class="section" id="column-instance-variables">
<h4>Column instance variables<a class="headerlink" href="#column-instance-variables" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="tables.Column.dtype">
<tt class="descclassname">Column.</tt><tt class="descname">dtype</tt><a class="headerlink" href="#tables.Column.dtype" title="Permalink to this definition">¶</a></dt>
<dd><p>The NumPy dtype that most closely matches this column.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.index">
<tt class="descclassname">Column.</tt><tt class="descname">index</tt><a class="headerlink" href="#tables.Column.index" title="Permalink to this definition">¶</a></dt>
<dd><p>The Index instance (see <a class="reference internal" href="helper_classes.html#indexclassdescr"><em>The Index class</em></a>)
associated with this column (None if the column is not
indexed).</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.is_indexed">
<tt class="descclassname">Column.</tt><tt class="descname">is_indexed</tt><a class="headerlink" href="#tables.Column.is_indexed" title="Permalink to this definition">¶</a></dt>
<dd><p>True if the column is indexed, false otherwise.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.maindim">
<tt class="descclassname">Column.</tt><tt class="descname">maindim</tt><a class="headerlink" href="#tables.Column.maindim" title="Permalink to this definition">¶</a></dt>
<dd><p>“The dimension along which iterators work. Its value is 0 (i.e. the
first dimension).</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.shape">
<tt class="descclassname">Column.</tt><tt class="descname">shape</tt><a class="headerlink" href="#tables.Column.shape" title="Permalink to this definition">¶</a></dt>
<dd><p>The shape of this column.</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.table">
<tt class="descclassname">Column.</tt><tt class="descname">table</tt><a class="headerlink" href="#tables.Column.table" title="Permalink to this definition">¶</a></dt>
<dd><p>The parent Table instance (see
<a class="reference internal" href="#tableclassdescr"><em>The Table class</em></a>).</p>
</dd></dl>
<dl class="attribute">
<dt id="tables.Column.type">
<tt class="descclassname">Column.</tt><tt class="descname">type</tt><a class="headerlink" href="#tables.Column.type" title="Permalink to this definition">¶</a></dt>
<dd><p>The PyTables type of the column (a string).</p>
</dd></dl>
</div>
<div class="section" id="column-methods">
<h4>Column methods<a class="headerlink" href="#column-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="tables.Column.create_index">
<tt class="descclassname">Column.</tt><tt class="descname">create_index</tt><big>(</big><em>optlevel=6</em>, <em>kind='medium'</em>, <em>filters=None</em>, <em>tmp_dir=None</em>, <em>_blocksizes=None</em>, <em>_testmode=False</em>, <em>_verbose=False</em><big>)</big><a class="headerlink" href="#tables.Column.create_index" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an index for this column.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">In some situations it is useful to get a completely sorted
index (CSI). For those cases, it is best to use the
<a class="reference internal" href="#tables.Column.create_csindex" title="tables.Column.create_csindex"><tt class="xref py py-meth docutils literal"><span class="pre">Column.create_csindex()</span></tt></a> method instead.</p>
</div>
<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>optlevel</strong> : int</p>
<blockquote>
<div><p>The optimization level for building the index. The levels ranges
from 0 (no optimization) up to 9 (maximum optimization). Higher
levels of optimization mean better chances for reducing the entropy
of the index at the price of using more CPU, memory and I/O
resources for creating the index.</p>
</div></blockquote>
<p><strong>kind</strong> : str</p>
<blockquote>
<div><p>The kind of the index to be built. It can take the ‘ultralight’,
‘light’, ‘medium’ or ‘full’ values. Lighter kinds (‘ultralight’
and ‘light’) mean that the index takes less space on disk, but will
perform queries slower. Heavier kinds (‘medium’ and ‘full’) mean
better chances for reducing the entropy of the index (increasing
the query speed) at the price of using more disk space as well as
more CPU, memory and I/O resources for creating the index.</p>
<p>Note that selecting a full kind with an optlevel of 9 (the maximum)
guarantees the creation of an index with zero entropy, that is, a
completely sorted index (CSI) - provided that the number of rows in
the table does not exceed the 2**48 figure (that is more than 100
trillions of rows). See <a class="reference internal" href="#tables.Column.create_csindex" title="tables.Column.create_csindex"><tt class="xref py py-meth docutils literal"><span class="pre">Column.create_csindex()</span></tt></a> method for a
more direct way to create a CSI index.</p>
</div></blockquote>
<p><strong>filters</strong> : Filters</p>
<blockquote>
<div><p>Specify the Filters instance used to compress the index. If None,
default index filters will be used (currently, zlib level 1 with
shuffling).</p>
</div></blockquote>
<p><strong>tmp_dir</strong> :</p>
<blockquote class="last">
<div><p>When kind is other than ‘ultralight’, a temporary file is created
during the index build process. You can use the tmp_dir argument
to specify the directory for this temporary file. The default is
to create it in the same directory as the file containing the
original table.</p>
</div></blockquote>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="tables.Column.create_csindex">
<tt class="descclassname">Column.</tt><tt class="descname">create_csindex</tt><big>(</big><em>filters=None</em>, <em>tmp_dir=None</em>, <em>_blocksizes=None</em>, <em>_testmode=False</em>, <em>_verbose=False</em><big>)</big><a class="headerlink" href="#tables.Column.create_csindex" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a completely sorted index (CSI) for this column.</p>
<p>This method guarantees the creation of an index with zero entropy, that
is, a completely sorted index (CSI) – provided that the number of rows
in the table does not exceed the 2**48 figure (that is more than 100
trillions of rows). A CSI index is needed for some table methods (like
<a class="reference internal" href="#tables.Table.itersorted" title="tables.Table.itersorted"><tt class="xref py py-meth docutils literal"><span class="pre">Table.itersorted()</span></tt></a> or <a class="reference internal" href="#tables.Table.read_sorted" title="tables.Table.read_sorted"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read_sorted()</span></tt></a>) in order to
ensure completely sorted results.</p>
<p>For the meaning of filters and tmp_dir arguments see
<a class="reference internal" href="#tables.Column.create_index" title="tables.Column.create_index"><tt class="xref py py-meth docutils literal"><span class="pre">Column.create_index()</span></tt></a>.</p>
<p class="rubric">Notes</p>
<p>This method is equivalent to
Column.create_index(optlevel=9, kind=’full’, ...).</p>
</dd></dl>
<dl class="method">
<dt id="tables.Column.reindex">
<tt class="descclassname">Column.</tt><tt class="descname">reindex</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Column.reindex" title="Permalink to this definition">¶</a></dt>
<dd><p>Recompute the index associated with this column.</p>
<p>This can be useful when you suspect that, for any reason,
the index information is no longer valid and you want to rebuild it.</p>
<p>This method does nothing if the column is not indexed.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Column.reindex_dirty">
<tt class="descclassname">Column.</tt><tt class="descname">reindex_dirty</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Column.reindex_dirty" title="Permalink to this definition">¶</a></dt>
<dd><p>Recompute the associated index only if it is dirty.</p>
<p>This can be useful when you have set <a class="reference internal" href="#tables.Table.autoindex" title="tables.Table.autoindex"><tt class="xref py py-attr docutils literal"><span class="pre">Table.autoindex</span></tt></a> to false
for the table and you want to update the column’s index after an
invalidating index operation (like <a class="reference internal" href="#tables.Table.remove_rows" title="tables.Table.remove_rows"><tt class="xref py py-meth docutils literal"><span class="pre">Table.remove_rows()</span></tt></a>).</p>
<p>This method does nothing if the column is not indexed.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Column.remove_index">
<tt class="descclassname">Column.</tt><tt class="descname">remove_index</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Column.remove_index" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the index associated with this column.</p>
<p>This method does nothing if the column is not indexed. The removed
index can be created again by calling the <a class="reference internal" href="#tables.Column.create_index" title="tables.Column.create_index"><tt class="xref py py-meth docutils literal"><span class="pre">Column.create_index()</span></tt></a>
method.</p>
</dd></dl>
</div>
<div class="section" id="column-special-methods">
<h4>Column special methods<a class="headerlink" href="#column-special-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="tables.Column.__getitem__">
<tt class="descclassname">Column.</tt><tt class="descname">__getitem__</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#tables.Column.__getitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a row or a range of rows from a column.</p>
<p>If key argument is an integer, the corresponding element in the column
is returned as an object of the current flavor. If key is a slice, the
range of elements determined by it is returned as an array of the
current flavor.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><pre>print "Column handlers:"
for name in table.colnames:
print table.cols._f_col(name)
print "Select table.cols.name[1]-->", table.cols.name[1]
print "Select table.cols.name[1:2]-->", table.cols.name[1:2]
print "Select table.cols.name[:]-->", table.cols.name[:]
print "Select table.cols._f_col('name')[:]-->",
table.cols._f_col('name')[:]</pre>
</div>
<p>The output of this for a certain arbitrary table is:</p>
<div class="highlight-python"><pre>Column handlers:
/table.cols.name (Column(), string, idx=None)
/table.cols.lati (Column(), int32, idx=None)
/table.cols.longi (Column(), int32, idx=None)
/table.cols.vector (Column(2,), int32, idx=None)
/table.cols.matrix2D (Column(2, 2), float64, idx=None)
Select table.cols.name[1]--> Particle: 11
Select table.cols.name[1:2]--> ['Particle: 11']
Select table.cols.name[:]--> ['Particle: 10'
'Particle: 11' 'Particle: 12'
'Particle: 13' 'Particle: 14']
Select table.cols._f_col('name')[:]--> ['Particle: 10'
'Particle: 11' 'Particle: 12'
'Particle: 13' 'Particle: 14']</pre>
</div>
<p>See the <tt class="file docutils literal"><span class="pre">examples/table2.py</span></tt> file for a more complete example.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Column.__len__">
<tt class="descclassname">Column.</tt><tt class="descname">__len__</tt><big>(</big><big>)</big><a class="headerlink" href="#tables.Column.__len__" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the number of elements in the column.</p>
<p>This matches the length in rows of the parent table.</p>
</dd></dl>
<dl class="method">
<dt id="tables.Column.__setitem__">
<tt class="descclassname">Column.</tt><tt class="descname">__setitem__</tt><big>(</big><em>key</em>, <em>value</em><big>)</big><a class="headerlink" href="#tables.Column.__setitem__" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a row or a range of rows in a column.</p>
<p>If key argument is an integer, the corresponding element is set to
value. If key is a slice, the range of elements determined by it is
set to value.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Modify row 1</span>
<span class="n">table</span><span class="o">.</span><span class="n">cols</span><span class="o">.</span><span class="n">col1</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span>
<span class="c"># Modify rows 1 and 3</span>
<span class="n">table</span><span class="o">.</span><span class="n">cols</span><span class="o">.</span><span class="n">col1</span><span class="p">[</span><span class="mi">1</span><span class="p">::</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]</span>
</pre></div>
</div>
<p>Which is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Modify row 1</span>
<span class="n">table</span><span class="o">.</span><span class="n">modify_columns</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="p">[[</span><span class="o">-</span><span class="mi">1</span><span class="p">]],</span> <span class="n">names</span><span class="o">=</span><span class="p">[</span><span class="s">'col1'</span><span class="p">])</span>
<span class="c"># Modify rows 1 and 3</span>
<span class="n">columns</span> <span class="o">=</span> <span class="n">numpy</span><span class="o">.</span><span class="n">rec</span><span class="o">.</span><span class="n">fromarrays</span><span class="p">([[</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">]],</span> <span class="n">formats</span><span class="o">=</span><span class="s">'i4'</span><span class="p">)</span>
<span class="n">table</span><span class="o">.</span><span class="n">modify_columns</span><span class="p">(</span><span class="n">start</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">step</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="n">columns</span><span class="p">,</span>
<span class="n">names</span><span class="o">=</span><span class="p">[</span><span class="s">'col1'</span><span class="p">])</span>
</pre></div>
</div>
</dd></dl>
</div>
</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="#">Structured storage classes</a><ul>
<li><a class="reference internal" href="#the-table-class">The Table class</a><ul>
<li><a class="reference internal" href="#table-properties">Table properties</a></li>
<li><a class="reference internal" href="#table-methods-reading">Table methods - reading</a></li>
<li><a class="reference internal" href="#table-methods-writing">Table methods - writing</a></li>
<li><a class="reference internal" href="#table-methods-querying">Table methods - querying</a></li>
<li><a class="reference internal" href="#table-methods-other">Table methods - other</a></li>
<li><a class="reference internal" href="#the-description-class">The Description class</a><ul>
<li><a class="reference internal" href="#description-methods">Description methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-row-class">The Row class</a><ul>
<li><a class="reference internal" href="#row-methods">Row methods</a></li>
<li><a class="reference internal" href="#row-special-methods">Row special methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-cols-class">The Cols class</a><ul>
<li><a class="reference internal" href="#cols-properties">Cols properties</a></li>
<li><a class="reference internal" href="#cols-methods">Cols methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-column-class">The Column class</a><ul>
<li><a class="reference internal" href="#column-instance-variables">Column instance variables</a></li>
<li><a class="reference internal" href="#column-methods">Column methods</a></li>
<li><a class="reference internal" href="#column-special-methods">Column special methods</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="hierarchy_classes.html"
title="previous chapter">Hierarchy definition classes</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="homogenous_storage.html"
title="next chapter">Homogenous storage classes</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/usersguide/libref/structured_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="homogenous_storage.html" title="Homogenous storage classes"
>next</a> </li>
<li class="right" >
<a href="hierarchy_classes.html" title="Hierarchy definition 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>
