Dataset multidimensionali e hyperslab
Corso Python scientifico in GX-TXT · Modulo 4 · Lezione 22
Un Dataset può contenere una variabile organizzata su più dimensioni. Un hyperslab è un sottoinsieme rettangolare definito da una posizione iniziale e da un numero di elementi per ciascun asse. In questa lezione creeremo una matrice sintetica nella Session GX-TXT e ne leggeremo una parte attraverso l’API pubblica.
Obiettivi: interpretare forma e indici multidimensionali; distinguere posizione iniziale e dimensioni richieste; pubblicare una piccola matrice e leggere un hyperslab; confrontare il risultato con i valori attesi.
Prerequisiti: array e shape delle lezioni 13–14; Dataset e lettura progressiva delle lezioni 19–21.
Una matrice con due assi
Consideriamo la seguente matrice sintetica di segnali in mV:
1 2 3 4
5 6 7 8
9 10 11 12
La forma è (3, 4): tre righe e quattro colonne. I due
assi sono identificati nell’esempio come riga e
colonna. I valori sono inventati per mostrare
l’indicizzazione: non sono misure sperimentali, non è assegnata
un’incertezza e gli indici non rappresentano automaticamente coordinate
fisiche.
L’elemento di indici [1, 1] è 6: gli indici
partono da zero, quindi si tratta della seconda riga e della seconda
colonna. Un hyperslab con inizio [1, 1] e conteggi
[2, 2] seleziona due righe e due colonne:
6 7
10 11
Per ciascun asse, il conteggio indica quanti elementi leggere, non l’ultimo indice incluso. L’intervallo di righe parte da 1 e contiene gli indici 1 e 2; quello delle colonne contiene anch’esso 1 e 2.
Oltre due dimensioni
Una variabile tridimensionale può avere, per esempio, assi tempo,
riga e colonna. La sua shape potrebbe essere
(n_t, n_r, n_c), ma il significato di ciascun asse deve
venire dallo schema e dai metadati, non dalla sola lunghezza. Un
hyperslab richiede una posizione iniziale e un conteggio per ogni
dimensione, nell’ordine logico dichiarato.
Il broadcasting NumPy può combinare array con forme compatibili, ma compatibilità di forma non significa compatibilità fisica. Prima di applicare operazioni tra un sottoinsieme e coordinate o calibrazioni, controlla quale asse rappresenta ciascuna grandezza e quali unità usa.
Pubblicare una matrice di esempio
DATASET_PUBLICATION_API_v2 permette di dichiarare
dimensioni e variabili prima di scrivere i valori. Lo script apre un
writer, dichiara due dimensioni fisse e una variabile
segnale di rango 2 con dtype float64, quindi
scrive la matrice e conclude la pubblicazione. Se la pubblicazione
solleva un’eccezione, il codice richiede l’annullamento del writer e
rilancia l’errore: non presenta una matrice parziale come risultato
completo.
La pubblicazione viene tentata solo se l’ID
corso_python_matrice_sintetica non è nel catalogo. L’ID
presente non garantisce da solo che un Dataset preesistente abbia la
stessa matrice: usa una Session dedicata al corso e verifica il
contenuto se l’ID è già occupato. Il formato di archiviazione richiesto
nell’esempio è HDF5; non accediamo a file interni dal codice.
Leggere un hyperslab
CANONICAL_DATASET_API_v2/read_hyperslab riceve ID
Dataset, ID variabile, vettore degli inizi e vettore dei conteggi.
Restituisce una struttura che comprende valori, forma e informazioni
sulla lettura. Per il nostro caso chiediamo [1, 1] e
[2, 2], poi stampiamo risposta["values"].
La posizione e la forma richieste devono rientrare nella forma del Dataset. Per un programma riutilizzabile consulta prima lo schema, controlla rango e limiti, e mantieni la relazione fra gli assi e le coordinate scientifiche. Qui conosciamo già la forma perché abbiamo creato l’esempio.
Codice completo
import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require
gxtxt_api_require("CANONICAL_DATASET_API_v2@2")
gxtxt_api_require("DATASET_PUBLICATION_API_v2@2")
dataset = "corso_python_matrice_sintetica"
api = "DATASET_PUBLICATION_API_v2"
catalogo = gxtxt_api_call("CANONICAL_DATASET_API_v2", "list", [])
if dataset not in catalogo:
definizione = {"dataset_id": dataset, "contract": "table.generic", "storage": "hdf5", "provenance": "Matrice sintetica didattica, non misure"}
writer = gxtxt_api_call(api, "begin", [definizione])
try:
gxtxt_api_call(api, "declare_dimension", [writer, "riga", 3, {"extendible": 0}])
gxtxt_api_call(api, "declare_dimension", [writer, "colonna", 4, {"extendible": 0}])
schema = {"dtype": "float64", "rank": 2, "dimension_ids": "riga;colonna", "coordinate_role": "data", "unit": "mV"}
gxtxt_api_call(api, "declare_variable", [writer, "segnale", schema])
matrice = np.array([[1., 2., 3., 4.], [5., 6., 7., 8.], [9., 10., 11., 12.]])
gxtxt_api_call(api, "write_variable", [writer, "segnale", matrice, [3, 4]])
gxtxt_api_call(api, "finalize", [writer])
except Exception:
gxtxt_api_call(api, "abort", [writer])
raise
risposta = gxtxt_api_call("CANONICAL_DATASET_API_v2", "read_hyperslab", [dataset, "segnale", [1, 1], [2, 2]])
print("Dataset:", dataset)
print("Hyperslab da [1,1] con forma [2,2]:", risposta)
print("Valori selezionati (mV):\n", risposta["values"])
La dichiarazione dimension_ids conserva l’ordine logico
riga;colonna; il client trasporta un array già sagomato
mantenendone gli indici logici. raise nel gestore ripropaga
l’errore dopo la richiesta di annullamento. Le operazioni di writer
saranno approfondite nella lezione 24.

La matrice sintetica è pubblicata nella Session prima della lettura del sottoinsieme.
Esecuzione
- Apri una Session dedicata e il Viewer Python Scripts.
- Importa
hyperslab.py, assegna nome e Script ID nello scopesession, quindi salva. - Apri il Runner, premi Run Job e attendi il completamento.
- Leggi l’output: i valori selezionati devono essere
[[6, 7], [10, 11]]mV e il conteggio deve essere quattro. La forma è 2 × 2.

Il sottoinsieme letto contiene le due righe e le due colonne richieste.
Errore comune
Confondere [2, 2] con l’ultimo indice da leggere porta a
un sottoinsieme diverso: in questa API è il numero di elementi
per asse. Un altro errore è appiattire la matrice e perdere la
relazione fra righe e colonne. Controlla sempre forma, ordine degli
assi, inizi e conteggi.
Esercizio
Nella matrice dell’esempio, quali valori ottieni con inizio
[0, 2] e conteggi [2, 2]?
Soluzione ragionata
Le righe sono 0 e 1; le colonne sono 2 e 3. Il risultato atteso è
[[3, 4], [7, 8]] mV, con forma (2, 2). I
valori sono sintetici e non rappresentano misure.
Nella prossima lezione pubblicheremo una serie derivata mantenendo chiara la sua origine.