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.

Script Runner originale con quattro parametri e pulsanti Load parameters e Save parameters as Dataset.
Figura 1. Il Runner espone i parametri tipizzati e i comandi Load parameters e Save parameters as Dataset.

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:

ParametroTipoValore scelto
gaindouble2,25
replicatesinteger5
modechoiceoffset
operatorstringbatch

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.

Script Runner con valori modificati, Dataset ID del preset e relativa etichetta descrittiva.
Figura 2. I valori dello Script sono stati impostati e il Dataset ID scelto prima del salvataggio.

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.

Dialogo Tk originale Add invocation parameter con nome, tipo, valore, Required, Choices e limiti.
Figura 3. Il dialogo originale permette di aggiungere un parametro ulteriore con tipo, default e limiti.

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.

Script Runner con parametro manuale offset double 0.75 e pulsanti Edit e Remove.
Figura 4. L’offset manuale appare tra i parametri aggiuntivi prima della pubblicazione del preset.

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.

Runner con messaggio Parameter Dataset committed, cinque valori tipizzati e nessun Job.
Figura 5. Il salvataggio del Parameter Dataset viene confermato senza avviare alcun Job.

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.

Runner con errore Save parameters as Dataset: Dataset ID già esistente.
Figura 6. Un secondo salvataggio con lo stesso Dataset ID viene rifiutato senza sovrascrivere il preset.

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.

Runner con valori correnti temporanei e senza parametro offset prima di Load parameters.
Figura 7. Le modifiche locali e la rimozione di offset distinguono il buffer corrente dai valori salvati nel preset.

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.

Runner con i cinque valori tipizzati ripristinati e offset manuale riapparso dopo Load.
Figura 8. Load parameters ripristina insieme valori registrati, modalità e parametro manuale offset.

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.

Runner con avviso Parameter Dataset load failed per contratto non compatibile.
Figura 9. Il caricamento di un Dataset numerico ordinario viene rifiutato e i valori correnti restano invariati.

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à.

Runner di altro Script con errore Parameter Dataset has incompatible reference.
Figura 10. Un altro Script non può caricare un preset creato per una diversa identità e schema.

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.

Runner con messaggio Parameter Dataset changed; load it again dopo cambio di revisione.
Figura 11. Validate review riconosce che la revisione del Parameter Dataset è cambiata e richiede un nuovo caricamento.

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.

Runner con preset ricaricato e Validate review valido dopo cambio di namespace del Dataset.
Figura 12. Il preset viene ricaricato correttamente da base, senza alterare la Session o lo Script.

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.

Python Script Workspace originale in tema High Contrast Dark dopo la chiusura del Runner, senza Job.
Figura 13. Dopo la verifica si ritorna al sorgente Python originale in High Contrast Dark.