Lezione 05: Dataset scientifici e Variable ID

Nelle lezioni precedenti abbiamo imparato a utilizzare GNU Octave per eseguire calcoli, manipolare vettori e matrici e costruire semplici programmi scientifici. Ora iniziamo a lavorare con uno degli elementi fondamentali di GX-TXT: i Dataset scientifici.

Quando si analizzano dati sperimentali, non è sufficiente disporre di una sequenza di numeri. È necessario conoscere la loro origine, il significato delle variabili, le unità di misura, l’organizzazione dei dati e le informazioni che permettono di identificarli senza ambiguità.

GX-TXT gestisce questi aspetti attraverso Dataset canonici, identificativi stabili e metadati strutturati. In questa lezione impareremo a esplorarli direttamente da uno script GNU Octave, utilizzando esclusivamente le API pubbliche del framework.

L’esperimento sarà eseguito su misure reali già importate in GX-TXT, senza creare Dataset artificiali e senza modificare i dati originali.

1. Obiettivi della lezione

Al termine dell’esercitazione saremo in grado di:

• Comprendere cosa rappresenta un Dataset canonico all’interno di una Session GX-TXT.
• Distinguere il Dataset ID dal nome visualizzato nell’interfaccia.
• Comprendere la differenza tra Variable ID, nome canonico e descrizione della variabile.
• Esplorare le proprietà di un Dataset attraverso le API pubbliche.
• Utilizzare le strutture (struct) e le celle (cell array) di Octave per interpretare i risultati restituiti dal framework.
• Esaminare tipo numerico, dimensioni, unità e relazioni fra variabili senza leggere direttamente i file che contengono i dati.

Il nostro script funzionerà come un piccolo ispettore di Dataset, capace di interrogare GX-TXT e produrre un resoconto delle informazioni scientifiche disponibili.

2. Partiamo da un Dataset sperimentale reale

Per questa esercitazione utilizziamo un Dataset contenente misure di corrente elettrica registrate nel tempo e importate in una Session GX-TXT.

Il Dataset è identificato dal codice meas0195 e contiene 942 righe di dati, conservate dal framework attraverso il provider CSV.

La prima operazione consiste nell’osservare i dati attraverso l’interfaccia grafica di GX-TXT, prima ancora di eseguire lo script.

Il grafico mostra una fase iniziale a corrente relativamente bassa, seguita da un aumento progressivo fino a una regione quasi stazionaria. Verso la fine della registrazione si osserva una brusca diminuzione della corrente.

In questa lezione non cercheremo di interpretare il fenomeno fisico responsabile dell’andamento osservato. Il nostro interesse è capire come GX-TXT organizza, identifica e descrive le informazioni che rendono possibile questa rappresentazione.

3. Dalla rappresentazione grafica alla tabella canonica

La curva appena osservata è una rappresentazione dei dati. Il Dataset, tuttavia, contiene anche una struttura canonica che possiamo esaminare attraverso la relativa tabella.

Aprendo la vista Canonical table troviamo tre colonne di variabili scientifiche:

• timestamp_s: valori temporali registrati.
• time_s: tempo trascorso, utilizzato nell’anteprima come coordinata orizzontale.
• current_A: corrente misurata, utilizzata come coordinata verticale.

Questi nomi consentono di riconoscere facilmente il contenuto delle colonne, ma introducono una distinzione importante.

Il nome di una colonna non è necessariamente l’identificativo stabile della variabile.

GX-TXT associa infatti a ciascuna variabile un Variable ID, indipendente dal nome utilizzato per visualizzarla.

Nel nostro Dataset, gli identificativi osservati sono:

Nome canonico	Variable ID
timestamp_s	v0001
time_s	v0002
current_A	v0003

Il Dataset nel suo insieme possiede invece l’identificativo meas0195.

Una variabile può quindi essere identificata attraverso la coppia:

(dataset_id, variable_id)

Per esempio, (meas0195, v0001) individua la prima variabile del nostro Dataset.

Questa distinzione è fondamentale: uno script scientifico deve fare riferimento agli identificativi previsti dal framework, senza dipendere dalla posizione delle colonne o dai loro nomi descrittivi.

C’è inoltre un altro aspetto da ricordare: il nome di una variabile non sostituisce i suoi metadati. Anche quando un nome contiene un riferimento apparente a un’unità fisica, l’unità effettivamente dichiarata deve essere verificata nello schema della variabile.

Nella prossima parte vedremo come ottenere tutte queste informazioni direttamente con GNU Octave, attraverso lo Script Bridge e le API pubbliche GX-TXT.

4. Preparazione dello script GNU Octave in GX-TXT

Ora che abbiamo osservato il Dataset e compreso la differenza fra i nomi delle variabili e i loro identificativi, possiamo iniziare a interrogarlo attraverso GNU Octave.

Per questa esercitazione utilizziamo lo script GXTXT_Octave_L05.m, sviluppato appositamente per esplorare i Dataset canonici e i loro metadati.

Lo script è un Dataset Inspector, ossia uno strumento che permette di ottenere informazioni sui Dataset e sulle variabili senza modificare i dati scientifici originali.

Apriamo lo Script Workspace di GX-TXT, importiamo il file .m e lo registriamo nella Session utilizzata per l’esperimento.

I dati di registrazione sono:

Proprietà	Valore
Script name	GXTXT_Octave_L05.m
Script ID	session:lesson05_1
Language	GNU Octave
Version	1.0.0
Scope	Session
Description	Lesson 05 – Canonical Dataset and Variable ID Inspector

È importante distinguere lo Script ID dal Dataset ID: il primo identifica lo script registrato nell’ambiente GX-TXT, mentre il secondo identifica il Dataset scientifico che vogliamo esplorare.

Nel nostro esempio, lo script è identificato da session:lesson05_1, mentre il Dataset sperimentale è meas0195. Sono due identificativi appartenenti a sistemi diversi, con scopi differenti.

Lo script non richiede di conoscere in anticipo il nome dei file CSV, i percorsi delle directory o la posizione delle colonne. Le informazioni necessarie vengono richieste al framework attraverso le sue API pubbliche.

5. Lo Script Bridge: come Octave comunica con GX-TXT

GNU Octave è un linguaggio di programmazione numerica autonomo. Tuttavia, quando uno script viene eseguito all’interno di GX-TXT, può utilizzare funzionalità aggiuntive offerte dal framework.

Questa comunicazione avviene attraverso lo Octave Script Bridge API v1.

Lo Script Bridge costituisce l’interfaccia pubblica che consente a uno script di individuare e richiamare le operazioni GX-TXT autorizzate per l’esecuzione.

Il meccanismo può essere riassunto così:

Script GNU Octave → Script Bridge → API pubblica GX-TXT → servizio del framework → risultato restituito a Octave

Non è necessario conoscere l’implementazione interna dei servizi o il formato fisico dei file utilizzati da GX-TXT. È sufficiente conoscere l’identificativo dell’API, l’operazione richiesta e gli argomenti da fornire.

Il framework provvede ad avviare lo Script Bridge quando viene eseguito uno script registrato e a chiuderlo al termine dell’esecuzione. Queste operazioni non devono essere effettuate manualmente dal nostro codice.

5.1 Verificare le API necessarie

Prima di interrogare un Dataset, è opportuno verificare che le API di cui abbiamo bisogno siano disponibili.

Nel nostro script definiamo due variabili:

dataset_api = 'CANONICAL_DATASET_API_v2';
schema_api = 'DATASET_VARIABLE_SCHEMA_API_v3';

Sono semplici variabili Octave contenenti stringhe. Le stringhe identificano due API pubbliche registrate nel framework.

La prima gestisce l’accesso ai Dataset canonici; la seconda permette di esaminare le informazioni strutturate associate alle loro variabili.

Utilizziamo quindi:

gxtxt_api_require({dataset_api, schema_api});

La funzione gxtxt_api_require() verifica che le dipendenze API dichiarate siano soddisfatte. In caso contrario, produce un errore esplicito invece di consentire allo script di continuare con funzionalità mancanti.

Le parentesi graffe {} indicano una cell array di Octave, una struttura che permette di raggruppare valori in elementi distinti. In questo caso contiene i due identificativi delle API.

La disponibilità di un’API, tuttavia, non significa necessariamente che ogni sua operazione sia utilizzabile.

Per questo motivo impieghiamo anche gxtxt_api_has_operation(), che controlla la disponibilità di una specifica operazione pubblica:

gxtxt_api_has_operation(dataset_api, 'list')

Il risultato è un valore logico che indica se l’operazione list è disponibile attraverso lo Script Bridge.

Questa verifica rende lo script più robusto rispetto alle differenze tra versioni e configurazioni del framework.

5.2 Consultare la descrizione pubblica di un’API

Un’altra funzione utile è:

dataset_api_info = gxtxt_api_describe(dataset_api);

gxtxt_api_describe() restituisce una struttura descrittiva dell’API registrata, comprendente informazioni come versione, provider, documentazione e operazioni disponibili.

Il risultato viene memorizzato in una variabile Octave e può essere esaminato mediante le normali operazioni sulle strutture.

Per esempio, se il campo documentation_ref è presente, esso identifica il riferimento alla documentazione dell’API.

Questa possibilità è particolarmente utile in un ambiente scientifico: uno script può verificare le caratteristiche delle interfacce effettivamente registrate, anziché presumere che tutte le installazioni di GX-TXT siano identiche.

6. Le API pubbliche per esplorare Dataset e variabili

Per svolgere l’esperimento utilizziamo due API scientifiche distinte.

6.1 CANONICAL_DATASET_API_v2

Questa API fornisce un’interfaccia canonica per individuare e accedere ai Dataset della Session corrente, indipendentemente dai dettagli del provider di memorizzazione.

Nella nostra lezione utilizziamo due operazioni.

Operazione	Argomenti	Risultato
list	Nessuno	Elenco dei Dataset ID disponibili
describe	Dataset ID	Struttura contenente metadati del Dataset

L’operazione list viene invocata attraverso la funzione generale gxtxt_api_call():

dataset_ids = gxtxt_api_call( ...
    'CANONICAL_DATASET_API_v2', 'list', {});

La chiamata richiede tre elementi: identificativo dell’API, nome dell’operazione e argomenti.

In questo caso l’ultima cell array è vuota, perché l’operazione list non richiede parametri.

Il risultato è una cell array contenente gli identificativi dei Dataset presenti nella Session.

Per ottenere il primo identificativo possiamo utilizzare:

dataset_id = dataset_ids{1};

In Octave, l’espressione {1} estrae il contenuto della prima cella, mentre (1) restituirebbe una cell array contenente soltanto quella cella.

È una distinzione essenziale quando si utilizzano le API GX-TXT.

Nel nostro esperimento l’identificativo individuato è meas0195.

Possiamo quindi ottenere la descrizione del Dataset:

dataset_info = gxtxt_api_call( ...
    'CANONICAL_DATASET_API_v2', ...
    'describe', {dataset_id});

Il risultato è una struttura Octave contenente i metadati del Dataset.

Tra le informazioni effettivamente ottenute troviamo:

Campo	Valore
dataset_id	meas0195
format	csv
storage_provider	csv
row_count	942
contract	table.generic

Questi valori provengono direttamente dal framework. Non sono stati ricavati dall’apertura manuale del file CSV.

6.2 DATASET_VARIABLE_SCHEMA_API_v3

Un Dataset può contenere variabili numeriche, testuali o multidimensionali. Per identificarle correttamente non basta conoscere il nome della colonna: occorre esaminare lo schema associato a ciascuna variabile.

La Dataset Variable Schema API v3 rende disponibili queste informazioni.

Per questa lezione utilizziamo due operazioni:

Operazione	Argomenti	Risultato
list	Dataset ID	Elenco delle strutture descrittive delle variabili
get	Dataset ID, Variable ID	Descrizione della variabile richiesta

La prima chiamata è:

variables = gxtxt_api_call( ...
    'DATASET_VARIABLE_SCHEMA_API_v3', ...
    'list', {dataset_id});

La funzione restituisce una cell array i cui elementi sono strutture contenenti i descrittori delle variabili.

Ogni descrittore possiede un identificativo stabile variable_id.

Possiamo, per esempio, esaminare il primo elemento:

first_variable = variables{1};
variable_id = first_variable.variable_id;

La prima istruzione estrae una struttura dalla cell array; la seconda accede al campo variable_id attraverso l’operatore punto ..

Una volta ottenuto l’identificativo reale, possiamo interrogare direttamente la variabile:

descriptor = gxtxt_api_call( ...
    'DATASET_VARIABLE_SCHEMA_API_v3', ...
    'get', {dataset_id, variable_id});

Questa operazione restituisce i metadati della singola variabile, tra cui tipo di dato, numero di dimensioni, forma, unità dichiarate e relazioni con altre variabili, quando disponibili.

È importante non inventare un Variable ID e non ricavarlo dal nome visualizzato. Il nostro script utilizza esclusivamente gli identificativi restituiti dalle API del framework.

Nella prossima sezione analizzeremo il codice completo del Dataset Inspector, soffermandoci sulle istruzioni Octave utilizzate per controllare, attraversare e interpretare le strutture restituite dalle API.

7. Analisi didattica dello script: lavorare con i metadati scientifici

Nelle lezioni precedenti abbiamo già incontrato i principali costrutti del linguaggio GNU Octave: variabili, vettori, matrici, strutture, condizioni, cicli e gestione degli errori.

Non è necessario riprenderli da zero. Il nostro obiettivo è ora capire come utilizzarli per elaborare le informazioni restituite dalle API di GX-TXT.

Il Dataset Inspector introduce soprattutto un nuovo problema di programmazione: ricevere dati strutturati da un servizio esterno, verificarne il contenuto e individuare informazioni precise senza fare ipotesi sulla loro organizzazione.

7.1 Verificare il tipo di risultato: iscell()

Abbiamo già incontrato le cell array nella Lezione 02. Qui impariamo a verificare che una funzione restituisca effettivamente il tipo di dato previsto.

Dopo aver richiesto l’elenco dei Dataset, lo script esegue:

dataset_ids = gxtxt_api_call(dataset_api, 'list', {});

if (!iscell(dataset_ids))
  error('Unexpected Dataset list result: expected a cell array');
endif

La funzione iscell() è una funzione nativa di GNU Octave che restituisce un valore logico:

• true quando l’argomento è una cell array.
• false quando appartiene a un altro tipo.

Per esempio:

iscell({'v0001', 'v0002'})
iscell([1, 2, 3])

La prima espressione restituisce true, mentre la seconda restituisce false, perché le parentesi quadre costruiscono un vettore numerico.

Il controllo è importante perché l’operazione pubblica CANONICAL_DATASET_API_v2/list prevede un risultato in forma di cell array contenente Dataset ID.

Se la risposta non rispetta il contratto, lo script si interrompe esplicitamente. Non tenta di interpretare arbitrariamente una struttura inattesa.

Lo stesso controllo viene effettuato sull’elenco delle variabili restituito da DATASET_VARIABLE_SCHEMA_API_v3/list.

7.2 Preparare una raccolta di identificativi con cell() e size()

Nella Lezione 03 abbiamo utilizzato le dimensioni di vettori e matrici. In questo script incontriamo una nuova applicazione di size() insieme alla funzione cell().

Dopo aver ottenuto i descrittori delle variabili, troviamo:

variable_ids = cell(size(variables));

Questa istruzione combina due funzioni native.

size(variables) restituisce le dimensioni della cell array variables.

cell(...) crea una nuova cell array vuota con le dimensioni indicate.

Se variables è una cell array di tre elementi disposti su una riga, anche variable_ids sarà una cell array di tre elementi con la stessa organizzazione.

La nuova raccolta viene quindi popolata attraversando i descrittori:

for k = 1:numel(variables)
  item = variables{k};

  if (!isstruct(item) || !isfield(item, 'variable_id'))
    error('Variable descriptor %d has no stable variable_id field', k);
  endif

  variable_ids{k} = item.variable_id;
endfor

Non ci soffermiamo nuovamente sul funzionamento del ciclo for o sulle strutture, già studiati.

Osserviamo invece la trasformazione effettuata:

• variables contiene descrittori completi, ciascuno con diversi campi scientifici.
• variable_ids contiene soltanto gli identificativi estratti da quei descrittori.

Nel nostro esperimento, il risultato corrisponde a:

variable_ids = {'v0001', 'v0002', 'v0003'};

Questa è una tecnica utile nella programmazione scientifica: estrarre una raccolta di identificativi da una raccolta di oggetti più complessi, mantenendo separati i dati descrittivi dalle loro identità.

7.3 Cercare un identificativo con strcmp() e find()

Una delle operazioni più importanti dello script è la ricerca di un Dataset specifico.

Finché target_dataset_id è vuoto, viene selezionato il primo Dataset disponibile. Ma possiamo anche richiedere esplicitamente un identificativo, per esempio meas0195.

In questo caso lo script utilizza:

index = find(strcmp(dataset_ids, target_dataset_id), 1);

Questa istruzione contiene due funzioni che meritano di essere approfondite.

strcmp() — Confrontare stringhe

La funzione confronta il contenuto di due stringhe e restituisce un risultato logico.

Per esempio:

strcmp('meas0195', 'meas0195')
strcmp('meas0195', 'meas0196')

La prima espressione restituisce true, la seconda false.

Quando il primo argomento è una cell array di stringhe, strcmp() può confrontare ciascun elemento con una stringa di riferimento.

Immaginiamo:

dataset_ids = {'meas0180', 'meas0195', 'meas0200'};
target_dataset_id = 'meas0195';

matches = strcmp(dataset_ids, target_dataset_id);

Otteniamo:

0   1   0

Il secondo elemento corrisponde all’identificativo richiesto.

find() — Individuare la posizione

La funzione find() restituisce gli indici degli elementi che soddisfano una condizione.

Nel nostro esempio:

index = find(matches, 1);

Il risultato è 2.

Il secondo argomento, 1, indica che vogliamo soltanto la prima corrispondenza.

Possiamo quindi estrarre l’identificativo:

dataset_id = dataset_ids{index};

Il vantaggio è evidente: non abbiamo bisogno di sapere in quale posizione si trovi un determinato Dataset.

Se l’identificativo non esiste, find() restituisce un array vuoto. Lo script riconosce questa condizione e genera un errore, invece di selezionare silenziosamente un Dataset differente.

La stessa tecnica viene utilizzata per cercare un Variable ID all’interno dell’elenco delle variabili del Dataset selezionato.

7.4 Accedere dinamicamente ai campi di una struttura: .(key)

Nella Lezione 02 abbiamo imparato a leggere i campi delle strutture con l’operatore punto.

Per esempio:

measurement.unit

Questa sintassi è appropriata quando conosciamo già il nome del campo.

Nel Dataset Inspector incontriamo una situazione diversa: vogliamo esaminare successivamente un insieme di campi, i cui nomi sono memorizzati in una cell array.

Lo script contiene:

dataset_fields = {'dataset_id', 'format', 'storage_provider', ...
                  'row_count', 'contract'};

for k = 1:numel(dataset_fields)
  key = dataset_fields{k};

  if (isfield(dataset_info, key))
    printf('  %-22s : ', key);
    disp(dataset_info.(key));
  else
    printf('  %-22s : (not declared)\n', key);
  endif
endfor

La novità principale è l’espressione:

dataset_info.(key)

Le parentesi dopo il punto indicano che il nome del campo deve essere ricavato dal contenuto della variabile key.

Se key contiene row_count, l’espressione è equivalente a:

dataset_info.row_count

Se nella successiva iterazione key contiene format, verrà letto invece:

dataset_info.format

Questa tecnica prende il nome di accesso dinamico ai campi di una struttura.

È particolarmente utile per esaminare metadati perché permette di utilizzare un unico blocco di codice per molti campi differenti.

La funzione isfield(), già introdotta nella Lezione 02, viene riutilizzata per evitare l’accesso a campi inesistenti.

Infine, disp() visualizza il valore restituito senza richiedere di conoscerne anticipatamente il tipo. È una scelta pratica perché alcuni campi possono contenere stringhe, altri numeri e altri ancora raccolte di valori.

7.5 Distinguere un campo assente da un campo vuoto

Questo è uno degli aspetti scientificamente più importanti della lezione.

Un metadato può trovarsi in almeno tre situazioni differenti:

Situazione	Significato
Campo presente con valore	Il metadato contiene un’informazione dichiarata
Campo presente ma vuoto	Il campo esiste, ma non contiene un valore
Campo assente	Il descrittore non contiene quel campo

Lo script mantiene esplicitamente questa distinzione:

if (isfield(descriptor, key))
  value = descriptor.(key);

  if (isempty(value))
    printf('(empty)\n');
  else
    disp(value);
  endif
else
  printf('  %-25s : (not declared)\n', key);
endif

La funzione isempty() verifica se un valore contiene zero elementi.

È importante comprendere che un campo vuoto non è necessariamente un errore. Molti metadati scientifici sono opzionali e possono non essere compilati.

Nel nostro esperimento, per la variabile v0001, GX-TXT restituisce:

variable_id   : v0001
canonical     : timestamp_s
unit          : (empty)
dtype         : float64
rank          : 1
shape         : 942
dimension_ids : row

Osserviamo il campo unit.

Il nome canonico è timestamp_s, ma il metadato unit è vuoto.

Non possiamo quindi affermare che il Dataset dichiari formalmente l’unità di misura s soltanto perché compare nel nome della variabile.

Una convenzione di denominazione non sostituisce una dichiarazione di metadati.

Questa distinzione diventerà essenziale quando lavoreremo con conversioni di unità, coordinate temporali e confronti fra Dataset provenienti da strumenti differenti.

7.6 Interpretare dtype, rank e shape

Lo schema restituito da GX-TXT non contiene soltanto i nomi delle variabili. Può descrivere anche l’organizzazione dei dati.

Nel caso reale della variabile v0001 abbiamo:

Campo	Valore	Interpretazione
dtype	float64	Tipo numerico dichiarato: virgola mobile a 64 bit
rank	1	La variabile possiede una dimensione
shape	942	La dimensione dichiarata contiene 942 elementi
dimension_ids	row	Identificativo logico della dimensione
coordinate_role	data	Ruolo dichiarato nello schema
axis_kind	explicit	Modalità di rappresentazione dell’asse dichiarata nello schema

Non dobbiamo confondere rank con il rango di una matrice nel senso dell’algebra lineare: in questo contesto indica il numero di dimensioni dell’array.

Analogamente, shape descrive le dimensioni della variabile e non i valori numerici contenuti nelle misure.

Lo script sta quindi leggendo una descrizione strutturale, non i 942 valori della colonna.

Questa è proprio la distinzione fra ispezione dei metadati e lettura dei dati scientifici, che approfondiremo nella Lezione 06.

7.7 Propagare correttamente gli errori con rethrow()

Abbiamo già studiato try e catch nella Lezione 02. Qui introduciamo un ulteriore dettaglio: come conservare l’errore originale dopo aver aggiunto un messaggio diagnostico.

Il nostro script termina con:

catch err
  fprintf(2, '\nLesson 05 failed: %s\n', err.message);
  rethrow(err);
end_try_catch

err contiene le informazioni sull’errore intercettato.

La prima istruzione scrive un messaggio sullo standard error, che GX-TXT può registrare nel log del Job.

La funzione rethrow(err) rilancia l’errore originale, preservandone le informazioni diagnostiche.

Questo comportamento è importante: se un’API fallisce, non vogliamo che lo script si concluda apparentemente senza problemi soltanto perché l’errore è stato intercettato.

In un flusso scientifico riproducibile occorre poter distinguere chiaramente un’esecuzione riuscita da un’elaborazione interrotta.

7.8 Cosa abbiamo imparato analizzando lo script

Il Dataset Inspector ci ha mostrato come applicare i costrutti di Octave a dati strutturati restituiti da un framework scientifico.

In particolare, abbiamo imparato a verificare i tipi delle risposte, preparare raccolte di identificativi, cercare stringhe, leggere dinamicamente campi delle strutture e distinguere metadati mancanti da metadati dichiarati.

Il risultato è uno script che non dipende dai nomi dei file CSV né dalla posizione fisica dei dati.

Tutte le informazioni vengono ottenute attraverso le interfacce pubbliche GX-TXT, utilizzando gli identificativi stabili previsti dal framework.

Nella prossima sezione esamineremo il risultato dell’esecuzione reale, registrato dal sistema Jobs di GX-TXT, e confronteremo i metadati restituiti dallo script con il Dataset che abbiamo osservato all’inizio dell’articolo.

8. Esecuzione dello script e verifica dei risultati

Dopo aver analizzato il codice del Dataset Inspector, possiamo esaminare ciò che accade quando viene eseguito all’interno di GX-TXT.

A differenza degli esempi dimostrativi costruiti direttamente in Octave, questa esecuzione utilizza un Dataset sperimentale reale, già importato nella Session e gestito attraverso le API pubbliche del framework.

8.1 Eseguire lo script dalla Session GX-TXT

Lo script GXTXT_Octave_L05.m è stato registrato nello Script Workspace con versione 1.0.0, revisione 1 e identificativo:

session:lesson05_1

L’esecuzione avviene attraverso il sistema Jobs di GX-TXT, che gestisce l’avvio del processo Octave, l’inizializzazione dello Script Bridge, la registrazione del log e lo stato finale dell’elaborazione.

Una volta avviato lo script, possiamo controllarne l’esito nella finestra Jobs.

[INSERIRE IMMAGINE 4 — Finestra Jobs di GX-TXT con esecuzione COMPLETED e log del Dataset Inspector]

Figura 4 — Il Dataset Inspector ha completato correttamente l’esecuzione. Il log mostra i metadati ottenuti attraverso le API pubbliche GX-TXT e la coppia di identificativi scientifici del Dataset e della variabile selezionata.

Il Job utilizzato per il collaudo ha restituito:

Proprietà	Valore
Script	GXTXT_Octave_L05.m
Versione	1.0.0
Revisione	1
Stato	COMPLETED
Codice di uscita	0
Durata	3,9 s
Errori	Nessuno registrato

Lo stato COMPLETED e il codice di uscita 0 indicano che il processo Octave è terminato senza errori segnalati.

La verifica scientifica, tuttavia, non consiste soltanto nell’ottenere un’esecuzione completata: dobbiamo anche controllare che il risultato corrisponda al Dataset che intendiamo esaminare.

8.2 Identificazione del Dataset reale

La prima parte significativa del log contiene:

Datasets in the active Session: 1
  [1] Dataset ID: meas0195

Selected Dataset ID: meas0195

Il framework ha individuato un Dataset canonico nella Session corrente e ne ha restituito l’identificativo stabile meas0195.

Poiché nello script abbiamo lasciato vuota la variabile target_dataset_id, è stato selezionato automaticamente il primo Dataset disponibile.

Questa scelta è utile per l’esercitazione, ma in un’applicazione scientifica riproducibile è preferibile specificare esplicitamente l’identificativo del Dataset da analizzare.

Successivamente, l’operazione describe della CANONICAL_DATASET_API_v2 ha restituito:

Canonical Dataset metadata:
  dataset_id       : meas0195
  format           : csv
  storage_provider : csv
  row_count        : 942
  contract         : table.generic

Queste informazioni descrivono il Dataset senza richiedere l’apertura diretta del suo file CSV.

Il campo row_count conferma che il Dataset contiene 942 righe, come osservato nell’anteprima della tabella canonica.

Il campo storage_provider identifica il provider utilizzato dal framework, mentre contract indica il contratto scientifico dichiarato per il Dataset.

Nel nostro caso table.generic identifica una struttura tabellare generica; non attribuisce automaticamente ai valori un significato fisico specifico.

8.3 Identificazione delle variabili

La seconda parte del log riguarda la struttura interna del Dataset:

Variables declared by Schema v3: 3
  [1] Variable ID: v0001
  [2] Variable ID: v0002
  [3] Variable ID: v0003

L’API DATASET_VARIABLE_SCHEMA_API_v3 ha restituito tre identificativi di variabile.

Possiamo confrontarli con le colonne già osservate nell’interfaccia grafica:

Variable ID	Nome canonico osservato
v0001	timestamp_s
v0002	time_s
v0003	current_A

È importante notare che il primo risultato contiene esclusivamente gli identificativi stabili.

Il nostro script ha poi richiesto il descrittore completo della prima variabile mediante l’operazione pubblica get.

Questa distinzione riprende uno dei concetti fondamentali della lezione: un elenco di identificativi permette di individuare le variabili, mentre lo schema permette di comprenderne le proprietà dichiarate.

8.4 Interpretazione del descrittore scientifico

Per la variabile v0001, il log riporta:

Selected Variable ID: v0001

Variable Schema v3 metadata:
  variable_id             : v0001
  display_label           : (empty)
  canonical               : timestamp_s
  unit                    : (empty)
  dtype                   : float64
  rank                    : 1
  shape                   : 942
  dimension_ids           : row
  coordinate_variable_ids : (empty)
  coordinate_role         : data
  axis_kind               : explicit
  axis_origin             : (empty)
  axis_step               : (empty)
  axis_count              : (empty)
  group_id                : (empty)

Questo risultato ci permette di formulare alcune osservazioni precise.

La variabile è identificata da v0001 e possiede il nome canonico timestamp_s. Il tipo dichiarato è float64, mentre rank=1 e shape=942 descrivono un array monodimensionale di 942 elementi.

Il campo dimension_ids=row identifica la dimensione logica dell’array.

Il descrittore riporta inoltre coordinate_role=data e axis_kind=explicit, ma non dichiara una relazione con altre variabili attraverso coordinate_variable_ids.

Non dobbiamo quindi dedurre automaticamente una particolare relazione di coordinate soltanto dal nome della colonna.

Ancora più interessante è la situazione del campo unit, che risulta vuoto.

Sebbene il nome timestamp_s suggerisca una grandezza temporale espressa in secondi, l’unità fisica non è esplicitamente dichiarata in questo campo dello schema.

L’assenza di un valore deve essere mantenuta e documentata: attribuire automaticamente un’unità di misura significherebbe introdurre un’informazione non fornita dai metadati.

Questo è un principio importante nella gestione di dati scientifici provenienti da strumenti differenti.

8.5 La coppia di identificativi scientifici

Al termine dell’ispezione, il log riporta:

Stable scientific identity: (meas0195, v0001)

Lesson 05 completed. No Dataset was modified.

La coppia (meas0195, v0001) rappresenta l’identità logica della variabile all’interno del Dataset.

Il primo elemento identifica il Dataset canonico; il secondo identifica una variabile specifica appartenente a quel Dataset.

Lo script non ha eseguito operazioni di modifica o pubblicazione. Le chiamate utilizzate riguardano esclusivamente la disponibilità delle API, l’elenco dei Dataset e la lettura dei descrittori.

Non sono stati richiesti i 942 valori numerici della variabile: abbiamo letto le informazioni necessarie per identificarla e descriverla.

8.6 Riproducibilità e versione di GX-TXT

Per un esperimento scientifico non basta conservare il risultato. Occorre poter identificare il codice e l’ambiente con cui è stato ottenuto.

Il nostro collaudo è documentato dai seguenti riferimenti:

Elemento	Identificazione
Repository	giuxlab-hub/GX-TXT
Branch GitHub	maintenance/dev111
Commit sorgente di riferimento	924c4231abfa2d69c25ef53673fc0c293d663469
Ambiente GX-TXT utilizzato	dev_111_r3
Script	GXTXT_Octave_L05.m
Versione script	1.0.0, revisione 1
Data del collaudo	26 ottobre 2026

Il sistema Jobs conserva inoltre l’identificativo dell’esecuzione, lo snapshot dello script registrato, il relativo SHA-256 e il log prodotto.

Questi elementi permettono di distinguere il codice effettivamente eseguito dalle successive revisioni dello script.

Il commit GitHub identifica invece la revisione dei sorgenti pubblici utilizzata come riferimento per verificare le API. Non va confuso con lo SHA-256 dello script Octave o con l’identificativo del Job.

8.7 Risultato del collaudo

L’esperimento ha verificato che lo script è in grado di:

• Individuare un Dataset reale attraverso il suo identificativo stabile.
• Leggere i metadati canonici senza accedere direttamente al file CSV.
• Ottenere i Variable ID attraverso lo Schema API v3.
• Ispezionare il descrittore di una variabile.
• Distinguere proprietà dichiarate, campi vuoti e identificativi.
• Concludere correttamente l’esecuzione attraverso il sistema Jobs di GX-TXT.

Il collaudo riguarda il Dataset esaminato e le operazioni effettivamente utilizzate; non rappresenta una verifica generale di tutti i provider e di tutte le API disponibili in GX-TXT.

La Lezione 05 ci ha quindi fornito gli strumenti necessari per individuare e comprendere i dati prima di elaborarli numericamente.

9. Materiale didattico scaricabile

Per permettere ai lettori di riprodurre l’esercitazione, abbiamo preparato un pacchetto didattico contenente lo script GNU Octave, il Dataset sperimentale e la relativa documentazione.

Il Dataset utilizzato in questa lezione proviene da un esperimento reale di fotocatalisi, durante il quale sono state registrate misure di corrente elettrica in funzione del tempo.

Non si tratta quindi di valori generati artificialmente per il tutorial. Abbiamo scelto di utilizzare dati sperimentali autentici per mostrare come GX-TXT organizza e descrive le informazioni scientifiche.

La finalità della lezione rimane comunque informatica e metodologica: non analizzeremo i meccanismi della reazione fotocatalitica, ma la struttura dei dati e le procedure per accedervi correttamente.

9.1 Contenuto del pacchetto

L’archivio lesson05.zip contiene quattro file:

File	Descrizione
GXTXT_Octave_L05.m	Script Octave utilizzato e collaudato nella lezione
Lesson_05_Experiment_Objectives.md	Obiettivi didattici e criteri di verifica
Lesson_05_Teaching_Notes.md	Note tecniche e approfondimenti sulle API
meas0195.csv	Dataset originale con 942 misure sperimentali

Lo script è distribuito con licenza GNU GPL v3 o successiva. La documentazione accompagna l’esperimento, mentre il Dataset viene fornito come materiale scientifico per riprodurre l’esercitazione.

9.2 Riprodurre l’esercitazione in GX-TXT

Il pacchetto non contiene una Session GX-TXT esportata: permette invece di ripetere il procedimento partendo dall’importazione dei dati.

Per eseguire l’esperimento:

1. Scaricare ed estrarre lesson05.zip.
2. Avviare GX-TXT e creare una nuova Session, oppure aprirne una destinata all’esercitazione.
3. Importare meas0195.csv come Dataset attraverso gli strumenti di importazione del framework.
4. Aprire lo Script Workspace GNU Octave e importare GXTXT_Octave_L05.m.
5. Registrare lo script nella Session, verificando la disponibilità delle API pubbliche richieste.
6. Eseguire lo script e consultare il risultato nella finestra Jobs.

L’ispettore individuerà i Dataset presenti nella Session e visualizzerà gli identificativi delle variabili e i metadati disponibili.

Attenzione agli identificativi: una nuova importazione può assegnare al Dataset un identificativo differente da meas0195. Lo script, lasciando vuoto target_dataset_id, seleziona automaticamente il primo Dataset disponibile. Per ottenere risultati riproducibili in Session contenenti più Dataset, è preferibile indicare esplicitamente l’identificativo restituito dall’importazione.

I nomi canonici e gli identificativi effettivi delle variabili devono sempre essere verificati attraverso le API, senza presupporre che coincidano con quelli mostrati in questo articolo.

9.3 Versione del framework e documentazione delle API

L’esercitazione è stata verificata utilizzando GX-TXT dev_111_r3, con riferimento ai sorgenti pubblici del branch maintenance/dev111.

Commit GitHub utilizzato per la verifica delle API:

924c4231abfa2d69c25ef53673fc0c293d663469

Documentazione pubblica:

• Octave Script Bridge API v1
• Canonical Dataset API v2
• Dataset Variable Schema API v3

I collegamenti fanno riferimento a un commit preciso, così da conservare nel tempo la documentazione tecnica associata alla lezione anche quando il framework verrà aggiornato.

10. Conclusioni e prossima lezione

In questa quinta lezione abbiamo compiuto un passaggio importante: siamo passati dall’elaborazione di variabili create direttamente in GNU Octave all’esplorazione di informazioni scientifiche gestite da GX-TXT.

Abbiamo imparato che un Dataset non è semplicemente un file contenente numeri, ma un insieme organizzato di variabili, identificativi stabili e metadati.

Abbiamo inoltre utilizzato nuove tecniche di programmazione Octave per esaminare strutture, individuare identificativi e verificare la presenza delle informazioni senza assumere che ogni campo sia necessariamente compilato.

Il nostro Dataset Inspector ha completato correttamente l’esecuzione su un Dataset reale di fotocatalisi, dimostrando il funzionamento delle API pubbliche utilizzate.

Nella Lezione 06 — Selezione e lettura dei dati faremo il passo successivo: non ci limiteremo più a descrivere le variabili, ma inizieremo a leggere i loro valori numerici attraverso le API canoniche di GX-TXT, mantenendo il controllo su identificativi, dimensioni e quantità di dati richiesti.