From c264b903ac872f2cb851e4d9be4bfe88abc3f524 Mon Sep 17 00:00:00 2001
From: Tjaart de Beer <tjaart@kb-pratchet.pz.unibas.ch>
Date: Tue, 3 Mar 2015 12:00:26 +0100
Subject: [PATCH] Updated more documentation.
Signed-off-by: Stefan Bienert <stefan.bienert@unibas.ch>
---
modules/base/pymod/table.py | 122 ++++++++++++++++++-----------------
modules/doc/contributing.rst | 10 +--
modules/doc/table.rst | 14 ++--
3 files changed, 75 insertions(+), 71 deletions(-)
diff --git a/modules/base/pymod/table.py b/modules/base/pymod/table.py
index 04fefecc0..5e67ee6a6 100644
--- a/modules/base/pymod/table.py
+++ b/modules/base/pymod/table.py
@@ -175,14 +175,14 @@ class Table(object):
.. code-block:: python
- tab=Table()
+ 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')
+ 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,
@@ -205,9 +205,9 @@ class Table(object):
tab=Table(['nameX','nameY','nameZ'],
'sfb',
- nameX=['a','b','c'],
- nameY=[0.1, 1.2, 3.414],
- nameZ=[True, False, False])
+ 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
@@ -314,6 +314,7 @@ class Table(object):
def SetName(self, name):
'''
Set name of the table
+
:param name: name
:type name: :class:`str`
'''
@@ -369,7 +370,7 @@ class Table(object):
'''
Returns the column index for the column with the given name.
- :raises: ValueError if no column with the name is found
+ :raises: ValueError if no column with the name is found.
'''
if col not in self.col_names:
raise ValueError('Table has no column named "%s"' % col)
@@ -383,7 +384,7 @@ class Table(object):
def SearchColNames(self, regex):
'''
- Returns a list of column names matching the regex
+ Returns a list of column names matching the regex.
:param regex: regex pattern
:type regex: :class:`str`
@@ -423,10 +424,10 @@ class Table(object):
Convert the table into a string representation.
The output format can be modified for int and float type columns by
- specifying a formatting string for the parameters 'float_format' and
- 'int_format'.
+ specifying a formatting string for the parameters *float_format* and
+ *int_format*.
- The option 'rows' specify the range of rows to be printed. The parameter
+ The option *rows* specify the range of rows to be printed. The parameter
must be a type that supports indexing (e.g. a :class:`list`) containing the
start and end row *index*, e.g. [start_row_idx, end_row_idx].
@@ -564,12 +565,12 @@ Statistics for column %(col)s
def PairedTTest(self, col_a, col_b):
"""
Two-sided test for the null-hypothesis that two related samples
- have the same average (expected values)
+ have the same average (expected values).
:param col_a: First column
:param col_b: Second column
- :returns: P-value between 0 and 1 that the two columns have the
+ :returns: P-value between 0 and 1 that the two columns have the
same average. The smaller the value, the less related the two
columns are.
"""
@@ -589,7 +590,7 @@ Statistics for column %(col)s
*data* may either be a dictionary or a list-like object:
- - If *data* is a dictionary the keys in the dictionary must match the
+ - 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
@@ -684,7 +685,7 @@ Statistics for column %(col)s
def RemoveCol(self, col):
"""
- Remove column with the given name from the table
+ Remove column with the given name from the table.
:param col: name of column to remove
:type col: :class:`str`
@@ -706,14 +707,14 @@ Statistics for column %(col)s
*string* or short versions: *i*, *f*, *b*, *s*)
:type col_type: :class:`str`
- :param data: data to add to new column.
+ :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 = Table(['x'], 'f', x=range(5))
tab.AddCol('even', 'bool', itertools.cycle([True, False]))
print tab
@@ -736,7 +737,7 @@ Statistics for column %(col)s
.. code-block:: python
- tab=Table(['x'], 'f', x=range(5))
+ tab = Table(['x'], 'f', x=range(5))
tab.AddCol('num', 'i', 1)
print tab
@@ -835,7 +836,7 @@ Statistics for column %(col)s
.. code-block:: python
- subtab=tab.Select('col_a>0.5 and (col_b=5 or col_c=5)')
+ 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'
@@ -846,10 +847,10 @@ Statistics for column %(col)s
.. code-block:: python
#selects rows, where 1.0<=col_a<=1.5
- subtab=tab.Select('col_a=1.0: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')
+ 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'
@@ -996,7 +997,7 @@ Statistics for column %(col)s
- pickle
- Deserializes the table from a pickled byte stream
+ Deserializes the table from a pickled byte stream.
- csv
@@ -1004,11 +1005,11 @@ Statistics for column %(col)s
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 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
+ 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
"""
@@ -1044,7 +1045,7 @@ Statistics for column %(col)s
def GetUnique(self, col, ignore_nan=True):
"""
- Extract a list of all unique values from one column
+ Extract a list of all unique values from one column.
:param col: column name
:type col: :class:`str`
@@ -1069,7 +1070,7 @@ Statistics for column %(col)s
.. code-block:: python
- tab=Table.Load('...')
+ tab = Table.Load('...')
for col1, col2 in tab.Zip('col1', 'col2'):
print col1, col2
@@ -1077,7 +1078,7 @@ Statistics for column %(col)s
.. code-block:: python
- tab=Table.Load('...')
+ tab = Table.Load('...')
for col1, col2 in zip(tab['col1'], tab['col2']):
print col1, col2
"""
@@ -1176,21 +1177,21 @@ Statistics for column %(col)s
.. 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))
+ 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 = tab.Plot('d')
plt.show()
# two dimensional plot of 'a' vs. 'c'
- plt=tab.Plot('a', y='c', style='o-')
+ 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')
+ plt = tab.Plot('a', y='c', z='b')
# manually save plot to file
plt.savefig("plot.png")
"""
@@ -1396,10 +1397,10 @@ Statistics for column %(col)s
.. code-block:: python
- tab=Table(['a'],'f', a=[math.cos(x*0.01) for x in range(100)])
+ 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 = tab.PlotHistogram('a')
plt.show()
"""
@@ -1514,7 +1515,7 @@ Statistics for column %(col)s
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 in [0;1]
+ Value must be between [0;1]
:type width: :class:`float`
:param bottom: Bottom
@@ -1765,7 +1766,7 @@ Statistics for column %(col)s
"""
Returns the row containing the cell with the maximal value in col. If
several rows have the highest value, only the first one is returned.
- None values are ignored.
+ ''None'' values are ignored.
:param col: column name
:type col: :class:`str`
@@ -1779,7 +1780,7 @@ Statistics for column %(col)s
def Max(self, col):
"""
Returns the maximum value in col. If several rows have the highest value,
- only the first one is returned. None values are ignored.
+ only the first one is returned. ''None'' values are ignored.
:param col: column name
:type col: :class:`str`
@@ -1791,7 +1792,7 @@ Statistics for column %(col)s
"""
Returns the row index of the cell with the maximal value in col. If
several rows have the highest value, only the first one is returned.
- None values are ignored.
+ ''None'' values are ignored.
:param col: column name
:type col: :class:`str`
@@ -1820,7 +1821,7 @@ Statistics for column %(col)s
def Min(self, col):
"""
Returns the minimal value in col. If several rows have the lowest value,
- only the first one is returned. None values are ignored.
+ only the first one is returned. ''None'' values are ignored.
:param col: column name
:type col: :class:`str`
@@ -1832,7 +1833,7 @@ Statistics for column %(col)s
"""
Returns the row containing the cell with the minimal value in col. If
several rows have the lowest value, only the first one is returned.
- None values are ignored.
+ ''None'' values are ignored.
:param col: column name
:type col: :class:`str`
@@ -1847,7 +1848,7 @@ Statistics for column %(col)s
"""
Returns the row index of the cell with the minimal value in col. If
several rows have the lowest value, only the first one is returned.
- None values are ignored.
+ ''None'' values are ignored.
:param col: column name
:type col: :class:`str`
@@ -1857,7 +1858,7 @@ Statistics for column %(col)s
def Sum(self, col):
"""
- Returns the sum of the given column. Cells with None are ignored. Returns
+ Returns the sum of the given column. Cells with ''None'' are ignored. Returns
0.0, if the column doesn't contain any elements. Col must be of numeric
column type ('float', 'int') or boolean column type.
@@ -1878,7 +1879,7 @@ Statistics for column %(col)s
def Mean(self, col):
"""
- Returns the mean of the given column. Cells with None are ignored. Returns
+ Returns the mean of the given column. Cells with ''None'' are ignored. Returns
None, if the column doesn't contain any elements. Col must be of numeric
('float', 'int') or boolean column type.
@@ -1911,7 +1912,7 @@ Statistics for column %(col)s
Cols are specified by their names and must be of numeric column
type ('float', 'int') or boolean column type. Cells with None are ignored.
- Adds None if the row doesn't contain any values.
+ Adds ''None'' if the row doesn't contain any values.
:param mean_col_name: name of new column containing mean values
:type mean_col_name: :class:`str`
@@ -1979,20 +1980,20 @@ Statistics for column %(col)s
def Percentiles(self, col, nths):
"""
- returns the percentiles of column *col* given in *nths*.
+ Returns the percentiles of column *col* given in *nths*.
- The percentils are calculated as
+ The percentiles are calculated as
.. code-block:: python
values[min(len(values), int(round(len(values)*p/100+0.5)-1))]
- where values are the sorted values of *col* not equal to none
- :param: nths: list of percentiles to be calculated. Each percentil is a number
+ where values are the sorted values of *col* not equal to ''None''
+ :param: nths: list of percentiles to be calculated. Each percentile is a number
between 0 and 100.
:raises: :class:`TypeError` if column type is ``string``
- :returns: List of percentils in the same order as given in *nths*
+ :returns: List of percentiles in the same order as given in *nths*
"""
idx = self.GetColIndex(col)
col_type = self.col_types[idx]
@@ -2018,8 +2019,8 @@ Statistics for column %(col)s
def Median(self, col):
"""
- Returns the median of the given column. Cells with None are ignored. Returns
- None, if the column doesn't contain any elements. Col must be of numeric
+ Returns the median of the given column. Cells with ''None'' are ignored. Returns
+ ''None'', if the column doesn't contain any elements. Col must be of numeric
column type ('float', 'int') or boolean column type.
:param col: column name
@@ -2044,8 +2045,8 @@ Statistics for column %(col)s
def StdDev(self, col):
"""
- Returns the standard deviation of the given column. Cells with None are
- ignored. Returns None, if the column doesn't contain any elements. Col must
+ Returns the standard deviation of the given column. Cells with ''None'' are
+ ignored. Returns ''None'', if the column doesn't contain any elements. Col must
be of numeric column type ('float', 'int') or boolean column type.
:param col: column name
@@ -2069,7 +2070,7 @@ Statistics for column %(col)s
def Count(self, col, ignore_nan=True):
"""
- Count the number of cells in column that are not equal to None.
+ Count the number of cells in column that are not equal to ''None''.
:param col: column name
:type col: :class:`str`
@@ -2298,6 +2299,7 @@ Statistics for column %(col)s
'''
Returns a numpy matrix containing the selected columns from the table as
columns in the matrix.
+
Only columns of type *int* or *float* are supported. *NA* values in the
table will be converted to *None* values.
@@ -2330,7 +2332,7 @@ Statistics for column %(col)s
def GaussianSmooth(self, col, std=1.0, na_value=0.0, padding='reflect', c=0.0):
'''
- In place gaussian smooth of a column in the table with a given standard deviation.
+ In place Gaussian smooth of a column in the table with a given standard deviation.
All nan are set to nan_value before smoothing.
:param col: column name
@@ -3064,6 +3066,8 @@ def Merge(table1, table2, by, only_matching=False):
4 400
==== ====
+ when merged by column x, produce the following output:
+
===== ===== =====
x y u
===== ===== =====
@@ -3073,7 +3077,7 @@ def Merge(table1, table2, by, only_matching=False):
4 None 400
===== ===== =====
- when merged by column x, produce the following output:
+
"""
def _key(row, indices):
return tuple([row[i] for i in indices])
diff --git a/modules/doc/contributing.rst b/modules/doc/contributing.rst
index a614f81b9..17c0060ce 100644
--- a/modules/doc/contributing.rst
+++ b/modules/doc/contributing.rst
@@ -3,7 +3,7 @@ Contributing to OpenStructure
.. note::
- This document describes how to develop features to be included in OpenStructure. If you are mainly planning to use the framework, from Python you probably shouldn't read this document and refer to the :doc:`API docs <index>` instead.
+ This document describes how to develop features to be included in OpenStructure. If you are mainly planning to use the framework from Python you probably shouldn't read this document and refer to the :doc:`API docs <index>` instead.
OpenStructure uses `git <http://git-scm.org>`_ as the revision control system. It allows for branch-and-merge driven workflows ideal for a scientific environment.
@@ -19,7 +19,7 @@ Even though, technically, there is no such a thing as a central repository in gi
For information on how to install OpenStructure from source, refer to :doc:`install`.
-Leaving aside all the short-lived features branches, the OpenStructure repository has two long-lived branches, one called master and one called develop. Master contains the latest stable changes, develop contains features currently under development that are potentially not working. Once stable, the changes in develop will be merged into master and together will form the next release. A very detailed description of the branching model used for OpenStructure is available at `this site <http://nvie.com/posts/a-successful-git-branching-model/>`_.
+Leaving aside all the short-lived features branches, the OpenStructure repository has two long-lived branches, one called *master* and one called *develop*. *Master* contains the latest stable changes, *develop* contains features currently under development that are potentially not working. Once stable, the changes in *develop* will be merged into *master* and together will form the next release. A very detailed description of the branching model used for OpenStructure is available at `this site <http://nvie.com/posts/a-successful-git-branching-model/>`_.
@@ -42,7 +42,7 @@ From now on, all your work will be carried out in my_branch. Make your changes a
Writing Good Commit Messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Your commit message should have a one-line description that summarize the change and optionally a more detailed description of what the changes imply. An example from the commit history.
+Your commit message should have a one-line description that summarizes the change and optionally a more detailed description of what the changes imply. An example from the commit history:
::
@@ -51,7 +51,7 @@ Your commit message should have a one-line description that summarize the change
Fixes BZDNG-204
-The one-liner and the detailed description are separated by an empty line. The reason for this format is that the one-line description will be used as the subject line for the patches generated by format-patch and the ones sent to the commit mailing lists. People can quickly see if the change is of interest to that they can savely ignore the e-mail.
+The one-liner and the detailed description are separated by an empty line. The reason for this format is that the one-line description will be used as the subject line for the patches generated by format-patch and the ones sent to the commit mailing lists. People can quickly see if the change is of interest so that they can safely ignore the e-mail.
Additionally, they also come in handy when using the --online option of ``git log``.
@@ -60,7 +60,7 @@ Writing Documentation
OpenStructure uses `sphinx <http://sphinx.pocoo.org>`_ as the documentation generator. The main part of the documentation of each module resides in files with the ``.rst`` extension (a markup language called `reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html#literal-blocks>`_) in a sub-folder called doc.
-From the toplevel directory of the git repository convert the .rst files to html by using the doc/make.py script :
+From the top level directory of the git repository convert the .rst files to html by using the doc/make.py script :
.. code-block:: bash
diff --git a/modules/doc/table.rst b/modules/doc/table.rst
index 7d15d0c16..d0dd45691 100644
--- a/modules/doc/table.rst
+++ b/modules/doc/table.rst
@@ -19,12 +19,12 @@ Populate table with data and plot the data:
from ost.table import *
# create table with two columns, x and y both of float type
- tab=Table(['x', 'y'], 'ff')
+ tab = Table(['x', 'y'], 'ff')
for x in range(1000):
tab.AddRow([x, x**2])
# create a plot
- plt=tab.Plot('x', 'y')
+ plt = tab.Plot('x', 'y')
# save resulting plot to png file
plt.savefig('x-vs-y.png')
@@ -34,10 +34,10 @@ Iterating over table items:
.. code-block:: python
# load table from file
- tab=Table.Load(...)
+ tab = Table.Load(...)
# get column index for col 'foo'
- idx=tab.GetColIndex('foo')
+ idx = tab.GetColIndex('foo')
# iterate over all rows
for row in tab.rows:
@@ -51,13 +51,13 @@ Iterating over table items:
for foo, bar in tab.Zip('foo','bar'):
print foo, bar
-Doing element wise mathematical operations on whole colums:
+Doing element wise mathematical operations on entire colums:
.. code-block:: python
# create table with two columns, foo and bar both of int type
# and fill with values
- tab=Table(['foo', 'bar'], 'ii', foo=[1,2,3,4], bar=[1,4,9,16])
+ tab = Table(['foo', 'bar'], 'ii', foo=[1,2,3,4], bar=[1,4,9,16])
# add new column by doing an element wise
# addition of column foo and column bar
@@ -72,7 +72,7 @@ Select part of the table based on a query:
# create table with two columns, foo and bar both of int type
# and fill with values
- tab=Table(['foo', 'bar'], 'ii', foo=[1,2,3,4], bar=[1,4,9,16])
+ tab = Table(['foo', 'bar'], 'ii', foo=[1,2,3,4], bar=[1,4,9,16])
# select all rows where foo>=2 and bar<10
subtab = tab.Select('foo>=2 and bar<10')
--
GitLab