Trasformazioni di Dataset: descrizione e piano
Corso Python scientifico in GX-TXT · Modulo 7 · Lezione 39
Prima di trasformare un Dataset è utile descrivere cosa vogliamo
ottenere e controllare le precondizioni. In questa lezione prepariamo
una proiezione delle variabili tempo e segnale
della serie sintetica, senza creare ancora il Dataset di
destinazione.
Obiettivi
- Scoprire un’operazione tramite l’API pubblica.
- Comporre un manifest con sorgente, variabili e destinazione.
- Validare e pianificare la trasformazione.
- Distinguere un piano pronto da un risultato pubblicato.
Manifest e contratto
Una trasformazione può essere vista come una sequenza: identificare
la sorgente, dichiarare l’operazione, controllare schema e unità, infine
eseguire. Il manifest è un dizionario che descrive la richiesta. In
questo esempio project_variables seleziona le due variabili
del Dataset sintetico e mantiene l’ordine delle righe. Non è prevista
interpolazione.
Esecuzione
Nella Sessione corso_python, importa piano_trasformazione.py,
salvalo e avvialo da Run → Open Script Runner → Run
Job. L’ID proposto per l’output deve essere libero perché la
trasformazione crea un nuovo Dataset.

from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("DATASET_TRANSFORM_API_v1@1")
api = "DATASET_TRANSFORM_API_v1"
manifest = {"api_version": 1, "operation": "project_variables",
"sources": [{"dataset_id": "corso_python_serie_sintetica", "variable_ids": ["tempo", "segnale"]}],
"output": {"dataset_id": "corso_python_proiezione", "contract": "auto", "storage": "auto"},
"options": {}, "schema_policy": {}, "metadata_policy": "inherit_single_source"}
print("Operazione disponibile:", "project_variables" in gxtxt_api_call(api, "operations", []))
descrizione = gxtxt_api_call(api, "describe_operation", ["project_variables"])
print("Interpolazione:", descrizione["interpolation"])
controllo = gxtxt_api_call(api, "validate", [manifest])
print("Valido:", controllo["valid"], "righe:", controllo["row_count"])
print("Variabili e unita:", [(v["variable_id"], v["unit"]) for v in controllo["variables"]])
piano = gxtxt_api_call(api, "plan", [manifest])
try:
print("Stato del piano:", piano["status"])
finally:
gxtxt_api_call(api, "release_plan", [piano["plan_id"]])
operations elenca le operazioni disponibili;
describe_operation descrive il contratto di quella scelta.
validate controlla la richiesta e restituisce, tra le altre
informazioni, validità, numero di righe e schema previsto.
plan prepara un piano utilizzabile nell’esecuzione
corrente; il blocco finally lo rilascia quando abbiamo
finito.

Il risultato riporta quattro righe e le variabili tempo
in s e segnale in mV.
ready significa che il piano è pronto; non
significa che l’output sia stato pubblicato. In questa lezione
non chiamiamo execute. I dati restano sintetici e la
proiezione non inventa nuovi campioni.
Errori da evitare
Non dedurre la sintassi di una trasformazione dal solo nome: consulta il descrittore e il contratto del manifest. Un ID di variabile inesistente, una destinazione già occupata o unità incompatibili richiedono di correggere la richiesta. Non confondere un controllo di schema con una verifica del significato scientifico.
Esercizio
- Qual è la sorgente e quale l’ID proposto per il risultato?
- Quante righe sono previste dal piano?
- Il piano
readyha già creato il Dataset di output?
Soluzione ragionata
- Sorgente
corso_python_serie_sintetica; output propostocorso_python_proiezione. - Quattro.
- No: per pubblicare serve l’esecuzione della trasformazione.
Nella prossima lezione eseguiremo una proiezione e confronteremo il risultato con la sorgente.