Libro di ricette di DSPL

Questo documento contiene un libro di ricette con DSPL e il concetto canonico "ricette" utili. Questi forniscono indicazioni dettagliate per una serie di attività che vanno oltre le funzionalità di base delle lingue descritte nel Tutorial e nella Guida per gli sviluppatori. I contenuti riportati di seguito presuppongono la conoscenza dei documenti precedenti, pertanto assicurati di leggerli prima di iniziare la "cucina".

Ogni ricetta inizia con un obiettivo seguito da un elenco specifico di passaggi da seguire. Molti includono anche snippet DSPL o link a esempi esterni. Per eventuali feedback su una ricetta o per suggerire altri utenti, pubblicate un messaggio nel forum di DSPL.

Ricette di base

Specificare i nomi visualizzati

Obiettivo

Associa un "nome visualizzato" a ogni istanza di un concetto (dimensione). Questi nomi vengono visualizzati nell'interfaccia utente di Public Data Explorer al posto degli ID delle istanze di concetto, che in genere sono più brevi e difficili da comprendere per gli utenti.

Passi

  1. Estendi il tuo concetto entity:entity.
  2. Aggiungi una colonna name alla tabella di definizione del concetto associata.
  3. Completa la seconda proprietà con il nome di ciascuna istanza.

Note

  • Non è necessario definire esplicitamente una proprietà name nei metadati del concetto; questa definizione viene inclusa automaticamente quando estendi entity:entity.
  • Puoi anche aggiungere colonne description e info_url per fornire rispettivamente descrizioni e URL a livello di istanza.

Creazione di gerarchie concettuali

Obiettivo

Crea una gerarchia di concetti (dimensione). Questi verranno visualizzati nell'interfaccia utente di Public Data Explorer come albero, consentendo agli utenti di comprendere i raggruppamenti e di spostarsi da uno all'altro.

Passi

  1. Definisci un concetto di "genitore" (ad es. region).
  2. Definisci un concetto di "secondario" (ad es. subregion).
  3. Aggiungi una proprietà nell'elemento secondario che fa riferimento all'elemento principale e include l'attributo isParent: 
    <property concept="..." isParent="true"/>
    dove i punti vengono sostituiti dall'ID principale.
  4. Nella tabella di definizione del publisher secondario, aggiungi una colonna che faccia riferimento alla risorsa principale.
  5. Per ogni istanza secondaria, compila quest'ultima con un'istanza valida del concetto padre.

Note

  • Per un esempio, consulta la relazione country/state nel set di dati del tutorial.
  • Ogni ID principale a cui si fa riferimento nell'elemento secondario deve trovarsi nella tabella di definizione dell'elemento principale. In caso contrario, l'importatore genererà un errore.
  • L'elemento principale e l'elemento secondario possono essere lo stesso concetto (ossia una gerarchia di auto-referral). Per un esempio, consulta il concetto di business nel Set di dati per la vendita al dettaglio negli Stati Uniti.

Classificazione delle istanze di concetto

Obiettivo

Crea categorie per le istanze di concetto che verranno visualizzate come opzioni nei selettori di colori di Public Data Explorer.

Passi

  1. Definisci un concetto di "categoria" (ad es. income_level).
  2. Definisci un concetto di "secondario" (ad es. country).
  3. Aggiungi una proprietà nell'elemento secondario che fa riferimento al concetto di categoria e include un elemento name: 
    <property concept="..."/>
  <info>
    <name><value>"..."</value></name>
  </info>
</property>
    dove il primo insieme di punti viene sostituito dall'ID concetto della categoria e il secondo viene sostituito dal nome visualizzato desiderato per la proprietà (ad es. "Livello di reddito").
  4. Nella tabella di definizione del publisher secondario, aggiungi una colonna che faccia riferimento al concetto di categoria.
  5. Per ogni istanza secondaria, compila quest'ultima con un'istanza valida del concetto di categoria.

Note

  • Un concetto può avere più proprietà che fungono da categorie; in questo caso, l'utente le vedrà tutte come opzioni nei selettori dei colori.
  • Una delle categorie può anche essere una risorsa padre ai fini dell'organizzazione gerarchica delle istanze nella UI. Per i dettagli, consulta la ricetta precedente.

Specificare l'ordinamento per le istanze concetto

Obiettivo

Specifica l'ordinamento per le istanze di un concetto. Questo ordine viene utilizzato quando si elencano le istanze nel menu di navigazione sinistro delle pagine di visualizzazione di Public Data Explorer.

Passi

  1. Fai in modo che il concetto si estende a entity:entity o a uno dei suoi elementi secondari (ad es. geo:location).
  2. Aggiungi un attributo entity_order ai metadati del concetto.
  3. Imposta il valore della precedente su uno di ALPHA o TABLE; la prima farà sì che le istanze siano elencate nell'ordine dei nomi visualizzati, mentre la seconda manterrà le istanze nello stesso ordine in cui vengono visualizzate nella tabella di definizione del concetto.

Note

  • ALPHA è l'impostazione predefinita corrente, quindi se vuoi utilizzare questo ordine, i passaggi precedenti sono facoltativi.
  • Per un esempio, consulta la documentazione di entity:entity.

Ricette temporali

Dati trimestrali

Obiettivo

Visualizza i dati specificati a intervalli trimestrali.

Passi

  1. Converti tutti i trimestri nei dati delle sezioni in mesi (ad esempio il primo mese del trimestre).
  2. Tratta questa dimensione come un elemento time:month nel file XML della tua sezione.

Dati settimanali

Obiettivo

Visualizza i dati specificati a intervalli settimanali.

Passi

  1. Converti tutte le settimane nei dati delle sezioni in giorni (ad es. il primo giorno della settimana).
  2. Considera questa dimensione come un elemento time:day nel file XML della tua sezione.

Ricette geografiche

Utilizzo dei concetti canonici di country o state

Obiettivo

Utilizza i concetti di country o state canonici, importando tutti i valori lat/long e così via, in modo che non debbano essere definiti all'interno del set di dati.

Passi

  1. Assicurati che tutti i riferimenti a paesi e/o Stati degli Stati Uniti nei file CSV dei dati delle sezioni siano ID validi delle tabelle di definizione canoniche per paese e stato.
  2. Aggiungi geo:country e/o geo_us:state come dimensioni nelle sezioni corrispondenti.
  3. Assicurati che i nomi delle colonne per questi nomi corrispondano ai nomi dei concetti precedenti (escluso il nome del set di dati importato, ad esempio country) o, in caso contrario, includi le istruzioni mapDimension nella definizione della tua sezione. Esempio: 
    <slice id="...">
  ...
  <dimension concept="geo:country"/>
  ...
  <mapDimension concept="geo:country" toColumn="my_country"/>
</slice>

Utilizza solo un sottoinsieme dei paesi o degli stati canonici

Obiettivo

Utilizza un sottoinsieme di un concetto geografico canonico, in modo che solo questo sottoinsieme (e non l'intero elenco, ad esempio tutti i paesi del mondo) venga visualizzato nell'interfaccia utente di Public Data Explorer.

Passi

  1. Definisci un concetto locale che estenda il concetto di superset. Esempio: 
    <concept id="my_country_subset" extends="geo:country">
...
</concept>
  2. Nel file CSV di definizione dei concetti associato, includi solo gli ID del concetto di superset che vuoi utilizzare. Esempio: 
    my_country_subset
FR  
MX
US

Note

  • Ogni istanza del concetto di sottoinsieme deve essere un'istanza valida del concetto di superset; non puoi "espandere" il concetto con nuove istanze.

Definizione di concetti geografici specifici

Obiettivo

Crea i tuoi concetti geografici che possono essere esplorati e mappati, proprio come quelli canonici e definiti da Google.

Passi

  1. Crea un concetto che estende geo:location.
  2. Nella tabella di definizione del concetto associata, includi le colonne name, latitude e longitude.
  3. Completa queste ultime proprietà per ogni istanza del tuo concetto; i valori di latitudine e longitudine sono decimali con la convenzione che N ed E sono positivi e W e S sono negativi.

Note

  • Non è necessario includere esplicitamente le proprietà name, latitude e longitude nella definizione del concetto, poiché queste vengono incluse automaticamente quando estendi geo:location.
  • Per un esempio, consulta la definizione di state nel set di dati del tutorial.

Ricette di metriche e unità di misura

Utilizzo delle percentuali

Obiettivo

Definisci un concetto (metrico) che rappresenti una percentuale di qualcos'altro.

Passi

  1. Estendi il tuo concetto quantity:ratio.
  2. Imposta l'attributo is_percentage su true. 
    <attribute id="is_percentage">
  <value>true</value>
</attribute>
  3. (Facoltativo) Imposta l'attributo percentage_of in base a che il concetto rappresenta una percentuale. Esempio: 
    <attribute id="percentage_of">
  <value>labor force</value>
</attribute>

currency unità in uso

Obiettivo

Definisci un concetto (metrica) che abbia le unità di valuta (ad es. dollari statunitensi).

Passi

  1. Imposta la metrica in modo da estendere quantity:quantity o uno dei relativi elementi secondari, ad esempio quantity:amount.
  2. Aggiungi un attributo unit che faccia riferimento a unit:currency e imposta il valore di questo su un ID dalla tabella di definizione della valuta associata. Esempio: 
    <concept id="...">
  <attribute concept="unit:currency">
    <value>EUR</value>
  </attribute>
</concept>

Creare un'unità personalizzata

Obiettivo

Crea un'unità personalizzata per una o più metriche.

Passi

  1. Crea un concetto che estende unit:unit.
  2. Aggiungi le colonne unit_text e symbol alla tabella delle definizioni associata. Facoltativamente, se vuoi modificare la posizione del simbolo, puoi anche aggiungere una colonna symbol_position.
  3. Inserisci i valori per le ultime proprietà per ogni istanza della tua unità. Esempio di CSV per le unità "area": 
    my_unit,unit_text,symbol,symbol_position
SQKM,square kilometers,km²,END
SQML,square miles,miles²,END
  4. Per utilizzare l'unità appena creata in un concetto (metrico), assicurati che la seconda includa quantity:quantity o una delle relative unità secondarie. Quindi, aggiungi un attributo che faccia riferimento al concetto dell'unità. Esempio: 
    <concept id="..." extends="quantity:amount">
  ...
  <attribute concept="my_unit">
    <value>SQKM</value>
  </attribute>
  ...
</concept>

Note

  • Se il concetto di unità ha una sola istanza, puoi omettere la colonna ID dalla tabella di definizione e i tag value nelle metriche che la utilizzano.
  • Per un esempio completo, consulta la definizione del concetto di valuta canonica.