Corso Python scientifico in GX-TXT · Modulo 3 · Lezione 15

Una maschera booleana associa a ogni elemento una decisione True o False. Possiamo usarla per selezionare valori che rispettano un criterio esplicito, mantenendo documentati anche quelli esclusi. In questa lezione confrontiamo una maschera NumPy con una combinazione equivalente dell’API numerica pubblica di GX-TXT.

Obiettivi: creare confronti elemento per elemento; combinare maschere con &, | e ~; usare np.isfinite, np.where e conteggi; distinguere selezione tecnica da decisione scientifica.

Prerequisiti: booleani della lezione 7 e array delle lezioni 13–14.

Un confronto elemento per elemento

import numpy as np
segnale = np.array([1.2, 1.5, 1.3, 1.6])
print(segnale >= 1.3)

Il confronto produce un array booleano, non un singolo valore: [False, True, True, True]. La maschera ha la stessa forma del segnale. segnale[maschera] seleziona i valori nelle posizioni vere; l’ordine rimane quello originale.

I valori dell’esempio sono segnali sintetici in mV, non misure sperimentali. Per illustrare la selezione, scegliamo la finestra inclusiva da 1,3 a 1,5 mV: sono selezionati 1,5 e 1,3 mV. Le soglie sono didattiche, non criteri di qualità universali.

Combinare maschere

Per combinare condizioni su array NumPy si usano gli operatori elemento per elemento & (e), | (o) e ~ (negazione):

maschera = (segnale >= 1.3) & (segnale <= 1.5)

Le parentesi attorno a ogni confronto sono necessarie per rendere esplicita la precedenza degli operatori. Gli operatori Python and e or richiedono una singola verità per ciascun operando e, con array contenenti più elementi, possono generare un errore di verità ambigua: non svolgono il confronto elemento per elemento.

~maschera inverte i booleani e individua i valori esclusi. np.count_nonzero(maschera) conta gli elementi veri. Non eliminare i dati esclusi senza conservarli e spiegare il criterio: una selezione può introdurre bias o nascondere un fenomeno interessante.

Valori non finiti e np.where

np.isfinite(segnale) è vero per valori finiti e falso per NaN e infiniti. Una condizione combinata può escludere esplicitamente valori non finiti. Il fatto che un valore sia finito non lo rende automaticamente valido per il modello o per lo strumento.

np.where(condizione, valore_se_vero, valore_se_falso) costruisce un array scegliendo elemento per elemento tra due alternative compatibili. Ad esempio, np.where(maschera, segnale, np.nan) conserva la forma e sostituisce i valori esclusi con NaN. Questo non equivale a cancellarli dal Dataset originale: conserva il dato sorgente e documenta la trasformazione. L’altra forma np.where(condizione) restituisce indici; presta attenzione a quale forma stai usando.

Il provider numerico GX-TXT

NUMERIC_API_v1/array_mask espone operazioni logiche pubbliche come logical_and. Il bridge riceve operandi strutturati che dichiarano kind e value e restituisce un risultato con campo values. Nel nostro esempio i due vettori 0/1 rappresentano i confronti inferiore e superiore; il provider li combina con logical_and. Il risultato ha gli stessi valori logici della maschera NumPy dell’esempio; il bridge lo mostra come colonna (4, 1), mentre l’array NumPy iniziale è monodimensionale (4,).

Confrontare valori e forma è importante: una differenza di forma può influenzare l’indicizzazione o operazioni successive anche quando la sequenza di booleani appare uguale. I predicati sulla disponibilità dell’API non garantiscono che ogni combinazione di dati sia ammessa: rispetta le condizioni di tipo e forma del provider.

Codice completo

import numpy as np
from gxtxt import gxtxt_api_call, gxtxt_api_require

gxtxt_api_require("NUMERIC_API_v1@1")
segnale = np.array([1.2, 1.5, 1.3, 1.6])
maschera = (segnale >= 1.3) & (segnale <= 1.5) & np.isfinite(segnale)
print("Segnale sintetico (mV):", segnale)
print("Maschera NumPy:", maschera)
print("Selezionati:", segnale[maschera])
print("Accettati:", np.count_nonzero(maschera), "esclusi:", np.count_nonzero(~maschera))
a = {"kind": "vector", "value": [0, 1, 1, 1]}
b = {"kind": "vector", "value": [1, 1, 1, 0]}
risultato = gxtxt_api_call("NUMERIC_API_v1", "array_mask", ["logical_and", a, b])
print("Maschera provider:", risultato["values"])

Gli operandi a e b sono esplicitamente costruiti per questa serie finita: non sono ricavati automaticamente dal segnale. Il confronto è quindi una dimostrazione sul caso mostrato; per altri dati occorre generare le maschere corrispondenti. Tutti e quattro i valori sintetici sono finiti.

Script sulle maschere nell'editor Python di GX-TXT.
Script sulle maschere nell'editor Python di GX-TXT.

Lo script confronta una selezione NumPy con una combinazione logica del provider pubblico.

Esecuzione

  1. Apri una Session e Viewers → Python Scripts.
  2. Importa maschere.py, assegna nome e Script ID nello scope session, quindi salva.
  3. Apri Run → Open Script Runner…, premi Run Job e leggi l’output.
  4. Controlla la maschera [False, True, True, False], i valori selezionati [1.5, 1.3] e il conteggio di due accettati e due esclusi. Il risultato del provider mostra gli stessi booleani come vettore colonna.
Maschere NumPy e provider nell'output di GX-TXT.
Maschere NumPy e provider nell'output di GX-TXT.

La finestra sintetica seleziona due valori; la colonna del provider riporta la stessa sequenza logica.

Errore comune

Scrivere (segnale >= 1.3) and (segnale <= 1.5) tenta di usare and su array e non produce la maschera desiderata. Usa & con ogni confronto fra parentesi. Se tempi e segnali sono array separati e corrispondenti riga per riga, applica la stessa maschera a entrambi per mantenere l’allineamento.

Esercizio

Per i valori sintetici [1.2, 1.5, 1.3, 1.6], costruisci una maschera che selezioni valori finiti strettamente maggiori di 1,3 mV. Quali valori e quanti elementi ottieni?

Soluzione ragionata
maschera = np.isfinite(segnale) & (segnale > 1.3)
print(segnale[maschera])
print(np.count_nonzero(maschera))

I valori sono 1.5 e 1.6, per un totale di due. 1.3 è escluso perché il confronto è strettamente maggiore, non maggiore o uguale.

Nella prossima lezione useremo operazioni vettoriali e conversioni di unità.

Scarica gli script del Modulo 03 (ZIP)

#GX-TXT #NumPy #Python

Altre tappe del progetto

Lascia un commento

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