Introduzione

Nel contesto IPSES, il VRE (Virtual Research Environment) è una funzionalità avanzata disponibile per gli utenti registrati. Un VRE è un'area in cui è possibile analizzare i dati precedentemente selezionati dalla GUI IPSES e combinarli con altri dati che l'utente può aggiungere a uno spazio dedicato e persistente. Il VRE è implementato utilizzando la popolare tecnologia Jupyter Notebook/Lab. L'ecosistema Jupyter e Python include estensioni come l'analisi, l'elaborazione e la visualizzazione dei dati, per lo più disponibili open source/gratuitamente.

L'obiettivo di questo documento è fornire all'utente un'introduzione e una guida introduttiva di base al VRE IPSES.

VRE, JupyterHub, JupyterLab, pyipses

IPSES VRE è stato implementato con l'approccio basato su JupyterHub, come descritto in D11.3 Fase 1: Analisi e progettazione della piattaforma. Maggiori informazioni sono disponibili nella sezione VRE del documento citato.

JupyterHub è stato integrato nell'architettura IPSES per gestire gli ambienti multiutente JupyterLab, come richiesto dal progetto (componente VRE JupyterHub nel diagramma dell'architettura). Nelle specifiche, in IPSES, JupyterHub è stato configurato per:

integrarsi con la soluzione di gestione delle identità e degli accessi di IPSES, come descritto nella sezione KeyCloak, per l'autorizzazione e l'autenticazione. Dotati delle autorizzazioni appropriate, gli utenti che hanno effettuato l'accesso alla GUI IPSES saranno in grado di accedere direttamente al VRE.

creare un'istanza di JupyterLab per ogni utente, utilizzando l'infrastruttura basata su container di IPSES.

fornire un ambiente JupyterLab persistente e uno storage per ogni utente, in cui i notebook dell'utente e le librerie Python che ha installato vengono salvati in diverse sessioni con il VRE.

Per supportare l'integrazione tra l'interfaccia grafica IPSES e il VRE, è stato sviluppato un servizio di condivisione dei dati nel backend IPSES. Attraverso questo servizio, la GUI sarà in grado di salvare i segnalibri degli utenti dal loro spazio di lavoro. Il VRE, dal canto suo, sarà in grado di recuperare i dati dal servizio e di utilizzarli, ad esempio per scaricare i dati dai servizi dei fornitori, salvarli in file, analizzarli utilizzando gli strumenti disponibili nell'ecosistema Python.

Per facilitare l'accesso allo spazio di lavoro dell'utente, è stata progettata e implementata una libreria python dedicata: pyipses. Tramite pyipses gli utenti possono accedere in modo programmatico ai propri segnalibri e scaricare i dati dall'URL di un segnalibro.

Pyipses fornisce anche un set di API di base, ad esempio per semplificare la rappresentazione dei dati su una mappa, utilizzando le popolari librerie pandas, ipyleaflet e plotly python. Le API di Pyipses sono documentate nel progetto della libreria su GitLab.

Accesso a JupyterHub dalla GUI di IPSES

Il VRE può essere utilizzato solo dagli utenti IPSES registrati autorizzati.

Per effettuare il login, punta prima il tuo browser verso la GUI di IPSES, clicca su "Accedi all'area personale" in alto a destra e inserisci le tue credenziali nella casella di login. Se si dispone dei diritti per accedere al VRE, verrà visualizzato un collegamento "Goto JupyterHub".

Facendo clic sul collegamento "Vai a JupyterHub" si aprirà una nuova scheda del browser con una barra di avanzamento che indica che la sessione VRE/JupyterHub è in fase di preparazione. Nel primo accesso questa fase richiede un po' di tempo a causa dell'installazione della libreria di supporto pyipses e di alcune dipendenze di base (es. pandas e ipyleaflet).

Quando la sessione di JupyterHub è pronta, verrà visualizzata un'interfaccia "standard" di JupyterLab.

JupyterLab, spazio utente, come installare le librerie

I dettagli sulla GUI di JupyterLab e sul suo utilizzo (creazione di notebook, esecuzione di celle, ecc.) sono disponibili nella guida ufficiale di JupyterLab.JupyterLab guide.

Il browser dei file nella barra laterale sinistra mostra il contenuto corrente dello spazio JupyterLab dell'utente.

Nello spazio utente è possibile creare file notebook, caricare file di dati esistenti e/o crearne di nuovi a livello di codice. Lo spazio personale viene salvato, quindi i file creati o modificati durante una sessione VRE saranno disponibili in una sessione successiva.

Se necessario, è possibile installare librerie dall'ecosistema Python, ad esempio eseguendo un

!pip install istruzione LIBRARYNAME , in una cella del notebook di Jupiter. Puoi trovare maggiori informazioni sulla sintassi del comando pip nella guida ufficiale di pip. Please note that the installation of a new library, or the upgrade of a library already installed could require a restart of the JupyterLab kernel.

Le librerie installate dall'utente sono private e vengono salvate in modo permanente dall'infrastruttura JupyterHub, in modo che la prossima volta che si attiva il VRE le si troverà già installate

Per impostazione predefinita, troverai alcune librerie preinstallate nel tuo nuovo ambiente JupyterLab: pandas, plotly and ipyleaflet, , oltre a pyipses, una libreria di connettori con il backend IPSES.

Esempio introduttivo di Pyipses

Si presume che l'area di lavoro dell'utente corrente non sia vuota nell'interfaccia utente di IPSES. Nella versione corrente dell'interfaccia grafica IPSES, per condividere l'area di lavoro corrente con il VRE, è sufficiente fare clic sul pulsante Condividi nella sezione dell'area di lavoro dell'interfaccia grafica.

Questo codice Python seguente può essere incollato in una cella del notebook ed eseguito. Tramite le API pyipses, recupera l'elenco dei segnalibri attualmente definiti nell'area di lavoro dell'utente e li stampa: il nome del segnalibro e i formati disponibili per quel segnalibro. Quindi, scarica i dati dal primo segnalibro trovato nell'elenco, in questo esempio in formato 'GeoJSON' e salva i dati in un file nello spazio JupyterLab.

da pyipses import Ipses

userdata=Ipses.get_workspace()

segnalibri=userdata.get_all_bookmarks()

per segnalibro nei segnalibri:

print(f'\'{bookmark.name} {bookmark.get_format_types()}\'')

Ipses.download_data_to_file(segnalibri[0].get_url('geojson'),'datafile.json')

Dopo aver salvato i dati in un file, è possibile elaborarli utilizzando le librerie Python.

API di Pyipses

Le sezioni seguenti forniscono maggiori dettagli su alcune delle funzionalità di pyipses. Le API complete per le funzioni menzionate qui sono documentate nel codice sorgente del progetto di libreria..

Importa pyipses

Per importare la libreria:

da ipses import Ipses

Recuperare i dati condivisi dell'area di lavoro

Per recuperare e visualizzare l'area di lavoro dell'utente corrente dal servizio dati dell'area di lavoro condivisa (ad esempio, i segnalibri raccolti utilizzando l'interfaccia grafica IPSES, tramite il pulsante Condividi, nella sezione Area di lavoro)

area di lavoro=Ipses.get_workspace()

segnalibri=workspace.get_all_bookmarks()

per segnalibro nei segnalibri: print(f'{bookmark.name}')

Salvare i dati dell'area di lavoro in un file

Per salvare il contenuto di un'area di lavoro (ad esempio, i segnalibri) in un file Json, nello spazio JupyterLab: poiché l'area di lavoro GUI può cambiare nel tempo, congelare il suo stato attuale in un file può essere utile per un uso futuro.

Ipses.write_workspace(area di lavoro, 'myworkspace.json')

Caricare i dati dell'area di lavoro da un file Json

Per caricare un file Json dell'area di lavoro salvato in precedenza in un'area di lavoro:

Ipses.read_workspace('myworkspace.json')

Scaricare i dati da un URL

Ogni segnalibro ha un elenco di formati di dati disponibili, che portano a URL diversi che sono i puntatori ai dati effettivi.

Per recuperare l'elenco dei formati disponibili (ad esempio, 'json', 'csv') per un segnalibro:

segnalibri[0].get_format_types()

Per scaricare i dati dall'URL del segnalibro, è necessario FORMAT_TYPE:

Ipses.download_data(segnalibri[0].get_url(FORMAT_TYPE))

Scaricare dati da un URL a un file

Per scaricare i dati da un URL (ad esempio, dall'URL di un segnalibro) e salvarli in un file nello spazio JupyterLab

Ipses.download_data_to_file (segnalibri[0].get_url(FORMAT_TYPE), 'mydata')

Visualizzazione dei dati

Pyipses fornisce anche alcune API di base per visualizzare i dati su una mappa, utilizzando il widget Jupiter di ipyleaflet, o in un grafico, utilizzando plotly; Si prega di notare che queste funzionalità non sono destinate a sostituire l'insieme ufficiale ed esteso di API ipyleaflet e plotly.

Inoltre, si noti che se queste API vengono utilizzate per visualizzare i dati da segnalibri IPSES generici, sarà necessaria una certa codifica in Python per trasformare tali dati, dal loro formato originale a un frame di dati pandas

Per importare le API di supporto:

da pyipses import IpsesUtils

Visualizza un frame di dati su una mappa

Un dataframe df contenente almeno due colonne con valori di latitudine e longitudine potrebbe essere visualizzato su una mappa, utilizzando la libreria IpyLeaflet.

Questo codice qui sotto mostra la mappa e utilizza OpenStreetMap per il livello di sfondo.

I parametri lat_col e lon_col sono i nomi delle colonne, nel dataframe df, con i dati di latitudine e longitudine, rispettivamente.

IpsesUtils.map_df(df, lat_col, lon_col, larghezza=800, altezza=600)

Si noti che ogni riga nel dataframe verrà visualizzata sulla mappa con un'icona di marcatore. Cliccando su un marker verrà visualizzato un popup, con tutti gli altri attributi presenti nella riga del dataframe.

Traccia un frame di dati con dati di serie temporali

Traccia un frame di dati con dati di serie temporali _col sono i nomi delle colonne, nel dataframe df, con i dati di tempo e valore da visualizzare, rispettivamente.

IpsesUtils.plot_df(df, time_col, value_col)