Livre de recettes DSPL

Ce document contient un livre de recettes sur le DSPL et le concept canonique "recettes". Ils fournissent des instructions détaillées pour diverses tâches allant au-delà des fonctionnalités de base du langage décrites dans le tutoriel et dans le guide du développeur. Le contenu ci-dessous suppose que vous connaissez les documents précédents. Assurez-vous donc de les lire avant de commencer votre cuisine.

Chaque recette commence par un objectif, suivi d'une liste d'étapes spécifiques à suivre. Beaucoup incluent également des extraits DSPL ou des liens vers des exemples externes. Si vous avez des commentaires sur une recette ou si vous souhaitez suggérer des recettes à d'autres personnes, vous pouvez les publier sur le forum DSPL.

Recettes de base

Spécifier des noms à afficher

Objectif

Associez un "nom à afficher" à chaque instance d'un concept (de dimension). Ces noms apparaîtront dans l'interface utilisateur de l'explorateur de données publiques à la place des ID d'instances de concept, qui sont généralement plus courts et plus difficiles à comprendre pour les utilisateurs.

Étapes

1. Étendez votre concept à entity:entity.
2. Ajoutez une colonne name au tableau de définition de concept associé.
3. Renseignez cette dernière propriété avec le nom de chaque instance.

Remarques

• Vous n'avez pas besoin de définir explicitement une propriété name dans les métadonnées de votre concept. Cette définition est automatiquement incluse lorsque vous étendez entity:entity.
• Vous pouvez également ajouter des colonnes description et info_url pour fournir des descriptions et des URL au niveau de l'instance, respectivement.

Créer des hiérarchies de concepts

Objectif

Créez une hiérarchie de concepts (dimension). Ils apparaîtront dans l'interface utilisateur de l'explorateur de données publiques sous la forme d'une arborescence, ce qui permettra aux utilisateurs de comprendre les regroupements et de naviguer entre eux.

Étapes

1. Définissez un concept "parent" (par exemple, region).
2. Définir un concept "enfant" (par exemple, subregion).
3. Ajoutez une propriété enfant qui référence le parent et qui inclut l'attribut isParent (

   <property concept="..." isParent="true"/>
   

   ), où les points sont remplacés par l'ID parent.
4. Dans la table de définition de l'enfant, ajoutez une colonne qui référence le parent.
5. Pour chaque instance enfant, indiquez à cette dernière une instance valide du concept parent.

Remarques

• Pour obtenir un exemple, consultez la relation country / state dans l'ensemble de données du tutoriel.
• Chaque ID parent référencé depuis l'enfant doit figurer dans la table de définition du parent. Sinon, l'importateur générera une erreur.
• Le parent et l'enfant peuvent avoir le même concept (c'est-à-dire une auto-référence). Pour voir un exemple, reportez-vous au concept business dans l'ensemble de données sur les ventes au détail aux États-Unis.

Catégoriser les instances de concept

Objectif

Créez des catégories pour les instances de concept qui s'afficheront en tant qu'options dans les sélecteurs de couleur de l'explorateur Google Données publiques.

Étapes

1. Définissez un concept de "catégorie" (par exemple, income_level).
2. Définir un concept "enfant" (par exemple, country).
3. Ajoutez une propriété enfant qui fait référence au concept de catégorie et inclut un élément name :

   <property concept="..."/>
     <info>
       <name><value>"..."</value></name>
     </info>
   </property>
   

   où le premier ensemble de points est remplacé par l'ID du concept de catégorie et le second est remplacé par le nom à afficher souhaité pour votre propriété (par exemple, "Niveau de revenu").
4. Dans la table de définition de l'enfant, ajoutez une colonne qui fait référence au concept de catégorie.
5. Pour chaque instance enfant, indiquez à cette dernière une instance valide du concept de catégorie.

Remarques

• Un concept peut avoir plusieurs propriétés qui servent de catégories. Dans ce cas, l'utilisateur les verra toutes comme options dans les sélecteurs de couleur.
• L'une des catégories peut également être un parent afin d'organiser les instances de manière hiérarchique dans l'interface utilisateur. Consultez la recette précédente pour en savoir plus.

Spécifier l'ordre de tri des instances conceptuelles

Objectif

Spécifiez l'ordre de tri des instances d'un concept. Cet ordre est utilisé pour répertorier les instances dans le volet de navigation de gauche des pages de visualisation de l'explorateur Google Données publiques.

Étapes

1. Faites en sorte que votre concept étende entity:entity ou l'un de ses enfants (par exemple, geo:location).
2. Ajoutez un attribut entity_order aux métadonnées de votre concept.
3. Définissez la valeur de l'instance précédente sur l'une des options suivantes : ALPHA ou TABLE. Si vous utilisez la première option, les instances sont répertoriées dans l'ordre de leur nom à afficher, tandis que la seconde les conserve dans l'ordre dans lequel elles apparaissent dans le tableau de définition de concepts.

Remarques

• ALPHA est la valeur par défaut actuelle. Par conséquent, si vous souhaitez utiliser cette commande, les étapes ci-dessus sont facultatives.
• Pour obtenir un exemple, consultez la documentation sur entity:entity.

Recettes temporelles

Données trimestrielles

Objectif

Visualiser les données spécifiées à intervalles trimestriels

Étapes

1. Convertissez tous les trimestres de vos données de tranches en mois (par exemple, le premier mois du trimestre).
2. Traitez cette dimension comme un time:month dans votre fichier XML de tranche.

Données hebdomadaires

Objectif

Visualiser les données spécifiées à intervalles hebdomadaires

Étapes

1. Convertissez toutes les semaines de vos données de tranche en jours (par exemple, le premier jour de la semaine).
2. Traitez cette dimension comme un time:day dans votre fichier XML de tranche.

Recettes géographiques

Utiliser les concepts canoniques country ou state

Objectif

Utilisez les concepts canoniques country ou state, en important toutes les valeurs de latitude et de longitude, etc., de sorte qu'elles n'aient pas besoin d'être définies dans l'ensemble de données.

Étapes

1. Assurez-vous que toutes les références de pays et/ou d'États aux États-Unis dans les fichiers CSV de données de tranche sont des ID valides provenant des tables de définition canoniques des pays et des États.
2. Ajoutez geo:country et/ou geo_us:state comme dimensions dans les secteurs correspondants.
3. Assurez-vous que les noms de colonne pour ces éléments correspondent aux noms des concepts précédents (à l'exception du nom de l'ensemble de données importé, par exemple country) ou, si ce n'est pas le cas, incluez des instructions mapDimension dans votre définition de tranche. Exemple :

   <slice id="...">
     ...
     <dimension concept="geo:country"/>
     ...
     <mapDimension concept="geo:country" toColumn="my_country"/>
   </slice>
   

N'utiliser qu'un sous-ensemble des pays ou États canoniques

Objectif

Utilisez un sous-ensemble d'un concept géographique canonique afin que seul ce sous-ensemble (et non la liste entière, par exemple tous les pays du monde) apparaisse dans l'interface utilisateur publique de l'explorateur de données.

Étapes

1. Définissez un concept local qui étend le concept de sur-ensemble. Exemple :

   <concept id="my_country_subset" extends="geo:country">
   ...
   </concept>
   

2. Dans le fichier CSV de définition de concept associé, n'incluez que les ID du concept de surensemble que vous souhaitez utiliser. Exemple :

   my_country_subset
   FR  
   MX
   US
   

Remarques

• Chaque instance de votre concept de sous-ensemble doit être une instance valide du concept de sur-ensemble. Vous ne pouvez pas "développer" le concept avec de nouvelles instances.

Définir vos propres concepts géographiques

Objectif

Créez vos propres concepts géographiques explorables et cartographiables, comme les concepts canoniques définis par Google.

Étapes

1. Créez un concept qui étend geo:location.
2. Dans le tableau de définition de concepts associé, incluez les colonnes name, latitude et longitude.
3. Renseignez les deux dernières propriétés pour chaque instance de votre concept. Les valeurs de latitude et de longitude sont des nombres à virgule flottante, selon la convention N et E, et W et S, une valeur négative.

Remarques

• Il n'est pas nécessaire d'inclure explicitement les propriétés name, latitude et longitude dans votre définition de concept, car elles sont automatiquement incluses lors de l'extension de geo:location.
• Consultez la définition de state dans l'ensemble de données du tutoriel pour obtenir un exemple.

Recettes et unités de mesure

Utilisation des pourcentages

Objectif

Définissez un concept (métrique) qui correspond à un pourcentage.

Étapes

1. Élargissez votre concept à quantity:ratio.
2. Définissez l'attribut is_percentage sur true.

   <attribute id="is_percentage">
     <value>true</value>
   </attribute>
   

3. Vous pouvez également définir l'attribut percentage_of en fonction du pourcentage de ce concept. Exemple :

   <attribute id="percentage_of">
     <value>labor force</value>
   </attribute>
   

currency unités utilisées

Objectif

Définissez un concept (métrique) avec des unités monétaires (par exemple, dollars américains).

Étapes

1. Faites en sorte que votre métrique étende quantity:quantity ou l'un de ses enfants, par exemple quantity:amount.
2. Ajoutez un attribut unit qui fait référence à unit:currency et définissez sa valeur sur un ID issu du tableau de définition des devises associé. Exemple :

   <concept id="...">
     <attribute concept="unit:currency">
       <value>EUR</value>
     </attribute>
   </concept>
   

Créer une unité personnalisée

Objectif

Créez une unité personnalisée pour une ou plusieurs métriques.

Étapes

1. Créez un concept qui étend unit:unit.
2. Ajoutez les colonnes unit_text et symbol au tableau de définition associé. Si vous souhaitez ajuster la position des symboles, vous pouvez également ajouter une colonne symbol_position.
3. Renseignez les valeurs de ces dernières propriétés pour chaque instance de votre unité. Exemple de fichier CSV pour des unités "area" :

   my_unit,unit_text,symbol,symbol_position
   SQKM,square kilometers,km²,END
   SQML,square miles,miles²,END
   

4. Pour utiliser votre unité nouvellement créée dans un concept (métrique), assurez-vous que cette dernière étend quantity:quantity ou l'un de ses enfants. Ajoutez ensuite un attribut faisant référence à votre concept d'unité. Exemple :

   <concept id="..." extends="quantity:amount">
     ...
     <attribute concept="my_unit">
       <value>SQKM</value>
     </attribute>
     ...
   </concept>
   

Remarques

• Si votre concept d'unité ne comporte qu'une seule instance, vous pouvez omettre la colonne d'ID dans sa table de définition, ainsi que les balises value dans les métriques qui l'utilisent.
• Consultez la définition du concept de devise canonique pour obtenir un exemple complet.