GX-TXT Python Script Workspace: Dataset canonici, calibrazione e pubblicazione numerica
Un esperimento Python completo con un Dataset di temperatura già registrato in GX-TXT, un parametro di calibrazione tipizzato e tre API pubbliche. Il risultato è un nuovo Dataset scientifico con cinque righe, variabili float64, unità esplicite e provenienza verificabile. Non servono strumenti o misure reali.
1. Obiettivo dell’esercitazione
Apriremo un Dataset canonico di cinque temperature sintetiche, applicheremo una correzione di +0,75 °C tramite il servizio numerico pubblico e pubblicheremo una nuova tabella canonica senza modificare il dato di partenza. Utilizzeremo Python Script Workspace, Script Runner, Validate review, Script Jobs Manager e Job Details. È un esempio di elaborazione scientifica tracciabile: dati iniziali, algoritmo, parametri, sorgente e risultato mantengono identità distinte.
2. Le temperature iniziali
Il Dataset contiene valori artificiali, non misure sperimentali. La quinta cifra non è una stima di incertezza: questo esempio non attribuisce incertezze alla correzione.
| Campione | Temperatura originale (°C) | Correzione (°C) | Temperatura corretta (°C) |
|---|---|---|---|
| 0 | 18,00 | +0,75 | 18,75 |
| 1 | 20,00 | +0,75 | 20,75 |
| 2 | 22,50 | +0,75 | 23,25 |
| 3 | 21,00 | +0,75 | 21,75 |
| 4 | 19,00 | +0,75 | 19,75 |
| Media | 20,10 | +0,75 | 20,85 |
La correzione è un offset additivo: T_corretta = T_originale + correzione_degC. Poiché si tratta di una differenza di temperatura, l’offset numerico è espresso in °C, mentre il risultato rimane una temperatura in °C. Non stiamo convertendo Celsius in kelvin.
3. Preparare il Dataset canonico
È necessario disporre di un Dataset table.generic con cinque righe e una variabile temperature_c, float64, unità degC. Nell’esempio il Dataset si chiama p16_synthetic_temperature_series, creato nelle esercitazioni precedenti. La sua seconda colonna contiene 18,0; 20,0; 22,5; 21,0; 19,0. Non occorre ricrearlo né sostituirlo: chi segue la guida può usare un proprio Dataset equivalente, adattando gli identificativi di colonna nel codice.
4. Identità, namespace e revisione
Un Dataset canonico non è soltanto un CSV: ha Dataset ID, namespace, contratto, variabili tipizzate, unità e una revisione riconoscibile. Qui il namespace è module/analysis.python_script. Lo Script Runner registra la revisione selezionata; se il Dataset cambia prima del Job, bisogna rivalidare l’input. L’alias usato dallo script sarà measured, che non coincide con l’ID canonico.
5. Aprire Python Script Workspace e creare uno Script
Aprire la propria Session e scegliere Python Script Workspace. Dal menu File → New Script, creare un nuovo sorgente Python nello scope Session. Come identificativo si può utilizzare w02_canonical_temperature_correction; il nome descrittivo è Temperature correction from canonical Dataset.

6. Versione, descrizione e ambiente di lavoro
Impostare Version a 1.0.0 e una descrizione breve: Typed calibration offset, canonical input and explicit numeric output. La versione semantica non va confusa con la revisione del Registry. Nel tema High Contrast Dark lasciare ampio spazio al codice e chiudere i pannelli non necessari.

7. Il programma Python completo
Copiare nel sorgente il programma seguente. I commenti sono in inglese; il codice impiega esclusivamente il client pubblico gxtxt e le API disponibili nel runtime gestito. Non apre direttamente file del framework, non ricorre a CORE interni e non richiede librerie aggiuntive installate dall’utente.
# Synthetic sensor correction with a canonical numeric GX-TXT input Dataset.
# Read a bounded float64 column, apply a typed calibration parameter, and publish.
from gxtxt import (
gxtxt_api_call,
gxtxt_api_require,
gxtxt_context,
gxtxt_parameter_declare,
)
gxtxt_parameter_declare(
"correction_degC", "double", default=0.0, min=-5.0, max=5.0,
description="Signed temperature correction in degrees Celsius",
)
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
gxtxt_api_require("NUMERIC_API_v1@1:math.numeric")
gxtxt_api_require("DATASET_PUBLICATION_API_v2@2")
context = gxtxt_context()
input_id = context["inputs"]["measured"]["dataset_id"]
correction_degC = float(context["parameters"]["correction_degC"])
output_id = context["output"].get("dataset_id")
if not output_id:
raise ValueError("Review an Output Dataset ID before running")
description = gxtxt_api_call(
"CANONICAL_DATASET_API_v2", "describe", [input_id]
)
columns = {item["variable_id"]: item for item in description["variables"]}
if (
"temperature_c" not in columns
or columns["temperature_c"]["unit"] != "degC"
or columns["temperature_c"]["dtype"] != "float64"
):
raise ValueError("Expected a float64 temperature_c variable in degC")
count = int(description["row_count"])
if count != 5:
raise ValueError("This tutorial expects exactly five samples")
block = gxtxt_api_call(
"CANONICAL_DATASET_API_v2", "read_range",
[input_id, ["temperature_c"], 0, count],
)
raw_c = [
float(value.item() if hasattr(value, "item") else value)
for value in block["temperature_c"]["values"]
]
if len(raw_c) != count:
raise ValueError("The requested canonical range is incomplete")
response = gxtxt_api_call(
"NUMERIC_API_v1", "array_binary",
["add", {"kind": "vector", "value": raw_c},
{"kind": "scalar", "value": correction_degC}],
)
corrected_c = [
float(value.item() if hasattr(value, "item") else value)
for value in response["values"]
]
if len(corrected_c) != count:
raise ValueError("The public numeric operation returned the wrong size")
mean_c = sum(corrected_c) / count
# Begin a new, create-only canonical numeric Dataset, preserving input lineage.
definition = {
"dataset_id": output_id,
"contract": "table.generic",
"storage": "csv",
"producer_version": "1.0.0",
"source_dataset_ids": [input_id],
"source_variable_ids": ["temperature_c"],
"source": "Five synthetic Celsius observations",
"provenance": f"Typed correction {correction_degC:.2f} degC",
"structured_metadata": {"tutorial.synthetic": "true"},
}
writer = gxtxt_api_call("DATASET_PUBLICATION_API_v2", "begin", [definition])
try:
gxtxt_api_call(
"DATASET_PUBLICATION_API_v2", "declare_dimension",
[writer, "row", 0, {"extendible": 1}],
)
for variable_id, name, role in (
("raw_c", "Original temperature", "observation"),
("corrected_c", "Corrected temperature", "derived"),
):
gxtxt_api_call(
"DATASET_PUBLICATION_API_v2", "declare_variable",
[writer, variable_id, {
"name": name,
"dtype": "float64",
"rank": 1,
"dimension_ids": "row",
"coordinate_role": "data",
"semantic_role": role,
"unit": "degC",
}],
)
gxtxt_api_call(
"DATASET_PUBLICATION_API_v2", "append",
[writer, "row", {"raw_c": raw_c, "corrected_c": corrected_c}],
)
published = gxtxt_api_call(
"DATASET_PUBLICATION_API_v2", "finalize", [writer],
)
writer = None
except Exception:
if writer is not None:
gxtxt_api_call("DATASET_PUBLICATION_API_v2", "abort", [writer])
raise
for original, corrected in zip(raw_c, corrected_c):
print(f"W02_SAMPLE {original:.2f} {corrected:.2f}")
print(f"W02_CORRECTION_DEGC {correction_degC:.2f}")
print(f"W02_MEAN_DEGC {mean_c:.2f}")
print("W02_DATASET_COMMITTED", published["dataset_id"])
8. Il client Python pubblico
gxtxt_context() restituisce il contesto del Job: input collegati, parametri efficaci e richiesta di output. gxtxt_api_require() dichiara la dipendenza da una specifica API/versione; non installa pacchetti. gxtxt_api_call(api_id, operation, args) richiama un’operazione registrata con una lista ordinata di argomenti e può segnalare errori del provider. Le dipendenze sono parte del contratto che GX-TXT verifica prima dell’esecuzione.
9. Tre servizi distinti e il loro scopo
CANONICAL_DATASET_API_v2@2 consente di descrivere e leggere dati canonici; NUMERIC_API_v1@1:math.numeric esegue l’operazione numerica vettoriale; DATASET_PUBLICATION_API_v2@2 costruisce e registra un nuovo Dataset strutturato. Il proprietario math.numeric nel requisito numerico identifica il modulo responsabile. Le tre API operano su responsabilità diverse: lettura, calcolo, pubblicazione.
10. Dichiarare un parametro tipizzato
La dichiarazione gxtxt_parameter_declare("correction_degC", "double", default=0.0, min=-5.0, max=5.0, ...) rende riconoscibile al Runner un valore reale modificabile in fase di esecuzione. Il valore iniziale è zero; nell’esercitazione lo imposteremo a 0.75. L’intervallo ammesso è da −5 a +5. Il nome include l’unità per chiarezza didattica, ma la dichiarazione double non assegna automaticamente alcuna semantica fisica al numero.
11. Salvare il sorgente nel Registry
Dal menu File → Save registrare lo Script. Il salvataggio verifica le dichiarazioni letterali e le dipendenze disponibili, senza eseguire il codice. Prima del Job deve esistere un sorgente salvato e non modificato. Versione, revisione e SHA del contenuto consentono di risalire all’esatta versione eseguita.

12. Aprire Script Runner
Scegliere Run → Open Script Runner…. La finestra riporta l’identità del programma, la revisione e le opzioni di esecuzione. Espandere, se necessario, Inputs and output: questi campi sono utili qui, ma non devono rimanere aperti negli screenshot dell’editor dedicati al solo codice.

13. Collegare l’input con Add input Dataset
Premere Add input Dataset, selezionare il namespace module/analysis.python_script e il Dataset p16_synthetic_temperature_series. Impostare l’alias semantico measured; un’etichetta leggibile può essere Synthetic Celsius observations. La scelta della voce Dataset registra anche la revisione corrente del contenuto.

14. Alias dello Script e identificativo canonico
Nel sorgente context["inputs"]["measured"]["dataset_id"] recupera l’ID canonico dal collegamento della finestra Runner. Non bisogna scrivere direttamente nel programma l’ID dell’esempio: l’alias measured permette di riutilizzare il codice con altri Dataset compatibili. Se l’alias della GUI è diverso, anche l’accesso nel codice deve essere adeguato.
15. Verificare schema e unità con describe
La chiamata gxtxt_api_call("CANONICAL_DATASET_API_v2", "describe", [input_id]) restituisce metadati, fra cui row_count e la descrizione delle variabili. Controlliamo che esistano temperature_c, tipo float64, unità degC e cinque righe. Questo controllo è scientificamente significativo: una colonna senza unità o in kelvin non sarebbe automaticamente compatibile con la correzione specificata in °C.
16. Leggere un intervallo con read_range
read_range riceve quattro argomenti posizionali: ID del Dataset, elenco delle variabili richieste, indice iniziale zero-based, numero di righe. Qui leggiamo [input_id, ["temperature_c"], 0, count]. Il risultato è indicizzato per Variable ID: block["temperature_c"]["values"]. La lettura è limitata alle cinque righe necessarie; non richiede percorsi fisici al file canonico.
17. Trattare correttamente i numeri trasportati
Il Bridge può restituire valori Python o elementi NumPy. L’espressione value.item() if hasattr(value, "item") else value estrae lo scalare da un contenitore singolo prima di convertirlo in float. Evita di trattare un array come se fosse già un numero. Le verifiche su cardinalità impediscono di pubblicare silenziosamente una tabella con meno o più righe del previsto.
18. Applicare l’offset con NUMERIC_API_v1
L’operazione array_binary usa ["add", {"kind": "vector", "value": raw_c}, {"kind": "scalar", "value": correction_degC}]. Per una somma, lo scalare viene applicato ai cinque elementi del vettore. Il servizio effettua l’aritmetica, non conosce automaticamente il significato di degC: per questo abbiamo già controllato le unità di ingresso.
19. Definire il Dataset da pubblicare
Il risultato richiesto è w02_temperature_corrected, con contratto table.generic, storage csv, cinque righe e due variabili: raw_c e corrected_c. Entrambe sono float64, rango 1, unità degC; la seconda porta il ruolo semantico derived. La definizione include inoltre source_dataset_ids e source_variable_ids: sono gli identificativi di provenienza del dato da cui siamo partiti.
20. Il ciclo transazionale di pubblicazione
DATASET_PUBLICATION_API_v2/begin avvia un writer per il nuovo ID. declare_dimension definisce una dimensione row estendibile; declare_variable descrive ogni colonna; append aggiunge i cinque valori delle due variabili; finalize completa la registrazione. Se una fase fallisce prima del completamento, abort libera il writer non finalizzato. Questo percorso è diverso da print(), che scrive solo nel log.
21. Impostare correzione e Output Dataset ID
Nel Runner impostare il parametro correction_degC a 0.75, compilare Output Dataset ID con w02_temperature_corrected e mantenere disabilitato Replace existing Dataset. In tal modo la nuova pubblicazione è di tipo create-only: non sovrascrive eventuali risultati precedenti. Il campo di output non crea, da solo, il Dataset; è il programma ad effettuare finalize.

22. Convalidare prima di inviare un Job
Premere Validate review. Il messaggio Review valid. No Job submitted conferma che la configurazione è ammissibile ma non è stato ancora eseguito alcun calcolo. Controllare di nuovo input e revisione, parametro 0.75, ID nuovo e disabilitazione di Replace. Solo dopo questa revisione premere Run Job.

23. Eseguire e controllare Script Jobs Manager
La pressione di Run Job avvia una nuova esecuzione gestita. In Script Jobs Manager verificare che il proprio Job raggiunga lo stato COMPLETED con codice d’uscita 0. Lo stato di accodamento non prova il successo, e la pubblicazione scientifica richiede l’effettiva conclusione della transazione.

24. Interpretare Program output
In Job Details, selezionare Program output. Sono presenti cinque righe W02_SAMPLE, il valore W02_CORRECTION_DEGC 0.75, la media W02_MEAN_DEGC 20.85 e la conferma W02_DATASET_COMMITTED w02_temperature_corrected. Sono messaggi di controllo leggibili dall’utente; per dimostrare l’esistenza del Dataset serve anche leggerlo dal catalogo canonico.

W02_SAMPLE 18.00 18.75
W02_SAMPLE 20.00 20.75
W02_SAMPLE 22.50 23.25
W02_SAMPLE 21.00 21.75
W02_SAMPLE 19.00 19.75
W02_CORRECTION_DEGC 0.75
W02_MEAN_DEGC 20.85
W02_DATASET_COMMITTED w02_temperature_corrected
25. Verificare il Dataset canonico, non soltanto il log
Il Dataset pubblicato contiene realmente cinque righe, due colonne numeriche float64, unità degC per entrambe e ruolo derived per corrected_c. La Canonical Dataset API v2 restituisce esattamente gli originali [18, 20, 22.5, 21, 19] e i corretti [18.75, 20.75, 23.25, 21.75, 19.75]. La media calcolata indipendentemente sui valori canonici è 20,85 °C. Il risultato conserva il riferimento al Dataset sorgente e alla sua variabile temperature_c. Lo Script Registry e lo snapshot immutabile del Job consentono di collegare questo prodotto alla versione del programma e al parametro usato.
26. Chiudere, riaprire e riutilizzare
Chiudere prima Job Details e Runner, poi la scheda del sorgente salvato; riaprirla dal Registry per verificare che il contenuto non sia andato perduto. Il nuovo Dataset rimane nella Session, mentre l’input originale non viene sostituito. Per ripetere il processo con altri dati, cambiare il collegamento dell’alias measured, convalidare lo schema e scegliere un nuovo Output Dataset ID. Questa esercitazione non usa Script Library e non richiede il Debugger: il prossimo tutorial dedicato ai Project affronterà quel percorso separatamente.
