DSPL Gen ist ein Befehlszeilenprogramm, mit dem eine CSV-Datentabelle in ein einfaches DSPL-Dataset konvertiert werden kann. Das Tool parst die Eingabedatei, erstellt alle erforderlichen Datentabellen und erstellt eine DSPL-XML-Datei. Das Ergebnis ist eine fast vollständige Dataset-"Vorlage", die vor dem Hochladen und Visualisieren nur geringfügig optimiert werden muss.
Bei DSPL Gen geht es grundsätzlich darum, dass jede Spalte in der CSV-Eingabedatei einem einzelnen DSPL-Konzept entspricht und jede Zeile eine einzelne Beobachtung für eine Kombination von Dimensionen darstellt. Das Tool iteriert durch die Spalten, ermittelt die entsprechenden Metadaten für jede Spalte / jedes Konzept (z. B. ID, Typ, ob es sich um eine Dimension oder einen Messwert handelt) und generiert dann alle erforderlichen Konzeptdefinitionen und Segmenttabellen.
DSPL-Gen ausführen
Syntax
Hinweis: Bei dieser Anleitung wird davon ausgegangen, dass Sie die Installationsanleitung bereits auf der Seite mit den DSPL-Tools befolgt haben.
Geben Sie zum Ausführen von DSPL Gen (Terminal / Eingabeaufforderung) auf Ihrem System Folgendes ein:
python dsplgen.py -o [output path] [path to CSV file]
Dabei werden die in Klammern gesetzten Begriffe so ersetzt:
[output path]: Pfad zu dem Verzeichnis, in dem Ihre Ausgabedateien gespeichert werden sollen. Dieses Verzeichnis muss bereits in Ihrem Dateisystem vorhanden sein.[path to CSV file]: Pfad zur CSV-Eingabedatei. Weitere Informationen zum Formatieren dieser Datei finden Sie im Abschnitt unten.
Die Komponente -o [output path] ist optional. Wenn nichts angegeben ist, werden die Ausgabedateien im aktuellen Verzeichnis abgelegt.
Das Tool wird anschließend ausgeführt, iteriert durch Ihre CSV-Datei, extrahiert Konzeptdefinitionen und generiert Segmentsegmente. Sofern keine Fehler gefunden werden, werden eine XML-Datei und eine oder mehrere CSV-Dateien in das Ausgabeverzeichnis geschrieben.
Öffnen Sie dann die XML-Datei in einem Texteditor Ihrer Wahl und nehmen Sie die gewünschten Änderungen vor. Sie sollten mindestens die Namen, Beschreibungen und anderen Werte eingeben, die vom Tool mit der Notation ** INSERT ... ** markiert wurden.
Einfaches Beispiel
Angenommen, wir haben eine CSV-Datei, die die Gesamtzahl der Fälle einer Krankheit enthält, aufgeschlüsselt nach Monat, Land und Altersgruppe. Gehen wir der Einfachheit halber davon aus, dass es für jede Dimension zwei Werte gibt:
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
Wenn Sie das Tool für die obige Eingabe ausführen, erhalten Sie 4 Dateien:
dataset.xml: die DSPL-XML-Vorlagecountry_table.csv: Werte des Konzeptscountryage_group_table.csv: Werte des Konzeptsage_groupslice_0_table.csv: Tabelle für Dataset-Slice (identisch mit Eingabetabelle, mit Ausnahme der Sortierung)
In diesem speziellen Fall kann das Tool alle Spaltentypen und -formate korrekt erraten. Jetzt müssen Sie nur noch die XML-Datei aufrufen und die verschiedenen Namen, Beschreibungen und URLs in den Metadaten des Datasets bearbeiten.
Eingabe-CSV mit Anmerkungen versehen
Grundlegende Optionen
In vielen Fällen, wie im Beispiel oben, kann DSPL Gen die grundlegenden Metadaten für jede Spalte erraten, z.B. den Typ, das Format und ob es sich um eine Dimension oder einen Messwert handelt. In anderen Fällen kann das Tool diese möglicherweise nicht erraten, sie können nicht richtig raten oder richtig raten, aber dennoch nicht dem gewünschten Verhalten folgen.
Für diese Fälle unterstützt das Tool in der CSV-Header-Zeile das Hinzufügen von DSPL-Generierungsoptionen/Hinweisen. Die Syntax dafür lautet so:
column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...
Beachten Sie insbesondere, dass die Liste der Optionen in Klammern rechts neben dem Spaltennamen platziert wird und die Einstellungen für die nachfolgenden Optionen durch Semikolons getrennt sind. Jede Option besteht aus einem Optionsnamen, einem Gleichheitszeichen und einem Optionswert.
DSPL Gen unterstützt derzeit die folgenden grundlegenden Optionen:
| Option | Beschreibung | Standard |
|---|---|---|
type |
Der DSPL-Datentyp für diese Spalte; muss date, float, integer oder string sein. |
Vermutlich anhand von Daten |
format |
Das Format dieser Datumsspalte. Wie in DSPL sollte dieses Format mit dem Joda DateTime-Standard codiert werden. | Vermutlich anhand von Daten |
slice_role |
Die Rolle dieser Spalte in beliebigen Segmenten. Muss entweder dimension oder metric sein. |
dimension, wenn die Spalte vom Typ date oder string ist, sonst metric |
concept |
Das kanonische Konzept, das diese Spalte darstellt, z. B. geo:country. Wenn dieses Attribut angegeben ist, wird das Konzept importiert und in der XML-Datei keine Definition generiert. |
– |
extends |
Das kanonische Konzept, das diese Spalte erweitert, z.B. entity:entity. |
– |
parent |
Das übergeordnete Konzept für diese Spalte. Dieses übergeordnete Element muss ein Dimensionskonzept sein, das im Dataset definiert ist (d. h. nicht importiert). Anhand dieser Informationen wird eine Konzepthierarchie im Dataset definiert. Beachten Sie, dass jede untergeordnete Instanz nur eine übergeordnete Instanz haben kann. Wenn mehrere übergeordnete Werte erkannt werden, gibt das Tool einen Fehler aus. |
– |
Sammel-Properties
Zusätzlich zu den oben beschriebenen grundlegenden Hinweisoptionen unterstützt DSPL Gen. auch Rollup-Ansichten: Bei einer einzelnen Tabelleneingabe kann das Tool automatisch zusätzliche Tabellen mit einer begrenzten Teilmenge der Dimensionen erstellen. Wenn die Eingabetabelle beispielsweise einem Segment mit drei Dimensionen ohne Zeitangabe entspricht (z.B. dimension1, dimension2 und dimensions3) erstellt das Tool auch zusätzliche Segmente: nur dimension1, nur dimension2, nur dimension1 und
dimension2 usw.
Wenn Sie diese zusätzlichen Segmente hinzufügen, können Sie das Dataset leichter untersuchen, da es die Anzahl der Dimensionsfilter reduziert, die zum Erstellen von Visualisierungen erforderlich sind. Andererseits können bei diesem Vorgang auch „neue“ Daten entstehen, die nicht in der Originaldatei gefunden werden. Daher können auch Fehler auftreten, wenn sie nicht ordnungsgemäß verwendet werden. Prüfen Sie die zusammengefassten Zahlen vor der Veröffentlichung des Datasets.
Der Rollup-Vorgang wird durch Hinzufügen einiger zusätzlicher Optionen zum CSV-Header der Eingabe ausgelöst:
| Option | Beschreibung | Standard |
|---|---|---|
aggregation |
Die Aggregationsmethode, die verwendet werden soll, wenn mehrere Werte dieser Spalte kombiniert werden. Sie muss entweder AVG, COUNT, MAX, MIN oder SUM sein. Nur für Messwerte sinnvoll. |
SUM |
rollup |
Wenn der Wert true ist, ist das Konzept für diese Spalte „zusammengefasst“ (d.h. aggregiert), also nur für Konzepte der Dimension sinnvoll. |
Falsch |
total_val |
Der Wert in dieser Spalte gibt an, welche Zeilen bei einem Rollup der Spalte beibehalten werden sollen. Dies ist nur für Konzepte der Dimension sinnvoll. | None |
DSPL Gen berechnet die Rollups dann mit dem folgenden Algorithmus:
- Berechnen Sie anhand der Werte der
rollup-Tags alle möglichen Spaltenkombinationen - Für jede Kombination:
- Wenn bei Sammel-Spalten ein
total_val-Parameter festgelegt ist, filtern Sie die Zeilen nach diesem Wert oder wählen Sie alle Zeilen aus - Sammel-Spalten löschen
- Zeilen nach den Werten der verbleibenden Dimensionsspalten gruppieren
- Aggregieren Sie jeden Messwert mit der im Parameter
aggregationangegebenen Methode. - Segment und verknüpfte Tabelle für das Ergebnis erstellen
- Wenn bei Sammel-Spalten ein
Wenn es in jeder Gruppierung nur einen einzigen Wert gibt und die Aggregationsfunktion auf SUM (den Standardwert) festgelegt ist, bleiben die Messwerte in der Quell- und den generierten Tabellen gleich, d.h., es werden keine neuen Werte generiert. Wenn Sie den Parameter total_val verwenden und dafür sorgen, dass es nur eine „Gesamt“-Zeile für jede Kombination der anderen Dimensionen gibt, können Sie vorab berechnete Aggregationen direkt in der Quelle speichern.
Warnung: Die Anzahl der generierten Segmente entspricht 2 Rollup-Spalten. Das Anwenden dieser Option auf eine große Anzahl von Spalten kann zu sehr langen Laufzeiten und/oder großen Datasets führen.
Erweitertes Beispiel
Nehmen wir an, dass wir dieselben Eingabedaten wie im vorherigen Beispiel haben, jetzt jedoch für alle Länder aggregiert wurden:
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
Die Summe der einzelnen Altersgruppen entspricht möglicherweise nicht der Summe der Länderwerte, beispielsweise aufgrund unterschiedlicher Methoden oder der Existenz anderer Länder, die nicht in der Liste aufgeführt sind.
Wir möchten jetzt ein DSPL-Dataset mit den folgenden zusätzlichen Funktionen erstellen:
- So können wir die Gesamtzahl der Erkrankungen allein nach Altersgruppe aufschlüsseln
- Verwende das kanonische
geo:country-Konzept für die Spaltecountry, damit wir für diese automatisch die vollständigen Namen, Standorte usw. abrufen können - Erweitern Sie
quantity:amountdurch das Konzeptdisease_cases, damit wir Einheiteninformationen (manuell) in die XML-Datei einfügen können.
Dazu ändern wir die Kopfzeile der CSV-Eingabedatei so:
date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]
Wenn Sie das Tool noch einmal ausführen, erhalten Sie eine zusätzliche Segmenttabelle, in der die Unterscheidung nach Land nicht mehr enthalten ist:
date,age_group,disease_cases 01/2000,old,152012 02/2000,old,211310 01/2000,young,241011 02/2000,young,240131
Ohne die Gesamtwerte und das Tag total_val in der Quelltabelle hätte die berechnete Summe für jede Altersgruppe berechnet.
Außerdem umfasst die Definition von disease_cases in der XML-Datei jetzt wie gewünscht die Erweiterung von quantity:amount. Die Definition von country wird aus der XML-Datei entfernt, da wir stattdessen ein importiertes Konzept verwenden.
Nachdem Sie die verschiedenen Namen, Beschreibungen und Einheiteninformationen eingegeben haben, können wir das Dataset-Bundle komprimieren und zur Visualisierung in den Public Data Explorer hochladen.