Merge pull request #86 from signaux-faibles/develop

Last release

Author: vviers

.github/workflows/test.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.8
+      - name: Set up Python 3.6
         uses: actions/setup-python@v2
         with:
           python-version: 3.6

.gitignore

@@ -60,6 +60,9 @@ local_settings.py
 db.sqlite3
 db.sqlite3-journal
 
+# Emacs stuff
+.dir-locals.el
+
 # Flask stuff:
 instance/
 .webassets-cache
@@ -68,7 +71,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 target/

CHANGELOG.md

@@ -27,4 +27,21 @@ and this project is versionned in the `YY.MM` format corresponding to the month
 - Nothing, it's our first release :smile: :tada:
 
 ### Fixed
-- Nothing, it's our first release :smile: :tada:
+- Nothing, it's our first release :smile: :tada:
+
+
+## [21.09] - September 2021
+### Added
+- Created documentation using Sphinx
+- Created synthetic data generation capabilities
+- Created [explainability module](/predictsignauxfaibles/explain.py)
+- Created a [CLI](/predictsignauxfaibles/__main__.py) to easily parameterize model training runs
+- Created [model config files](/models)
+- Created "redressements experts" capacities [starting with a URSSAF-based rule](/predictsignauxfaibles/redressements.py)
+- Created [evaluation module](/predictsignauxfaibles/evaluate.py)
+
+### Fixed
+- fill missing fields after fetching data
+- merging redundant operations on data.columns
+- force siren and sirets to be strings + pad them to 9 characters
+- downgrade jedi version to fix auto-complete bug with ipython.

README.md

@@ -1,58 +1,67 @@
 # predictsignauxfaibles
+
 Dépôt du code python permettant la production de liste de prédiction Signaux Faibles.
+
+⚠️ ce dépôt est aujourd'hui archivé est n'est plus en cours de développement ! En effet, la partie data science du projet Signaux Faibles a migrée sur le lac de données de la DGFiP dans le cadre d'une évolution du partenariat et a donc changé d'environnement technique.
+
 ## Dépendances / pré-requis
+
 - python 3.6.4
-- Docker (:construction_worker:)
 - un accès à la base de données du projet
 
 ## Installation pour un développeur/data scientist :
 
 ### Cloner et naviguer dans le repo
-```
+
+``` sh
 git clone git@github.com:signaux-faibles/predictsignauxfaibles.git
 
 ```
-### Optionnel : Pour les personnes qui travaillent sur le serveur labtenant avec un proxy  
+### Optionnel : Pour les personnes qui travaillent sur le serveur labtenant avec un proxy
 
 Pour pouvoir télécharger les packages, leurs dépendances ainsi que la documentation de données de opensignauxfaibles, il est nécessaire de prendre en compte le proxy pour les personnes qui travaillent sur le serveur. 
 
 Par exemple, pour installer un package : 
 
-```
+``` sh
 pip install --proxy socks5h://localhost:<PORT_INTERNET> <MON_PACKAGE>
 ```
+
 Pour éviter de fournir l'option --proxy à chaque fois, vous pouvez créer un fichier ~/.conf/pip/pip.conf 
 
-```
-mkdir ~/.conf
-mkdir ~/.conf/pip
+``` sh
+mkdir -p ~/.config/pip
 nano pip.conf
 ```
 Et y ajouter la configuration suivante :
 
-```
-[global]
+``` config
+
 proxy = socks5h://localhost:<PORT_INTERNET>
 ```
 Cette configuration est cruciale pour l'installation automatique des packages indiqué dans requirements.  
 
 ### créer un environnement virtuel python (recommandé)
-exemple avec [pyenv](https://github.com/pyenv/pyenv):
-```
+
+Exemple avec [pyenv](https://github.com/pyenv/pyenv) :
+
+``` sh
 pyenv install 3.6.4
 pyenv virtualenv 3.6.4 sf
 pyenv local sf
 ```
 
 ### installer les dépendences du projet
-```
+
+``` sh
 pip install -r requirements.txt
 ```
 
 Note: la procédure sur le serveur est légèrement différente.
 
 ### activer les githooks
-```
+
+``` sh
 python -m python_githooks
 ```
 
@@ -68,37 +77,64 @@ Chaque run de modèle produit 2 fichiers dans `./model_runs/<model_id>` **qui n'
 
 La variable d'environnement `ENV` permet de faire tourner le modèle en mode `develop` (utilisant moins de données, le défaut) ou bien en `prod`:
 
-```sh
+``` sh
 export ENV=prod
 python -m predictsignauxfaibles
 ```
 
 ## Structure du Dépot
-(librement inspiré du [cookiecutter data science](https://drivendata.github.io/cookiecutter-data-science))
-
-- `lib` contient l'essentiel du code nécéssaire à la production de listes signaux faibles
-- `bin` contient des scripts utiles au projet
-- `models` contient les artefacts de modèle (entrainés et serialisés), ses prédictions, et son évaluation
-- `notebooks` contient les notebooks Jupyter (exploration, documentation intéractive, tutoriels, ...)
-- `tests` contient les tests du projet : tests unitaires, d'intégration, et "end-to-end" (e2e). Le module python utilisé pour les tests est `pytest`.
-- `Makefile` contient les commandes make pour l'execution de taches communes (`make train`, `make predict`, etc.)
-- `config.py` est module de gestion de configuration du projet
-- `requirements.txt` liste les dépendences (et leurs versions) nécessaires à la production d'une liste signaux faibles, `requirements-dev.txt` y rajoute les dépendences optionnelles qui ne concernent que les développeurs (pour les tests, le linting, etc.)
-- `.githooks.ini` et `.pylintrc` dont des fichiers de configuration pour les githooks et le linter.
+
+Librement inspiré du [cookiecutter data science](https://drivendata.github.io/cookiecutter-data-science)
+
+- `lib/` contient l'essentiel du code nécéssaire à la production de listes signaux faibles.
+- `bin/` contient des scripts utiles au projet.
+- `models/` contient les artefacts de modèle (entrainés et serialisés), ses prédictions, et son évaluation.
+- `model_run/` contient les prédictions, et les métriques d'évaluation des modèles exécutés.
+- `notebooks/` contient les notebooks Jupyter (exploration, documentation intéractive, tutoriels…)
+- `tests/` contient les tests du projet : tests unitaires, d'intégration, et "end-to-end" (e2e). Le module python utilisé pour les tests est `pytest`.
+- `Makefile` peut être utilisé pour l'execution de taches communes (`make train`, `make predict`, etc.) _Rq_ : Ceci n'est pas implémenté car déjà couvert par l'utilitaire en ligne de commandes.
+- `setup.cfg` est un fichier contenant les métaonnées du projet utilisées par `setuptools` lors de l'installation du projet.
+- `requirements.txt` liste les dépendences (et leurs versions) nécessaires à la production d'une liste signaux faibles.
+- `.githooks.ini` et `.pylintrc` sont les fichiers de configuration pour les githooks et le linter.
 
 ## Documentation
 
+### Démo
+
 Un notebook jupyter interactif de démo est disponible [ici](./notebooks/00-get_started.ipynb).
 
-Il est également possible de télécharger le listing des features disponibles pour le modèle Signaux Faibles, fichier json présent dans le dépôt Github opensignauxfaibles. Ce listing est utilisé dans le notebook de démo. 
+### Générer la documentation
+
+La documentation peut être générée en exécutant la commande (toujours depuis `docs/`)
+
+``` sh
+make html
+```
+
+pour obtenir un dossier formattant la documentation en html (type «readthedocs.io»). Celle-ci est ensuite navigable en ouvrant `docs/build_/html/index.html`
+
+Beaucoup d'autres formats d'export sont disponibles (pdf, man, texinfo); pour plus d'informations, voir
 
+``` sh
+make help
 ```
+
+La documentation est générée grâce aux fichiers `.rst` contenus dans le dossier `docs/source`. Si besoin, ceux-ci peuvent être automatiquement générés à l'aide de `sphinx` : depuis le dossier `docs/`, exécuter
+
+``` sh
+sphinx-apidoc -fP -o source/ ../predictsignauxfaibles
+```
+
+### Variables d'apprentissage
+
+Il est également possible de télécharger la liste des features disponibles pour le modèle Signaux Faibles, fichier `json` présent dans le dépôt Github opensignauxfaibles. Ce listing est utilisé dans le notebook de démo. 
+
+``` sh
 cd notebooks
 curl --proxy socks5h://localhost:<PORT_INTERNET> -OL https://raw.githubusercontent.com/signaux-faibles/opensignauxfaibles/master/js/reduce.algo2/docs/variables.json -o variables.json
 cd ..
 ```
 
-
 ## Gestion des fonctions aléatoires
 
 Les fonctions aléatoires doivent être décorées avec le décorateur `is_random` (dans `lib.decorators`).
@@ -107,12 +143,12 @@ Dès lors, la variable d'environnement `RANDOM_SEED` permet aux fonctions aléat
 
 Au début d'un notebook, vous pouvez créer cette variable d'environnement de la manière suivante :
 
-```python
+``` python
 import os
 os.environ["RANDOM_SEED"]="42"
 ```
 
 Ou depuis le terminal :
-```sh
+``` sh
 export RANDOM_SEED=42
-```
+```

datascience_workflow.md

@@ -124,8 +124,18 @@ Les git hooks permettent de s'assurer que certains scripts tournent automatiquem
   - `pytest`
   - faire tourner et évaluer le modèle (ça peut juste être un rappel si c'est trop lourd)
 
-L'évaluation du modèle peut produire un artefact "model_evaluation.json", 
-versionné dans git avec chaque nouvelle version du modèle.
+L'évaluation du modèle peut produire un artefact "model_evaluation.json", versionné dans git avec chaque nouvelle version du modèle.
+
+## Documentation
+
+Une documentation du code peut être générée automatiquement grâce à `sphinx` (voir [README.md](./README.md)). Celle-ci se base sur les «docstrings» des modules, classes et autres objets pythons du code, il est donc très utile de bien les documenter ! 
+
+Le format `napoleon` (variante google) est employé. Un exemple de ce format est disponible [ici](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). Quelques éléments importants du format des docstrings :
+- La première ligne est une courte description de l'objet.
+- Des sauts de lignes séparent la première ligne, la description plus longue, les arguments, la valeur renvoyée.
+- Si la ligne de description d'un argument dépasse la longueur maximale autorisée, on indente la ligne suivante de deux espaces.
+- On préférera indiquer les types des variables d'entrée et de sortie directement dans la signature d'une fonction plutôt que dans la docstring.
+- Il est possible d'intégrer des équations à l'aide de la directive `:math:`.
 
 ## Securité et Configuration :construction_worker:
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,56 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../predictsignauxfaibles/"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "predictsignauxfaibles"
+copyright = "2021, the signaux-faibles contributors"
+author = "The signaux-faibles contributors."
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,20 @@
+.. predictsignauxfaibles documentation master file, created by
+   sphinx-quickstart on Tue Aug 31 14:35:33 2021.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to predictsignauxfaibles's documentation!
+=================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/modules.rst

@@ -0,0 +1,7 @@
+predictsignauxfaibles
+=====================
+
+.. toctree::
+   :maxdepth: 4
+
+   predictsignauxfaibles