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

Review the userguide figures numbering using numfig.

parent aa970e6e
.. include:: hyperlinks.txt
.. _Appendix E:
Appendix E: smart query
=======================
The following operators are understood:
* ``&``, ``and``
* ``|``, ``or``
* ``~``
* ``==``, ``=``, ``equal to``, ``equal``, ``equals``, ``is``
* ``<``, ``less than``
* ``>``, ``greater than``
* ``<=``, ``=<``, ``less or equal than``, ``equal or less than``,
``less or equal``, ``equal or less``
* ``>=``, ``=>``, ``greater or equal than``, ``equal or greater than``,
``greater or equal``, ``equal or greater``
* ``<>``, ``not equal to``, ``not equal``
* ``starts with``
* ``ends with``
* ``contains``
* ``in``
* ``not in``
......@@ -5,30 +5,14 @@ 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 table. Foreign tables fields, 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::
select history related changelog events, enter:
history.id_events = 7
.. code::
The following operators are understood:
* ``&``, ``and``
* ``|``, ``or``
* ``~``
* ``==``, ``=``, ``equal to``, ``equal``, ``equals``, ``is``
* ``<``, ``less than``
* ``>``, ``greater than``
* ``<=``, ``=<``, ``less or equal than``, ``equal or less than``,
``less or equal``, ``equal or less``
* ``>=``, ``=>``, ``greater or equal than``, ``equal or greater than``,
``greater or equal``, ``equal or greater``
* ``<>``, ``not equal to``, ``not equal``
* ``starts with``
* ``ends with``
* ``contains``
* ``in``
* ``not in``
history.id_events = 7
Possible operators are given :ref:`Appendix E`.
......@@ -3,16 +3,17 @@ Addressing database fields
.. include:: hyperlinks.txt
.. _Fig 3:
.. _database-figure:
.. figure:: ../../static/docs/database.png
:align: center
:width: 90%
Figure 3
The database scheme.
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
:num:`Fig. #database-figure` 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`.
......
......@@ -46,13 +46,11 @@ In order to create a new event definition:
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
The form to enter an event definition in the database.
4. Enter the event name in the ``event`` entry.
5. Enter the python dictionary structure in the ``model`` field.
......@@ -78,12 +76,10 @@ In order to create a new one:
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
The form to enter an event in the database.
4. Scan the different tabs and fill the appropriate entries.
......@@ -17,16 +17,17 @@ display the data. In order to create a new one:
#. open contextual menu in the right panel.
#. select the menu item ``Add``
.. _Fig 10:
.. _graph-form-figure:
.. figure:: figures/graph-form.png
:align: center
:width: 50%
Figure 10
The form to configure a graph and to store it in the database.
The configuration form, shown in :ref:`Fig 10`, contains two tabs:
The configuration form, shown in :num:`Fig. #graph-form-figure`, contains
two tabs:
``General``
the name of the graph, the title of the report and the link
......@@ -47,9 +48,7 @@ Configure
---------
The configuration of the graph is defined in the ``Configure`` tab. It has a
single entry which has to be filled with JSON_-type ``object``:
.. include:: json.txt
single entry which has to be filled with JSON_-type ``object``.
The graph can be a displayed as a plot, an histogram, a stacked bar char, ...
It is rendered by the matplotlib_ library through the DataFrame.plot_ method.
......@@ -60,23 +59,26 @@ 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::
The 2-dim metric, shown in the previous chapter, can be displayed as the
stacked bar chart, shown in :num:`Fig. #graph-figure`, through the following
configuration:
.. code:: javascript
{
"kind": "bar",
"stacked": true,
"width": 0.90,
"ylim": [0, 20]
}
{
"kind": "bar",
"stacked": true,
"width": 0.90,
"ylim": [0, 20]
}
.. _Fig 11:
.. _graph-figure:
.. figure:: figures/graph-example.png
:align: center
:width: 50%
Figure 11
An example of graph.
Many more details are given in the :ref:`Appendix D`.
\ No newline at end of file
......@@ -21,6 +21,7 @@ Documentation contents
appendix_virtualfield
appendix_column
appendix_graph
appendix_smartquery
Indices and tables
==================
......
......@@ -3,19 +3,20 @@
How to configure a list
=======================
.. _Fig 4:
.. _list-figure:
.. figure:: figures/list-example.png
:align: center
:width: 60%
Figure 4
An example of list corresponding to a changelog.
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`.
The table is rendered through a grid widget has shown in the
:num:`Fig. #list-figure`.
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.
......@@ -40,15 +41,16 @@ In order to create a ``list``:
#. open contextual menu in the right panel.
#. select the menu item ``Add``
.. _Fig 5:
.. _list-form-figure:
.. figure:: figures/list-form.png
:align: center
:width: 50%
:width: 60%
Figure 5
The form to configure a list and to store it in the database.
The configuration form, shown in :ref:`Fig 5`, contains four tabs:
The configuration form, shown in :num:`Fig. #list-form-figure`,
contains four tabs:
``General``
the name of the list, the title of the report and the conditions
......@@ -91,12 +93,8 @@ 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
``array`` of object. Each object configures a columns.
The language used is JSON_ in which:
.. include:: json.txt
``Columns`` tab. It has a single entry which has to be filled with a
JSON_-type ``array`` of object. Each object configures a columns.
The configuration of a column requires a minimum of two properties:
......@@ -106,24 +104,25 @@ The configuration of a column requires a minimum of two properties:
``text``
the label of the column
This minimal configuration will render the value as a string.
This minimal configuration will render the string value.
Many more properties are available. They are detailed in :ref:`Appendix C`.
The following configuration displays the list of people with their current age::
The following configuration displays the list of people with their current age:
.. code:: python
[{
"xtype": "rownumbered"
}, {
"dbfield": "people.last_name",
"text": "name"
}, {
"align": "right",
"dbfield": "history.age",
"format": "0",
"text": "age",
"xtype": "numbercolumn"
}]
[{
"xtype": "rownumbered"
}, {
"dbfield": "people.last_name",
"text": "name"
}, {
"align": "right",
"dbfield": "history.age",
"format": "0",
"text": "age",
"xtype": "numbercolumn"
}]
The first column is peculiar since it display a row number starting at 1 as for
a spread sheet.
......@@ -132,9 +131,7 @@ 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
``array`` of object. The language used is JSON_ in which:
.. include:: json.txt
JSON_-type``array`` of object.
For a given column, a summary can be computed over the value of a group and /
or over the values of the whole column.
......@@ -143,15 +140,17 @@ 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::
Then, summaries have to be activated:
.. code:: python
[{
"ftype":"groupingsummary",
"groupHeaderTpl": "{name}",
"startCollapsed": false
}, {
"ftype":"summary"
}]
[{
"ftype":"groupingsummary",
"groupHeaderTpl": "{name}",
"startCollapsed": false
}, {
"ftype":"summary"
}]
The first object activated the summary for each group and the second one for
the whole column.
......
.. include:: hyperlinks.txt
How to configure a 1-dimension metric
=====================================
How to configure a 1-dim metric
===============================
.. _Fig 6:
.. _metric1d-figure:
.. figure:: figures/metric1d-example.png
:align: center
:width: 60%
Figure 6
An example of 1-dim metric.
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
A 1-dim 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*.
......@@ -22,9 +22,9 @@ 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.
In the :num:`Fig. #metric1d-figure`, 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
......@@ -34,17 +34,17 @@ Several metric can be computed as the same time applying different aggregation
function possibly on different fields.
Mathematical operation can be applied on the content of the different columns
and stored in the new one. For example, in :ref:`Fig 6`, the last column
contain the ratio between the *standard deviation* and the *average*, computed
for each row.
and stored in the new one. For example, in :num:`Fig. #metric1d-figure`, the
last column contain the ratio between the *standard deviation* and the
*average*, computed for each row.
A summary row 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-dim 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
viewport.
......@@ -52,15 +52,16 @@ order to create a new one:
#. select the menu item ``Add``
.. _Fig 7:
.. _metric1d-form-figure:
.. figure:: figures/metric1d-form.png
:align: center
:width: 50%
Figure 7
The form to configure a 1-dim metric and to store it in the database.
The configuration form, shown in :ref:`Fig 7`, contains tree tabs:
The configuration form, shown in :num:`Fig. #metric1d-form-figure`,
contains tree tabs:
``General``
the name of the metric 1d, the title of the report and the
......@@ -91,11 +92,7 @@ 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
JSON_-type ``array`` of object. Each object configures a columns and its metric.
The configuration of a column requires a minimum of three properties:
......@@ -122,30 +119,33 @@ column cells, use the properties ``eval`` instead of ``dbfield`` and
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 6`::
[{
"aggregate": "count",
"align": "right",
"dbfield": "people.id",
"format": "0",
"text": "entrées"
}, {
"aggregate": "mean",
"align": "right",
"dataIndex": "a",
"dbfield": "people.age",
"format": "0.0",
"text": "&lt;age&gt;"
}, {
"aggregate": "std",
"align": "right",
"dataIndex": "b",
"dbfield": "people.age",
"format": "0.0",
"text": "&sigma;(age)"
},{
"align": "right",
"eval": "b/a",
"text": "sigma/mean"
}]
The following configuration has been used for the metrics of the
:num:`Fig. #metric1d-figure`:
.. code:: javascript
[{
"aggregate": "count",
"align": "right",
"dbfield": "people.id",
"format": "0",
"text": "entrées"
}, {
"aggregate": "mean",
"align": "right",
"dataIndex": "a",
"dbfield": "people.age",
"format": "0.0",
"text": "&lt;age&gt;"
}, {
"aggregate": "std",
"align": "right",
"dataIndex": "b",
"dbfield": "people.age",
"format": "0.0",
"text": "&sigma;(age)"
},{
"align": "right",
"eval": "b/a",
"text": "sigma/mean"
}]
.. include:: hyperlinks.txt
How to configure a 2-dimension metric
======================================
How to configure a 2-dim metric
===============================
.. _Fig 8:
.. _metric2d-figure:
.. figure:: figures/metric2d-example.png
:align: center
:width: 60%
Figure 8
An example of 2-dim metrics.
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
A 2-dim 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*.
......@@ -22,16 +22,16 @@ 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``.
In the :num:`Fig. #metric2d-figure`, 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.
The configuration of the 2-dimension metric is stored in the database. It
The configuration of the 2-dim 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
......@@ -40,15 +40,16 @@ defines the group fields, and the metric. In order to create a new one:
#. select the menu item ``Add``
.. _Fig 9:
.. _metric2d-form-figure:
.. figure:: figures/metric2d-form.png
:align: center
:width: 50%
Figure 9
The form to configure a 2-dim metric and to store it in the database.
The configuration form, shown in :ref:`Fig 9`, contains two tabs:
The configuration form, shown in :num:`Fig #metric2d-form-figure`,
contains two tabs:
``General``
the name of the metric 2d, the title of the report and the
......
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