integration-nouvelle-source-donnees.md

Comment intégrer une nouvelle source de données

Cette page donne la marche à suivre pour intégrer une nouvelle source de données, en plusieurs étapes:

• Définition des attentes / Écriture de tests automatisés
• Implémentation du parseur
• Mise à disposition des données pour la chaine de traitement
• Publication des données sur le web
• Pré-traitement des données pour l'apprentissage et la génération de listes
• Détection des fichiers pour population automatique du batch à importer

La plupart de ces étapes auront pour effet d'enrichir les fonctionnalités de la commande sfdata, en modifiant le code source du dépôt signaux-faibles/opensignauxfaibles.

Définition des attentes / Écriture de tests automatisés

Pré-requis:

• Se procurer des données d'exemple depuis cette source + la documentation de leur format

• Vérifier que cette source de données n'est pas déjà supportée, ou redondante avec une source déjà supportée (cf Description des données, Tableau des types de fichiers supportés et liste registeredParsers de opensignauxfaibles)

• Choisir un identifiant unique mais reconnaissable (ex: paydex, sirene_ul...) qui sera utilisé pour nommer le parseur, grouper les fichiers de ce type dans le batch et pour identifier la source d'erreurs éventuelles de parsing dans le Journal

Étapes recommandées:

1. Constituer un jeu de données concis et anonymisé (mais réaliste et représentatif) qui sera utilisé pour tester le bon fonctionnement du parseur et du reste de la chaine de traitement sur ces données. Exemple: lib/paydex/testData/paydexTestData.csv

2. Inclure ces données de test dans le batch de test-import.sh. Nous allons laisser le test échouer, jusqu'à ce que le parseur soit opérationnel. (cf dernière étape de la section suivante) Exemple: ajout d'un fichier paydex dans la propriété "files"

Ces premières étapes vont permettre de mesurer notre avancement pendant l'implémentation du parseur, en observant les résultats de chaque itération, après avoir exécuté tests/test-import.sh.

Implémentation du parseur

Étapes recommandées:

1. Écrire un test unitaire pour définir les données attendues en sortie du parseur, après lecture du jeu de données de test constitué à l'étape précédente. Ce test passera une fois que le parseur sera correctement implémenté. Exemple: "should parse a valid row" défini pour le parseur paydex

2. Définir le type struct en sortie du parseur, sans oublier d'implémenter les méthodes Key(), Scope() et Type() associées. Exemple: type Paydex

3. Écrire le parseur en implémentant les méthodes attendues par l'interface marshal/parser.go puis définir une variable publique contenant une instance de ce parseur. Exemple: instance de paydexParser

4. Ajouter l'instance du parseur dans registeredParsers. Exemple: association de l'instance paydex.ParserPaydex à l'identifiant paydex

5. Exécuter go generate ./..., make puis tests/test-import.sh --update pour inclure dans tests/output-snapshots/test-import.golden.txt les données parsées depuis le jeu de données de test. Si nécéssaire, effectuer des modifications du parseurs puis ré-exécuter ces commandes.

Mise à disposition des données pour la chaine de traitement

Une fois le parseur fonctionnel et correctement testé, nous allons documenter les données qu'il intègre puis rendre ces données exploitables par les commandes sfdata public et sfdata reduce.

Étapes recommandées:

1. Ajouter une section dans description-donnees.md pour décrire la source des données. Exemple: ajout de la documentation des données Ellisphere

2. Ajouter la source dans la liste des fichiers supportés, de processus-traitement-donnees.md. Exemple: ajout de la source paydex dans la liste

3. Pour permettre la validation des données importées en base de données ainsi que pour garantir l'alignement de leur structure (en sortie du parseur) avec les types qui seront manipulés en TypeScript/JavaScript par la chaine de traitements, écrire un fichier JSON Schema dans le répertoire validation et le référencer dans la liste typesToCompare de validation/validation_test.go.

4. Générer les types TypeScript (js/GeneratedTypes.d.ts) à l'aide de la commande go generate ./... puis exécuter go test ./... pour s'assurer que le fichier JSON Schema est aligné avec la structure en sortie du parseur.

5. Ajouter un champ pour la nouvelle source de données dans le type EntrepriseBatchProps ou EtablissementBatchProps de js/RawDataTypes.ts. Utiliser l'identifiant de la source de données en guise de clé et le type TypeScript correspondant, celui qui a été ajouté à js/GeneratedTypes.d.ts dans l'étape précédente. Dans les documents de la collection RawData, cette propriété contiendra les données de la nouvelle source, classées par hash. Exemple: ajout de paydex: ParHash<EntréePaydex> dans le type EntrepriseBatchProps

Note: cet ajout aura pour effet de rendre incomplets les jeux de données employés par des tests d'intégration définis dans les répertoires js/public/ et js/reduce.algo2/. Nous allons compléter ces données de tests dans les étapes suivantes.

Publication des données sur le web

La publication de données sur l'application web de Signaux Faible commence par l'exécution d'une opération map-reduce sur la collection RawData appelant des fonctions TypeScript.

Dans la section précédente, nous avons documenté le type des entrées de données introduites de manière à ce qu'elles soient manipulables depuis ces fonctions, tout en bénéficiant de la vérification statique de l'intégrité de ces données.

Il ne nous reste donc plus qu'à tester la présence et la validité de ces entrées, puis à les intégrer dans les fonctions de l'opération map-reduce appelée public.

Étapes recommandées:

1. Compléter le test d'intégration "public.map() retourne toutes les propriétés d'entreprise (ou d'établissement) attendues sur le frontal" défini dans js/public/ava_tests.ts, en ajoutant à rawEntrData (ou rawEtabData) la propriété rattachant des données de test au nom de la source de données. Exemple: ajout de paydex à rawEntrData.

2. Implémenter l'intégration des entrées de données dans la fonction map() du map-reduce public, dans le fichier public/map.ts. Exemple: intégration du champ paydex dans map()

Note: Si l'intégration prend un nombre considérable de lignes de code, ne pas hésiter à l'extraire dans une fonction séparée, définie dans un fichier dédié. Exemple: public/diane.ts. Dans ce cas, ne pas oublier d'inclure cette fonction dans l'espace de noms f, défini dans functions.ts. Exemple: inclusion de raison_sociale dans public/functions.ts

3. Pour transpiler et empaqueter les fonctions en JavaScript puis mettre à jour les clichés (snapshots et golden masters) de résultats attendus de tests automatisés, exécuter ./test-all.sh --update-snapshots.

Pré-traitement des données pour l'apprentissage et la génération de listes

La génération de liste de détection et l'apprentissage permettant ces prévisions s'appuie sur des variables pré-traitées par l'exécution d'une opération map-reduce sur la collection RawData appelant des fonctions TypeScript.

Plus haut, nous avons documenté le type des entrées de données introduites de manière à ce qu'elles soient manipulables depuis ces fonctions, tout en bénéficiant de la vérification statique de l'intégrité de ces données.

Il ne nous reste donc plus qu'à tester la présence et la validité de ces entrées depuis l'opération map-reduce appelée reduce.algo2, puis à les intégrer dans les fonctions appelées par cette opération.

Étapes recommandées:

1. Compléter le test d'intégration "algo2.map() retourne les propriétés d'entreprise (ou d'établissement) attendues par l'algo d'apprentissage" défini dans js/reduce.algo2/algo2_tests.ts, en ajoutant à rawEntrData (ou rawEtabData) la propriété rattachant des données de test au nom de la source de données. Exemple: ajout de paydex à rawEntrData.

2. Implémenter l'intégration des entrées de données dans la fonction map() du map-reduce reduce.algo2, dans le fichier reduce.algo2/map.ts. Exemple: intégration du champ paydex dans map()

Note: Si l'intégration prend un nombre considérable de lignes de code, ne pas hésiter à l'extraire dans une fonction séparée, définie dans un fichier dédié. Exemple: reduce.algo2/entr_paydex.ts. Dans ce cas, ne pas oublier d'inclure cette fonction dans l'espace de noms f, défini dans functions.ts. Exemple: inclusion de entr_paydex dans reduce.algo2/functions.ts

3. Recommandé: écrire des tests unitaires pour documenter les traitements effectués et éviter les régressions. Exemple: reduce.algo2/entr_paydex_tests.ts

4. Exporter un type Variables constitué des propriétés source, computed et transmitted, afin de générer de manière automatique la documentation des variables fournies à l'algorithme (js/reduce.algo2/docs/variables.json). Exemple: description des champs calculés et transmis de entr_paydex.

Note: Le commentaire JSDoc de chaque champs sera automatiquement extrait comme description de ce champ, au moment de la génération de variables.json. Exemple: commentaire JSDoc du champ statut_juridique de entr_paydex

5. Pour transpiler et empaqueter les fonctions en JavaScript puis mettre à jour les clichés (snapshots et golden masters) de résultats attendus de tests automatisés, exécuter ./test-all.sh --update-snapshots.

Détection des fichiers pour population automatique du batch à importer

La nouvelle source de donnée est désormais supportée par toute la chaine d'intégration couverte par la commande sfdata.

Pour faciliter l'intégration régulière de données, nous pouvons à présent faire en sorte que la commande prepare-import reconnaisse automatiquement les fichiers permettant d'importer ces données.

Étapes recommandées:

1. Ajouter le(s) nom(s) de fichier(s) de test dans le test de bout en bout de prepare-import (main_test.go). Exemple: intégration d'un fichier paydex de test

2. Ajouter dans le test unitaire TestExtractFileTypeFromFilename quelques exemples de noms que pourraient avoir les fichiers issues de la nouvelle source de données, pour assurer que ces noms seront systématiquement reconnus par prepare-import. Exemple: ajout de noms de fichiers sirene et paydex.

3. Implémenter la détection du type de données à partir du nom du fichier (exemple: détection paydex par une expression régulière), ou à partir des métadonnées associées (exemple: détection bdf depuis la métadonnée goup-path).

4. Vérifier que tous les tests passent, et mettre à jour les clichés (snapshots et golden masters) de résultats attendus par les tests automatisés, en exécutant make test-update.