GX-TXT Python Script Workspace: salvare e ricaricare Parameter Dataset tipizzati
Il Parameter Dataset consente di conservare in GX-TXT i valori di un’invocazione Python già verificata, insieme ai tipi, alle dichiarazioni e alla revisione del relativo Script. Lo Script Runner offre Save parameters as Dataset e Load parameters: questi comandi preparano e recuperano configurazioni riproducibili, senza eseguire Python. La guida mostra un insieme di parametri sintetici e i controlli che impediscono di applicare preset incompleti, obsoleti o riferiti a un altro Script.
1. Perché salvare i parametri di una procedura scientifica
Una stessa procedura può essere ripetuta cambiando coefficienti, numero di repliche o modalità di elaborazione. Conservare soltanto il sorgente non documenta quali valori siano stati scelti in una particolare preparazione del calcolo. Un Parameter Dataset conserva un insieme tipizzato di valori per un preciso Script registrato, permettendo di recuperarli per un nuovo controllo prima dell’eventuale esecuzione.
2. Parameter Dataset e Dataset scientifico non sono la stessa cosa
Un Dataset numerico può contenere osservazioni o misure, per esempio una sequenza di temperature. Un Parameter Dataset è invece un Dataset canonico di configurazione, con contratto gxtxt.script_parameters.v1. Le sue variabili descrivono i parametri dell’invocazione. Non va confuso con un Dataset di risultati né con il file Python che realizza l’analisi.
3. Tre identità da conservare distinte
Lo Script è identificato dal riferimento registrato, dalla revisione e dallo SHA-256 del sorgente. Il Parameter Dataset ha un proprio Dataset ID, revisione e integrità del contenuto. Un eventuale Job è una terza entità, creata soltanto con un invio esplicito. Salvare o caricare un preset non modifica la revisione del programma e non crea un Job.
4. Requisiti per utilizzare un preset
Aprire la Session corretta e scegliere nel Python Script Workspace uno Script già salvato. Lo Script dovrebbe dichiarare i suoi parametri tramite gxtxt_parameter_declare() oppure mediante la tabella dei parametri tipizzati dell’editor. Verificare il riferimento, la versione e la revisione del sorgente: un preset può essere recuperato soltanto quando la sua identità e lo schema risultano compatibili con quelli dello Script corrente.
5. Aprire Script Runner e individuare Parameter Dataset
Usare Run → Open Script Runner… con uno Script salvato e non modificato. Il Runner presenta i parametri tipizzati e, sotto di essi, la sezione Parameter Dataset con i campi Dataset ID e Save label (optional). I pulsanti Load parameters e Save parameters as Dataset effettuano operazioni diverse. La loro presenza non significa che un Job sia già stato lanciato.

6. Preparare un esempio sintetico
Consideriamo quattro parametri dello Script: gain di tipo double, replicates di tipo integer, mode di tipo choice e operator di tipo string. Il loro schema è stato registrato insieme al sorgente. Per illustrare il salvataggio, impostiamo valori diversi da alcuni default:
| Parametro | Tipo | Valore scelto |
|---|---|---|
gain | double | 2,25 |
replicates | integer | 5 |
mode | choice | offset |
operator | string | batch |
Sono valori didattici, non misure sperimentali o risultati di un’esecuzione.
7. Compilare i campi tipizzati
Modificare i valori direttamente nel Runner. L’editor numerico applica il tipo e gli eventuali limiti previsti dalla dichiarazione; un campo choice consente soltanto le alternative disponibili. È utile premere Validate review prima del salvataggio: una configurazione che non supera la validazione non dovrebbe essere trattata come un preset pronto all’uso.

8. Aggiungere un parametro valido per una sola invocazione
Per associare anche un coefficiente non presente nello schema registrato, scegliere Add parameter… nella sezione Additional parameters for this invocation. Il dialogo nativo permette di indicare Name, Type, Value, Required, Description, Choices, Minimum e Maximum. Nel nostro esempio aggiungiamo un offset di tipo double, con valore iniziale 0,75 e intervallo ammesso da −2,0 a 2,0.

9. Uno schema aggiuntivo non modifica il sorgente
Dopo Apply, il nuovo offset compare con i pulsanti Edit e Remove. È un parametro manual_invocation, cioè appartenente alla configurazione corrente e non al Registry dello Script. Il salvataggio del Parameter Dataset conserva anche questa dichiarazione aggiuntiva, così che il suo significato e i limiti possano essere ricostruiti durante il caricamento.

10. Dataset ID e Save label hanno funzioni diverse
Nel riquadro Parameter Dataset, inserire un Dataset ID nuovo e valido. L’identificativo è la chiave canonica nella Session; la Save label (optional) è una descrizione per l’utente, che può comunicare il ruolo del preset. Non inserire un percorso di file al posto dell’ID. È preferibile un nome stabile, comprensibile e diverso da quelli già registrati.
11. Salvare con Save parameters as Dataset
Controllati i valori, premere Save parameters as Dataset. Se tutti i vincoli sono rispettati e il Dataset ID è disponibile, GX-TXT pubblica il preset come Dataset canonico. Il Runner conferma l’avvenuto commit con un messaggio che specifica che nessun Job è stato inviato. La procedura non cambia la revisione dello Script Python.

12. Il formato canonico e le variabili salvate
Il Parameter Dataset usa il contratto gxtxt.script_parameters.v1 e contiene una riga di valori. A ogni parametro effettivo corrisponde una variabile stabile, con prefisso p_, per esempio p_gain o p_replicates. Il tipo integer viene conservato come int64, double come float64, mentre string e choice utilizzano variabili testuali. È inoltre presente preset_marker, un marcatore booleano che preserva una riga canonica anche per preset con valori vuoti.
13. Il preset conserva anche le dichiarazioni
Oltre ai cinque valori, i metadati conservano la versione dello schema, il riferimento qualificato dello Script, lo SHA-256, la revisione e le definizioni tipizzate. I parametri provenienti dal Registry e quelli aggiunti manualmente restano distinti come registry_declarations e invocation_declarations. Questo consente al caricamento di ricostruire uno schema effettivo, verificandone origine e compatibilità.
14. Il namespace della pubblicazione
Il salvataggio crea normalmente il Parameter Dataset nel namespace privato del modulo produttore, per esempio quello del modulo di analisi Python. Il namespace è una proprietà organizzativa della Session, non una directory da compilare nel campo Dataset ID. La lettura può utilizzare un preset compatibile anche quando questo è stato spostato legittimamente in un altro namespace della stessa Session; ciò non concede nuovi diritti di scrittura.
15. Un Dataset ID esistente non viene sovrascritto
Se si preme nuovamente Save parameters as Dataset con un identificativo già presente, GX-TXT rifiuta il nuovo commit. Non viene effettuata una sostituzione implicita: il Dataset esistente mantiene revisione, valori e SHA-256. Per salvare una configurazione diversa, scegliere un nuovo Dataset ID anziché contare su un aggiornamento automatico del preset precedente.

16. Modificare i valori correnti prima di caricare
Per comprendere il recupero, cambiare temporaneamente i valori visualizzati: riportare gain a 1,5, replicates a 3, mode a linear, modificare operator e rimuovere la riga offset. Queste operazioni interessano soltanto il Runner; il Parameter Dataset già pubblicato rimane invariato. Il caricamento serve proprio a sostituire questa configurazione locale con quella precedentemente salvata.

17. Utilizzare Load parameters
Inserire nel campo Dataset ID l’identificativo del Parameter Dataset da recuperare e premere Load parameters. GX-TXT controlla l’intero documento, compresi tipo, vincoli, provenienza e integrità, prima di applicare qualunque valore. Se il caricamento riesce, il Runner informa che i valori sono stati caricati e richiede un controllo esplicito prima di un eventuale Run Job.
18. Il caricamento ripristina anche l’offset
Dopo Load parameters ricompaiono i valori gain=2.25, replicates=5, mode=offset e operator=batch, oltre alla riga manuale offset=0.75. Non viene ripristinato soltanto il valore: torna anche la dichiarazione aggiuntiva necessaria per interpretarlo e validarlo. Validate review può quindi confermare che la richiesta è coerente, senza eseguire il programma.

19. I controlli di integrità del caricamento
La lettura richiede un Dataset canonico con il contratto corretto, una riga completa e i Variable ID attesi. Verifica anche i tipi, l’impronta del contenuto, l’identità dello Script e la compatibilità delle dichiarazioni. Un valore mancante o non compatibile provoca un rifiuto, non un caricamento parziale. I valori originali della finestra devono rimanere disponibili quando l’operazione non riesce.
20. Un Dataset numerico ordinario non è un preset
Scegliere per errore l’ID di un Dataset di osservazioni anziché quello di un Parameter Dataset non è sufficiente per il caricamento. Il Runner riconosce che il contratto non è gxtxt.script_parameters.v1 e mostra Parameter Dataset load failed, lasciando invariati i valori correnti. Occorre individuare il vero preset e ripetere Load parameters.

21. Uno Script differente non può usare automaticamente lo stesso preset
Un preset è associato a un preciso riferimento qualificato dello Script e al suo schema. Se viene aperto il Runner di uno Script diverso e si tenta di caricare lo stesso Dataset, compare un messaggio di incompatible reference. Non basta che due programmi abbiano nomi di parametri simili: occorre che l’identità e le dichiarazioni soddisfino integralmente il contratto di compatibilità.

22. Perché la revisione del preset va controllata
Un Parameter Dataset possiede una propria revisione, indipendente dalla revisione del sorgente Python. Dopo il caricamento, il Runner conserva un riferimento alla revisione e allo SHA-256 verificati. Se il Dataset cambia o viene spostato in un diverso namespace con una modifica registrata nei metadati, quell’associazione può diventare stale. Il Runner non deve sostituire automaticamente la revisione precedentemente accettata.
23. Validate review intercetta una revisione cambiata
Supponiamo che il Parameter Dataset venga riorganizzato nella Session dopo essere stato caricato e che cambi il suo token di revisione, pur conservando identità e contenuto numerico. Premendo Validate review, il Runner segnala Parameter Dataset changed; load it again. Il controllo rifiuta la vecchia associazione prima di un Job e richiede una nuova decisione dell’utente.

24. Ricaricare il preset dalla nuova collocazione
Dopo aver verificato l’attuale identità del Dataset, premere di nuovo Load parameters e ripetere Validate review. Un preset compatibile può essere letto anche da un altro namespace della stessa Session; il Current namespace non deve necessariamente coincidere con quello di pubblicazione iniziale. La nuova revisione viene verificata esplicitamente, mentre i valori scientifici rimangono quelli salvati.

25. Cosa succede quando cambia il sorgente Python
Il Parameter Dataset conserva anche lo SHA-256 e la revisione dello Script registrato al momento del salvataggio. Se successivamente lo Script cambia, il caricamento controlla l’attuale sorgente e le dichiarazioni; un preset non più compatibile viene rifiutato. È preferibile creare un nuovo preset per la revisione attuale, invece di alterare manualmente i metadati del precedente. L’identità verificata protegge da esecuzioni con parametri appartenenti a un’altra versione del programma.
26. I valori caricati restano modificabili
Dopo Load parameters, i campi del Runner restano disponibili. È possibile effettuare nuove correzioni, rispettando i vincoli dello schema; ciò non modifica il Dataset già salvato. Se si desidera conservare anche la nuova configurazione, serve un Dataset ID differente e un nuovo salvataggio esplicito. Validate review controlla la preparazione corrente, mentre Run Job è un comando separato.
27. I parametri nel contesto di esecuzione
In una reale esecuzione Python, i valori effettivi sono disponibili attraverso l’API pubblica:
from gxtxt import gxtxt_context
context = gxtxt_context()
parameters = context["parameters"]
gain = parameters["gain"]
replicates = parameters["replicates"]
L’eventuale provenienza del Parameter Dataset viene conservata nel contesto di esecuzione e nella tracciabilità del Job. Questo esempio descrive come leggere i valori quando un Job viene realmente eseguito: non è necessario avviarlo per salvare, caricare o validare un preset.
28. Chiudere il Runner senza eseguire Python
Al termine, controllare l’identità dello Script, il Dataset ID del preset, i parametri recuperati e lo stato di Validate review. Premere Close per tornare all’editor Python, preferibilmente con i pannelli inutili chiusi e in High Contrast Dark. Il salvataggio, il caricamento e la verifica del Parameter Dataset sono operazioni di preparazione: non hanno bisogno di avviare uno Script o generare un Dataset di risultati. La successiva guida mostrerà come configurare la richiesta di output, validare e avviare consapevolmente un Job.
