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

Una trasformazione scientifica dovrebbe produrre un risultato distinguibile dai dati di partenza e accompagnato da informazioni sulla sua origine. In questa lezione convertiamo una serie sintetica da millivolt a volt, la pubblichiamo come nuovo Dataset canonico e la rileggiamo tramite l’API pubblica.

Obiettivi: distinguere dato sorgente e derivato; applicare una conversione dichiarata; pubblicare una serie con identità e unità proprie; confrontare i valori riletti con quelli attesi.

Prerequisiti: conversioni della lezione 16, identità Dataset e lettura delle lezioni 19–21.

Perché creare un nuovo Dataset

Un risultato in memoria esiste soltanto durante l’esecuzione dello script; un file scritto su disco non è automaticamente un Dataset registrato nella Session. La pubblicazione attraverso un’API GX-TXT crea un’identità e uno schema che altri strumenti della Session possono utilizzare.

Conservare il Dataset sorgente e pubblicare un derivato separato rende più chiara la relazione fra input e output. Occorre inoltre descrivere la trasformazione: un’etichetta diversa non dimostra che i valori siano stati convertiti correttamente.

Trasformazione proposta

Partiamo dalla serie sintetica corso_python_serie_sintetica: tempi [0.0, 0.5, 1.0, 1.5] s e segnali [1.2, 1.5, 1.3, 1.6] mV. Sono valori inventati, non misure sperimentali, senza incertezza assegnata. La conversione proporzionale è:

segnale in V = segnale in mV / 1000

I valori attesi sono [0.0012, 0.0015, 0.0013, 0.0016] V. Il tempo rimane espresso in secondi e associato alla stessa riga. Nella lezione 16 abbiamo confrontato la conversione con il registro delle unità; qui ci concentriamo sulla pubblicazione del risultato.

publish_series e provenienza

DATASET_PUBLICATION_API_v2/publish_series riceve una richiesta con ID del nuovo Dataset, contratto, valori X e Y e descrittori delle variabili. Nell’esempio l’ascissa è tempo in s, l’ordinata è segnale_v in V e il campo source_dataset_ids indica il Dataset sorgente. La stringa provenance descrive la divisione per 1000 e la natura sintetica dei dati.

La richiesta usa replace_owned=True: una nuova esecuzione può sostituire il Dataset derivato solo se le regole del provider autorizzano quel produttore. Non usare questa opzione per sovrascrivere un Dataset di proprietà diversa; in caso di conflitto scegli un ID libero. La pubblicazione non modifica intenzionalmente il Dataset sorgente.

Codice completo

import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require

gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
gxtxt_api_require("DATASET_PUBLICATION_API_v2@2")
sorgente = "corso_python_serie_sintetica"
derivato = "corso_python_serie_volt"
b = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range", [sorgente, ["tempo", "segnale"], 0, 4])
tempo = np.asarray(b["tempo"]["values"]).reshape(-1)
segnale_mv = np.asarray(b["segnale"]["values"]).reshape(-1)
segnale_v = segnale_mv / 1000.0
richiesta = {"dataset_id": derivato, "contract": "table.generic", "storage": "csv", "replace_owned": True,
    "x_values": tempo, "y_values": segnale_v,
    "x_variable": {"variable_id": "tempo", "name": "tempo", "unit": "s", "semantic_role": "time"},
    "y_variable": {"variable_id": "segnale_v", "name": "segnale_v", "unit": "V", "semantic_role": "voltage"},
    "source_dataset_ids": [sorgente], "provenance": "Serie sintetica: conversione da mV a V, divisione per 1000"}
gxtxt_api_call("DATASET_PUBLICATION_API_v2", "publish_series", [richiesta])
rilettura = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_range", [derivato, ["segnale_v"], 0, 4])
valori = np.asarray(rilettura["segnale_v"]["values"]).reshape(-1)
print("Sorgente (mV):", segnale_mv)
print("Serie pubblicata (V):", valori)
print("Confronto con conversione:", np.allclose(valori, segnale_v, rtol=1e-12, atol=1e-15))

Lo script conosce la forma a colonna e il numero di righe della serie di partenza; un programma generico deve controllare schema, lunghezza e unità prima di trasformare i dati. np.allclose confronta i valori con tolleranze esplicite, qui scelte per il piccolo esempio numerico: non sono un’incertezza sperimentale.

La rilettura del derivato usa l’API canonica, quindi controlla ciò che GX-TXT ha pubblicato invece di limitarsi all’array in memoria. Per un caso reale verifica anche metadati, selezione, unità e completezza dell’insieme.

Script di pubblicazione della serie derivata nell'editor Python di GX-TXT.
Script di pubblicazione della serie derivata nell'editor Python di GX-TXT.

Lo script legge la sorgente, converte e pubblica una nuova serie.

Esecuzione

  1. Apri la Session con corso_python_serie_sintetica e il Viewer Python Scripts.
  2. Importa serie_derivata.py, assegna nome e Script ID nello scope session, quindi salva.
  3. Apri il Runner e premi Run Job.
  4. Confronta i valori della serie pubblicata con quelli attesi in volt e controlla che il confronto stampato sia True. Il Dataset derivato ha ID corso_python_serie_volt.
Valori sorgente e valori riletti dalla serie derivata.
Valori sorgente e valori riletti dalla serie derivata.

La serie riletta contiene i valori convertiti e concorda con il calcolo per le tolleranze scelte.

Errore comune

Pubblicare gli stessi numeri cambiando soltanto l’unità da mV a V moltiplicherebbe il valore fisico per mille. Una conversione richiede sia la trasformazione dei valori sia metadati coerenti. Anche una funzione di conversione corretta va applicata alle variabili e agli assi giusti.

Esercizio

Una lettura sintetica di 2.5 mV viene convertita in volt. Qual è il valore numerico? Quale informazione dovresti conservare insieme alla serie derivata?

Soluzione ragionata

2.5 / 1000 = 0.0025 V. Conserva almeno l’identità della sorgente, l’operazione e le unità di partenza e arrivo; per misure reali conserva anche incertezza, metodo e altre informazioni necessarie alla loro interpretazione.

Nella prossima lezione approfondiremo il writer strutturato e l’annullamento di una pubblicazione incompleta.

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 *