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.

Script per la pubblicazione e la lettura di una matrice nell'editor Python.
Script per la pubblicazione e la lettura di una matrice nell'editor Python.

La matrice sintetica è pubblicata nella Session prima della lettura del sottoinsieme.

Esecuzione

  1. Apri una Session dedicata e il Viewer Python Scripts.
  2. Importa hyperslab.py, assegna nome e Script ID nello scope session, quindi salva.
  3. Apri il Runner, premi Run Job e attendi il completamento.
  4. Leggi l’output: i valori selezionati devono essere [[6, 7], [10, 11]] mV e il conteggio deve essere quattro. La forma è 2 × 2.
Valori letti dall'hyperslab della matrice sintetica in GX-TXT.
Valori letti dall'hyperslab della matrice sintetica in GX-TXT.

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.

Scarica gli script del Modulo 04 (ZIP)

#Dataset #GX-TXT #Python

Altre tappe del progetto

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *