Merge pull request #25 from sdevenes/feature/documentation

Feature/documentation

README.rst

@@ -0,0 +1,19 @@
+.. image:: https://travis-ci.org/sdevenes/M05_MiniProject.svg?branch=master
+   :target: https://travis-ci.org/github/sdevenes/M05_MiniProject
+.. image:: https://img.shields.io/badge/docs-latest-orange.svg
+   :target: https://sdevenes.github.io/M05_MiniProject/index.html
+.. image:: https://img.shields.io/badge/github-project-0000c0.svg
+   :target: https://github.com/sdevenes/M05_MiniProject
+
+===============================================================
+ Human Activity Recognition from Continuous Ambient Sensor Data
+===============================================================
+
+This mini project was developed during the M05 course "reproducibility and open science"
+taught by Idiap as part of the AI master 2020-2021.
+
+.. topic:: Working hypothesis
+
+    It is possible to perform human activity recognition using data from continuous ambient sensors
+
+

docs/source/guide.rst

@@ -0,0 +1,25 @@
+============
+ User Guide
+============
+
+This guide explains how to use this package and obtain results published in our
+paper.  Results can be re-generated automatically by executing the following
+command:
+
+.. code-block:: sh
+
+   (project) $ python paper.py
+
+
+For your reference, the paper tables are repeated below, so you can check the
+reproducibility of our solution.
+
+
+Results for Protocol `proto1`
+-----------------------------
+
+.. warning::
+   This graph is only a example, we need to update it with final results !
+
+.. raw:: html
+   :file: img/result_exemple.html

docs/source/index.rst

@@ -1,22 +1,16 @@
 Welcome to M05 miniProject's documentation!
 ===========================================
 
+Documentation
+-------------
+
 .. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Contents
-   :glob:
 
+   installation
+   guide
+   troubleshooting
    modules
 
-Getting started
----------------
-
-You can view the content as a:
-
-* `Webpage <https://put/the/correct/link/here/>`_
-* `pdf <https://is/there/a/pdf?.pdf>`_
-
 
 Authors
 -------

docs/source/installation.rst

@@ -0,0 +1,31 @@
+------------
+Installation
+------------
+
+This package depends on the python libraries listed in requirements.txt to run properly. 
+Please install a modern version of these packages before trying to run the code examples.
+Or create directly a conda virtual environment using the conda.yml file as in the following
+exemple.
+
+To download a copy of this package, clone it from its repository in GitHub:
+
+.. code:: sh
+
+   $ git clone https://github.com/sdevenes/M05_MiniProject.git project
+   $ cd project
+   $ conda create -q -n project python=3.8 -c plotly --file requirements.txt
+   $ conda activate project
+
+   (project) $ #you are ready to run baselines!
+
+Building the documentation
+--------------------------
+
+The project documentation is generated with sphinx and can simply be build using the command:
+
+.. code:: sh
+
+   $ make doc
+
+The python API documentation will be automatically generated for all the python modules located
+in `scripts <https://github.com/sdevenes/M05_MiniProject/tree/feature/documentation/scripts>`_, as long as their docstring is completed.

docs/source/troubleshooting.rst

@@ -0,0 +1,13 @@
+Troubleshooting
+---------------
+
+Unit tests are available for the project and can be run simply with the following command:
+
+.. code-block:: shell
+
+   (project) $ make unitTests
+
+.. note::
+   the tests are implemented using `nose <https://pypi.org/project/nose/>`_ python package, it needs to be installed beforhand
+   in the case where the conda environment provided is not activated
+

requirements.txt

@@ -3,4 +3,5 @@ scikit-learn
 plotly_express==0.4.1
 sphinx
 sphinx_rtd_theme
-nose
+nose
+tabulate

scripts/analysis.py

@@ -16,14 +16,15 @@ def get_confusion_matrix(prediction_label, true_label):
     """
     return confusion_matrix(true_label, prediction_label)
 
-def plot_confusion_matrix(cm, classes, normalize=False, title='Confusion matrix'):
+def plot_confusion_matrix(cm, classes, normalize=False, title='Confusion matrix', file_name="graph"):
     """Generate a plot of the given confusion matrix using plotly express
 
     Args:
         cm (numpy.ndarray): A 2D array (with a dtype of int) containing the confusion matrix.
         classes (numpy.ndarray): A 1D array (with a dtype of str) containing the lable name for each class
         normalize (boolean): Flag to normalize the data 
-        title (str): The title of the plot  
+        title (str): The title of the plot
+        file_name (str): File name to export the graph
     Returns:
         None
     Raises:
@@ -41,4 +42,6 @@ def plot_confusion_matrix(cm, classes, normalize=False, title='Confusion matrix'
                     color_continuous_scale='Blues',
                     title=title
                     )
-    fig.show()
+    #fig.show()
+    # Export graph
+    fig.write_html("{}.html".format(file_name))