add doc

actes-princiers/docs/source/index.rst

@@ -4,6 +4,8 @@ Projet Actes Princiers
 .. toctree::
    :maxdepth: 1
 
+   kedro
+   pipeline
    data
    xml
    coding_standards

actes-princiers/docs/source/kedro.rst

@@ -0,0 +1,117 @@
+.. meta:: 
+   :description: data engineering  
+   :keywords:  reproducible, maintainable, modular data science code
+
+Orientation Data du projet
+============================
+
+A quoi ça sert ? 
+--------------------
+
+La question peut se poser : à quoi ça sert de passer à du code datascience ? 
+Pourquoi s'acharner à produire du code maintenable, modulaire, de manière 
+à pouvoir reproduire une interprétation de data ? 
+
+.. admonition:: Les questions que posent l'orientation datas d'un projet 
+
+    - Qu'est-ce qu'une orientation data ? 
+    - Quel est l'intérêt de produire du "datascience code" ? 
+    - Ne faut-il pas mieux revenir au code `database -> html renderer ?` 
+
+
+Le code d'une web app 
+-------------------------
+
+Pour partir d'un exemple voici un bout du code de la maquette : 
+
+.. code-block:: python
+
+        source_doc = etree.parse(
+            os.path.join(APPPATH, "static", "xml", house, acte_id + '.xml'))
+        # remove namespace :
+        query = "descendant-or-self::*[namespace-uri()!='']"
+        for element in source_doc.xpath(query):
+            #replace element name with its local name
+            element.tag = etree.QName(element).localname
+        etree.cleanup_namespaces(source_doc)
+
+        xslt_doc = etree.parse(os.path.join(APPPATH, "static", "xsl", "actes_princiers.xsl"))
+        xslt_transformer = etree.XSLT(xslt_doc)
+        output_doc = xslt_transformer(source_doc)
+        return render_template("acte.html", house=house, prince=prince,
+            infos=q_acte, place=place[0], doc=doc[0][0], arch=inst[0],
+            diplo=diplo_t[0].replace("_", " "), state=state[0],
+            output_doc=output_doc, name_prince=prince_name[0],
+            transcribers=transcribers)
+
+Ce code est : 
+
+- difficilement compréhensible, 
+- difficilement maintenable par quelqu'un d'autre que 
+  celui qui a produit ce code, 
+- est fortement lié à l'organisation d'une base de données
+  et d'un document xml, il n'y a donc pas d'unité des sources 
+  de données, 
+- etc...
+
+
+Un data science pipeline ? 
+--------------------------------
+
+Un datascience framework, plutôt :
+
+.. image:: img/KedroRunTimeline.png
+
+- on charge d'abord un catalogue de données sources 
+- on fait le traitement dans des étapes bien distinctes appelées pipeline 
+
+.. glossary::
+
+    pipeline 
+    
+        Un pipeline est un processus ordonné. 
+        Plusieurs actions sont lancées de manière successives ou 
+        bien en parallèle, ces actions sont dépendantes les unes des autres
+        et sont encapsulées dans des nodes. 
+
+`Voici la définition d'un pipeline d'après kedro <https://docs.kedro.org/en/stable/get_started/kedro_concepts.html#pipeline>`_ :
+
+A pipeline organises the dependencies and execution order of a collection of nodes and connects inputs and outputs while keeping your code modular. The pipeline determines the node execution order by resolving dependencies and does not necessarily run the nodes in the order in which they are passed in.
+
+Here is a pipeline comprised of the nodes shown above::
+
+    from kedro.pipeline import pipeline
+
+    # Assemble nodes into a pipeline
+    greeting_pipeline = pipeline([return_greeting_node, join_statements_node])
+
+    
+    node 
+    
+        Un node encapsule (enveloppe) une action. 
+        Cette action est une fonction (un traitement) python.
+        
+`Voici la définition d'un node d'après kedro <https://docs.kedro.org/en/stable/get_started/kedro_concepts.html#node>`_ :
+
+In Kedro, a node is a wrapper for a pure Python function that names the inputs and outputs of that function. Nodes are the building block of a pipeline, and the output of one node can be the input of another.
+
+Here are two simple nodes as an example:
+
+.. code-block:: python
+
+    from kedro.pipeline import node
+
+    # First node
+    def return_greeting():
+        return "Hello"
+
+
+    return_greeting_node = node(func=return_greeting, inputs=None, outputs="my_salutation")
+
+    # Second node
+    def join_statements(greeting):
+        return f"{greeting} Kedro!"
+
+
+    join_statements_node = node(
+        join_statements, inputs="my_salutation", outputs="my_message"

actes-princiers/docs/source/pipeline.rst

@@ -0,0 +1,282 @@
+Vue d'ensemble sur le process de pipeline
+=========================================
+
+Quels data pipelines mettre en place ? 
+
+Qu'est-ce qu'un pipeline de données
+------------------------------------
+
+.. glossary::
+
+    pipeline de données
+
+        Un pipeline de données est une méthode dans laquelle les données brutes 
+        sont ingérées à partir de diverses sources de données, puis transférées 
+        vers un magasin de données, un entrepôt de données, pour ensuite 
+        les analyser.
+
+Avant que les données ne circulent dans un :term:`référentiel de données`, 
+elles subissent généralement un traitement de l'information. 
+Cette opération inclut les transformations de données, telles que le filtrage, 
+le masquage et les agrégations, qui garantissent une intégration 
+et une standardisation adéquates des données.
+Ceci est particulièrement important lorsque la destination du fichier 
+est une base de données relationnelle. 
+Ce type de référentiel de données a un schéma défini qui nécessite un *alignement*, 
+c'est-à-dire qu'il faut faire correspondre les colonnes et les types de données 
+afin de mettre à jour les données existantes avec de nouvelles données.
+
+Le trajet dans le pipeline de données
+-----------------------------------------
+
+Qu'entend-t-on par "data processing" ? 
+
+- La collecte ou l’extraction d’ensembles de données brutes.
+- La gouvernance des données. Une fois les données collectées, il faut constituer 
+  une discipline pour organiser les données. 
+  Cette discipline s’appelle la gouvernance des données. 
+  On commence par relier les données brutes au contexte pour qu’elles aient un sens. 
+  On contrôle ensuite la qualité des données et la sécurité des données, 
+  avant de les organiser pleinement en vue de leur consommation.
+
+Le pipeline ETL
+----------------
+
+.. glossary::
+
+   ETL
+
+       ETL signifie **E**\ xtract, **T**\ ransform, **L**\ oad.
+       C'est historiquement le premier data pipeline, (pipeline sur les données).
+
+
+.. rubric:: Exemple de YAML descriptif d'un pipeline
+
+
+.. code-block:: yaml
+
+    stage: 
+
+      prepared:
+        - name: bourbon_clean_up
+          depends: bourbon_xml_catalog
+          outputs: bourbon_data
+  
+
+
+
+Qu'est-ce que intégrer des données ? 
+---------------------------------------
+
+.. glossary:: 
+
+   intégration des données
+
+        L'intégration des données est le processus qui consiste à combiner des données 
+        provenant de différentes sources dans une vue unifiée : de l'importation au nettoyage 
+        en passant par le mapping et la transformation dans un gisement cible, 
+        pour finalement rendre les données plus exploitables et plus utiles.
+
+.. rubric:: exemple 
+
+Les métadatas contenues dans un fichier CSV et les datas contenues dans un fichier XML. 
+
+Qu’est-ce que l'étiquetage des données ?
+-------------------------------------------------------
+
+Dans le cas de processus tels que l’intégration des données, la migration des données, 
+l’automatisation des entrepôts de données, la synchronisation des données, 
+l’extraction automatique de données ou d’autres projets de gestion des données, 
+la qualité de l'étiquetage conditionnera la qualité des données qui seront analysées 
+pour en tirer des informations exploitables.
+
+.. glossary::
+
+   étiquetage des données
+
+       Un label est associé à une donnée pour savoir par exemple quelle est 
+       sa provenance. 
+
+**E**\ xtraire les données
+-----------------------------
+
+
+- **Extraire les données** c'est, dans ce cas, charger depuis le système de fichiers en local, 
+  les fichiers CSV et XML.
+
+.. note:: Pas besoin de collecte et agrégation des données.
+          Les Sources de datas sont présentes en local dans l'application. 
+
+.. admonition:: TODO 
+
+   Il faudra les enlever de l'arborescence flask pour les mettre dans 
+   un :term:`référentiel de données`. 
+
+Datasource CSV::
+
+    ./app/static/csv/corpus-agnes-bourgogne.csv
+    ./app/static/csv/corpus-charles-i.csv
+    ./app/static/csv/actors.csv
+
+Datasource XML :
+
+Dans `./app/static/xml/` : 
+
+.. image:: img/xml.png
+
+Le référentiel de données
+--------------------------------
+
+.. glossary::
+
+   source de données
+
+       Une source de données peut être l'endroit où les données ont été créées ou celui où les informations physiques ont été numérisées. Cependant, même les données les plus élaborées peuvent être considérées comme des sources, tant qu'un autre processus y accède et les utilise. Concrètement, une source de données peut être une base de données, un fichier plat, des mesures provenant directement d'appareils physiques, des données obtenues par web scraping ou l'une des nombreux services de données statiques et de données en streaming qui abondent sur Internet.
+
+   référentiel de données
+
+       Le référentiel contient la totalité des données brutes collectées. Une collection, (Data Collection, data catalog, 
+       data lakes, etc).
+
+
+Il s'agit de charger des catalogues de données. 
+
+Les catalogues 
+----------------
+
+`intake <https://intake.readthedocs.io/en/latest/index.html>`_
+
+.. glossary:: 
+
+   Catalogue 
+   
+       Un catalogue est un inventaire de sources de données.
+       An inventory of entries, each of which corresponds to a specific Data-set. 
+
+   Catalog file
+
+       A YAML specification file which contains a list of named entries describing how to load data sources. 
+
+   Data-set
+
+       A specific assemblage of data. The type of data (tabular, multi-dimensional or something else) and the format (file type, data service type) are all attributes of the data-set. In addition, in the context of Intake, data-sets are usually entries within a Catalog with additional descriptive text and metadata and a specification of how to load the data.
+
+
+.. rubric:: Exemple de catalogue 
+
+
+.. code-block:: yaml
+
+    sources:
+      states:
+        description: Bourbon Charles Ier
+        driver: xml
+        args:
+          urlpath: '{{ CATALOG_DIR }}/Bourbon/5-Charles-Ier/charles_ier_*.xml'
+        metadata:
+          origin_url: '{{ ORIGIN_URL }}/charles_ier_*.xml'
+
+Le chargement du catalogue XML doit pouvoirse faire par du code de haut niveau
+de la manière suivante : 
+
+.. code-block:: python
+
+    cat = intake.open_catalog('bourbon.yml')
+    list(cat)
+    ['Bourbon', 'CharlesIer']
+
+
+Il faut pouvoir charger un catalogue en deux lignes
+
+.. code-block:: python
+
+    cat = intake.load_catalog('catalog.yml')
+    data = cat.data_source().read()
+
+Comment ce genre de librairie fonctionne : 
+Il suffit de lui renseigner un pattern : 
+
+.. code-block:: python
+
+    >>> reverse_format('data_{year}_{month}_{day}.csv', 'data_2014_01_03.csv')
+    {'year': '2014', 'month': '01', 'day': '03'}
+
+Et intake charge les fichiers en fonction de ces patterns. 
+
+La **T**\ ransformation des données
+------------------------------------
+
+- **Transformer ces données** (validations de typage, validation de schéma de
+  structure de données, etc), typiquement avec des librairies comme `pydantic <https://docs.pydantic.dev/latest/>`_
+
+.. glossary::
+
+   transformation des données
+
+        La transformation des données consiste à convertir les données d’un format source dans un format cible. Cela peut inclure un nettoyage des données par une modification des types de données, une suppression des données invalides ou des doublons, une agrégation des données, un enrichissement des données ou d’autres transformations.
+
+- La transformation des données
+
+  - normalisation
+  - dédoublonnage
+  - vérification
+  - classement
+  - partage des données
+
+Autres types de transformation :
+
+- Cleaning
+- Filtering
+- Joining
+- Sorting
+- Splitting
+- Deduplication
+- Summarization
+
+"The data cleaning and organization stage is the transformation stage."
+
+.. rubric:: Quel type de transformation des données et pourquoi ? 
+
+Il s'agit surtout de les structurer, ce que faisait, avant, le storage 
+dans une base de données relationnelle. 
+
+Aujourd'hui, l'organisation des datas ne relève plus de la responsabilité du storage 
+(`cohérence de type ACID <http://monge.univ-mlv.fr/~dr/XPOSE2011/BDD/acid.html>`_),
+le storage n'ayant que la responsabilité de type `BASE <http://monge.univ-mlv.fr/~dr/XPOSE2011/BDD/acid.html>`_
+
+Que signifie le data reshaping ? 
+--------------------------------------
+
+On parle de data shape shifting ou data reshaping. 
+
+- data shape shifting (changement de forme des datas)
+- data reshaping avec pandas
+- data reshaping avec les schémas, que ce soient les schémas d'une database
+  ou bien les librairies de schémas d'une structure de données. 
+
+Avant, on utilisait uniquement les databases pour faire du data reshaping.
+La database etait vue comme cela : 
+
+- PostgreSQL as a data processing engine, 
+- sqlite as a data processing engine. 
+
+Aujourd'hui, on utilise plutôt des librairies de validation de schémas (pydantic, JSON schema,
+XML schema...)
+
+Le chargement des données (**L**\ oad)
+----------------------------------------
+  
+- mettre ces données dans un storage (dans ce contexte, une database nosql
+  de type mongodb). 
+  
+.. note:: concernant le storage, un serveur mongo n'est pas gourmand en ressources 
+   et reste dans le cadre d'outil "low tech" à mon avis. 
+   
+   On peut aussi utiliser une base nosql qui ne soit pas un serveur 
+   (comme pour sqlite dans le monde des databases relationnelles). 
+
+.. note:: Chacune de ces étapes fait aujourd'hui l'objet d'un pipeline
+          indépendant.
+          Par exemple, dans le "data understanding", la question de l'extraction
+          d'information représente de nombreux pipelines.
+