Inherits object.
The table class provides convenient access to data in tabular form. An empty
table can be easily constructed as follows
.. code-block:: python
tab = Table()
If you want to add columns directly when creating the table, column names
and *column types* can be specified as follows
.. code-block:: python
tab = Table(['nameX','nameY','nameZ'], 'sfb')
this will create three columns called nameX, nameY and nameZ of type string,
float and bool, respectively. There will be no data in the table and thus,
the table will not contain any rows.
The following *column types* are supported:
======= ========
name abbrev
======= ========
string s
float f
int i
bool b
======= ========
If you want to add data to the table in addition, use the following:
.. code-block:: python
tab=Table(['nameX','nameY','nameZ'],
'sfb',
nameX = ['a','b','c'],
nameY = [0.1, 1.2, 3.414],
nameZ = [True, False, False])
if values for one column is left out, they will be filled with NA, but if
values are specified, all values must be specified (i.e. same number of
values per column)
Definition at line 170 of file table.py.
def AddCol |
( |
|
self, |
|
|
|
col_name, |
|
|
|
col_type, |
|
|
|
data = None |
|
) |
| |
Add a column to the right of the table.
:param col_name: name of new column
:type col_name: :class:`str`
:param col_type: type of new column (long versions: *int*, *float*, *bool*,
*string* or short versions: *i*, *f*, *b*, *s*)
:type col_type: :class:`str`
:param data: data to add to new column
:type data: scalar or iterable
**Example:**
.. code-block:: python
tab = Table(['x'], 'f', x=range(5))
tab.AddCol('even', 'bool', itertools.cycle([True, False]))
print tab
'''
will produce the table
==== ====
x even
==== ====
0 True
1 False
2 True
3 False
4 True
==== ====
'''
If data is a constant instead of an iterable object, it's value
will be written into each row:
.. code-block:: python
tab = Table(['x'], 'f', x=range(5))
tab.AddCol('num', 'i', 1)
print tab
'''
will produce the table
==== ====
x num
==== ====
0 1
1 1
2 1
3 1
4 1
==== ====
'''
As a special case, if there are no previous rows, and data is not
None, rows are added for every item in data.
Definition at line 701 of file table.py.
def AddRow |
( |
|
self, |
|
|
|
data, |
|
|
|
overwrite = None |
|
) |
| |
Add a row to the table.
*data* may either be a dictionary or a list-like object:
- If *data* is a dictionary, the keys in the dictionary must match the
column names. Columns not found in the dict will be initialized to None.
If the dict contains list-like objects, multiple rows will be added, if
the number of items in all list-like objects is the same, otherwise a
:class:`ValueError` is raised.
- If *data* is a list-like object, the row is initialized from the values
in *data*. The number of items in *data* must match the number of
columns in the table. A :class:`ValuerError` is raised otherwise. The
values are added in the order specified in the list, thus, the order of
the data must match the columns.
If *overwrite* is not None and set to an existing column name, the specified
column in the table is searched for the first occurrence of a value matching
the value of the column with the same name in the dictionary. If a matching
value is found, the row is overwritten with the dictionary. If no matching
row is found, a new row is appended to the table.
:param data: data to add
:type data: :class:`dict` or *list-like* object
:param overwrite: column name to overwrite existing row if value in
column *overwrite* matches
:type overwrite: :class:`str`
:raises: :class:`ValueError` if *list-like* object is used and number of
items does *not* match number of columns in table.
:raises: :class:`ValueError` if *dict* is used and multiple rows are added
but the number of data items is different for different columns.
**Example:** add multiple data rows to a subset of columns using a dictionary
.. code-block:: python
# create table with three float columns
tab = Table(['x','y','z'], 'fff')
# add rows from dict
data = {'x': [1.2, 1.6], 'z': [1.6, 5.3]}
tab.AddRow(data)
print tab
'''
will produce the table
==== ==== ====
x y z
==== ==== ====
1.20 NA 1.60
1.60 NA 5.30
==== ==== ====
'''
# overwrite the row with x=1.2 and add row with x=1.9
data = {'x': [1.2, 1.9], 'z': [7.9, 3.5]}
tab.AddRow(data, overwrite='x')
print tab
'''
will produce the table
==== ==== ====
x y z
==== ==== ====
1.20 NA 7.90
1.60 NA 5.30
1.90 NA 3.50
==== ==== ====
'''
Definition at line 589 of file table.py.
def GetOptimalPrefactors |
( |
|
self, |
|
|
|
ref_col, |
|
|
|
args, |
|
|
|
kwargs |
|
) |
| |
This returns the optimal prefactor values (i.e. a, b, c, ...) for the
following equation
.. math::
:label: op1
a*u + b*v + c*w + ... = z
where u, v, w and z are vectors. In matrix notation
.. math::
:label: op2
A*p = z
where A contains the data from the table (u,v,w,...), p are the prefactors
to optimize (a,b,c,...) and z is the vector containing the result of
equation :eq:`op1`.
The parameter ref_col equals to z in both equations, and \*args are columns
u, v and w (or A in :eq:`op2`). All columns must be specified by their names.
**Example:**
.. code-block:: python
tab.GetOptimalPrefactors('colC', 'colA', 'colB')
The function returns a list of containing the prefactors a, b, c, ... in
the correct order (i.e. same as columns were specified in \*args).
Weighting:
If the kwarg weights="columX" is specified, the equations are weighted by
the values in that column. Each row is multiplied by the weight in that row,
which leads to :eq:`op3`:
.. math::
:label: op3
weight*a*u + weight*b*v + weight*c*w + ... = weight*z
Weights must be float or int and can have any value. A value of 0 ignores
this equation, a value of 1 means the same as no weight. If all weights are
the same for each row, the same result will be obtained as with no weights.
**Example:**
.. code-block:: python
tab.GetOptimalPrefactors('colC', 'colA', 'colB', weights='colD')
Definition at line 2395 of file table.py.
def Load |
( |
|
stream_or_filename, |
|
|
|
format = 'auto' , |
|
|
|
sep = ' |
|
) |
| |
|
static |
Load table from stream or file with given name.
By default, the file format is set to *auto*, which tries to guess the file
format from the file extension. The following file extensions are
recognized:
============ ======================
extension recognized format
============ ======================
.csv comma separated values
.pickle pickled byte stream
<all others> ost-specific format
============ ======================
Thus, *format* must be specified for reading file with different filename
extensions.
The following file formats are understood:
- ost
This is an ost-specific, but still human readable file format. The file
(stream) must start with header line of the form
col_name1[type1] <col_name2[type2]>...
The types given in brackets must be one of the data types the
:class:`Table` class understands. Each following line in the file then must
contains exactly the same number of data items as listed in the header. The
data items are automatically converted to the column format. Lines starting
with a '#' and empty lines are ignored.
- pickle
Deserializes the table from a pickled byte stream.
- csv
Reads the table from comma separated values stream. Since there is no
explicit type information in the csv file, the column types are guessed,
using the following simple rules:
* if all values are either NA/NULL/NONE the type is set to string.
* if all non-null values are convertible to float/int the type is set to
float/int.
* if all non-null values are true/false/yes/no, the value is set to bool.
* for all other cases, the column type is set to string.
:returns: A new :class:`Table` instance
Definition at line 967 of file table.py.
def Plot |
( |
|
self, |
|
|
|
x, |
|
|
|
y = None , |
|
|
|
z = None , |
|
|
|
style = '.' , |
|
|
|
x_title = None , |
|
|
|
y_title = None , |
|
|
|
z_title = None , |
|
|
|
x_range = None , |
|
|
|
y_range = None , |
|
|
|
z_range = None , |
|
|
|
color = None , |
|
|
|
plot_if = None , |
|
|
|
legend = None , |
|
|
|
num_z_levels = 10 , |
|
|
|
z_contour = True , |
|
|
|
z_interpol = 'nn' , |
|
|
|
diag_line = False , |
|
|
|
labels = None , |
|
|
|
max_num_labels = None , |
|
|
|
title = None , |
|
|
|
clear = True , |
|
|
|
save = False , |
|
|
|
kwargs |
|
) |
| |
Function to plot values from your table in 1, 2 or 3 dimensions using
`Matplotlib <http://matplotlib.sourceforge.net>`__
:param x: column name for first dimension
:type x: :class:`str`
:param y: column name for second dimension
:type y: :class:`str`
:param z: column name for third dimension
:type z: :class:`str`
:param style: symbol style (e.g. *.*, *-*, *x*, *o*, *+*, *\**). For a
complete list check (`matplotlib docu <http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.plot>`__).
:type style: :class:`str`
:param x_title: title for first dimension, if not specified it is
automatically derived from column name
:type x_title: :class:`str`
:param y_title: title for second dimension, if not specified it is
automatically derived from column name
:type y_title: :class:`str`
:param z_title: title for third dimension, if not specified it is
automatically derived from column name
:type z_title: :class:`str`
:param x_range: start and end value for first dimension (e.g. [start_x, end_x])
:type x_range: :class:`list` of length two
:param y_range: start and end value for second dimension (e.g. [start_y, end_y])
:type y_range: :class:`list` of length two
:param z_range: start and end value for third dimension (e.g. [start_z, end_z])
:type z_range: :class:`list` of length two
:param color: color for data (e.g. *b*, *g*, *r*). For a complete list check
(`matplotlib docu <http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.plot>`__).
:type color: :class:`str`
:param plot_if: callable which returnes *True* if row should be plotted. Is
invoked like ``plot_if(self, row)``
:type plot_if: callable
:param legend: legend label for data series
:type legend: :class:`str`
:param num_z_levels: number of levels for third dimension
:type num_z_levels: :class:`int`
:param diag_line: draw diagonal line
:type diag_line: :class:`bool`
:param labels: column name containing labels to put on x-axis for one
dimensional plot
:type labels: :class:`str`
:param max_num_labels: limit maximum number of labels
:type max_num_labels: :class:`int`
:param title: plot title, if not specified it is automatically derived from
plotted column names
:type title: :class:`str`
:param clear: clear old data from plot
:type clear: :class:`bool`
:param save: filename for saving plot
:type save: :class:`str`
:param z_contour: draw contour lines
:type z_contour: :class:`bool`
:param z_interpol: interpolation method for 3-dimensional plot (one of 'nn',
'linear')
:type z_interpol: :class:`str`
:param \*\*kwargs: additional arguments passed to matplotlib
:returns: the ``matplotlib.pyplot`` module
**Examples:** simple plotting functions
.. code-block:: python
tab = Table(['a','b','c','d'],'iffi', a=range(5,0,-1),
b=[x/2.0 for x in range(1,6)],
c=[math.cos(x) for x in range(0,5)],
d=range(3,8))
# one dimensional plot of column 'd' vs. index
plt = tab.Plot('d')
plt.show()
# two dimensional plot of 'a' vs. 'c'
plt = tab.Plot('a', y='c', style='o-')
plt.show()
# three dimensional plot of 'a' vs. 'c' with values 'b'
plt = tab.Plot('a', y='c', z='b')
# manually save plot to file
plt.savefig("plot.png")
Definition at line 1095 of file table.py.
def PlotBar |
( |
|
self, |
|
|
|
cols = None , |
|
|
|
rows = None , |
|
|
|
xlabels = None , |
|
|
|
set_xlabels = True , |
|
|
|
xlabels_rotation = 'horizontal' , |
|
|
|
y_title = None , |
|
|
|
title = None , |
|
|
|
colors = None , |
|
|
|
width = 0.8 , |
|
|
|
bottom = 0 , |
|
|
|
legend = False , |
|
|
|
legend_names = None , |
|
|
|
show = False , |
|
|
|
save = False |
|
) |
| |
Create a barplot of the data in cols. Every column will be represented
at one position. If there are several rows, each column will be grouped
together.
:param cols: List of column names. Every column will be represented as a
single bar. If cols is None, every column of the table gets
plotted.
:type cols: :class:`list`
:param rows: List of row indices. Values from given rows will be plotted
in parallel at one column position. If set to None, all rows
of the table will be plotted. Note, that the maximum number
of rows is 7.
:type rows: :class:`list`
:param xlabels: Label for every col on x-axis. If set to None, the column
names are used. The xlabel plotting can be supressed by
the parameter set_xlabel.
:type xlabels: :class:`list`
:param set_xlabels: Controls whether xlabels are plotted or not.
:type set_xlabels: :class:`bool`
:param x_labels_rotation: Can either be 'horizontal', 'vertical' or an
integer, that describes the rotation in degrees.
:param y_title: Y-axis description
:type y_title: :class:`str`
:title: Title of the plot. No title appears if set to None
:type title: :class:`str`
:param colors: Colors of the different bars in each group. Must be a list
of valid colors in matplotlib. Length of color and rows must
be consistent.
:type colors: :class:`list`
:param width: The available space for the groups on the x-axis is divided
by the exact number of groups. The parameters width is the
fraction of what is actually used. If it would be 1.0 the
bars of the different groups would touch each other.
Value must be between [0;1]
:type width: :class:`float`
:param bottom: Bottom
:type bottom: :class:`float`
:param legend: Legend for color explanation, the corresponding row
respectively. If set to True, legend_names must be provided.
:type legend: :class:`bool`
:param legend_names: List of names, that describe the differently colored
bars. Length must be consistent with number of rows.
:param show: If set to True, the plot is directly displayed.
:param save: If set, a png image with name save in the current working
directory will be saved.
:type save: :class:`str`
Definition at line 1477 of file table.py.
def PlotHexbin |
( |
|
self, |
|
|
|
x, |
|
|
|
y, |
|
|
|
title = None , |
|
|
|
x_title = None , |
|
|
|
y_title = None , |
|
|
|
x_range = None , |
|
|
|
y_range = None , |
|
|
|
binning = 'log' , |
|
|
|
colormap = 'jet' , |
|
|
|
show_scalebar = False , |
|
|
|
scalebar_label = None , |
|
|
|
clear = True , |
|
|
|
save = False , |
|
|
|
show = False |
|
) |
| |
Create a heatplot of the data in col x vs the data in col y using matplotlib
:param x: column name with x data
:type x: :class:`str`
:param y: column name with y data
:type y: :class:`str`
:param title: title of the plot, will be generated automatically if set to None
:type title: :class:`str`
:param x_title: label of x-axis, will be generated automatically if set to None
:type title: :class:`str`
:param y_title: label of y-axis, will be generated automatically if set to None
:type title: :class:`str`
:param x_range: start and end value for first dimension (e.g. [start_x, end_x])
:type x_range: :class:`list` of length two
:param y_range: start and end value for second dimension (e.g. [start_y, end_y])
:type y_range: :class:`list` of length two
:param binning: type of binning. If set to None, the value of a hexbin will
correspond to the number of datapoints falling into it. If
set to 'log', the value will be the log with base 10 of the above
value (log(i+1)). If an integer is provided, the number of a
hexbin is equal the number of datapoints falling into it divided
by the integer. If a list of values is provided, these values
will be the lower bounds of the bins.
:param colormap: colormap, that will be used. Value can be every colormap defined
in matplotlib or an own defined colormap. You can either pass a
string with the name of the matplotlib colormap or a colormap
object.
:param show_scalebar: If set to True, a scalebar according to the chosen colormap is shown
:type show_scalebar: :class:`bool`
:param scalebar_label: Label of the scalebar
:type scalebar_label: :class:`str`
:param clear: clear old data from plot
:type clear: :class:`bool`
:param save: filename for saving plot
:type save: :class:`str`
:param show: directly show plot
:type show: :class:`bool`
Definition at line 1639 of file table.py.
def PlotHistogram |
( |
|
self, |
|
|
|
col, |
|
|
|
x_range = None , |
|
|
|
num_bins = 10 , |
|
|
|
normed = False , |
|
|
|
histtype = 'stepfilled' , |
|
|
|
align = 'mid' , |
|
|
|
x_title = None , |
|
|
|
y_title = None , |
|
|
|
title = None , |
|
|
|
clear = True , |
|
|
|
save = False , |
|
|
|
color = None , |
|
|
|
y_range = None |
|
) |
| |
Create a histogram of the data in col for the range *x_range*, split into
*num_bins* bins and plot it using Matplotlib.
:param col: column name with data
:type col: :class:`str`
:param x_range: start and end value for first dimension (e.g. [start_x, end_x])
:type x_range: :class:`list` of length two
:param y_range: start and end value for second dimension (e.g. [start_y, end_y])
:type y_range: :class:`list` of length two
:param num_bins: number of bins in range
:type num_bins: :class:`int`
:param color: Color to be used for the histogram. If not set, color will be
determined by matplotlib
:type color: :class:`str`
:param normed: normalize histogram
:type normed: :class:`bool`
:param histtype: type of histogram (i.e. *bar*, *barstacked*, *step*,
*stepfilled*). See (`matplotlib docu <http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.hist>`__).
:type histtype: :class:`str`
:param align: style of histogram (*left*, *mid*, *right*). See
(`matplotlib docu <http://matplotlib.sourceforge.net/api/pyplot_api.html#matplotlib.pyplot.hist>`__).
:type align: :class:`str`
:param x_title: title for first dimension, if not specified it is
automatically derived from column name
:type x_title: :class:`str`
:param y_title: title for second dimension, if not specified it is
automatically derived from column name
:type y_title: :class:`str`
:param title: plot title, if not specified it is automatically derived from
plotted column names
:type title: :class:`str`
:param clear: clear old data from plot
:type clear: :class:`bool`
:param save: filename for saving plot
:type save: :class:`str`
**Examples:** simple plotting functions
.. code-block:: python
tab = Table(['a'],'f', a=[math.cos(x*0.01) for x in range(100)])
# one dimensional plot of column 'd' vs. index
plt = tab.PlotHistogram('a')
plt.show()
Definition at line 1349 of file table.py.
def Select |
( |
|
self, |
|
|
|
query |
|
) |
| |
Returns a new table object containing all rows matching a logical query
expression.
*query* is a string containing the logical expression, that will be
evaluated for every row.
Operands have to be the name of a column or an expression that can be
parsed to float, int, bool or string.
Valid operators are: and, or, !=, !, <=, >=, ==, =, <, >, +, -, \*, /
.. code-block:: python
subtab = tab.Select('col_a>0.5 and (col_b=5 or col_c=5)')
The selection query should be self explaining. Allowed parenthesis are:
(), [], {}, whereas parenthesis mismatches get recognized. Expressions like
'3<=col_a>=col_b' throw an error, due to problems in figuring out the
evaluation order.
There are two special expressions:
.. code-block:: python
#selects rows, where 1.0<=col_a<=1.5
subtab = tab.Select('col_a=1.0:1.5')
#selects rows, where col_a=1 or col_a=2 or col_a=3
subtab = tab.Select('col_a=1,2,3')
Only consistent types can be compared. If col_a is of type string and col_b
is of type int, following expression would throw an error: 'col_a<col_b'
Definition at line 827 of file table.py.