Commit 7ebe1a1b authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Complete the user documentation.

parent e5ce9cfe
......@@ -5,3 +5,94 @@
Appendix D: Graph configuration
===================================
The graph configuration is a JSON_-type object. Its properties are mainly the
keywords arguments of the DataFrame.plot_ method.
The basic
---------
The selection of the graph type is done via the ``kind`` parameter.
For each graph type, additional parameters are available. They are those of the
underlying matplotlib functions and not detailed here:
.. list-table::
* - ``line``
- line plot
-
* - ``bar``
- vertical bar plot
- `pyplot.bar`_
* - ``barh``
- horizontal bar plot
- `pyplot.barh`_
* - ``hist``
- histogram
- `pyplot.hist`_
* - ``box``
- box plot
- `pyplot.box`_
* - ``kde``
- density estimation plot
-
* - ``area``
- area plot
-
* - ``pie``
- pie plot
- `pyplot.pie`_
* - ``scatter``
- scatter plot
- `pyplot.scatter`_
* - ``hexbin``
- hexbin plot
- `pyplot.hexbin`_
* ``hist`` or ``bar(h)`` can be stacked when ``stacked`` is ``true``.
* The scale and limit can be tuned via the parameters ``logx``, ``logy``,
``loglog``, ``xlim`` and ``ylim``.
* Grid (legend) can be deactivated when the parameters ``grid``
(``legend``) is ``false``.
* Errors bar can be set via the parameter ``xerr`` and ``yerr``.
* ...
The mapping between the columns of the report and the graph is implicit when
all columns of the DataFrame are used. It can be performed via the
parameters ``index``, ``x`` and ``y`` but depends on the graph type:
.. list-table::
:widths: 20 30
* - ``index``
- ``bar``, ``barh``, ``hist``
* - ``x`` and ``y``
- ``line plot``, ``scatter plot``, ``hexbin``
Column addressing
-----------------
The report is a series of values organized
in columns. In order to:
* histogram the value of one column, use::
index = column label or position
* plot the values of one column against the values of the other one
(line plot, scatter plot, hexbin plot), use::
x = column label or position
y = column label or position
* a stacked histogram/bar with the reduced set of columns, use the list::
index = [column labels, or positions]
.. note::
The column label is derived from the database field address by removing
the dot, *e.g* ``tablenamefieldname``.
\ No newline at end of file
......@@ -9,39 +9,60 @@ History
-------
.. list-table::
* -
-
:widths: 20 10 50
* -
-
-
* - ``history.coverage``
- float
- the time coverage of the history record with respect
to the period range selected by the user. It is a value between 0 and 1.
* - ``history.duration``
- float
- the duration of the history record. The end date is ``now`` when
the history record is not yet terminated.
* - ``history.fte``
- float
- the full time equivalent of the person associated to the history
record. It is the product of the time coverage and the percentage of the
person assigned to the record. It is a value between 0 and 1.
* - ``history.is_end``
- boolean
- Return true is the history record ends during the period range selected
by the user.
* - ``history.is_over``
- boolean
- Return true is the history record is over ``now``.
* - ``history.is_start``
- boolean
- Return true is the history record starts during the period range
selected by the user.
People
------
.. list-table::
* -
-
:widths: 20 10 50
* -
-
-
* - ``people.age``
- float
- the age of the person ``now``.
Time axis
---------
The ``time`` is not as is in the database table since at each event is
associated a time span. However, mechanism has been introduce to extact
the information on a year basis. Therefor the virtual field ``year`` can be
used in the reporting.
The ``time`` is not a field of the ``history`` table since a time period is
associated to each event. However, mechanism has been introduce to extract the
database information on a year basis. Therefore the pseudo field ``year`` can
be used in the reporting.
.. list-table::
* -
-
* -
-
* - ``year``
- integer
......@@ -17,7 +17,7 @@ display the data. In order to create a new one:
#. open contextual menu in the right panel.
#. select the menu item ``Add``
.. _Fig 10:
.. _Fig 10:
.. figure:: figures/graph-form.png
:align: center
......@@ -41,23 +41,44 @@ Details are given in the next subsections.
General
-------
The link to the ``list`` or ``metrics`` is defined by the two entries
``Report type`` and ``Report name``. The latter has to be equal to a list or
metric name.
The link between the ``lists`` or ``metrics`` and the graph is defined in the
``General`` tab through the two ComboBox ``Report`` and ``Report name``.
Configure
---------
The configuration of the graph is defined in the ``Configure`` tab. It has a
single entry which has to be filled with an ``object``. The language used is
JSON_ in which:
single entry which has to be filled with JSON_-type ``object``:
.. include:: json.txt
The graph can be a displayed as a plot, an histogram, a stacked bar char, ...
It is rendered by the matplotlib_ library through the ``plot`` method of the
DataFrame_ class. The method has many keywords allowing to select the
graph type and to tune its rendering. The properties of the object correspond
to the keyword, value pairs of the plot method. Detailed description can be
found in `DataFrame.plot`_ documentation or in :ref:`Appendix D`.
It is rendered by the matplotlib_ library through the DataFrame.plot_ method.
The method has many keywords allowing to select the graph type and to tune its
rendering.
The graph configuration corresponds to the keyword, value pairs of the plot
method. The most important one is ``kind`` allowing to select the graph
type.
The 2-dimension metric of the :ref:`Fig 8` can be displayed as the stacked bar
chart, shown in :ref:`Fig 11`, through the following configuration::
{
"kind": "bar",
"stacked": true,
"width": 0.90,
"ylim": [0, 20]
}
.. _Fig 11:
.. figure:: figures/graph-example.png
:align: center
:width: 50%
Figure 11
Many more details are given in the :ref:`Appendix D`.
\ No newline at end of file
......@@ -13,8 +13,33 @@
.. _matplotlib: http://matplotlib.org/
.. _matplotlib.pyplot: http://matplotlib.org/api/pyplot_summary.html
.. _pandas: http://pandas.pydata.org/pandas-docs/stable/
.. _plotting: http://pandas.pydata.org/pandas-docs/stable/visualization.html
.. _pyplot.bar:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.bar
.. _pyplot.barh:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.barh
.. _pyplot.box:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.box
.. _pyplot.hexbin:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.hexbin
.. _pyplot.hist:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.hist
.. _pyplot.pie:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.pie
.. _pyplot.scatter:
http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.scatter
.. _smart_query: http://web2py.com/books/default/chapter/29/06/the-database-
abstraction-layer#smart_query--experimental
......
......@@ -100,13 +100,13 @@ The language used is JSON_ in which:
The configuration of a column requires a minimum of two properties:
.. list-table::
:widths: 10 70
.. list-table::
:widths: 10 70
* - ``dbfield``
- the address of the database field
* - ``text``
- the label of the column
* - ``dbfield``
- the address of the database field
* - ``text``
- the label of the column
This minimal configuration will render the value as a string.
Many more properties are available. They are detailed in :ref:`Appendix C`.
......
......@@ -95,19 +95,19 @@ The language used is JSON_ in which:
The configuration of a column requires a minimum of three properties:
.. list-table::
:widths: 10 70
* - ``aggregate``
- the aggregation function applied on the values
of the database field for a fixed value of the group field.
Possible values are ``count``, ``max``, ``mean``, ``median``, ``min``,
``size``, ``std``, ``sum``... In fact, all the descriptive stats methods
of the ``pandas.DataFrame`` class
* - ``dbfield``
- the address of the database field
* - ``text``
- the label of the column
.. list-table::
:widths: 10 70
* - ``aggregate``
- the aggregation function applied on the values
of the database field for a fixed value of the group field.
Possible values are ``count``, ``max``, ``mean``, ``median``,
``min``, ``size``, ``std``, ``sum``... In fact, all the
descriptive stats methods of the ``pandas.DataFrame`` class
* - ``dbfield``
- the address of the database field
* - ``text``
- the label of the column
In order to compute a summary for the column, use the ``summaryType`` property.
Possible values are ``count``, ``sum``, ``min``, ``max`` and
......
......@@ -150,13 +150,12 @@ class MySelector(SelectorActiveItems):
def _age(self, row):
"""Compute the age of a person of the person associated to
the history record.
"""Compute the age of the person associated to the history record, now.
@type row: gluon.dal.Row
@param row: row of the history table.
@rtype: int
@rtype: int or None
"""
value = None
......@@ -168,27 +167,32 @@ class MySelector(SelectorActiveItems):
def _coverage(self, row):
"""Compute the fraction of time spend per a person on the
history record.
"""Compute the time coverage of the history record with respect
to the period range.
@type row: gluon.dal.Row
@param row: row of the history table.
@rtype: float
@return: a value between C{0} and C{1}.
"""
value = 0.
period_end = self._period_end
period_start = self._period_start
if self._period_start and self._period_end:
if period_start and period_end:
start = max(self._period_start, row.history.start_date)
start = max(period_start, row.history.start_date)
end = self._period_end
end = period_end
if row.history.end_date:
end = min(self._period_end, row.history.end_date)
end = min(period_end, row.history.end_date)
x = (end - start).days
y = (self._period_end - self._period_start).days
y = (period_end - period_start).days
value = float(x) / float(y)
return value
......@@ -196,6 +200,7 @@ class MySelector(SelectorActiveItems):
def _duration(self, row):
"""Compute the duration of the history record.
The end date is C{now} when the history record is not finished.
@type row: gluon.dal.Row
@param row: row of the history table.
......@@ -222,15 +227,15 @@ class MySelector(SelectorActiveItems):
def _fte(self, row):
"""Compute the full time equivalent that the person associated
to the history record spend on the record. It is a product of
the time coverage and the percentage of the person assigned to
the record.
"""Compute the full time equivalent of the person associated
to the history record. It is the product of the time coverage
and the percentage of the person assigned to the record.
@type row: gluon.dal.Row
@param row: row of the history table.
@rtype: float
@return: a value between 0 and 1.
"""
value = 0.
......@@ -240,6 +245,27 @@ class MySelector(SelectorActiveItems):
return value
def _is_end(self, row):
"""Return true is the history record ends during the period range.
@type row: gluon.dal.Row
@param row: row of the history table.
@rtype: bool
"""
end = row.history.end_date
start = row.history.start_date
period_end = self._period_end
period_start = self._period_start
if end and start != end:
return period_start <= end <= period_end
return False
def _is_over(self, row):
"""Return true is the history record is over now.
......@@ -257,6 +283,27 @@ class MySelector(SelectorActiveItems):
return end < now
return False
def _is_start(self, row):
"""Return true is the history record starts during the period range.
@type row: gluon.dal.Row
@param row: row of the history table.
@rtype: bool
"""
end = row.history.end_date
start = row.history.start_date
period_end = self._period_end
period_start = self._period_start
if start and start != end:
return period_start <= start <= period_end
return False
def query(self, table):
......
This diff is collapsed.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment