Commit 15265fe6 authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Fill the metric 1d section of the user guide.

parent e6a169ea
......@@ -13,13 +13,7 @@ sections. Those marked with a (*) are mandatory.
The properties and their values have to follow the JSON_ syntax:
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
.. include:: json.txt
all columns
^^^^^^^^^^^
......
.. _smart_query: http://web2py.com/books/default/chapter/29/06/the-database-
abstraction-layer#smart_query--experimental
.. _Web2py: http://web2py.com/
The fitler conditions is defined in the ``General`` tab.
The ``Conditions`` are used to select a sub-sample of the history records. It
is based on the smart_query_ available in the Web2py_ framework. The query
is written in the natural language, but it is limited to field of the
history table. Fields of the foreign tables, virtual fields or keys of the
``history.data`` dictionary can not be used.
The ``changelog`` event introduced earlier has the ``id`` equal to 7. To
select history related changelog events, enter::
history.id_events = 7
The operator ``contain``, ``greater then``, ... as well as the logical operator
``and``, ``or`` can be used.
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
......@@ -55,7 +55,7 @@ In order to create a ``list``:
Figure 3
the configuration form, shown in :ref:`Fig 3`, contains four tabs:
The configuration form, shown in :ref:`Fig 3`, contains four tabs:
.. list-table::
:widths: 10 70
......@@ -78,28 +78,14 @@ Details are given in the next subsections.
Filter conditions
-----------------
The fitler conditions is defined in the ``General`` tab.
The ``Conditions`` are used to select a sub-sample of the history records. It
is based on the smart_query_ available in the Web2py_ framework. The query
is written in the natural language, but it is limited to field of the
history table. Fields of the foreign tables, virtual fields or keys of the
``history.data`` dictionary can not be used.
The ``changelog`` event introduced earlier has the ``id`` equal to 7. To
select history related changelog events, enter::
history.id_events = 7
The operator ``contain``, ``greater then``, ... as well as the logical operator
``and``, ``or`` can be used.
.. include:: conditions.txt
Group and sorters
-----------------
The group and sorters are defined in the ``Group`` tab through the form entries
``group field`` and ``sorters``. Both contain the address of database field,
virtual field or key of the ``history.data`` dictionary.
virtual field, key of the ``history.data`` dictionary or ``year``.
The row of the grid can be *grouped* according to the value of a given column.
Once defined, the column containing the group values is masked but and
......@@ -117,14 +103,8 @@ The configuration of the grid columns is defined in the
The language used is JSON_ in which:
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
.. include:: json.txt
The configuration of a column requires a minimum of two properties:
.. list-table::
......@@ -163,13 +143,7 @@ The configuration of the summary per columns is defined in the
``Summary`` tab. It has a single entry which has to be filled with an
``array`` of object. The language used is JSON_ in which:
* ``array`` is a collection of value between ``[]``
* ``object`` is a collection of properties between ``{}``
* ``property`` is a ``string: value`` pair
* ``string`` is surrounded by the double quote, *e.g.* ``"foo"``
* ``value`` a string, a number, a boolean, an array or an object
* ``boolean`` values are ``true`` or ``false``
* ...
.. include:: json.txt
For a given column, a summary can be computed over the value of a group and /
or over the values of the whole column.
......
How to configure a 1-dimension metric
=====================================
.. _JSON: http://www.json.org/
.. _Pandas: http://pandas.pydata.org/pandas-docs/stable/
.. _Fig 4:
.. figure:: figures/metric1d-example.png
:align: center
:width: 60%
Figure 4
A ``metric`` is the result of an *aggregation function* applied on the values
of a given database field.
A 1-dimension metric is a table displaying several metrics when records are
aggregated by value for a given database field. This peculiar field is defined
as *group field*.
Each column is associated to a database field. The first one shows the value of
the group field while the others correspond to the database fields on which the
aggregation functions are applied.
In the example shown in the :ref:`Fig 4`, the group field is the people
category. Three metrics are computed for each category: the number of people,
their average age and the standard deviation.
Many aggregation functions are available: ``count``, ``max``,
``mean``, ``median``, ``min``, ``size``, ``std``, ``sum``... In fact, all the
descriptive stats methods of the ``pandas.DataFrame`` class (more in the
Pandas_ documentation).
Several metric can be computed as the same time applying different aggregation
function possibly on different field.
A summary information can also be computed for each column. In the
current implementation only the functions ``count``, ``sum``, ``min``,
``max`` and ``average`` are available.
In order to create a ``metric 1d``:
#. open the leaf ``configure > the metrics 1d`` in the left panel of the
viewport.
#. right click anywhere in the right panel
#. select the menu item ``Add``
.. _Fig 5:
.. figure:: figures/metric1d-form.png
:align: center
:width: 50%
Figure 5
The configuration form, shown in :ref:`Fig 5`, contains tree tabs:
.. list-table::
:widths: 10 70
* - ``General``
- the name of the metric 1d, the title of the report and the conditions
to select the ``history`` records.
* - ``Group``
- the database field to group values.
* - ``Column``
- the mapping between the metric and the column including
how the values are displayed;
Details are given in the next subsections.
Filter conditions
-----------------
.. include:: conditions.txt
Group
-----
The group field is defined in the ``Group`` tab. It is the address of database
field, virtual field, key of the ``history.data`` dictionary or ``year``.
Columns
-------
The configuration of the grid columns is defined in the
``Columns`` tab. It has a single entry which has to be filled with an
``array`` of object. Each object configures a columns and its metric.
The language used is JSON_ in which:
.. include:: json.txt
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
In order to compute a summary for the column, use the ``summaryType`` property.
Possible values are ``count``, ``sum``, ``min``, ``max`` and
``average``.
Many more properties are available. They are detailed in :ref:`Appendix C`.
The following configuration has been used for the metrics of the :ref:`Fig 4`::
[{
"aggregate": "count",
"align": "right",
"dbfield": "people.id",
"format": "0",
"text": "entrées"
}, {
"aggregate": "mean",
"align": "right",
"dbfield": "people.age",
"format": "0.0",
"text": "<age>"
}, {
"aggregate": "std",
"align": "right",
"dbfield": "people.age",
"format": "0.0",
"text": "σ(age)"
}]
\ No newline at end of file
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