Corso Python scientifico in GX-TXT · Modulo 4 · Lezione 20

Una colonna numerica non è ancora una descrizione completa di un dato scientifico. Per interpretarla servono almeno identità, significato e unità, oltre al contesto necessario per capire origine e qualità. In questa lezione leggeremo lo schema delle variabili di un Dataset GX-TXT e i suoi metadati pubblici.

Obiettivi: distinguere ID e nome di una variabile; leggere descrittori e unità; riconoscere campi assenti; evitare di attribuire significati non documentati.

Prerequisiti: dizionari, catalogo e identità Dataset delle lezioni 5 e 19; Session con la serie sintetica della lezione 9.

Che cosa descrive uno schema

Uno schema descrive la struttura dei dati: quali variabili esistono, come sono identificate e quali proprietà sono disponibili. A seconda del Dataset e della versione, un descrittore può contenere tipo numerico, forma, unità, etichetta, ruolo semantico e informazioni sulle coordinate.

Un ID di variabile è il riferimento usato nelle chiamate pubbliche. Un nome o una etichetta sono informazioni di presentazione e possono avere regole diverse. Non usare la posizione della colonna come sostituto dell’ID quando l’API offre un’identità stabile.

Nel Dataset corso_python_serie_sintetica gli ID sono tempo e segnale. La prima variabile usa secondi (s), la seconda millivolt (mV). I quattro punti sono sintetici, scelti per il corso, e non hanno un’incertezza sperimentale assegnata.

Tipo, unità e ruolo

Il tipo, per esempio float64, descrive come sono rappresentati i valori numerici. Non dice da solo se un numero rappresenta tempo o tensione. L’unità specifica la scala della grandezza, mentre il ruolo semantico può indicarne il significato, come time o voltage.

Un’intestazione di colonna come segnale non garantisce da sola unità, precisione, provenienza o incertezza. Se una proprietà non è presente, va trattata come assente: non inventare un’unità o una conversione sulla base del solo nome. Una stringa vuota, un campo assente e un valore None possono richiedere interpretazioni diverse secondo il contratto dell’API.

API pubbliche per lo schema

DATASET_VARIABLE_SCHEMA_API_v3/list riceve l’ID del Dataset e restituisce una lista di descrittori di variabile. get riceve l’ID del Dataset e quello di una variabile e restituisce il suo descrittore. DATASET_METADATA_API_v1/read legge i metadati del Dataset nella Session corrente.

Nell’esempio iteriamo sulle variabili restituite da list, prendiamo variable_id e chiediamo i dettagli con get. Usiamo .get per campi facoltativi. Nel risultato osservato il campo interrogato come name non è presente e quindi viene mostrato None: questo non significa che la variabile non abbia un ID. Per i nomi e le etichette effettivamente disponibili occorre consultare i campi documentati del descrittore nella versione in uso.

Le chiamate nel ciclo sono una per variabile: su Dataset con molte variabili o su archivi remoti possono avere un costo. Riutilizza i descrittori già ottenuti quando il tuo lavoro lo consente e non fare ipotesi sull’ordine della lista.

Codice completo

from gxtxt import gxtxt_api_call, gxtxt_api_require

gxtxt_api_require("DATASET_VARIABLE_SCHEMA_API_v3@3")
gxtxt_api_require("DATASET_METADATA_API_v1@1")
dataset = "corso_python_serie_sintetica"
variabili = gxtxt_api_call("DATASET_VARIABLE_SCHEMA_API_v3", "list", [dataset])
print("Numero variabili:", len(variabili))
for voce in variabili:
    identificatore = voce["variable_id"]
    dettaglio = gxtxt_api_call("DATASET_VARIABLE_SCHEMA_API_v3", "get", [dataset, identificatore])
    print("ID:", identificatore, "nome:", dettaglio.get("name"), "unita:", dettaglio.get("unit"))
    print("Tipo:", dettaglio.get("dtype"), "ruolo:", dettaglio.get("semantic_role"))
metadati = gxtxt_api_call("DATASET_METADATA_API_v1", "read", [dataset])
print("Metadati disponibili:", metadati)

voce["variable_id"] richiede un campo indispensabile per la chiamata successiva. Gli altri campi sono letti con get, così un’assenza rimane visibile come None. L’ultima chiamata legge metadati del Dataset, distinti dai descrittori delle singole variabili.

Script di lettura dello schema delle variabili nell'editor Python di GX-TXT.
Script di lettura dello schema delle variabili nell'editor Python di GX-TXT.

Lo script interroga l’elenco e i dettagli delle variabili con le API pubbliche.

Esecuzione

  1. Apri la Session che contiene corso_python_serie_sintetica e il Viewer Python Scripts.
  2. Importa schema_variabili.py, assegna nome e Script ID nello scope session, quindi salva.
  3. Avvia il Runner e premi Run Job.
  4. Controlla l’output: nell’esempio sono presenti due variabili. tempo riporta unità s e ruolo time; segnale riporta mV e ruolo voltage. Il campo name interrogato appare come None nella risposta mostrata.
Output con identificativi, tipi e unità delle variabili sintetiche.
Output con identificativi, tipi e unità delle variabili sintetiche.

Gli ID, le unità e i ruoli sono letti dal Dataset; un campo non presente non viene inventato.

Errore comune

Vedere una colonna chiamata tempo e assumere che sia sempre espressa in secondi può produrre conversioni sbagliate. Leggi l’unità dichiarata e verifica che sia appropriata per l’analisi. Allo stesso modo, float64 non indica la precisione sperimentale: descrive la rappresentazione numerica, non l’incertezza della misura.

Esercizio

Un descrittore contiene {"variable_id": "temperatura", "unit": "K"} ma non contiene la chiave dtype. Che cosa restituisce descrittore.get("dtype")? È corretto concludere che il tipo sia float64?

Soluzione ragionata

get restituisce None quando la chiave manca e non è fornito un valore alternativo. Non è corretto inventare float64: consulta lo schema e i dati disponibili o segnala che l’informazione non è presente.

Nella prossima lezione leggeremo più variabili per blocchi mantenendone l’allineamento.

Scarica gli script del Modulo 04 (ZIP)

#Dataset #GX-TXT #Python

Altre tappe del progetto

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *