Pubblicare risultati numerici e output testuali

Al termine di uno script GNU Octave, GX-TXT può conservare due tipi di risultati molto diversi: i dati scientifici strutturati, che un’API di pubblicazione registra come Dataset numerico, e il testo emesso dal programma, che può essere pubblicato come Dataset documentale dalla finestra dei dettagli del Job. La distinzione è importante: un file di log non diventa automaticamente una tabella di misure.

Questa guida utilizza GX-TXT DEV112-P005, Octave Script Workspace 1.8.3 e un esempio sintetico di cinque letture di tensione. I nomi inglesi dei comandi sono quelli visualizzati nella GUI. L’editor impiega High Contrast Dark, mentre le altre finestre mantengono i colori nativi dei controlli Tk/ttk.

1. Preparare uno script che pubblica una serie numerica

Aprire Octave Script Workspace con una Session attiva, scegliere File → New Script, attribuire un identificativo e salvare mediante File → Save. Copiare il seguente esempio, con commenti inglesi, senza riferimenti a strumenti o file esterni.

% Synthetic five-point voltage series; controlled GX-TXT Octave Job.
% Public Script Bridge; no instrument or filesystem paths.
gxtxt_parameter_declare('gain', 'double', 'default', 2.0, ...
                        'min', 0.0, 'max', 4.0, ...
                        'description', 'Synthetic voltage multiplier');
ctx = gxtxt_context();
time_s = [0; 1; 2; 3; 4];
voltage_V = ctx.parameters.gain .* [0.1; 0.2; 0.3; 0.4; 0.5];
if (!gxtxt_api_has_operation('DATASET_PUBLICATION_API_v2', 'publish_series'))
  error('Required Dataset Publication API operation unavailable');
endif
request = struct('dataset_id', 'o26_numeric_calibration', ...
                 'contract', 'table.generic', 'storage', 'csv', ...
                 'x_values', time_s, 'y_values', voltage_V, ...
                 'x_variable', struct('variable_id', 'time_s', ...
                                      'name', 'Elapsed time', 'unit', 's', ...
                                      'semantic_role', 'time'), ...
                 'y_variable', struct('variable_id', 'voltage_V', ...
                                      'name', 'Synthetic voltage', 'unit', 'V', ...
                                      'semantic_role', 'voltage'), ...
                 'notes', 'Five synthetic calibrated readings with numerical provenance');
receipt = gxtxt_api_call('DATASET_PUBLICATION_API_v2', 'publish_series', {request});
disp('O26_NUMERIC_PUBLICATION_COMPLETE');
fprintf('O26_POINT_COUNT=%d\n', numel(voltage_V));
disp(receipt);
Source Octave salvato con cinque campioni sintetici di tensione e la chiamata publish_series della Dataset Publication API v2.
Figura 1 — Lo script Octave salvato, con cinque campioni sintetici e chiamata alla pubblicazione scientifica.

La funzione gxtxt_parameter_declare descrive al Runner il parametro gain come numero double, predefinito a 2,0, con limiti da 0 a 4. gxtxt_context() restituisce il contesto dell’invocazione e consente di leggere il valore convalidato, ctx.parameters.gain. Le coordinate temporali sono 0, 1, 2, 3, 4 secondi; le tensioni ottenute con il moltiplicatore 2 sono 0,2; 0,4; 0,6; 0,8; 1,0 volt.

2. Comprendere le operazioni dell’API pubblica

La condizione gxtxt_api_has_operation(…) controlla che il Bridge gestito esponga effettivamente l’operazione richiesta, prima di tentare una pubblicazione. Se non fosse disponibile, il programma genererebbe un errore esplicito anziché continuare fingendo che il risultato sia stato registrato.

gxtxt_api_call(‘DATASET_PUBLICATION_API_v2’, ‘publish_series’, {request}) invia al servizio pubblico di GX-TXT un dizionario di richiesta composto da:

  • dataset_id: identificativo stabile del Dataset, qui o26_numeric_calibration;
  • contract: table.generic, che identifica una tabella scientifica con variabili;
  • storage: csv, formato canonico del risultato;
  • x_values / y_values: due vettori della stessa lunghezza;
  • x_variable / y_variable: descrittori con identificativo, nome, unità di misura e ruolo semantico.

Solo il completamento effettivo della chiamata di pubblicazione crea il Dataset numerico. La stampa effettuata con disp o fprintf produce invece testo nel log e non è una pubblicazione di misure.

3. Convalidare la richiesta nel Runner

Aprire Run → Open Script Runner…. Controllare gain = 2.0 e, nella sezione Output request (optional), scegliere l’identificativo o26_numeric_calibration, un nome descrittivo e Replace owned output disabilitato. La richiesta esplicita di output non sostituisce il codice che realizza la pubblicazione: indica al Runner quale risultato si desidera registrare.

Premere Validate review. Quando compare Review valid. No Job submitted, i parametri e gli input sono stati convalidati, ma non esiste ancora un nuovo Job. Solo Run Job dà avvio all’esecuzione.

Script Runner con gain 2.0 e l’identificativo o26_numeric_calibration nella Output request convalidati.
Figura 2 — Runner con il parametro gain e l’identificativo del Dataset numerico convalidati.

4. Verificare il completamento del Job scientifico

Dopo Run Job, aprire Run → Script Jobs Manager… e controllare lo stato dell’esecuzione. Nell’esempio è COMPLETED: il codice GNU Octave si è concluso correttamente e la funzione publish_series ha registrato cinque righe scientifiche.

Script Jobs Manager con il Job della pubblicazione numerica nello stato COMPLETED.
Figura 3 — Il Job originale appare in Script Jobs Manager con stato COMPLETED.

Selezionando il Job e scegliendo Jobs → Open execution details si apre lo storico della specifica esecuzione, con revisione del sorgente, identificativo e flussi disponibili.

Execution details con il testo prodotto dal programma e la ricevuta della pubblicazione numerica.
Figura 4 — I dettagli della stessa esecuzione mostrano il testo generato dal programma e la ricevuta della pubblicazione numerica.

Il testo contiene il messaggio O26_NUMERIC_PUBLICATION_COMPLETE, il numero di punti e una ricevuta di pubblicazione. Questo testo è utile per documentare il risultato, ma il Dataset table.generic esiste separatamente nello storage canonico della Session.

5. Pubblicare un flusso del Job come Dataset documentale

Nella finestra Execution details selezionare Program output e premere Publish source as Dataset…. La GUI presenta una richiesta per registrare il flusso conservato come Dataset canonico testuale.

Finestra Publish source as Dataset per registrare il Program output come Dataset canonico testuale.
Figura 5 — Finestra di pubblicazione del Program output come Dataset di testo.

Il comando Publish as canonical text Dataset pubblica il contenuto del flusso scelto. In questo esempio assegniamo il nuovo identificativo o26_stdout_document. Il contratto che ne risulta è document.text, con formato txt, non table.generic.

Importante: la pubblicazione documentale copia il testo prodotto dal Job; non ripete il calcolo Octave e non ricava automaticamente nuove variabili numeriche dal contenuto del log.

6. Gestire gli identificativi non validi

Gli identificativi dei Dataset devono rispettare le regole di GX-TXT. Se nella finestra si inserisce un nome contenente spazi, come invalid text dataset with spaces, la pubblicazione viene rifiutata.

Pubblicazione del documento rifiutata per un identificativo Dataset contenente spazi.
Figura 6 — La GUI rifiuta un identificativo Dataset non valido senza registrare un nuovo risultato.

Correggere il campo con un identificativo valido, per esempio o26_stdout_document, e ripetere Publish as canonical text Dataset. Dopo il commit, la finestra dei dettagli indica che il nuovo Dataset è stato pubblicato dal Program output.

Execution details con la conferma della pubblicazione del Dataset o26_stdout_document dal Program output.
Figura 7 — Conferma della pubblicazione del documento testuale proveniente dal Job.

7. Evitare sovrascritture involontarie

Un ulteriore tentativo di pubblicare lo stesso flusso usando di nuovo o26_stdout_document viene rifiutato perché il Dataset esiste già. La pubblicazione ordinaria non equivale a una richiesta esplicita di sostituzione del Dataset.

Tentativo di ripubblicare il documento con lo stesso identificativo rifiutato perché il Dataset esiste già.
Figura 8 — Il tentativo di pubblicare un secondo documento con lo stesso identificativo non altera quello già registrato.

Quando si desidera conservare un nuovo risultato, scegliere un identificativo diverso e verificare la Session attiva. Un Dataset esistente non deve essere usato come destinazione temporanea del log.

8. Consultare il documento testuale canonico

Il Dataset document.text contiene il flusso stdout completo, non un riassunto del calcolo. La consultazione canonica di GX-TXT lo presenta in sola lettura insieme alle informazioni disponibili sul contratto e sulla provenienza.

Consultazione read-only del Dataset document.text con il contenuto completo del Program output.
Figura 9 — Consultazione read-only del Dataset document.text con il contenuto del Program output.

La registrazione documentale conserva informazioni che collegano il risultato alla sorgente: Job ID, ruolo del flusso stdout, impronta del sorgente eseguito, impronta del flusso e stato di completezza. Questo permette di distinguere un testo proveniente da una specifica esecuzione dal testo scritto direttamente nell’editor.

Il contenuto del documento è identico ai byte stdout conservati dal Job originale. Tuttavia non va trattato come una serie scientifica: per operazioni numeriche occorre aprire il Dataset strutturato.

9. Leggere i cinque punti nel Dataset numerico

Aprire la consultazione canonica del Dataset o26_numeric_calibration e scegliere la scheda Canonical table. Si visualizzano le colonne Elapsed time (s) e Synthetic voltage (V).

Scheda Canonical table del Dataset o26_numeric_calibration con le colonne Elapsed time e Synthetic voltage.
Figura 10 — Tabella canonica con cinque righe, le coordinate temporali e le tensioni numeriche.

La verifica dei punti dà:

Tempo (s)Tensione (V)
00,2
10,4
20,6
30,8
41,0

I valori sono numeri double: l’interfaccia può mostrarne le cifre della rappresentazione in virgola mobile, per esempio 0.20000000000000001. Non si tratta di una sesta misura né di un errore nella calibrazione; la precisione numerica resta quella prevista dal tipo di dato.

10. Consultare schema e provenienza

La scheda Schema and provenance della consultazione scientifica presenta i descrittori delle variabili e le proprietà del Dataset. È il luogo appropriato per distinguere le colonne, le unità, il contratto e le informazioni registrate sul risultato.

Scheda Schema and provenance del Dataset numerico con descrittori delle variabili, unità e contratto.
Figura 11 — Schema e provenienza del Dataset numerico nella consultazione scientifica.

Le due pubblicazioni appartengono alla Session scientifica corrente e al produttore Octave, ma hanno contratti e contenuti differenti. Il Dataset numerico è adatto alla lettura delle variabili time_s e voltage_V; quello testuale è la copia canonica dell’output leggibile da un essere umano. La provenienza permette di risalire all’esecuzione senza confondere questi due livelli.

11. Tornare al sorgente e conservare i risultati

Chiudere le consultazioni dei Dataset e la finestra dei dettagli del Job. Lo storico dell’esecuzione rimane disponibile nel Script Jobs Manager. Per tornare a un editor ampio, nascondere i pannelli opzionali e utilizzare View → Focus source / restore panes.

Editor Octave concentrato sul sorgente salvato dopo la pubblicazione dei due Dataset canonici.
Figura 12 — Editor Octave di nuovo concentrato sul sorgente salvato, dopo la pubblicazione dei due Dataset canonici.

La chiusura delle finestre non elimina il codice registrato, il Job completato o i Dataset. Occorre però distinguere fra gli oggetti conservati: Script Registry memorizza la revisione dello script, Script Jobs memorizza l’identità e i risultati dell’esecuzione, mentre il Dataset Registry identifica i due risultati canonici pubblicati nella Session.

In sintesi, usare publish_series quando il risultato deve rimanere una tabella di variabili e misure, e Publish source as Dataset… quando occorre archiviare in forma documentale un flusso di output già conservato. Il testo di un Job è prezioso come documentazione, ma non sostituisce la pubblicazione dei dati numerici strutturati.