DSPL-Cookbook

Dieses Dokument enthält ein Kochbuch mit nützlichen DSPL- und kanonischen „Rezepten“-Konzepten. Sie enthalten Schritt-für-Schritt-Anleitungen für eine Vielzahl von Aufgaben, die über die in der Anleitung und dem Entwicklerhandbuch beschriebenen grundlegenden Sprachfunktionen hinausgehen. Im folgenden Inhalt wird davon ausgegangen, dass Sie mit den vorherigen Dokumenten vertraut sind. Lesen Sie sich diese daher sorgfältig durch, bevor Sie mit dem Kochen beginnen.

Jedes Schema beginnt mit einem Ziel, gefolgt von einer bestimmten Liste von Schritten. Viele enthalten auch DSPL-Snippets oder Links zu externen Beispielen. Wenn Sie Feedback zu einem Rezept haben oder andere Vorschläge machen möchten, können Sie im DSPL-Forum eine Nachricht posten.

Grundlegende Rezepte

Anzeigenamen angeben

Ziel

Verknüpfen Sie einen „Anzeigenamen“ mit jeder Instanz eines Konzepts (Dimension). Diese Namen werden in der Benutzeroberfläche von Public Data Explorer anstelle der Konzept-Instanz-IDs angezeigt, die für Nutzer in der Regel kürzer und schwerer verständlich sind.

Schritte

1. Konzept erweitern entity:entity.
2. Fügen Sie der zugehörigen Konzeptdefinitionstabelle eine name-Spalte hinzu.
3. Geben Sie in die letzte Eigenschaft die Namen der Instanzen ein.

Hinweise

• Es ist nicht erforderlich, in den Konzeptmetadaten explizit eine name-Property zu definieren. Diese Definition ist automatisch eingeschlossen, wenn Sie entity:entity erweitern.
• Sie können auch die Spalten description und info_url hinzufügen, um Beschreibungen bzw. URLs auf Instanzebene anzugeben.

Konzepthierarchien erstellen

Ziel

Erstellen Sie eine Hierarchie von (Dimensions-)konzepten. Diese werden in der Benutzeroberfläche von Public Data Explorer als Baumstruktur angezeigt, sodass Nutzer die Gruppierungen verstehen und zwischen ihnen wechseln können.

Schritte

1. Legen Sie ein übergeordnetes Konzept fest (z.B. region).
2. Legen Sie ein untergeordnetes Konzept fest (z.B. subregion).
3. Füge dem untergeordneten Element ein Attribut hinzu, das auf das übergeordnete Element verweist und das Attribut isParent enthält:

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

   , wobei die Punkte durch die übergeordnete ID ersetzt werden.
4. Fügen Sie in der Definitionstabelle für das untergeordnete Element eine Spalte ein, die auf das übergeordnete Element verweist.
5. Tragen Sie in jede untergeordnete Instanz eine gültige Instanz des übergeordneten Konzepts ein.

Hinweise

• Ein Beispiel hierfür finden Sie unter der Beziehung country / state im Dataset der Anleitung.
• Jede übergeordnete ID, auf die in der untergeordneten Datei verwiesen wird, muss in der Definitionstabelle der übergeordneten Datei enthalten sein. Andernfalls gibt der Importeur einen Fehler aus.
• Das übergeordnete und das untergeordnete Element können dasselbe Konzept sein (also eine Selbstverweis-Hierarchie). Ein Beispiel hierfür finden Sie im Konzept business im US-Verkaufsvertrieb-Dataset.

Konzeptinstanzen kategorisieren

Ziel

Erstellen Sie Kategorien für Konzeptinstanzen, die in der Farbauswahl von Public Data Explorer als Optionen angezeigt werden.

Schritte

1. Legen Sie ein Konzept für die Kategorie fest, z.B. income_level).
2. Legen Sie ein untergeordnetes Konzept fest (z.B. country).
3. Füge im untergeordneten Element eine Property hinzu, die auf das Kategoriekonzept verweist und ein name-Element enthält:

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

   wobei der erste Satz von Punkten durch die Kategoriekonzept-ID und der zweite Satz durch den gewünschten Anzeigenamen deiner Property ersetzt wird (z.B. „Einkommensebene“).
4. Fügen Sie in der Definitionstabelle für das untergeordnete Element eine Spalte ein, die auf das Kategoriekonzept verweist.
5. Tragen Sie in jede untergeordnete Instanz eine gültige Instanz des Kategoriekonzepts ein.

Hinweise

• Ein Konzept kann mehrere Attribute haben, die als Kategorien dienen. In diesem Fall werden dem Nutzer alle Optionen als Optionen in der Farbauswahl angezeigt.
• Eine der Kategorien kann auch übergeordnete Elemente sein, um die Instanzen hierarchisch zu organisieren. Weitere Informationen finden Sie im vorherigen Schema.

Sortierreihenfolge für Konzeptinstanzen festlegen

Ziel

Geben Sie die Sortierreihenfolge für Instanzen eines Konzepts an. Diese Reihenfolge wird verwendet, wenn die Instanzen im linken Navigationsbereich der Visualisierungsseiten von Public Data Explorer aufgelistet werden.

Schritte

1. Erweitern Sie Ihr Konzept auf entity:entity oder eines seiner untergeordneten Elemente (z.B. geo:location).
2. Fügen Sie Ihren Konzeptmetadaten ein entity_order-Attribut hinzu.
3. Legen Sie den vorherigen Wert auf ALPHA oder TABLE fest. Ersteres bewirkt, dass die Instanzen in der Reihenfolge ihrer Anzeigenamen aufgelistet werden. Letzteres sorgt dafür, dass die Instanzen in derselben Reihenfolge wie in der Konzeptdefinitionstabelle aufgeführt werden.

Hinweise

• ALPHA ist die aktuelle Standardeinstellung. Wenn Sie diese Reihenfolge verwenden möchten, sind die oben genannten Schritte optional.
• Ein Beispiel findest du in der Dokumentation zu entity:entity.

Zeitrezepte

Vierteljährliche Daten

Ziel

Visualisieren Sie Daten, die in vierteljährlichen Intervallen angegeben werden.

Schritte

1. Wandeln Sie alle Quartalsdaten in Ihre Segmentdaten in Monate um (z.B. den ersten Monat des Quartals).
2. Behandeln Sie diese Dimension als time:month im Segment-XML.

Wöchentliche Daten

Ziel

Visualisieren Sie Daten, die in wöchentlichen Intervallen angegeben werden.

Schritte

1. Wandeln Sie alle Wochendaten in Ihren Segmentdaten in Tage um (z.B. den ersten Wochentag).
2. Behandeln Sie diese Dimension als time:day im Segment-XML.

Geo-Rezepte

Kanonische Konzepte country oder state verwenden

Ziel

Verwenden Sie die kanonischen country- oder state-Konzepte, indem Sie alle Breiten-/Längengradwerte usw. importieren, sodass diese nicht im Dataset definiert werden müssen.

Schritte

1. Achten Sie darauf, dass alle Verweise auf Länder und/oder US-Bundesstaaten in den CSV-Datendateien gültige Kennungen aus den Definitionstabellen der kanonischen Länder und Bundesstaaten sind.
2. Füge geo:country und/oder geo_us:state als Dimensionen in die entsprechenden Segmente hinzu.
3. Die Spaltennamen müssen mit den Namen der vorherigen Konzepte übereinstimmen (ohne den Namen des importierten Datasets, z.B. country) oder, falls nicht, mapDimension-Anweisungen in die Segmentdefinition aufnehmen. Beispiel:

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

Nur einen Teil der kanonischen Länder oder Bundesstaaten verwenden

Ziel

Verwenden Sie eine Teilmenge eines kanonischen geografischen Konzepts, damit nur diese Teilmenge (und nicht die gesamte Liste, z.B. alle Länder der Welt) in der UI von Public Data Explorer angezeigt wird.

Schritte

1. Definieren Sie ein lokales Konzept, das das übergeordnete Konzept erweitert. Beispiel:

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

2. Fügen Sie in die zugehörige CSV-Datei für die Konzeptdefinition nur die IDs des übergeordneten Konzepts ein, das Sie verwenden möchten. Beispiel:

   my_country_subset
   FR  
   MX
   US
   

Hinweise

• Jede Instanz des Teilkonzepts muss eine gültige Instanz des Superset-Konzepts sein. Sie kann das Konzept nicht mit neuen Instanzen „erweitert“ werden.

Eigene geografische Konzepte definieren

Ziel

Erstellen Sie eigene geografische Konzepte, die genau wie die kanonischen, von Google definierten Konzepte erkundebar und zuordnungsfähig sind.

Schritte

1. Erstellen Sie ein Konzept, das geo:location erweitert.
2. Fügen Sie in die zugehörige Konzeptdefinitionstabelle die Spalten name, latitude und longitude ein.
3. Füllen Sie die letzten Attribute für jede Instanz Ihres Konzepts aus. Die Breiten- und Längengradwerte sind Gleitkommazahlen mit der Konvention, dass N und E positiv sind, und W und S sind negativ.

Hinweise

• Du musst die Attribute name, latitude und longitude nicht explizit in deine Konzeptdefinition aufnehmen, da diese beim Erweitern von geo:location automatisch eingeschlossen werden.
• Ein Beispiel finden Sie in der Definition von state im Dataset der Anleitung.

Messwerte und Einheitenrezepte

Prozentangaben verwenden

Ziel

Definieren Sie ein (metrisches) Konzept, das ein Prozentsatz von etwas anderem ist.

Schritte

1. Erweitern Sie Ihr Konzept um quantity:ratio.
2. Legen Sie das Attribut is_percentage auf true fest.

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

3. Legen Sie optional das Attribut percentage_of anhand des Prozentsatzes für dieses Konzept fest. Beispiel:

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

currency Einheiten verwenden

Ziel

Definieren Sie ein (metrisches) Konzept mit Währungseinheiten (z.B. US-Dollar).

Schritte

1. Erweitern Sie den Messwert um quantity:quantity oder eines seiner untergeordneten Elemente, z.B. quantity:amount.
2. Fügen Sie ein unit-Attribut hinzu, das auf unit:currency verweist, und legen Sie den Wert dafür auf eine ID aus der verknüpften Währungsdefinitionstabelle fest. Beispiel:

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

Benutzerdefinierte Einheit erstellen

Ziel

Erstellen Sie eine benutzerdefinierte Einheit für einen oder mehrere Ihrer Messwerte.

Schritte

1. Erstellen Sie ein Konzept, das unit:unit erweitert.
2. Fügen Sie der zugehörigen Definitionstabelle die Spalten unit_text und symbol hinzu. Wenn Sie die Symbolposition anpassen möchten, können Sie auch eine symbol_position-Spalte hinzufügen.
3. Geben Sie für jede Instanz Ihrer Einheit die Werte für letztere Attribute an. CSV-Beispieldatei für „area“-Einheiten:

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

4. Damit Sie die neu erstellte Einheit in einem (metrischen) Konzept verwenden können, muss Letzteres quantity:quantity oder eines seiner untergeordneten Elemente erweitern. Fügen Sie dann ein Attribut hinzu, das auf Ihr Einheitenkonzept verweist. Beispiel:

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

Hinweise

• Wenn das Einheitenkonzept nur eine einzige Instanz hat, können Sie die ID-Spalte aus der Definitionstabelle und den value-Tags in den Messwerten, die sie verwenden, weglassen.
• Ein vollständiges Beispiel finden Sie in der Definition des Konzepts der kanonischen Währung.