Commit b58a7cdc authored by LE GAC Renaud's avatar LE GAC Renaud
Browse files

Fill the events and metric 2d sections of the user guide.

parent eef4e0f6
......@@ -3,24 +3,24 @@ Addressing database fields
.. include:: hyperlinks.txt
.. _Fig 1:
.. _Fig 3:
.. figure:: ../../database.png
:align: center
:width: 90%
Figure 1
The fields of the database and their relations are shown in the
:ref:`Fig 1` and summarized in the :ref:`Appendix A`. The ``history`` and
``people`` table contains also virtual fields. Their values are not stored in
the database but computed, on-demand, for each request. Their definitions are
Figure 3
The fields of the database and their relations are shown in the
:ref:`Fig 3` and summarized in the :ref:`Appendix A`. The ``history`` and
``people`` table contains also virtual fields. Their values are not stored in
the database but computed, on-demand, for each request. Their definitions are
given in the :ref:`Appendix B`.
Basic field type
----------------
The basic field contains ``blob``, ``boolean``, ``date``, ``datetime``,
The basic field contains ``blob``, ``boolean``, ``date``, ``datetime``,
``double``, ``float``, ``integer``, ``string``, ``text`` and ``time`` values.
The addressing of these field follows the usual rules::
......@@ -29,11 +29,11 @@ The addressing of these field follows the usual rules::
JSON field type
----------------
The Web2py_ framework introduces the additional type ``json`` which can store
JSON_ serializable object. It is used, in this application, to store python
The Web2py_ framework introduces the additional type ``json`` which can store
JSON_ serializable object. It is used, in this application, to store python
dictionary. This is the case of ``events.data`` and ``history.data`` fields.
Reports have to access to any dictionary key. In that case, the address is
Reports have to access to any dictionary key. In that case, the address is
given by::
tablename.fieldname.keyname
.. include:: hyperlinks.txt
Events
=======
This applications record events. It can happen at a date or span during a
period of time. An event is the relation between a person and a team /
project. When he/she arrive, left. How many time does he/she spent. It can also
be an entry in a changelog. Why and when the content of the database has been
modified. In fact, there are no limitation on the events which can be tracked.
An event is defined by a *starting date*, by an *ending date* and by a *name*.
An event contains *meta-data* linking the event to:
* a person
* a teams
* a project
* a category (the category of people in this application)
* a funding agency
The event are stored in the ``history`` table and the meta-data in the foreign
tables ``fundings``, ``people``, ``people_categories``, ``projects`` and
``teams``. The organization of the table can not be changed. All the fields of
these tables are standard database field. They can be used in standard SQL
request or in reports.
An event contains also a *user data block*. It is stored in one database field.
The user data block is a python dictionary serialized as a JSON_ string.
The structure of the dictionary, *the keys*, are defined by the user, once, for
each event type. The structure of the dictionary can be modified at any
time by the user. Mechanisms are in placed to guaranty the consistency across
the database. The SQL Request are limited to string operations.
Individual key of the dictionary can not be used. But, any key can be used in
reports.
How to define an event
----------------------
The event definitions are stored in the ``events`` table.
In order to create a new event definition:
1. open the leaf ``events > definition`` in the left panel of the
viewport.
2. right click anywhere in the right panel
3. select the menu item ``Add``
.. _Fig 1:
.. figure:: figures/event-form.png
:align: center
:width: 50%
Figure 1
4. Enter the event name in the first field.
5. Enter the python dictionary structure in the last field.
Key, value pair can be ``Add``, ``Modify`` or ``Delete`` using the
contextual menu.
.. warning::
the data user block of all the existing events are modified when the
python dictionary structure is modified.
A good practice is to enter the type of key (``boolean``,
``date``, ``string``, ``number``) or a default value.
How to enter an event
----------------------
The events of any kind are stored in the ``history`` table.
In order to create a new one:
1. open the leaf ``events > history`` in the left panel of the
viewport.
2. right click anywhere in the right panel
3. select the menu item ``Add``
.. _Fig 2:
.. figure:: figures/history-form.png
:align: center
:width: 50%
Figure 2
4. Scan the different tabs and fill the appropriate entries.
......@@ -11,6 +11,7 @@ Documentation contents
.. toctree::
:maxdepth: 2
event
dbfields
list
metric1d
......
.. include:: hyperlinks.txt
How to configure a list
=======================
.. include:: hyperlinks.txt
.. _Fig 2:
.. _Fig 4:
.. figure:: figures/list-example.png
:align: center
:width: 60%
Figure 2
A list is a table in which each column shows the values of one database
field. The table contains heterogeneous values since it merges different types
of database field.
Figure 4
The table is rendered through a grid widget has shown in the :ref:`Fig 2`.
In that figure, the list shows a *changelog* in which the rows are grouped per
year and sorted per date. The first group is collapsed while the second one is
A list is a table in which each column shows the values of one database
field. The table contains heterogeneous values since it merges different types
of database field.
The table is rendered through a grid widget has shown in the :ref:`Fig 4`.
In that figure, the list shows a *changelog* in which the rows are grouped per
year and sorted per date. The first group is collapsed while the second one is
expanded.
The grid provides a lot of flexibility to manipulate interactively the data.
The rows can be grouped per value of a given column. A group can be
expanded or masked. The column can be masked or moved around. Summary
information can be computed for each group as well as
for the whole table. Finally, the data of the table can be extracted in
different formats ``CSV``, ``LaTeX`` or ``PDF``. More information can be found
in the ExtJS_ documentation of the ``Ext.grid.Panel``.
The configuration of the list is stored in the database. It defines the mapping
between the database field and the column, the group as well as the summary
information. Any database field can be displayed in the column including the
The grid provides a lot of flexibility to manipulate interactively the data.
The rows can be grouped per value of a given column. A group can be
expanded or masked. The column can be masked or moved around. Summary
information can be computed for each group as well as
for the whole table. Finally, the data of the table can be extracted in
different formats ``CSV``, ``LaTeX`` or ``PDF``. More information can be found
in the ExtJS_ documentation of the ``Ext.grid.Panel``.
The configuration of the list is stored in the database. It defines the mapping
between the database field and the column, the group as well as the summary
information. Any database field can be displayed in the column including the
virtual fields, one key of the history.data dictionary or the ``year``.
In order to create a ``list``:
#. open the leaf ``configure > the lists`` in the left panel of the
#. open the leaf ``configure > the lists`` in the left panel of the
viewport.
#. right click anywhere in the right panel
#. open contextual menu in the right panel.
#. select the menu item ``Add``
.. _Fig 3:
.. _Fig 5:
.. figure:: figures/list-form.png
:align: center
:width: 50%
Figure 3
The configuration form, shown in :ref:`Fig 3`, contains four tabs:
.. figure:: figures/list-form.png
:align: center
:width: 50%
.. list-table::
:widths: 10 70
Figure 5
The configuration form, shown in :ref:`Fig 5`, contains four tabs:
.. list-table::
:widths: 10 70
* - ``General``
- the name of the list, the title of the report and the conditions
to select ``history`` records.
* - ``Group``
- the database field to group rows as well as the list of
database field to sort the row of the table.
* - ``Column``
- the mapping between database field and column
as well as how the values are displayed;
* - ``Summary``
- the summary information compute for each group
and for the whole column.
* - ``General``
- the name of the list, the title of the report and the conditions
to select ``history`` records.
* - ``Group``
- the database field to group rows as well as the list of
database field to sort the row of the table.
* - ``Column``
- the mapping between database field and column
as well as how the values are displayed;
* - ``Summary``
- the summary information compute for each group
and for the whole column.
Details are given in the next subsections.
Details are given in the next subsections.
Filter conditions
-----------------
......@@ -76,22 +76,22 @@ Filter conditions
Group and sorters
-----------------
The group and sorters are defined in the ``Group`` tab through the form entries
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, key of the ``history.data`` dictionary or ``year``.
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
additional row is created with the group value, followed by all the rows with
the same group value. An example is shown in :ref:`Fig 2`.
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
additional row is created with the group value, followed by all the rows with
the same group value.
In addition, rows of a group can be sorted according to the value of the others
In addition, rows of a group can be sorted according to the value of the others
columns.
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
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.
The language used is JSON_ in which:
......@@ -107,7 +107,7 @@ The configuration of a column requires a minimum of two properties:
- 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`.
......@@ -127,36 +127,36 @@ The following configuration displays the list of people with their current age::
"xtype": "numbercolumn"
}]
The first column is peculiar since it display a row number starting at 1 as for
The first column is peculiar since it display a row number starting at 1 as for
a spread sheet.
Summary
-------
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
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:
.. include:: json.txt
For a given column, a summary can be computed over the value of a group and /
For a given column, a summary can be computed over the value of a group and /
or over the values of the whole column.
A summary function has to be defined for the column, in the *column
configuration*, using the property ``summaryType``. Possible values are
A summary function has to be defined for the column, in the *column
configuration*, using the property ``summaryType``. Possible values are
``"count"``, ``"sum"``, ``"min"``, ``"max"`` and ``"average"``.
Then, summaries have to be activated::
[{
"ftype":"groupingsummary",
"groupHeaderTpl": "{name}",
"groupHeaderTpl": "{name}",
"startCollapsed": false
}, {
"ftype":"summary"
}]
The first object activated the summary for each group and the second one for
The first object activated the summary for each group and the second one for
the whole column.
More information on the grouping features can be found in the
More information on the grouping features can be found in the
``Ext.grid.features`` section of the ExtJS_ documentation.
.. include:: hyperlinks.txt
How to configure a 1-dimension metric
=====================================
.. include:: hyperlinks.txt
.. _Fig 4:
.. _Fig 6:
.. figure:: figures/metric1d-example.png
:align: center
:width: 60%
Figure 4
A ``metric`` is the result of an *aggregation function* applied on the values
Figure 6
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 latter field is defined
A 1-dimension metric is a table displaying several metrics when records are
aggregated by value for a given database field. This latter 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
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 :ref:`Fig 6`, 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``,
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.
The configuration of the 1-dimension metric is stored in the database. It
defines the group field, the metrics as well as the summary information.
In order to create a new one:
The configuration of the 1-dimension metric is stored in the database. It
defines the group field, the metrics as well as the summary information. In
order to create a new one:
#. open the leaf ``configure > the metrics 1d`` in the left panel of the
#. open the leaf ``configure > the metrics 1d`` in the left panel of the
viewport.
#. right click anywhere in the right panel
#. open contextual menu in the right panel.
#. select the menu item ``Add``
.. _Fig 5:
.. figure:: figures/metric1d-form.png
:align: center
:width: 50%
Figure 5
.. _Fig 7:
The configuration form, shown in :ref:`Fig 5`, contains tree tabs:
.. figure:: figures/metric1d-form.png
:align: center
:width: 50%
.. list-table::
:widths: 10 70
Figure 7
The configuration form, shown in :ref:`Fig 7`, 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;
* - ``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.
Details are given in the next subsections.
Filter conditions
-----------------
......@@ -80,14 +80,14 @@ Filter conditions
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``.
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
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:
......@@ -100,10 +100,10 @@ The configuration of a column requires a minimum of three properties:
:widths: 10 70
* - ``aggregate``
- the aggregation function applied on the values
- 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
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
......@@ -111,12 +111,12 @@ The configuration of a column requires a minimum of three properties:
- 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
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`::
The following configuration has been used for the metrics of the :ref:`Fig 6`::
[{
"aggregate": "count",
......@@ -137,4 +137,3 @@ The following configuration has been used for the metrics of the :ref:`Fig 4`::
"format": "0.0",
"text": "σ(age)"
}]
\ No newline at end of file
......@@ -3,6 +3,65 @@
How to configure a 2-dimension metric
======================================
.. _Fig 8:
.. figure:: figures/metric2d-example.png
:align: center
:width: 60%
Figure 8
A ``metric`` is the result of an *aggregation function* applied on the values
of a given database field.
A 2-dimension metric is a table displaying one metric when records are
aggregated by values for a given database fields along the *x* and *y* axis.
These latter fields are defined as *group field x* and *group field y*.
The first column shows the value of the group field y while the first row
displays the value of the group field x. Each cell contains the results of the
metric
In the :ref:`Fig 8`, the table shows the number of people per category and per
year. In other words, the group field y is the people category while the group
field x is the year. The aggregation function is a ``count`` applied on the
database field ``people.id``.
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).
The configuration of the 2-dimension metric is stored in the database. It
defines the group fields, and the metric. In order to create a new one:
#. open the leaf ``configure > the metrics 2d`` in the left panel of the
viewport.
#. open contextual menu in the right panel.
#. select the menu item ``Add``
.. _Fig 9:
.. figure:: figures/metric2d-form.png
:align: center
:width: 50%
Figure 9
The configuration form, shown in :ref:`Fig 9`, contains two tabs:
.. list-table::
:widths: 10 70
* - ``General``
- the name of the metric 2d, the title of the report and the
conditions to select the ``history`` records.
* - ``Aggregate``
- the group field along the x and y-axis and the metric.
Details are given in the next subsections.
Filter conditions
-----------------
......@@ -10,3 +69,13 @@ Filter conditions
Aggregate
---------
The group fields and the metric are defined in the ``Aggregate`` tab. The
entries ``Group (x)``, ``Group(y)`` and ``Aggregate (z)`` are equal to the
address of database field, virtual field, key of the ``history.data``
dictionary or ``year``.
The entry ``metric (z)`` is the name of the aggregation function. Possible
values are: ``count``, ``max``, ``mean``, ``median``, ``min``, ``size``,
``std``, ``sum``... In fact, all the descriptive stats methods of the
``pandas.DataFrame`` class.
\ 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