GX-TXT Python Script Workspace: eseguire uno Script dalla scheda Analysis

Uno Script Python registrato nella Session può essere eseguito anche dalla normale interfaccia Analysis di GX-TXT, senza aprire lo Script Runner. In questo percorso si configurano Script source mode, Session registered script, Working directory, Required GX-TXT APIs e gli eventuali Dataset di ingresso, poi si avvia il calcolo dalla scheda Run. La guida illustra un esperimento sintetico con cinque temperature, due revisioni dello Script e i rapporti di esecuzione originali.

1. Quando utilizzare il modulo Python Script in Analysis

Il Python Script Workspace serve alla scrittura, alla registrazione e alla manutenzione del codice. Il modulo Python Script presente in Analysis, invece, permette di eseguire uno Script della Session attraverso il normale ciclo di calcolo GX-TXT. È lo stesso codice registrato, ma con una modalità di selezione e una presentazione diverse: il modulo usa la configurazione scientifica dell’esperimento e produce un rapporto di esecuzione.

2. Abilitare Python Script nella configurazione

Se il modulo non è attivo, aprire Configuration → Modules, cercare Python Script e scegliere Enable module. Nell’elenco la voce mostra il proprio stato, ad esempio CORE / ON, e la versione installata. L’abilitazione rende disponibile il modulo alla Session; non esegue Python e non crea Dataset. Verificare separatamente la selezione Run / recalculate now.

Configurazione GX-TXT con modulo Python Script 1.6.3 CORE ON.
Figura 1. Python Script 1.6.3 è attivato nella configurazione dei moduli GX-TXT.

3. La Session deve essere quella corretta

Prima di selezionare il programma, controllare quale Session è aperta. Lo Script di Analysis deve avere una registrazione Session valida, non un percorso di file arbitrario. Anche i Dataset da utilizzare devono appartenere alla Session corrente. L’identificativo qualificato dello Script consente a GX-TXT di ritrovare sorgente, versione, revisione e API richieste.

4. Creare uno Script dimostrativo nell’editor

Aprire il Python Script Workspace e utilizzare File → New Script. L’esempio legge cinque temperature sintetiche da un Dataset canonico: 18,0, 20,0, 22,5, 21,0 e 19,0 °C. Le misura non sono dati sperimentali, ma valori scelti per il tutorial. Il programma calcola la media aritmetica, che in questo caso è 20,1 °C.

Editor Python High Contrast Dark con sorgente sintetico per il modulo Analysis.
Figura 2. Il codice Python sintetico viene scritto nell’editor ad alto contrasto.

5. Dichiarare l’API numerica di accesso ai Dataset

Lo Script si basa sul Python Script Client pubblico e usa CANONICAL_DATASET_API_v2, senza chiamare funzioni private del framework. Una dichiarazione esplicita delle API richieste consente al Registry di riconoscere i prerequisiti dello Script prima dell’esecuzione:

from gxtxt import gxtxt_context, gxtxt_api_call, gxtxt_api_require

gxtxt_api_require("CANONICAL_DATASET_API_v2@2")

La dichiarazione viene riconosciuta staticamente da GX-TXT: non avvia il calcolo e non apre il Dataset.

6. Salvare e registrare lo Script della Session

Inserire Script ID, Name, Version e Scope appropriati, quindi scegliere File → Save. Il Registry conserva il sorgente Python, la revisione, lo SHA-256 e le API necessarie. La scheda dell’editor indica che il file è stato salvato. In seguito, se si cambia il codice, il normale salvataggio registra una nuova revisione dello stesso Script.

Editor Python dopo il salvataggio della sorgente con API CANONICAL_DATASET_API_v2.
Figura 3. File Save registra la revisione dello Script e scopre le API pubbliche richieste.

7. Selezionare il modulo dalla scheda Analysis

Aprire Analysis e individuare il riquadro Python Script. Il modulo ha una propria casella Run / recalculate now e una sezione Calculation configuration. In una Session con numerosi moduli è possibile nascondere temporaneamente i pannelli non pertinenti dalla scheda Modules, senza disabilitare i loro servizi o eliminare i risultati precedenti.

8. Scegliere Script source mode

Il campo Script source mode indica come GX-TXT individua il programma. Nel modulo Python installato viene utilizzata la modalità registered_script, cioè una sorgente già presente nel Registry della Session. Non sostituire il riferimento registrato con un percorso di file esterno: il percorso e l’identità dello Script non sono equivalenti.

9. La scelta Session registered script

La combobox Session registered script elenca le sorgenti Python registrate nella Session. Selezionando lo Script previsto, la descrizione mostra lingua, ID, nome, versione, revisione e SHA-256. Controllare questi dati prima di procedere: l’identità visibile permette di distinguere due revisioni dello stesso programma e impedisce di confondere una scheda editor con la sorgente eseguibile selezionata.

Sezione Analysis Python Script con identità dello Script registrato, revisione e API.
Figura 4. La scelta dello Script di Session mostra lingua, versione, revisione, SHA e API richieste.

10. Required GX-TXT APIs viene sincronizzato

La selezione dello Script può compilare automaticamente Required GX-TXT APIs (semicolon-separated) usando le dichiarazioni salvate nel Registry. Per il nostro esempio compare CANONICAL_DATASET_API_v2@2. Non è necessario ricopiare manualmente una lista di API già dichiarate nel sorgente; il contratto effettivo deve essere verificato con la revisione registrata corrente.

11. Working directory: una directory di esecuzione

Working directory (optional) imposta la directory di lavoro della procedura. Se viene specificata, deve essere una posizione ammessa e coerente con la Session e con gli strumenti di analisi. Non confonderla con la cartella del sorgente, con il Dataset canonico o con l’output_dir gestita dal Job. L’output_dir è la destinazione supervisionata in cui l’esecuzione scrive rapporto e file temporanei.

12. La tabella Dataset sources

La sezione Dataset sources (Analysis Source Map API v1) associa un identificativo semantico a un Dataset canonico. Nell’esempio l’ingresso usa Source ID: primary, selezionando un Dataset numerico già registrato. La scelta è effettuata mediante la combobox originale, non scrivendo direttamente percorsi fisici del CSV. Il Dataset può trovarsi nel namespace di un modulo diverso dal namespace corrente della Session.

Riga del modulo Analysis con Source ID primary e Dataset numerico canonico selezionato.
Figura 5. L’Analysis Source Map collega l’ingresso primary al Dataset canonico scelto.

13. Source ID e Dataset ID non sono intercambiabili

primary è il nome logico assegnato all’ingresso del programma. Il Dataset ID identifica invece il contenuto canonico della Session. Nel nostro caso sono presenti le variabili sample_index e temperature_c. Il collegamento rende disponibile al Job un riferimento controllato al Dataset, senza cambiare il suo produttore, il suo contenuto o il namespace della Session.

14. Recuperare l’ingresso tramite gxtxt_context

Durante l’esecuzione reale il contesto pubblico Python espone il Dataset associato all’alias:

context = gxtxt_context()
primary = context["inputs"]["primary"]
dataset_id = primary["dataset_id"]

info = gxtxt_api_call(
    "CANONICAL_DATASET_API_v2", "describe", [dataset_id]
)

Il codice usa l’identificativo ricevuto dal CORE e non presuppone un nome di file né una posizione sul disco. È la Session a controllare quale Dataset corrisponde a quell’ID.

15. Leggere le temperature con Canonical Dataset API v2

Per acquisire la variabile scientifica richiesta si può utilizzare l’operazione pubblica read_range. Si specificano Dataset ID, Variable ID e intervallo delle righe:

block = gxtxt_api_call(
    "CANONICAL_DATASET_API_v2",
    "read_range",
    [dataset_id, ["temperature_c"], 0, int(info["row_count"])]
)

Il risultato espone valori e tipo della variabile secondo il contratto canonico. Non è necessario usare direttamente il parser CSV o interpretare a mano i metadati della Session.

16. Gestire correttamente gli scalari NumPy

Alcuni valori provenienti dal trasporto scientifico possono essere rappresentati da array NumPy con un solo elemento. Convertire direttamente un array non scalare con float(array) può generare avvisi di deprecazione. Una conversione esplicita consente di usare valori numerici Python mantenendo un comportamento chiaro:

samples = [
    float(value.item() if hasattr(value, "item") else value)
    for value in block["temperature_c"]["values"]
]
if len(samples) != 5:
    raise ValueError("Expected five synthetic samples")

mean_c = sum(samples) / len(samples)
print(f"Synthetic mean: {mean_c:.1f} degC")

L’esempio controlla anche il numero di campioni, anziché assumere che la selezione abbia sempre la forma desiderata.

17. Il rapporto e l’output_dir del Job

Il contesto contiene anche output_dir, la directory gestita dal framework per i file della singola esecuzione. È possibile scrivervi un testo riassuntivo:

from pathlib import Path

Path(context["output_dir"]).joinpath("summary.txt").write_text(
    f"Mean: {mean_c:.1f} degC\n", encoding="utf-8"
)

Un file scritto nel Job non è automaticamente un Dataset canonico. La pubblicazione scientifica richiede un’API di registrazione dedicata, illustrata nei capitoli relativi agli output.

18. Preparare il comando nella scheda Run

Dopo avere verificato Script e Dataset, aprire Run. Il comando principale è Run enabled analyses. La pagina contiene anche Execution plan, che dovrebbe riepilogare i moduli selezionati e gli ingressi. Non usare indiscriminatamente Run: accertarsi che i moduli richiesti siano gli unici selezionati e che la Session sia quella corretta.

19. Una limitazione dell’Execution plan

Nella versione descritta, il prospetto Execution plan può non elencare Python Script anche quando il modulo è abilitato, visibile e selezionato per l’elaborazione. Può quindi indicare erroneamente che nessun modulo è pronto. È una discrepanza della presentazione del piano: l’azione Run enabled analyses mantiene il proprio percorso di esecuzione. Prima di usarla, verificare direttamente le scelte nella scheda Analysis e non interpretare lo zero del prospetto come prova che lo Script sia inattivo.

Pagina Run con Execution plan che non mostra Python Script selezionato.
Figura 6. Il prospetto Execution plan può omettere Python Script benché selezionato in Analysis.

20. Avviare l’analisi Python

Premere Run enabled analyses dopo aver controllato la configurazione. GX-TXT prepara il runtime del modulo e avvia la procedura attraverso il proprio supervisore. Durante l’esecuzione la pagina Run presenta il modulo attivo e uno stato come Python Script — Running…. Non è necessario aprire il Python Script Runner e non occorre passare attraverso la Script Library.

Pagina Run originale durante l’esecuzione Python con pulsante Stop e stato Running.
Figura 7. Il comando Run enabled analyses avvia l’elaborazione Python e aggiorna lo stato.

21. La conclusione viene confermata da GX-TXT

Quando il calcolo termina correttamente, lo stato della pagina Run e una finestra informativa indicano che l’analisi selettiva è completata. Queste informazioni attestano la chiusura del percorso Analysis, ma la verifica scientifica deve esaminare anche il rapporto, il sorgente e il contenuto dell’output.

Finestra Tk GX-TXT che indica Selective analysis completed.
Figura 8. GX-TXT conferma la conclusione del primo calcolo con la finestra di stato originale.

22. Leggere il risultato dell’esempio

Il programma ha letto le cinque temperature dal Dataset canonico e stampato la media 20,1 °C, coerente con i valori sintetici di input. Ha confermato anche la directory di lavoro configurata. Nessun nuovo Dataset numerico è stato pubblicato da questa procedura: il calcolo è stato registrato come Job con rapporto e file di output del runtime.

23. Il file python_script_run_report.txt

Il modulo produce un rapporto Python contenente informazioni come stato PASS, linguaggio, modulo, versione, modalità registered_script, riferimento e revisione dello Script, SHA-256 atteso e verificato, runtime Python, API richieste e identificativo della singola esecuzione. Questi campi aiutano a stabilire che il Job ha utilizzato la sorgente prevista.

24. executed_script.py è una copia congelata

La copia executed_script.py conserva il codice effettivamente eseguito. Non va confusa con il sorgente correntemente aperto nell’editor, che potrebbe essere stato modificato in seguito. Una revisione successiva dello Script mantiene il precedente Job e la sua copia di esecuzione: la provenienza scientifica rimane distinta e verificabile.

25. Correggere una conversione senza cambiare i dati

Se il programma genera un avviso legato alla rappresentazione di uno scalare NumPy, modificarne la conversione nell’editor Python, lasciando invariati il Dataset di origine, le API richieste e l’algoritmo della media. Usare il normale File → Save per registrare la sorgente corretta. Non alterare manualmente il contenuto delle copie congelate nei Job precedenti.

Sorgente Python nell’editor con conversione esplicita di valori NumPy a scalari.
Figura 9. L’editor consente di migliorare una conversione numerica senza cambiare gli input.

26. La revisione 2 mantiene la provenienza della revisione 1

Salvando il codice corretto, il Registry assegna una nuova revisione e un nuovo SHA-256 al medesimo Script. Il primo Job conserva la revisione precedente, mentre la nuova esecuzione utilizzerà il sorgente aggiornato. Questo è il vantaggio di lavorare con Script registrati: le revisioni sono esplicite e non cancellano la storia dell’esperimento.

Editor GX-TXT con Script Python aggiornato e salvato come revisione 2.
Figura 10. Una nuova operazione File Save registra la revisione 2 lasciando immutabile la precedente.

27. Ripetere il calcolo dalla pagina Run

Con lo Script aggiornato, tornare alla scheda Run e ripetere l’esecuzione selettiva del modulo Python. Il nuovo Job utilizza la revisione 2, legge lo stesso Dataset e restituisce ancora 20,1 °C, senza l’avviso precedente. Il rapporto originale registra la nuova revisione e il nuovo SHA-256. Il prospetto Execution plan può continuare a omettere il modulo, benché lo stato finale riporti Selective analysis completed.

Pagina Run con la seconda esecuzione Python in corso.
Figura 11. La revisione aggiornata viene eseguita dal normale pulsante della scheda Run.
Pagina Run con stato Selective analysis completed e prospetto senza Python Script.
Figura 12. La seconda Analysis è completata, anche se il prospetto Run continua a omettere Python.

28. Tornare al Workspace e verificare la Session

Dopo avere esaminato rapporto, dati e provenienza, chiudere eventuali finestre di esecuzione e tornare al Python Script Workspace. In High Contrast Dark è possibile riprendere la modifica dei sorgenti. Il modulo Analysis e il Runner rimangono strumenti distinti, basati sullo stesso Registry e sulle API scientifiche pubbliche; lo sviluppo successivo riguarderà gli strumenti di debugging, con nuove procedure autonome.

Python Script Workspace con sorgente Project originale in tema High Contrast Dark.
Figura 13. Conclusa l’esecuzione si può tornare al sorgente nel Python Script Workspace High Contrast Dark.