Complete the user documentation.

documentations/userguide/appendix_graph.rst

@@ -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

documentations/userguide/appendix_virtualfield.rst

@@ -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

documentations/userguide/graph.rst

@@ -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

documentations/userguide/hyperlinks.txt

@@ -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
 

documentations/userguide/list.rst

@@ -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`.

documentations/userguide/metric1d.rst

@@ -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

modules/selector.py

@@ -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):