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.

CampioneTemperatura originale (°C)Correzione (°C)Temperatura corretta (°C)
018,00+0,7518,75
120,00+0,7520,75
222,50+0,7523,25
321,00+0,7521,75
419,00+0,7519,75
Media20,10+0,7520,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.

Menu File di GX-TXT Python Script Workspace con New Script.
Figura 1. File e New Script aprono un nuovo sorgente Python nella Session attiva.

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.

Editor Python ad alto contrasto con script di correzione delle temperature.
Figura 2. L’editor High Contrast Dark contiene il programma di calibrazione scientifica.

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.

Python Script Workspace mostra il programma scientifico salvato.
Figura 3. Il sorgente viene salvato nel Registry con versione e API pubbliche richieste.

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.

Script Runner con identificativo e revisione del programma Python.
Figura 4. Script Runner identifica il sorgente Python che sarà eseguito.

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.

Script Runner con Dataset numerico canonico collegato come input measured.
Figura 5. Un Dataset canonico viene collegato all’alias measured nel namespace del modulo.

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.

Script Runner con parametro correction_degC e Output Dataset ID.
Figura 6. La correzione tipizzata 0,75 °C e il nuovo Output Dataset sono configurati prima del Job.

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.

Script Runner riporta Review valid senza invio di un Job.
Figura 7. Validate review controlla input, parametro e output senza avviare il 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.

Script Jobs Manager con il Job Python scientifico completato.
Figura 8. Il Job Python scientifico risulta COMPLETED con exit code zero.

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.

Job Details con risultati numerici e identificativo del Dataset corretto.
Figura 9. Program output mostra cinque temperature corrette, media 20,85 °C e Dataset pubblicato.
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.

Editor Python con lo script scientifico riaperto e conservato.
Figura 10. Il programma salvato viene riaperto dal Registry senza modifiche pendenti.