GX-TXT Python Script Workspace: collegare Dataset di input e scegliere il namespace
Lo Script Runner di GX-TXT permette di associare Dataset scientifici canonici a uno Script Python registrato, senza modificare il codice e senza eseguirlo. Ogni ingresso può avere un Semantic alias, un’etichetta, un Namespace, un Dataset ID e una revisione selezionata. Questo capitolo mostra come comporre, verificare, modificare e rimuovere tali collegamenti dall’interfaccia originale.
1. Perché collegare i Dataset nello Script Runner
Uno Script scientifico può utilizzare dati registrati nella Session corrente, ma il loro collegamento all’esecuzione va definito esplicitamente. Un input binding indica quale Dataset si intende rendere disponibile a uno Script e con quale nome logico. La compilazione della riga non avvia Python e non produce automaticamente nuovi risultati. Consente invece di preparare una richiesta riproducibile.
2. Prerequisiti per la procedura
Aprire Python Script Workspace, scegliere uno Script Python già registrato e verificare di essere nella Session corretta. È inoltre necessario che nella Session esista almeno un Dataset canonico: un file generico non ancora importato non equivale a un Dataset registrato. Il capitolo precedente spiega come identificare lo Script salvato e aprire il Runner sulla sua revisione.
3. Un Dataset canonico ha un’identità stabile
Il Dataset ID identifica un oggetto nel registro della Session; il contenuto può essere conservato dal provider di archiviazione appropriato, per esempio CSV oppure HDF5. La selezione nel Runner usa l’identità canonica, non il percorso fisico del file. Non inserire manualmente percorsi assoluti in luogo degli identificativi mostrati nella combobox.
4. Un esempio di dati sintetici
Per illustrare i controlli si considera una serie di cinque temperature inventate, associate agli indici da 0 a 4. Non sono misure sperimentali e non derivano da un Job. Le unità sono gradi Celsius (degC) e le variabili del Dataset sono sample_index e temperature_c.
| Indice del campione | Temperatura (°C) |
|---|---|
| 0 | 18,0 |
| 1 | 20,0 |
| 2 | 22,0 |
| 3 | 21,0 |
| 4 | 19,0 |
Una correzione successiva di un valore sarà utilizzata per illustrare il controllo delle revisioni.
5. Aprire il Runner sullo Script salvato
Nel Workspace selezionare lo Script desiderato e scegliere Run → Open Script Runner…. In alto appaiono nome, linguaggio, riferimento, versione, revisione e SHA-256 del sorgente registrato. Questi elementi identificano lo Script, non il Dataset di input. La sola apertura del Runner non avvia un Job.

6. Individuare Inputs and output
Nella finestra di revisione espandere Inputs and output ▾, se necessario. Il pannello presenta il comando Add input Dataset e una sezione distinta per le richieste di output. Per il momento lasciare vuoti gli eventuali campi di output: qui ci interessano soltanto i Dataset da utilizzare come ingresso.

7. Aggiungere una riga di ingresso
Premere Add input Dataset. Compare una sezione Input 1 con i controlli di associazione. La nuova riga non implica che sia già stato caricato un Dataset: occorre selezionare un namespace e un identificativo compatibile. In una Session in cui il namespace corrente è base, la riga può inizialmente mostrare proprio base.

8. I quattro campi dell’input
Ogni riga contiene Semantic alias, Display label (optional), Namespace e Dataset ID. I primi due forniscono rispettivamente il nome logico per lo Script e la descrizione visualizzata; gli ultimi due individuano un Dataset nella Session. I quattro campi non sono intercambiabili e non cambiano automaticamente il contenuto del Dataset.
9. Semantic alias: il nome logico
Il campo Semantic alias definisce come distinguere scientificamente un ingresso dagli altri. Per esempio, measured può indicare le osservazioni e reference un secondo insieme di riferimento. Usare nomi univoci e semplici, formati da lettere, cifre e underscore, senza iniziare con una cifra. L’alias non è il Dataset ID e non rinomina alcun Dataset.
10. Display label: una descrizione facoltativa
Display label (optional) può contenere una frase leggibile, come Temperature sintetiche (°C). Questa etichetta aiuta a riconoscere il ruolo del collegamento, ma non sostituisce l’alias e non viene usata come identità canonica. Modificare l’etichetta nell’interfaccia non cambia le unità dichiarate nelle variabili scientifiche del Dataset.
11. Il namespace è un filtro organizzativo
Il campo Namespace seleziona lo spazio organizzativo nel quale cercare un Dataset canonico. I namespace non sono cartelle fisiche né una seconda identità dei dati. GX-TXT distingue, per esempio, base e i namespace dei moduli produttori. È importante scegliere quello in cui si trova realmente il Dataset richiesto.
12. Selezionare il namespace che contiene i dati
Aprire la combobox Namespace della riga e scegliere il namespace appropriato, ad esempio module/analysis.python_script quando l’input proviene dal modulo Python. La lista Dataset ID viene aggiornata per mostrare solo gli oggetti del namespace selezionato; scegliere il namespace non equivale ancora a selezionare un Dataset.

13. Scegliere il Dataset ID esatto
Aprire Dataset ID e selezionare dall’elenco il Dataset che si vuole collegare. Non basta digitare un’etichetta o scegliere il primo nome disponibile: identificare il Dataset corretto è una parte essenziale della revisione. La combobox è associata al catalogo canonico della Session e filtra gli oggetti secondo il namespace della riga.
14. Una selezione completa
Nell’esempio, l’alias measured identifica il ruolo scientifico, l’etichetta descrive le temperature sintetiche e il Dataset ID punta al dato canonico scelto. Il testo sotto la riga conferma il contratto table.generic e indica che è stata acquisita una revisione. Questo messaggio documenta la selezione corrente, non un’esecuzione.

15. Che cosa significa revision captured
Quando si sceglie un Dataset, il Runner acquisisce un riferimento alla sua revisione corrente. Questa informazione consente di riconoscere un cambiamento dei dati o dei metadati rilevanti avvenuto dopo la selezione. Non è la revisione dello Script Python: sorgente e Dataset hanno identità e cronologie proprie.
16. Script, Dataset e input binding sono tre elementi differenti
Lo Script rimane il programma registrato; il Dataset rimane un oggetto canonico conservato nella Session; il binding è la riga che li associa per una futura invocazione. Modificare l’alias o la label non modifica lo Script né il Dataset. Se invece il Dataset cambia, il Runner deve verificare nuovamente l’associazione prima di ammettere un’esecuzione.
17. Usare più ingressi indipendenti
Premendo una seconda volta Add input Dataset compare Input 2, con un nuovo alias iniziale e la propria selezione di namespace. Le righe sono indipendenti: si possono associare dati osservati e di riferimento anche da namespace diversi, purché accessibili. Ogni ingresso deve possedere un alias distinto e una revisione selezionata.

18. Un namespace per ogni riga
Cambiare il namespace di Input 2 non sposta il Dataset utilizzato in Input 1. La selezione agisce soltanto sulla riga interessata; non cambia il Current namespace della Session. Questo permette di preparare invocazioni con input di origine diversa senza riorganizzare il Catalogo.
19. Rimuovere una riga non necessaria
Se una riga è stata aggiunta per errore o non serve, usare il relativo pulsante Remove input. La riga scompare dalla finestra di preparazione. L’operazione non elimina lo Script e soprattutto non cancella il Dataset canonico nella Session. Un’altra riga può continuare a riferirsi allo stesso oggetto.
20. Cambiare namespace cancella la selezione della riga
Supponiamo di avere già scelto un Dataset in un namespace e di cambiare poi Namespace in base. Il Runner svuota Dataset ID e la revisione precedentemente acquisita, perché non può conservare un’identità associata a un namespace diverso. Se non esistono oggetti disponibili, viene mostrato un messaggio appropriato.

21. Conservare alias e label durante il cambio
Il cambio di namespace non richiede di rinominare l’alias semantico né di riscrivere la descrizione, che possono rimanere validi. Tuttavia bisogna selezionare di nuovo il Dataset ID e controllarne la revisione. Una riga con alias corretto ma senza Dataset selezionato non è pronta per una successiva revisione valida.
22. Ripristinare l’associazione corretta
Tornare al namespace dove si trova il Dataset e sceglierlo nuovamente dalla combobox. Il Runner ricostruisce la selezione e acquisisce la revisione corrente. L’operazione non pubblica un nuovo Dataset: ripristina il collegamento fra la riga dello Script Runner e un oggetto già registrato.

23. Quando un Dataset diventa stale
Una selezione può diventare stale quando il Dataset viene aggiornato dopo che il Runner ne ha acquisito la revisione. Nell’esempio illustrativo viene modificato un valore della serie, da 22,0 a 22,5 °C, mantenendo il medesimo Dataset ID. La nuova revisione non deve essere confusa con quella memorizzata nella riga originaria.
24. La revisione non aggiornata viene rifiutata
Con un Dataset cambiato dopo la selezione, Validate review segnala che l’input è stato modificato e richiede di sceglierlo di nuovo. Il messaggio Review needs attention impedisce di trattare una vecchia selezione come ancora valida. Questa verifica non avvia un Job e non sostituisce silenziosamente il Dataset richiesto.

25. Reselezionare il Dataset aggiornato
Riportare l’attenzione su Dataset ID, scegliere nuovamente l’oggetto canonico e verificare che la sua revisione sia stata acquisita. Non è necessario cambiare l’alias, la descrizione o il namespace se questi restano corretti. La nuova selezione rappresenta una decisione esplicita su quale revisione utilizzare.
26. Verificare la revisione aggiornata senza eseguire
Dopo la nuova selezione, Validate review può indicare Review valid. No Job submitted. Questo conferma che i collegamenti attualmente dichiarati superano i controlli di revisione, non che lo Script sia stato eseguito né che siano stati prodotti output. La procedura di invio effettivo di un Job viene trattata separatamente.

27. Remove input non cancella il Dataset
Usare Remove input sulla riga rimasta, quando non occorre più. L’oggetto canonico resta presente nella Session e potrà essere selezionato in una nuova invocazione. Non usare il pulsante di rimozione della riga come procedura di eliminazione dei dati: modifica soltanto la preparazione del Runner.

28. Chiudere il Runner e tornare al codice
Usare Close per tornare al Python Script Workspace. Una riga di input incompleta o cancellata non altera il sorgente Python registrato; il Current namespace della Session non viene spostato dall’uso delle combobox dei singoli ingressi. Nel capitolo successivo verranno illustrati i parametri tipizzati e le dichiarazioni dello Script; il vero Run Job rimane un’azione separata che qui non viene eseguita.
