Génération DSPL

DSPL Generation est un utilitaire de ligne de commande qui permet de convertir une table de données CSV en un simple ensemble de données DSPL. L'outil analyse le fichier d'entrée, crée toutes les tables de données nécessaires et établit un fichier XML DSPL. Il en résulte un "modèle" d'ensemble de données presque complet qui ne nécessite qu'un affinement mineur avant l'importation et la visualisation.

L'hypothèse de base sur la génération DSPL est que chaque colonne du fichier CSV d'entrée correspond à un seul concept DSPL et chaque ligne correspond à une seule observation pour une combinaison de dimensions. L'outil parcourt les colonnes et établit les métadonnées appropriées pour chaque colonne / concept (par exemple, son ID, son type, s'il s'agit d'une dimension ou d'une métrique, etc.), puis génère toutes les définitions de concepts et tables de secteurs nécessaires.

Exécution de la génération DSPL

Syntaxe

Remarque : Ces instructions partent du principe que vous avez déjà suivi les instructions d'installation fournies sur la page "Outils" de DSPL.

Pour exécuter la génération DSPL, accédez au terminal ou à l'invite sur votre système, puis saisissez:

python dsplgen.py -o [output path] [path to CSV file] 

où les termes entre crochets sont remplacés comme suit:

• [output path]: chemin d'accès au répertoire dans lequel vous souhaitez placer vos fichiers de sortie. Ce répertoire doit déjà exister dans votre système de fichiers.
• [path to CSV file]: chemin d'accès à votre fichier CSV d'entrée. Consultez la section ci-dessous pour découvrir comment mettre en forme ce fichier.

Le composant -o [output path] est facultatif. S'il est omis, les fichiers de sortie seront placés dans le répertoire actuel.

Ensuite, l'outil exécute des itérations dans votre fichier CSV, extrait les définitions de concepts et génère des tables de tranche. Sauf en cas d'erreur, un fichier XML et un ou plusieurs fichiers CSV sont écrits dans le répertoire de sortie.

Enfin, ouvrez le fichier XML dans l'éditeur de texte de votre choix et apportez les modifications souhaitées. Vous devez au moins renseigner les noms, les descriptions et les autres valeurs marquées par l'outil au format ** INSERT ... **.

Exemple simple

Supposons que nous disposons d'un fichier CSV qui indique le nombre total de cas pour une maladie, par mois, pays et tranche d'âge. Par souci de simplicité, supposons qu'il existe deux valeurs pour chaque dimension:

date,country,age_group,disease_cases
01/2000,US,old,102030
01/2000,MX,old,192939
01/2000,US,young,23131
01/2000,MX,young,12311
02/2000,US,old,143135
02/2000,MX,old,203131
02/2000,US,young,22990
02/2000,MX,young,12591

L'exécution de l'outil sur l'entrée ci-dessus produit quatre fichiers:

• dataset.xml: modèle XML DSPL
• country_table.csv : valeurs du concept country
• age_group_table.csv: valeurs du concept age_group
• slice_0_table.csv: table pour la tranche d'ensemble de données (identique à la table d'entrée, sauf pour le tri)

Dans ce cas particulier, l'outil peut deviner correctement tous les types et formats de colonnes. Il vous suffit donc d'accéder au fichier XML et de modifier les différents noms, descriptions et URL dans les métadonnées de l'ensemble de données.

Annoter votre fichier CSV d'entrée

Options de base

Dans de nombreux cas, comme dans l'exemple ci-dessus, la génération DSPL peut deviner les métadonnées de base de chaque colonne (par exemple, le type, le format, et même s'il s'agit d'une dimension ou d'une métrique). Toutefois, dans d'autres cas, il est possible que l'outil ne soit pas en mesure de deviner ces résultats, soit de le deviner de manière incorrecte, soit de le deviner correctement. En revanche, il ne respecte pas le comportement souhaité.

Pour gérer ces cas, l'outil permet l'ajout d'options/d'"indices" DSPL dans la ligne d'en-tête du fichier CSV. La syntaxe pour ces éléments est la suivante:

column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...

Notez en particulier que la liste d'options est placée entre crochets à droite du nom de la colonne et que les paramètres d'option successifs sont séparés par des points-virgules. Chaque option se compose d'un nom d'option, d'un signe égal et d'une valeur d'option.

DSPL Genom est actuellement compatible avec les options de base suivantes:

Option	Description	Par défaut
type	Type de données DSPL associé à cette colonne. Doit correspondre à date, float, integer ou string.	D'après les données
format	Format de cette colonne de date. Comme dans DSPL, ce format doit être encodé selon la norme Joda DateTime.	D'après les données
slice_role	Rôle de cette colonne dans une tranche. Doit être dimension ou metric.	dimension si la colonne est de type date ou string, sinon metric
concept	Concept canonique que cette colonne représente, par exemple geo:country. S'il est indiqué, le concept est importé et aucune définition n'est produite dans le fichier XML.	Aucune
extends	Concept canonique que cette colonne étend, par exemple entity:entity.	Aucune
parent	Concept parent de cette colonne. Ce parent doit être un concept de dimension défini dans l'ensemble de données (c'est-à-dire non importé). Ces informations seront utilisées pour définir une hiérarchie de concepts dans l'ensemble de données. Notez que chaque instance enfant ne peut avoir qu'un seul parent. Si plusieurs valeurs parentes sont détectées, l'outil génère une erreur.	Aucune

Vues d'ensemble des valeurs

En plus des options de base de "conseil" décrites ci-dessus, DSPL Genom est également compatible avec les consolidations de tranches : avec une seule entrée de table, l'outil peut créer automatiquement des tables supplémentaires avec des sous-ensembles limités de dimensions. Par exemple, si votre table d'entrée correspond à une tranche avec trois dimensions non temporelles (par exemple, dimension1, dimension2 et dimensions3), l'outil peut également créer des secteurs supplémentaires: dimension1, dimension2, dimension1 et dimension2, etc.

L'ajout de ces tranches supplémentaires peut faciliter l'exploration de votre ensemble de données, car il réduit le nombre de filtres de dimension requis pour produire des visualisations. D'autre part, ce processus peut introduire de "nouvelles" données introuvables dans le fichier d'origine. Il peut donc également entraîner des erreurs s'il n'est pas utilisé correctement. Vérifiez attentivement les chiffres de consolidation avant de publier votre ensemble de données.

Le processus de consolidation est déclenché par l'inclusion d'options supplémentaires dans l'en-tête du fichier CSV d'entrée:

Option	Description	Par défaut
aggregation	Méthode d'agrégation à utiliser lors de la combinaison de plusieurs valeurs de cette colonne. Doit prendre l'une des valeurs suivantes : AVG, COUNT, MAX, MIN ou SUM. Uniquement significative pour les métriques.	SUM
rollup	Si la valeur est true, le concept de cette colonne est "développé" (c'est-à-dire agrégé) ; ne concerne que les concepts de dimension.	False
total_val	Valeur de cette colonne qui indique les lignes à conserver lorsque cette colonne est cumulée. Ne s'applique qu'aux concepts de dimension.	None

DSPL Generation calcule ensuite les cumuls à l'aide de l'algorithme suivant:

• À l'aide des valeurs des tags rollup, calculez toutes les combinaisons de colonnes possibles.
• Pour chaque combinaison :
  • Si un paramètre total_val est défini pour des colonnes englobantes, filtrez les lignes en fonction de cette valeur. Sinon, sélectionnez toutes les lignes.
  • Supprimer les colonnes de consolidation
  • Regrouper les lignes en fonction des valeurs des colonnes de dimension restantes
  • Agréger chaque métrique à l'aide de la méthode spécifiée dans son paramètre aggregation
  • Créer une tranche et une table associée pour le résultat

Notez que si chaque regroupement ne contient qu'une seule valeur et que la fonction d'agrégation est définie sur SUM (valeur par défaut), les valeurs des métriques de la table source et de la table générée seront identiques, c'est-à-dire qu'aucune nouvelle valeur ne sera générée. Ainsi, en utilisant le paramètre total_val et en vous assurant qu'il n'y a qu'une ligne "total" pour chaque combinaison des autres dimensions, vous pouvez stocker des agrégats précalculés directement dans la source.

Avertissement : Le nombre de tranches générées est égal à deux ^{colonnes regroupées}. L'application de cette option à un grand nombre de colonnes peut entraîner des temps d'exécution très longs et/ou des ensembles de données volumineux.

Exemple avancé

Supposons que nous disposons des mêmes données d'entrée que dans l'exemple précédent, mais qu'elles incluent désormais les agrégats de tous les pays :

date,country,age_group,disease_cases
01/2000,US,old,102030
01/2000,MX,old,192939
01/2000,total,old,152012
01/2000,US,young,23131
01/2000,MX,young,12311
01/2000,total,young,241011
02/2000,US,old,143135
02/2000,MX,old,203131
02/2000,total,old,211310
02/2000,US,young,22990
02/2000,MX,young,12591
02/2000,total,young,240131

Le total de chaque tranche d'âge peut ne pas correspondre à la somme des valeurs de pays, par exemple en raison de différences de méthodologie ou de l'existence d'autres pays non énumérés dans la liste.

Nous voulons maintenant créer un ensemble de données DSPL doté des fonctionnalités supplémentaires suivantes:

1. "Regrouper" les pays pour obtenir le nombre total de cas de maladie par tranche d'âge
2. Utilisez le concept canonique geo:country pour la colonne country afin d'obtenir automatiquement les noms complets, les lieux, etc.
3. Faites en sorte que le concept disease_cases étende quantity:amount afin que nous puissions ajouter (manuellement) des informations sur les unités dans le fichier XML

Pour ce faire, modifiez la ligne d'en-tête du fichier CSV d'entrée comme suit:

date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]

En exécutant à nouveau l'outil, nous obtenons une table de tranche supplémentaire, qui élimine la distinction par pays:

date,age_group,disease_cases
01/2000,old,152012
02/2000,old,211310
01/2000,young,241011
02/2000,young,240131

Notez que si nous n'avions pas inclus les valeurs totales et la balise total_val dans la table source, nous aurions obtenu la somme calculée pour chaque tranche d'âge.

De plus, la définition de disease_cases dans le fichier XML inclut désormais l'extension quantity:amount, comme vous le souhaitez. La définition de country est supprimée du fichier XML, car nous utilisons un concept importé à cet effet.

Après avoir renseigné les différents noms, descriptions et informations sur les unités, nous pouvons compresser le groupe d'ensembles de données et l'importer dans Public Data Explorer pour visualisation.