<!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>Condition Syntax — 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="PyTables User’s Guide" href="index.html" />
<link rel="next" title="PyTables parameter files" href="parameter_files.html" />
<link rel="prev" title="Supported data types in PyTables" href="datatypes.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="parameter_files.html" title="PyTables parameter files"
accesskey="N">next</a> </li>
<li class="right" >
<a href="datatypes.html" title="Supported data types in PyTables"
accesskey="P">previous</a> </li>
<li><a href="../index.html">PyTables 3.0.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">PyTables User’s Guide</a> »</li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="condition-syntax">
<span id="id1"></span><h1>Condition Syntax<a class="headerlink" href="#condition-syntax" title="Permalink to this headline">¶</a></h1>
<p>Conditions in PyTables are used in methods related with in-kernel and indexed
searches such as <a class="reference internal" href="libref/structured_storage.html#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> or <a class="reference internal" href="libref/structured_storage.html#tables.Table.read_where" title="tables.Table.read_where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.read_where()</span></tt></a>.
They are interpreted using Numexpr, a powerful package for achieving C-speed
computation of array operations (see <a class="reference internal" href="bibliography.html#numexpr"><em>[NUMEXPR]</em></a>).</p>
<p>A condition on a table is just a <em>string</em> containing a Python expression
involving <em>at least one column</em>, and maybe some constants and external
variables, all combined with algebraic operators and functions. The result of
a valid condition is always a <em>boolean array</em> of the same length as the
table, where the <em>i</em>-th element is true if the value of the expression on the
<em>i</em>-th row of the table evaluates to true</p>
<p>That is the reason why multidimensional fields in a table are not supported
in conditions, since the truth value of each resulting multidimensional
boolean value is not obvious.
Usually, a method using a condition will only consider the rows where the
boolean result is true.</p>
<p>For instance, the condition ‘sqrt(x*x + y*y) < 1’ applied on a table with x
and y columns consisting of floating point numbers results in a boolean array
where the <em>i</em>-th element is true if (unsurprisingly) the value of the square
root of the sum of squares of x and y is less than 1.
The sqrt() function works element-wise, the 1 constant is adequately
broadcast to an array of ones of the length of the table for evaluation, and
the <em>less than</em> operator makes the result a valid boolean array. A condition
like ‘mycolumn’ alone will not usually be valid, unless mycolumn is itself a
column of scalar, boolean values.</p>
<p>In the previous conditions, mycolumn, x and y are examples of <em>variables</em>
which are associated with columns.
Methods supporting conditions do usually provide their own ways of binding
variable names to columns and other values. You can read the documentation of
<a class="reference internal" href="libref/structured_storage.html#tables.Table.where" title="tables.Table.where"><tt class="xref py py-meth docutils literal"><span class="pre">Table.where()</span></tt></a> for more information on that. Also, please note that the
names None, True and False, besides the names of functions (see below) <em>can
not be overridden</em>, but you can always define other new names for the objects
you intend to use.</p>
<p>Values in a condition may have the following types:</p>
<ul class="simple">
<li>8-bit boolean (bool).</li>
<li>32-bit signed integer (int).</li>
<li>64-bit signed integer (long).</li>
<li>32-bit, single-precision floating point number (float or float32).</li>
<li>64-bit, double-precision floating point number (double or float64).</li>
<li>2x64-bit, double-precision complex number (complex).</li>
<li>Raw string of bytes (str).</li>
</ul>
<p>Nevertheless, if the type passed is not among the above ones, it will be
silently upcasted, so you don’t need to worry too much about passing
supported types, except for the Unsigned 64 bits integer, that cannot be
upcasted to any of the supported types.</p>
<p>However, the types in PyTables conditions are somewhat stricter than those of
Python. For instance, the <em>only</em> valid constants for booleans are True and
False, and they are <em>never</em> automatically cast to integers. The type
strengthening also affects the availability of operators and functions.
Beyond that, the usual type inference rules apply.</p>
<p>Conditions support the set of operators listed below:</p>
<ul class="simple">
<li>Logical operators: &, |, ~.</li>
<li>Comparison operators: <, <=, ==, !=, >=, >.</li>
<li>Unary arithmetic operators: -.</li>
<li>Binary arithmetic operators: +, -, *, /, **, %.</li>
</ul>
<p>Types do not support all operators. Boolean values only support logical and
strict (in)equality comparison operators, while strings only support
comparisons, numbers do not work with logical operators, and complex
comparisons can only check for strict (in)equality. Unsupported operations
(including invalid castings) raise NotImplementedError exceptions.</p>
<p>You may have noticed the special meaning of the usually bitwise operators &,
| and ~. Because of the way Python handles the short-circuiting of logical
operators and the truth values of their operands, conditions must use the
bitwise operator equivalents instead.
This is not difficult to remember, but you must be careful because bitwise
operators have a <em>higher precedence</em> than logical operators. For instance,
‘a and b == c’ (<em>a is true AND b is equal to c</em>) is <em>not</em> equivalent to
‘a & b == c’ (<em>a AND b is equal to c)</em>. The safest way to avoid confusions is
to <em>use parentheses</em> around logical operators, like this: ‘a & (b == c)’.
Another effect of short-circuiting is that expressions like ‘0 < x < 1’ will
<em>not</em> work as expected; you should use ‘(0 < x) & (x < 1)’.</p>
<p>All of this may be solved if Python supported overloadable boolean operators
(see PEP 335) or some kind of non-shortcircuiting boolean operators (like C’s
&&, || and !).</p>
<p>You can also use the following functions in conditions:</p>
<ul class="simple">
<li>where(bool, number1, number2):
number - number1 if the bool condition is true, number2 otherwise.</li>
<li>{sin,cos,tan}(float|complex):
float|complex - trigonometric sine, cosine or tangent.</li>
<li>{arcsin,arccos,arctan}(float|complex):
float|complex - trigonometric inverse sine, cosine or tangent.</li>
<li>arctan2(float1, float2):
float - trigonometric inverse tangent of float1/float2.</li>
<li>{sinh,cosh,tanh}(float|complex):
float|complex - hyperbolic sine, cosine or tangent.</li>
<li>{arcsinh,arccosh,arctanh}(float|complex):
float|complex - hyperbolic inverse sine, cosine or tangent.</li>
<li>{log,log10,log1p}(float|complex):
float|complex - natural, base-10 and log(1+x) logarithms.</li>
<li>{exp,expm1}(float|complex):
float|complex - exponential and exponential minus one.</li>
<li>sqrt(float|complex): float|complex - square root.</li>
<li>{abs}(float|complex): float|complex - absolute value.</li>
<li>{real,imag}(complex):
float - real or imaginary part of complex.</li>
<li>complex(float, float):
complex - complex from real and imaginary parts.</li>
</ul>
</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>
<h4>Previous topic</h4>
<p class="topless"><a href="datatypes.html"
title="previous chapter">Supported data types in PyTables</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="parameter_files.html"
title="next chapter">PyTables parameter files</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/usersguide/condition_syntax.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="parameter_files.html" title="PyTables parameter files"
>next</a> </li>
<li class="right" >
<a href="datatypes.html" title="Supported data types in PyTables"
>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>
</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>
