SPREAD, Spatiotemporal Pathogen Relationships and Epidemiological Analysis Dashboard (Relazioni spazio-temporali dei patogeni e dashboard delle analisi epidemiologiche)

Prima conosciuto come GrapeTree Extended.

Descrizione

La dashboard si basa su GrapeTree, un programma di visualizzazione di grafici ad albero da file Newick (nwk), totalmente interattivo e appartenente al sistema EnteroBase. GrapeTree supporta la manipolazione sia del layout e sia dei metadati dell'albero. Le figure generate sono prodotte usando gli algoritmi Neighbor-Joining (NJ) e Minimal Spanning Tree (MSTree) o un algoritmo Minimal Spanning Tree migliorato, chiamato MSTree V2. La versione originale è parte integrante di EnteroBase e, per maggiori dettagli, puoi consultare la relativa documentazione.

Per una descrizione formale, puoi consultare la pubblicazione validata in Genome Research.

La versione standalone di GrapeTree è stata integrata, in piattaforma, come strumento principale per la manipolazione dei grafici ad albero e dei metadati; essa, inoltre, al fine di consentire analisi spazio-temporali, è stata ampliata attraverso un sistema integrato di informazioni geografiche (GIS) ed un sistema di visualizzazione basato sui dati temporali. L'applicazione web consente agli utenti di caricare le coordinate geografiche e i dati temporali relativi a ciascun campione e di visualizzarli in maniera tale che la selezione dell'albero si rifletta sulla mappa e viceversa. L'applicazione, inoltre, permette all'utente di riprodurre una visualizzazione temporale sia sulla mappa sia sull'albero.

Come si usa

La dashboard è integrata con la piattaforma; ciò rende possibile lanciare un'analisi e visualizzarne i dati. Accedendo, tuttavia, direttamemte all'indirizzo https://cohesive.izs.it/spread/, puoi caricare e visualizzare un tuo dataset.

Nota bene Il dataset caricato viene visualizzato e gestito esclusivamente lato client nel browser; ciò significa che nessun dato viene trasmesso e non vengono utilizzati cookie di tracciamento. Gli unici dati scaricati da Internet sono il codice di visualizzazione (JavaScript), i font e le eventuali parti necessarie alla creazione della mappa; in ogni caso, puoi anche caricare dati sensibili.

Puoi caricare i file trascinandoli direttamente sopra l'area di rilascio iniziale o utilizzando il bottone di caricamento. Puoi trascinare o caricare un file .nwk, seguito da un file .tsv contenente i metadati e, facoltativamente, un file .geojson contenente informazioni geospaziali relative ai campioni.

Importante!

Il file .nwk deve essere caricato sempre prima dei metadati o dei file geoJson.

La dashboard ti consente di scaricare un file JSON completo che include metadati e configurazioni. Il file JSON generato può essere caricato usando il trascina e rilascia oppure le funzionalità di caricamento menzionate in precedenza. Questa funzione risulta utile nel caso tu voglia salvare il tuo lavoro e/o condividerlo.

Puoi trovare un dataset di esempio sulla repository del progetto in https://github.com/genpat-it/spread/tree/main/datasets/test.

Presentazione delle funzioni generali

Sia che tu scelga di caricare dati dal tuo computer o che tu stia visualizzando un dataset pre-elaborato dalla piattaforma, ti troverai di fronte sempre alla stessa area di lavoro configurabile. I principali componenti della dashboard, oltre all'Albero, sono:

• Impostazioni
• Mappa
• Metadati
• Legenda
• Video

Questi componenti possono essere mostrati o nascosti tramite i relativi pulsanti posti nella barra sopra l'area di lavoro principale, in base alle tue esigenze. Prima di entrare nel dettaglio di questi componenti, è opportuno menzionare rapidamente due funzioni presenti sulla barra: la prima è relativa al cambio lingua che puoi impostare clccando sull'icona del mappamondo; la seconda mostra informazioni e link utili e può essere impostata cliccando sull'icona info.

Lingue disponibili e traduzioni

Al momento, le lingue disponibili sono l'inglese, il francese e l'italiano; l'applicativo è, tuttavia, facilmente estensibile con nuove traduzioni. Se vuoi contribuire, puoi prendere a modello il file en.js o it.js presente nella cartella i18n sulla repository pubblica del progetto e tradurre i valori presenti. Per qualsiasi ulteriore informazione o supporto in merito puoi scrivere a bionformatica@izs.it.

Componenti

Vediamo nel dettaglio le varie parti che compongono la dashboard.

Strumenti albero

Dal menù contestuale, posto in alto a destra dell'area di lavoro dell'albero, si accede a questa sezione che contiene sia strumenti utili per modificare l'aspetto e il layout dell'albero, sia un'opzione per poter riportare l'albero allo stato originario, annullando eventuali cambiamenti e modifiche. Tra le funzioni disponibili, in questa sezione troviamo:

• Centra albero che regola le impostazioni di visualizzazione per portare il centro del grafico in posizione centrale all'interno dell'area di lavoro;
• Ridisegno statico che ricarica il grafico e lo ridisegna nel layout predefinito;
• Albero iniziale che ricarica la pagina e riporta l'albero allo stato e con il layout in cui si trovava quando è stato caricato la prima volta. Ti verrà chiesto di confermare prima di abbandonare la pagina. Attenzione: l'uso di questa funzione provocherà la perdita di tutte le modifiche effettuate.

Impostazioni

Attivando le impostazioni, entrerai in una sezione modificabile con una serie di schede, suddivise in aree tematiche, che ti permettono di configurare l'albero. Ogni scheda può essere espansa o ridotta in base alle tue esigenze. Troverai descritte, qui di seguito, le varie configurazioni disponibili, visibili anche all'interno dell'applicazione cliccando sull'icona ? della relativa scheda.

Stile nodi

In questa categoria, è possibile trovare alcune opzioni per modificare l'aspetto dei nodi o delle relative informazioni visualizzate.

• Colora per: nel menù a cascata di questa sezione, si può selezionare il colore di riempimento dei nodi, in base ai metadati;
• Mostra/Nascondi etichette: l'opzione permette di scegliere se visualizzare o meno le etichette dei nodi. È anche possibile scegliere che tipo di etichetta mostrare dal menù a cascata previsto nel campo Etichette;
• Dimensione carattere: le dimensioni del font delle etichette sono modificabili trascinando l'apposito cursore o specificando le dimensioni desiderate nel campo sottostante;
• Evidenzia etichette: usa il campo di ricerca per evidenziare le etichette dei nodi. Sono supportate le Espressioni Regolari;
• Segmenti individuali: l'interruttore di questa opzione permette di trasformare i nodi in grafici a torta, ognuno dei quali presenterà una scomposizione degli elementi al suo interno. E' importante sottolineare evidenziare che l'attivazione della funzionalità di scomposizione dei nodi dipenderà dalla categoria selezionata nel menu Colora per.

Dimensione nodi

• Dimensione raggio (%): la dimensione dei nodi può essere aumentata o diminuita trascinando l'apposito cursore o specificando le dimensioni nel campo.
• Curtosi (%): l'area dei nodi è correlata di default al numero di elementi che ne fanno parte. Usando il cursore o il campo in questa sezione, le dimensioni dei nodi possono essere diminuite o aumentate sulla base della distribuzione della curtosi dei nodi. L'aumento del valore di curtosi comporta l'incremento della percentuale di crescita della dimensione del nodo per ogni membro in esso contenuto; quindi, i nodi con un maggior numero di membri avranno un'area più grande e risalteranno maggiormente.

Stile rami

In questa sezione sono presenti le seguenti opzioni utili a personalizzare i rami dell'albero:

• Mostra/Nascondi etichette: l'opzione permette di scegliere se mostrare o nascondere le etichette dei rami;
• Dimensione carattere: permette di scegliere le dimensioni del testo delle etichette o tramite l'uso del cursore o inserendo un valore nell'apposito campo;
• Adattamento in scala (%): questa opzione permette di aumentare/diminuire la lunghezza dei rami attraverso l'utilizzo del cursore oppure specificando un valore nel campo sottostante;
• Comprimi i rami: usando il cursore o scrivendo un valore nel campo di questa opzione, tutti i rami più corti del valore selezionato verranno compressi. I nodi che ricadono in tale intervallo verranno fusi. I valori delle lunghezze dei rami verranno adeguati in scala a quelli definiti nei dati dell'albero originale;
• Scala logaritmica: selezionando questa opzione, le lunghezze di tutti i rami verranno mostrate in scala logaritmica.

Taglio rami

Le impostazioni di questa sezione permettono di rappresentare i rami in modi diversi in relazione alla loro lunghezza (i valori di lunghezza dei rami vengono riprodotti in scala rispetto alle lunghezze definite nei dati del grafico originale). Per aumentare o diminuire la scala puoi inserire un valore numerico nel campo Taglia rami più lunghi di. In seguito puoi scegliere se mostrarli, nasconderli o ridurli:

• Mostra: mostra i rami più lunghi del valore inserito (predefinito);
• Nascondi: rende trasparenti i rami più lunghi del valore scelto. Nonostante i rami non siano mostrati, rimane possibile interagirvi;
• Riduci: i rami più lunghi del valore di cutoff specificato verranno ridotti al valore di cutoff. I rami ridotti saranno rappresentati con linee tratteggiate per indicare che sono interessati da una riduzione.

Rendering

Questa sezione contiene alcune opzioni che permettono di controllare il posizionamento dei nodi nel grafico. Un pulsante permette di alternare due modalità: Statico e Dinamico.

• Statico: in questa modalità, il layout dell'albero viene calcolato alla generazione del grafico e viene mantenuto statico (ma interattivo). La lunghezza relativa dei rami e la loro scala (sulla base dei dati del grafico originale) saranno sempre mantenute fintanto che l'opzione Lunghezza del ramo reale resta selezionata.
• Dinamico: i nodi vengono posizionati dinamicamente in maniera simile ad una modalità Force-directed ma tenderanno a sparpagliarsi per distanziarsi dai nodi vicini. In questa modalità, l'albero può essere spostato liberamente, trascinandolo con il mouse; i nodi si ridisporranno sempre automaticamente per mantenere le distanze dai nodi circostanti, a seguito dello spostamento. La modalità Dinamico può essere usata per migliorare l'estetica del grafico ma la scala dei rami verrà modificata rispetto all'originale: i rami NON saranno in scala in questa modalità. L'opzione Solo selezionati può essere attivata per applicare la scelta solo ai nodi selezionati.

Mappa

Questa sezione permette di visualizzare una mappa interattiva se, per i campioni, sono state definite delle coordinate geografiche (tramite file metadata o tramite file geoJSON). Sulla mappa vengono disegnati dei marcatori, con un raggio più o meno lungo, in base al numero di campioni presenti in una determinata area. Cliccando su ogni marcatore, puoi aprire un popup informativo contenente la lista dei campioni presenti all'interno.

I marcatori riflettono i colori del tematismo scelto per la visualizzazione e la selezione dell'albero. Puoi interagire con la mappa anche tramite il suo menu contestuale, accessibile con un click del tasto destro del mouse su di essa oppure tramite il pulsante in alto a destra raffigurante tre punti verticali.

Strumenti mappa

Tramite le opzioni presenti in questa sezione potrai controllare l'aspetto della mappa.

• Aggrega per coordinate/per metadati: il pulsante ti consente di aggregare i punti sulla mappa in base alla vicinanza geografica delle coordinate fornite o in base ai valori dei metadati caricati. Nel primo caso è possibile impostare un valore di delta che determina il grado di aggregazione.
• Raggio minimo/massimo del marcatore: tramite questi due campi, è possibile intervenire sulla dimensione dei punti sulla mappa definendo un raggio minimo ed un raggio massimo. La dimensione iniziale è relativa alla quantità di nodi presenti sulle stesse coordinate geografiche.
• Modalità diagramma/Modalità heatmap: questo pulsante permette di cambiare la modalità di visualizzazione dei punti sulla mappa. Con la prima opzione, (selezionata di default), i punti saranno visualizzati con grafici a torta in base alle categorie dei nodi dell'albero laddove, con la seconda, ai nodi viene applicata una sfocatura.

Metadati

Attivando il pulsante Metadati, potrai visualizzare i metadati all'interno di una tabella interattiva. La tabella permette di spostare le colonne, estenderle e/o ridurle, ordinarle o filtrarle in base a delle chiavi di ricerca. Cliccando su una riga, puoi selezionare/deselezionare i campioni presenti nell'albero.

Come per la mappa, anche la tabella dei metadati ha degli strumenti ai quali si può accedere cliccando sulla tabella con il tasto destro del mouse o, in alternativa, usando il bottone in alto a destra con i tre punti verticali.

Legenda

Questo è uno strumento chiave sia per l'interazione con l'albero sia per la visualizzazione/selezione temporale dei dati. Tramite gli Strumenti legenda, è possibile cambiare categoria e colore dell'albero, personalizzare i colori o selezionare campioni da una determinata categoria.

Il video seguente mostra come accedere al menu contestuale della legenda e alle sue opzioni, come interagire con la legenda e come modificare le preferenze e la palette di colori.

Video

In modalità Video, la legenda si trasforma in una vera e propria timeline. Il video player, posizionato in basso a destra, permette di iterare sugli elementi della legenda ad una velocità configurabile. Le funzioni video sono completamente metadata driven quindi, se all'interno dei metadati sono presenti informazioni temporali, puoi colorare la legenda per tale informazione, ordinarla in ordine ascendente e, di conseguenza, avere una timeline per misurare la diffusione e lo sviluppo nel tempo di un agente patogeno.

Nel video seguente troverai un possibile caso d'uso.

Macro

Il componente Macro è accessibile tramite l'icona fast-forward situata nell'angolo in alto a destra dell'applicazione. Questa sezione offre una raccolta in continua espansione di sequenze di azioni (macro), che possono essere ricercate e categorizzate per tag.

Il componente consente di cercare le macro e, utilizzando chiavi specifiche (title:, tag:, desc:), è possibile restringere la ricerca per concentrarsi sugli elementi di interesse.

Se hai suggerimenti per nuove macro, saremo lieti di riceverli!

Zoom dei cluster

L'applicazione può essere usata per visualizzare risultati generati con ReporTree. Molto brevemente, ReporTree permette la generazione di una serie di zoom sui cluster specificando i campioni di interesse e alcuni parametri quali soglie e distanze; in questo contesto, è possibile indicare alla dashboard la loro presenza e, di conseguenza, essere visualizzati. Sull'interfaccia dell'albero, cliccando sul pulsante Zoom disponibili si ha accesso agli Strumenti zoom per poter avere un focus sugli eventuali cluster disponibili. È possibile selezionare il tipo di zoom, la soglia e il cluster al quale il campione può essere associato, così come è possibile selezionare i nodi coinvolti. Le funzioni permettono, inoltre, di poter aprire in una nuova scheda un cluster modificato, potendo decidere se mantenere o meno le impostazioni correnti.

Nel video seguente troverai un possibile caso d'uso.

Albero

Questo è ovviamente il componente principale e, pertanto, è sempre visibile. Esso mostra la visualizzazione ad albero dei dati ed è completamente interattivo. Con questo componente è possibile interagire direttamante tramite il menu contestuale o tramite tutti gli altri componenti.

Puoi interagire direttamente con l'albero, spostando i singoli nodi o posizionandoti sopra di essi per vedere dei tooltip; puoi anche selezionarli premendo Shift e cliccando su di essi oppure disegnando un'area con il mouse. La selezione si rifletterà anche sui componenti Mappa e Metadati.

CONSIGLIO

Per abilitare la selezione nell'area di lavoro del grafico, si tenga premuto il tasto Shift della tastiera: fintanto che il cursore viene mostrato con la forma di un mirino, sarà possibile selezionare o deselezionare i singoli nodi cliccando su di essi; sarà altresì possibile selezionare più nodi tracciando un'area di selezione (è necessario trascinare il cursore mentre si tiene premuto il tasto sinistro del mouse).

Attività più interessanti sicuramente possono essere fatte tramite il menu contestuale o, come detto, tramite l'interazione con gli altri componenti (trattati nelle relative sezioni). Puoi accedere al menu contestuale facendo click con il tasto destro del mouse sull'albero oppure tramite bottone in alto a destra con tre punti verticali. Le voci del menu sono abbastanza auto esplicative e ti invitiamo a provarle per capire meglio, tramite l'interazione, a cosa servono. Di base, vanno a modificare la visualizzazione dell'albero.

Ci concentriamo, qui, sulla funzione di salvataggio.

Salva SPREAD

Tramite questo pulsante, hai accesso ad una modale che permette di salvare e/o esportare SPREAD in diversi formati:

• Salva come json completo (.json): permette di salvare il lavoro corrente in un file .json completo di tutte le informazioni sull'albero, sui relativi metadati e sulle configurazioni correnti dei diversi componenti. Questa funzionalità è fondamentale poichè rappresenta l'unico modo per salvare i progressi del tuo lavoro di modifica di SPREAD, riprenderlo in un secondo momento o condividerlo con altri. Nel .json vengono salvate informazioni quali: il posizionamento e il colore dei nodi, la categoria corrente, la modalità di visualizzazione dei nodi sulla mappa, la configurazione del layout dell'area di lavoro e persino le schede delle impostazioni che sono espanse o compresse.
• Esporta newick (.nwk): esporta i dati nel formato .nwk
• Esporta metadata (.tsv): esporta i metadati nel formato .tsv
• Esporta geoJson (.geoJson): esporta i metadati spaziali nel formato .geojson

Tutti i file prodotti sono compatibili per essere ricaricati successivamente nella dashboard come accennato in Come si usa.