DSPL Gen è un'utilità a riga di comando che aiuta a convertire una tabella di dati CSV in un semplice set di dati DSPL. Lo strumento analizza il file di input, crea tutte le tabelle di dati necessarie e dispone un file XML DSPL. Il risultato è un "modello" di set di dati quasi completo che richiede solo un perfezionamento minimo prima di caricare e visualizzare.
Il presupposto fondamentale alla base di DSPL Gen è che ogni colonna nel file CSV di input corrisponde a un singolo concetto DSPL e ogni riga è una singola osservazione per una combinazione di dimensioni. Lo strumento esegue l'iterazione tra le colonne, stabilendo i metadati appropriati per ogni colonna / concetto (ad es. l'ID, il tipo, se si tratta di una dimensione o una metrica e così via), quindi generando tutte le definizioni di concetto necessarie e le tabelle di suddivisione.
Esecuzione di DSPL Gen
Sintassi
Nota: queste istruzioni presuppongono che tu abbia già seguito le istruzioni di installazione fornite nella pagina degli strumenti DSPL.
Per eseguire DSPL Gen, vai al terminale / al prompt sul tuo sistema e digita:
python dsplgen.py -o [output path] [path to CSV file]
dove i termini tra parentesi sono sostituiti come segue:
[output path]: percorso alla directory in cui vuoi inserire i file di output; questa directory deve già esistere nel file system.[path to CSV file]: percorso al file CSV di input. Per saperne di più su come formattare questo file, consulta la sezione di seguito.
Il componente -o [output path] è facoltativo; se omesso, i file di output verranno inseriti nella directory attuale.
Lo strumento esegue quindi l'iterazione tramite il file CSV, estraendo le definizioni dei concetti e generando tabelle di controllo. A meno che non vengano trovati errori, un file XML e uno o più file CSV vengono scritti nella directory di output.
Infine, apri il file XML nell'editor di testo che preferisci e apporta le modifiche. Come minimo, devi inserire i nomi, le descrizioni e gli altri valori che sono stati contrassegnati dallo strumento con la notazione ** INSERT ... **.
Esempio semplice
Supponiamo di avere un file CSV che fornisce il numero totale di casi di una malattia suddivisi per mese, paese ed età. Per semplicità, supponiamo che ci siano due valori per ogni dimensione:
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
Se esegui lo strumento sull'input precedente, vengono generati quattro file:
dataset.xml: modello XML di DSPLcountry_table.csv: valori del concettocountryage_group_table.csv: valori del concettoage_groupslice_0_table.csv: tabella per la sezione del set di dati (identica alla tabella di input, tranne per l'ordinamento)
In questo caso particolare, lo strumento è in grado di indovinare correttamente tutti i tipi e le colonne di colonne. A questo punto, non ti resta che accedere al file XML e modificare i vari nomi, descrizioni e URL nei metadati del set di dati.
Annotazione del file CSV di input
Opzioni di base
In molti casi, come nell'esempio sopra, la generazione DSPL può indovinare i metadati di base per ogni colonna, ad esempio il tipo, il formato e se si tratta di una dimensione o una metrica. In altri casi, tuttavia, lo strumento potrebbe non essere in grado di indovinare questi errori, indovinare in modo errato o indovinare, ma comunque, non seguire il comportamento desiderato.
Per gestire questi casi, lo strumento supporta l'aggiunta di opzioni di generazione/"suggerimenti" di DSPL nella riga di intestazione CSV. La sintassi è la seguente:
column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...
In particolare, tieni presente che l'elenco delle opzioni è posizionato tra parentesi quadre a destra del nome della colonna e le successive impostazioni delle opzioni sono separate da punti e virgola. Ogni opzione è composta dal nome di un'opzione, da un segno di uguale e da un valore.
Al momento, la generazione DSPL supporta le seguenti opzioni di base:
| Opzione | Descrizione | Predefinito |
|---|---|---|
type |
Il tipo di dati DSPL per questa colonna; deve essere uno tra date,
float, integer o string. |
Indovina dai dati |
format |
Il formato di questa colonna della data; come in DSPL, questo formato deve essere codificato utilizzando lo standard Joda DateTime. | Indovina dai dati |
slice_role |
Il ruolo di questa colonna è in tutte le sezioni; deve essere dimension o metric. |
dimension se la colonna è di tipo date o string, altrimenti metric |
concept |
Il concetto canonico rappresentato da questa colonna, ad esempio geo:country; se fornito, il concetto viene importato e non viene prodotta alcuna definizione nel file XML. |
Nessuno |
extends |
Il concetto canonico che estende questa colonna, ad esempio
entity:entity. |
Nessuno |
parent |
Il concetto padre per questa colonna. Questo elemento padre deve essere un concetto di dimensione definito all'interno del set di dati (ovvero non importato); se specificato, queste informazioni verranno utilizzate per definire una gerarchia gerarchica nel set di dati. Tieni presente che ogni istanza secondaria può avere un solo elemento padre. Se vengono rilevati più valori padre, lo strumento genererà un errore. |
Nessuno |
Aggregazioni di valori
Oltre alle opzioni "suggerimento" di base descritte sopra, la generazione DSPL supporta anche i roll-up dei segmenti: con un singolo input di tabella, lo strumento può creare automaticamente tabelle aggiuntive con sottoinsiemi limitati di dimensioni. Ad esempio, se la tabella di input corrisponde a una sezione con tre dimensioni non temporali (ad es. dimension1, dimension2 e dimensions3), lo strumento può creare anche altre sezioni: solo dimension1, solo dimension2, solo dimension1 e
dimension2 e così via.
L'aggiunta di queste sezioni aggiuntive può semplificare l'esplorazione del set di dati, in quanto riduce il numero di filtri di dimensione necessari per produrre visualizzazioni. D'altra parte, questo processo potrebbe introdurre dati "nuovi" non trovati nel file originale, quindi potrebbe anche introdurre errori se non utilizzati correttamente; controlla attentamente i numeri raggruppati prima di pubblicare il set di dati.
Il processo di aggregazione viene attivato includendo alcune opzioni aggiuntive nell'intestazione CSV di input:
| Opzione | Descrizione | Predefinito |
|---|---|---|
aggregation |
Il metodo di aggregazione da utilizzare quando si combinano più valori di questa colonna; deve essere uno tra AVG, COUNT, MAX, MIN o SUM; significativo solo per le metriche. |
SUM |
rollup |
Se il valore è true, il concetto di questa colonna viene "aggregato" (ossia aggregato; fuori) e significativo solo per i concetti di dimensione. |
False |
total_val |
Il valore in questa colonna che indica le righe da mantenere quando questa viene aggregata; significativo solo per i concetti di dimensione. | None |
La generazione DSPL calcola le proprietà di aggregazione utilizzando il seguente algoritmo:
- Utilizzando i valori dei tag
rollup, calcola tutte le possibili combinazioni di colonne - Per ogni combinazione:
- Se le colonne roll-up hanno un parametro
total_valimpostato, filtra le righe in base a questo valore; in caso contrario, seleziona tutte le righe - Trascina le colonne aggregate
- Raggruppa le righe in base ai valori delle colonne di dimensione rimanenti
- Aggrega ogni metrica utilizzando il metodo specificato nel relativo parametro
aggregation - Crea una sezione e una tabella associata per il risultato
- Se le colonne roll-up hanno un parametro
Tieni presente che se c'è un solo valore in ogni raggruppamento e la funzione di aggregazione è impostata su SUM (valore predefinito), i valori delle metriche nelle tabelle di origine e generate rimarranno invariati, ovvero non verranno generati nuovi valori. Pertanto, utilizzando il parametro total_val e assicurandoti che ci sia una sola riga "totale" per ogni combinazione delle altre dimensioni, puoi archiviare gli aggregati precalcolati direttamente nell'origine.
Avviso: il numero di sezioni generate è uguale a 2 colonne aggregate. L'applicazione di questa opzione a un numero elevato di colonne può comportare tempi di esecuzione molto lunghi e/o set di dati di grandi dimensioni.
Esempio avanzato
Supponiamo di avere gli stessi dati di input dell'esempio precedente, ma ora di aggregare i dati di tutti i paesi:
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
Il totale per ciascuna fascia d'età potrebbe non corrispondere alla somma dei valori dei paesi perché, ad esempio, delle differenze di metodologia o dell'esistenza di altri paesi non enumerati nell'elenco.
Ora vogliamo creare un set di dati DSPL con le seguenti funzionalità aggiuntive:
- "Aggrega" i paesi in modo da ottenere il numero totale di casi di malattia in base all'età
- Utilizza il concetto canonico
geo:countryper la colonnacountry, in modo da ottenere automaticamente nomi completi, località e così via - Il concetto
disease_casesestendequantity:amount, in modo da poter aggiungere (manualmente) le informazioni sull'unità nel file XML
A questo scopo, modifichiamo la riga di intestazione del file CSV di input nel seguente modo:
date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]
Eseguendo di nuovo lo strumento, otteniamo una tabella aggiuntiva, che elimina la distinzione per paese:
date,age_group,disease_cases 01/2000,old,152012 02/2000,old,211310 01/2000,young,241011 02/2000,young,240131
Se non avessimo incluso i valori totali e il tag total_val nella tabella di origine, otterremmo la somma calcolata per ogni fascia d'età.
Inoltre, la definizione di disease_cases nel file XML ora include l'estensione di quantity:amount, come desiderato. La
definizione di country è stata eliminata dal file XML perché
stiamo utilizzando un concetto importato in questo caso.
Dopo aver inserito i nomi, le descrizioni e le informazioni sulle unità, possiamo comprimere il set di dati e caricarlo in Public Data Explorer per la visualizzazione.