A class for evaluating expressions with arbitrary array-like objects. Expr is a class for evaluating expressions containing array-like objects. With it, you can evaluate expressions (like "3 * a + 4 * b") that operate on arbitrary large arrays while optimizing the resources required
| 24 | |
| 25 | |
| 26 | class Expr: |
| 27 | """A class for evaluating expressions with arbitrary array-like objects. |
| 28 | |
| 29 | Expr is a class for evaluating expressions containing array-like objects. |
| 30 | With it, you can evaluate expressions (like "3 * a + 4 * b") that |
| 31 | operate on arbitrary large arrays while optimizing the resources |
| 32 | required to perform them (basically main memory and CPU cache memory). |
| 33 | It is similar to the Numexpr package (see :ref:`[NUMEXPR] <NUMEXPR>`), |
| 34 | but in addition to NumPy objects, it also accepts disk-based homogeneous |
| 35 | arrays, like the Array, CArray, EArray and Column PyTables objects. |
| 36 | |
| 37 | .. warning:: |
| 38 | |
| 39 | Expr class only offers a subset of the Numexpr features due to the |
| 40 | complexity of implement some of them when dealing with huge amount of |
| 41 | data. |
| 42 | |
| 43 | All the internal computations are performed via the Numexpr package, |
| 44 | so all the broadcast and upcasting rules of Numexpr applies here too. |
| 45 | These rules are very similar to the NumPy ones, but with some exceptions |
| 46 | due to the particularities of having to deal with potentially very large |
| 47 | disk-based arrays. Be sure to read the documentation of the Expr |
| 48 | constructor and methods as well as that of Numexpr, if you want to fully |
| 49 | grasp these particularities. |
| 50 | |
| 51 | |
| 52 | Parameters |
| 53 | ---------- |
| 54 | expr : str |
| 55 | This specifies the expression to be evaluated, such as "2 * a + 3 * b". |
| 56 | uservars : dict |
| 57 | This can be used to define the variable names appearing in *expr*. |
| 58 | This mapping should consist of identifier-like strings pointing to any |
| 59 | `Array`, `CArray`, `EArray`, `Column` or NumPy ndarray instances (or |
| 60 | even others which will tried to be converted to ndarrays). When |
| 61 | `uservars` is not provided or `None`, the current local and global |
| 62 | namespace is sought instead of `uservars`. It is also possible to pass |
| 63 | just some of the variables in expression via the `uservars` mapping, |
| 64 | and the rest will be retrieved from the current local and global |
| 65 | namespaces. |
| 66 | kwargs : dict |
| 67 | This is meant to pass additional parameters to the Numexpr kernel. |
| 68 | This is basically the same as the kwargs argument in |
| 69 | Numexpr.evaluate(), and is mainly meant for advanced use. |
| 70 | |
| 71 | Examples |
| 72 | -------- |
| 73 | The following shows an example of using Expr:: |
| 74 | |
| 75 | >>> f = tb.open_file('/tmp/test_expr.h5', 'w') |
| 76 | >>> a = f.create_array('/', 'a', np.array([1,2,3])) |
| 77 | >>> b = f.create_array('/', 'b', np.array([3,4,5])) |
| 78 | >>> c = np.array([4,5,6]) |
| 79 | >>> expr = tb.Expr("2 * a + b * c") # initialize the expression |
| 80 | >>> expr.eval() # evaluate it |
| 81 | array([14, 24, 36], dtype=int64) |
| 82 | >>> sum(expr) # use as an iterator |
| 83 | 74 |