Creare dashboard con Superset

Un tutorial per imparare ad usare Superset partendo da un file csv

Introduzione

Apache Superset è un prodotto open source creato dai laboratori di AirBnB engineering & data science per creare dashboard interattive via web. Il progetto è partito più di un anno fa da una hackathon assumendo il nome di Caravel poi di Panoramix e infine di Superset. L’interesse che si è creato poi intorno al progetto ha fatto si che ora il progetto sia ospitato nello spazio GitHub di Apache Foundation.

Installazione

Superset è sviluppato usando Flask un framework Python molto snello per lo sviluppo web. La parte che genera i grafici interattivi invece fa uso di NVD3 — una libreria javascript costruita su D3.js. L'installazione di Superset avviene in pochissimi passaggi su una macchina dove si ha già installato Python (indifferente se versione 2.7 che versione 3.5 — AirBnB usa la versione 2.7 per i suoi prodotti in produzione) e alcune dipendenze di sistema.
Una volta installato occorre definire un utente di amministrazione attraverso cui inizializzare alcune configurazioni e, eventualmente, caricare dei dati di esempio. Le istruzioni sono presenti per i sistemi operativi più diffusi (distribuzioni GNU/Linux, Windows e MacOSX).
Per gli utenti pigri che usano Ubuntu ho realizzato questo script che raccoglie tutti i comandi da eseguire (verrà chiesta la password di amministrazione per installare le librerie e gli estremi per creare l'utente che amministrerà Superset).
Per usarlo basta seguire questi passaggi da shell
wget http://de.straba.us/install_superset.sh
chmod 755 install_superset.sh
./install_superset
NOTA: lo script installa superset creando la cartella "superset" nella home utente (es./home/napo/superset).
Una volta fatta l'installazione, l'avvio del programma avviene attivando l'ambiente python creato nella installazione e lanciando supersetcon l'opzione runserver (si rimanda alla documentazione).
Nel caso dell'utente Ubuntu di sopra che ha usato lo script, questo si riduce a queste operazioni da shell
- entrare nella directory dove si ha installato superset
cd $HOME/superset
- esecuzione dell'ambiente python con superset
source bin/activate
- avvio di superset
superset runserver
Da qui si abbandona la shell per usare il browser e aprirlo all'indirizzo http://localhost:8088
[se si vuole chiudere il servizio, allora premere CTRL-ce uscire con il comando deactivate]

Le funzioni base di Superset

Verrà presentata la pagina di login e, una volta inserite le credenziali scelte in fase di installazione si accederà ad una pagina con l'elenco delle dashboard pre-installate (ammesso che si abbia fatto questa scelta in fase di setup).

la pagina di Superset dopo l'autenticazione con le configurazioni dimostrative installate

Basterà sceglierne una qualsiasi per rimanere stupiti delle potenzialità di questo strumento.

dashboard creata con superset sui dati della popolazione offerto da World Bank — in evidenza la funzione di filtro

Una qualsiasi dashboard creata con Superset è composta da una serie di pannelli (chiamati slice). Ciascuno di questi può essere ridimensionato, spostato rispetto agli altri o mostrato a schermo intero.
Inoltre, ogni dataset rappresentato in un grafico, può essere anche esportato in formato csv o json o ricavarne anche la query SQL.
Le "slice" sono create a partire da una tabella presente nelle sorgenti dati che Superset è in grado di gestire.
La slice di filtro inoltre, cambia al volo le visualizzazione in relazione ai parametri scelti.

Superset utilizza tutti i database relazionali supportati dalla libreria python SQLAlchemy. Fra questi vale la pena di citare SQLite, MySQL, PostgreSQL, Microsoft SQL Server e Oracle.
Inoltre offre una completa integrazione con Druid: un progetto java open source per un datastore column-oriented distribuito in grado di gestire velocemente grandi quantità di dati (diversi petabyte) in tempo reale (trilioni di eventi).
Le dashboard create con Superset pertanto sono in grado di rappresentare dati in tempo reale. Questo a patto che, la tabella che viene interrogata, abbia un campo (una colonna) che contiene un data (anche completa di ora, minuti, secondi e millesecondi).
Anche in questo caso, l'interfacciamento ai database, è ben spiegato nella documentazione ufficiale.

Utilizzare un CSV in Superset attraverso CSVKit e SQLite

Il CSV è (ahimè) il formato più utilizzato nel rilascio degli Open Data.
Spesso si tratta di estrazioni periodiche da database (quando meglio sarebbe averli disponibili in tempo reale) che danno vita a tantissimi "dialetti' sulla loro struttura (es. la scelta del carattere di separatore di campo) o che non informano su alcuni metadati vitali come il significato dei campi, il tipo di dato che assumono (intero, reale, stringa, data …), la gestione dei valori mancanti, come sono formattati i valori di numeri o date, i possibili valori attesi (es. nelle variabili categoriche) e — argomento spesso dimenticato — la codifica caratteri.
Gran parte di queste carenze possono essere "indovinate" guardando i dati stessi e da lì popolare un tabella di un database.
A fare questo bellissimo lavoro ci pensa la suite CSVKit: una libreria python con diversi script in grado di maneggiare ed estrarre valore da file in formato CSV.
Come esempio prendiamo un file CSV dalla sezione Open Data di CONSIP.
Questo portale offre alcuni dataset aggiornati ma la metadatazione lascia a desiderare (ma hanno comunque la capacità di produrre grattacapi).
Fra i dataset disponibili andiamo a prenderne uno che contiene almeno una colonna con una data, pertanto il più aggiornato della sezione "Bandi e Gare". Il file bandiegare2017.csv. Aprendolo con LibreCalc si può cominciare ad investigarlo e scoprire che la codifica caratteri è la ISO-8859–15.

importazione del file bandiegari2017.csv in LibreCalc

una ulteriore verifica sulla qualità del csv si può fare usando il tool online CSVLint.

Veniamo però all'uso di CSVKit: la prima azione da svolgere è l'installazione.
Il consiglio è quello di utilizzare il comando python pip lanciandolo dall'ambiente dove si ha installato superset.
Pertanto, se si ha fatto uso dello script di sopra i comandi da console da eseguire sono questi:
- posizionarsi nella directory dove è presente superset
cd $HOME/superset
- attivare l'ambiente python
source bin/activate
- installare CSVKit
pip install csvkit
Se l'ultimo comando è andato a buon fine, una volta scaricato il file csv
wget http://dati.consip.it/dataset/934b3e63-c83b-4185-bb06-60c04d209bc6/resource/377784b5-bb11-4a3e-a3a7-e1e48d122892/download/bandiegare2017.csv
Si potrà ottenere delle statistiche sui dati del csv attraverso il comando csvstat arricchito dall'informazione della codifica caratteri.
Pertanto l'istruzione
csvstat -e iso8859–15 bandiegare2017.csv
darà come output delle statistiche per ogni colonna del file.
E arriviamo quindi alla trasformazione del file in una tabella di una database relazione.
Il comando di CSVKit in grado di fare questa operazione è csvsql ed anche questo è in grado di interfacciarsi ad innumerevoli database relazionali.
Nel nostro caso, per comodità, semplicità e performance andremo a creare un file SQLite che conterrà la tabella bandiegare2017.
Questo il comando
csvsql --db sqlite:///consip.db --insert -e ISO-8859-15 bandiegare2017.csv
Dove "consip.db" è il nome del file SQLite che CSVKit andrà a creare e che si troverà nella stessa directory che ospita bandiegare2017.csv.

A questo punto rilanciamo Superset e configuriamo questa nuova risorsa.
Seguendo il percorso nel menu Sources -> Databases, premendo sull'icona "+", si potrà aggiungere la nuova risorsa e da lì aggiungere il nome del database (nel nostro caso "consip") e le informazioni su come raggiungere il file SQLite (voce "SQLAlchemy URI").
Nel caso di SQLite si tratta di creare una stringa composta da "sqlite:///" e dal percorso assoluto del file.
Esempio
sqlite:////home/napo/superset/consip.db
Premendo poi il tasto "Test Connection" si potrà verificare di avere fatto correttamente il collegamento.
(abilitando Expose in SQL Lab e Allow CREATE TABLE AS si attivano funzioni per fare operazioni più complesse — vedi più avanti)

Esempio di collegamento SQLite

Fatto il collegamento al database occorre ora informare Superset di quale tabella fare uso.
Il percorso del menu da seguire questa volta è Source -> Tables
Nuovamente premendo sul "+" si ottiene la scheda dove inserire le informazioni che si trattano del nome del database e nome della tabella.

aggiungere nuove tabelle in Superset

Salvata la tabella, si torna alla lista delle tabelle disponibili.

L'elenco presenta, vicino al nome di ogni tabella, tre bottoni: show record, edit record e delete record.
Prima di creare la "slice" è opportuno andare a modificare le impostazioni dei campi (= colonne) della tabella ("edit record")

le opzioni possibili sulle colonne della tabella

In questa sezione saranno presentate, riga per riga, tutte le colonne presenti nella tabella e, per ciascuna, le varie modalità attraverso cui aggregare i valori al fine di creare le visualizzazioni.
Le prime due colonne contengono rispettivamente il nome della colonna e il tipo di dato contenuto (e qui si nota anche la "magia" del lavoro fatto da CSVKit nell'identificarlo in maniera automatica). Le successive invece mostrano come i valori possono essere trattati per la visualizzazione:
- Groupable: se si vuole che i valori vengano raggruppati per i valori contenuti (es. per creare grafici come treemap o torte)
- Filterable: se si vuole avere l'opzione di filtrare i dati per uno o più valori contenuti in quella colonna
- Count Distinct: se si vuole avere il totale delle ricorrenze
- Sum: se si vuole avere il totale (= la somma) dei valori contenuti in quella colonna (vale solo per le colonne che contengono valori numerici)
- Min: se si vuole conoscere il valore minimo fra tutti quelli contenuti in quella colonna
- Max: se si vuole conoscere il valore massimo fra tutti quelli contenuti in quella colonna
- Is Temporal: se la colonna contiene un valore temporale (giorno, mese, anno, ore, minuti…)
Superset assegna in automatico le proprietà correte in relazione al tipo di dato dichiarato. Qui si può decidere di cambiarle o aumentare i dettagli.

Una attenzione particolare va fatta per le colonne di tipo data. Le formattazioni e gli ordini di giorno, mese e anno possono cambiare.
Superset permette di personalizzare queste formattazioni grazie a tutte le combinazioni che si possono creare con la gestione delle date in python.
Nel caso specifico della tabella dati che stiamo analizzando va fatta la considerazione che CSVKit ha individuato in automatico le colonne che contengono date e poi le ha formattate seguendo lo standard anno-mese-giorno. Questa formattazione, in superset, viene definita in questo modo: %Y-%m-%d

definizione del formato della data

La sezione "List metrics" inoltre permette di avere ulteriori calcoli come la media dei valori (avg) o altre funzioni SQL che il database relazionale è in grado di calcolare (Es. funzioni di SQLite).
Per chi conosce il linguaggio SQL, in particolare sulla sintassi della SELECT, tutto questo appare molto semplice.
Una buona guida per cominciare la si può trovare su W3Schools (inglese) e su HTML.it (italiano)

Creazione di una Dashboard
Una volta sicuri delle impostazioni fatte si può passare alla creazione delle slice (= i singoli grafici) tornando sull'elenco delle tabelle e cliccando sulla tabella di nostro interesse ("bandiegare2017").

l'interfaccia per la creazione delle slice

L'interfaccia si presenta con una colonna a sinistra con tutte le operazioni possibili e l'area di destra con la visualizzazione di cosa rappresentare.
Viene subito proposta la visualizzazione a tabella presentando il primo valore delle metriche disponibili e del valore assunto nella prima colonna temporale dell'elenco.
Quello che si ottiene, al primo colpo, lascia un po' perplessi visto che non si vede un grafico e il valore riportato è spesso nullo.

la colonna per selezionare i dati da visualizzare

Scorrendo però la colonna verso il basso si scopre velocemente che il valore rappresentato è in base agli ultimi setti giorni a partire da oggi.
Basta cambiare il valore di "Since" con "100 years ago" e premere poi sul bottone di query in cima alla colonna, per vedere il valore cambiare.
Se poi si vuole investigare una o più variabili è sufficiente scegliere su "Metrics" quale/i variabile/i investigare ed eventualmente raggrupparle.

La lista dei grafici interattivi che si possono creare con Superset

La scelta del tipo di grafico avviene su una lista di 33 alternative che si raggiungono con un clic sull'etichetta del grafico scelto sotto la voce "Visualization Type".
In alcuni casi la colonna con le impostazioni cambia in relazione al tipo di grafico.

come si presenta la visualizzazione “Word Count” di Superset usando i dati consip per categoria merceologica

Il dataset "beni e gare 2017" di Consip contiene un colonna dal nome Categoria_Merceologica il cui significato è auto esplicativo
Supponiamo di voler creare la tag cloud delle categorie merceologiche.
Le operazioni da eseguire sono:
- scegliere il tipo di visualizzazione (Word cloud)
- definire la colonna del tempo nell'intervallo di 100 anni da ora
- sotto la voce Series selezionare il campo Categoria_Merceologica
- al fine di calcolare le ricorrenze di una parola occorre scegliere come metrica (Metric) il valore COUNT(*)
- infine scegliere a piacere le modalità di ordinamento (flat, random, square) e le dimensioni che il carattere deve avere dal valore più piccolo al più grande.
Premendo il tasto Query in alto a sinistra si otterrà la visualizzazione richiesta

come si presenta la visualizzazione "Word Count" di Superset usando i dati consip per categoria merceologica

Se si vuole escludere qualche valore, o definire un intervallo o altro ancora, occorre inserire i parametri nella sezione "Filters" nell'area dedicata all’interrogazione dei dati.

Esempio
si vuole non mostrare il valore "ND" (che suppongo voglia dire "non disponibile").
Nella sezione Filters, si sceglie il bottone "Add Filter", si seleziona il campo "Categoria_Merceologica", si inserisce la condizione "!=" (che vuol dire "diverso da"), si aggiunge il valore che non si vuole prendere in considerazione (ND) e si riesegue la query. Nella Word Cloud non comparirà più il valore "ND".

Se il risultato è quello che si vuole utilizzare per la dashboard che si vuole creare sarà sufficiente scegliere il bottone "Save" in alto a sinistra.
Da qui una finestra di dialogo chiederà che nome assegnare e se salvare la "slice" o se assegnarla ad una dashboard precedentemente creata o se assegnarla ad una dashboard da creare.

finestra di dialogo di salvataggio della pagina

lo schema per costruire ulteriori slice avviene allo stesso modo facendo sempre attenzione a cosa si vuole rappresentare e che messaggio si vuole dare.

heatmap calendar

Non manca poi la possibilità di creare tabelle semplici o complesse (come le tabelle pivot) e quella di creare filtri selezionabili dalla dashboard.
La creazione della dashboard vera e propria avviene o durante la creazione (delle slice aggiungendo o creando nuove dashboard) o dal menu dedicato

l'uso dei filtri da dashboard con influenza sugli altri grafici

nella configurazione dei database è possibile estenderne l'utilizzo nella funzione "SQL Lab" di Superset.
Questa funzione permette di investigare le tabelle di un database e di creare query complesse (es. unioni fra più tabelle) da cui creare quindi tabelle secondarie che possono poi essere esposte come slice e quindi nelle dashboard.

la funzione SQL Lab di Superset

Superset in produzione
Superset può essere eseguito in locale (sul proprio computer) o su un server remoto come servizio web.
La documentazione per l'installazione su server remoto è quella di Flask.
Le istruzioni passo passo vengono proposte sia per appoggiarsi a servizi remoti come Google AppEngine o Heroku, che all'installazione su un proprio server attraverso Apache o Nginx.

Configurazione accesso pubblico ad una dashboard
Ogni oggetto creato in Superset ha un indirizzo web univoco.
Quindi è facile immaginare che, condividendo l'url si condivida automaticamente la dashboard creata o altro.
Questa, in realtà, è una idea sbagliata.
Gli sviluppatori di Superset hanno realizzato un sistema di gestione degli accessi (ACL) molto avanzato che permette di definire i diritti di lettura, scrittura, modifica e cancellazione a vari livelli.
Per prendere confidenza con queste funzionalità vediamo come va sviluppata la visualizzazione in forma anonima (quindi in lettura e senza bisogno di autenticazione) di una dashboard creata a partire dal nostro dataset di esempio.

definizione dei permessi in lettura alla dashboard creata

Le operazioni vanno svolte dal menu Security.
Nel caso specifico dell'accesso pubblico occorre andare a modificare i permessi per il ruolo "public" alla voce List Roles e, qui, configurare l'accesso a:
- alla dashboard
can dashboard on Superset
- al database e relative tabelle che la dashboard usa nella forma [nomedatabase].[nometabella]
datasource access on [consip].[bandiegare2017](id:8)
- ai json generati dalle query che popolano le slice della dashboard
can explore json on Superset
A questo punto fornendo l'indirizzo univoco della dashboard creata, questa sarà visibile anche ad utente anonimo.

La lista di tutti i permessi di Superset è presente nel menu "List Base Permissions". Quando si è nella scheda dove vengono definiti i permessi, è sufficiente iniziare a scrivere le parole chiave (es. access, explore, json, datasource, consip ..) che nella casella appaiono tutte le possibili combinazioni da scegliere.

Il file config.py
Le personalizzazioni sono innumerevoli, se si considera poi che si è solo alla versione 0.19, e che Superset sta attirando l'attenzione di sempre più player (fra i nomi delle organizzazioni che lo usano si nota Zalando, Yahoo!, FBK e, ovviamente, AirBnB) sicuramente le sue evoluzioni porteranno sempre più migliore.
Intanto, per chi deve affinare alcune operazioni (es. uso nella piattaforma in altre lingue, configurazione del server SMTP, cambio del percorso di configurazione, ecc…) deve spostarsi nella directory di installazione di superset (es. $HOME/superset) e da lì nella directory omonima all'interno delle librerie della sottoinstallazione python creata (es. $HOME/superset/lib/python2.7/site-packages/superset ) e modificare — con un editor testuale — il file config.py.

Riassunto "quick&dirty"
- Superset è un prodotto open source creato da AirBnB per creare dashboard di dati con grafici che fanno uso di D3 direttamente da browser
- l'installazione avviene in pochi passaggi
- Superset è in grado di gestire diversi database relazionali oltre che a Druid
- CSVKit è un ottimo strumento per popolare una tabella di un database relazionale partendo da un file .csv
- Una tabella per essere usata in Superset deve essere prima controllata (in particolare per le colonne che contengono date)
- Una volta definita una dashboard, se la si vuole rendere pubblica, è necessario definire gli accessi per il ruolo "Public" facendo cura all'accesso alla tabella
- il servizio può essere messo in produzione secondo la documentazione fornita da Flask