Indice
Modulo corrente nella documentazione dev-031: analysis.cross_spectral_transfer 1.1.3
Session didattica usata in questo tutorial: analysis_cross_spectral_transfer_1.1.2
Framework registrato nell'export della Session: GX-TXT 0.9.8.07
Dataset sorgente: 49.152 campioni, 12 s, 4096 Hz, due tensioni sincrone.
1. Obiettivo
Vogliamo stimare la relazione in frequenza fra un segnale di ingresso x(t) e un segnale di uscita y(t) acquisiti in modo sincrono.
Il Dataset didattico è costruito in modo deterministico:
Di conseguenza, nei punti spettrali significativi ci aspettiamo:
- H1 magnitude ≈ 2.5;
- H2 magnitude ≈ 2.5;
- gain ≈ 7.9588 dB;
- phase ≈ 0°;
- coherence ≈ 1.
2. Perché questo esempio è utile
Non stiamo cercando di indovinare la risposta: la conosciamo già. Il tutorial serve a verificare che la pipeline restituisca ciò che deve restituire e a imparare come leggere H1, H2, fase e coerenza.
I tre toni di riferimento sono:
3. Il workflow GX-TXT
Il punto importante è la separazione fra segmentazione, calcolo scientifico e presentazione. Il Temporal Window Set definisce quali campioni appartengono a ciascuna finestra; il modulo calcola gli spettri; plot.dataset presenta i risultati.
4. Dataset sorgente e sincronizzazione
Il CSV contiene tre colonne:
time_s,input_V,output_V| Variabile | Ruolo | Unità | Variable ID nella Session |
|---|---|---|---|
time_s | independent / elapsed time | s | v0001 |
input_V | input X | V | v0002 |
output_V | output Y | V | v0003 |
Il modulo richiede che X e Y appartengano allo stesso Dataset. Non è una limitazione casuale: significa che ogni campione di X ha un campione Y corrispondente senza dover inventare una regola di riallineamento fra sorgenti indipendenti.
5. Importa il Dataset
Importa cross_spectral_transfer_demo.csv come timeseries.table.
Associa:
time_s → independent elapsed time [s]
input_V → measured [V]
output_V → measured [V]Il Dataset didattico contiene 49.152 righe. A 4096 Hz corrispondono a 12 secondi completi.
6. Crea il Temporal Window Set
La Session usa il Temporal Set tset_001:
Type = window_set
Window size = 4096 samples = 1 s
Step = 4096 samples = 1 s
Member count = 12
Partial = drop
Il Temporal Set è una risorsa riusabile: la segmentazione non viene duplicata dentro il modulo cross-spectral.
7. Configura Cross-Spectral & Transfer Function Analysis
Abilita Cross-Spectral & Transfer Function Analysis e imposta i binding:
Time = time_s
Input X = input_V
Output Y = output_VPer riprodurre la Session didattica usa:
Temporal Set = tset_001
Window = hann
Detrend = mean
NFFT mode = auto
NFFT = 4096
Workers = serialIl sample rate ricostruito dal tempo esplicito è circa 4096 Hz; con NFFT = 4096 la risoluzione spettrale è circa 1 Hz/bin.
8. Che cosa calcola il modulo
Per ogni finestra il modulo applica detrending e finestra di Hann, quindi calcola le FFT accoppiate:
Le stime one-sided sono normalizzate con la potenza della finestra:
Le dodici finestre vengono poi mediate:
La convenzione del cross-spectrum è quindi esplicita: Sxy = mean(conj(X) * Y).
9. H1 e H2: due stimatori della stessa transfer function
H1
È comunemente preferito quando il rumore di misura è soprattutto sul canale di uscita/risposta.
H2
È spesso utile quando il rumore di misura rilevante è maggiormente sul canale di ingresso.
In un sistema lineare ideale e privo di rumore H1 e H2 convergono alla stessa funzione di trasferimento. Nel nostro Dataset questo è esattamente ciò che deve succedere.
10. Coerenza
La magnitude-squared coherence è compresa fra 0 e 1. Una coerenza alta indica che, a quella frequenza e nelle finestre considerate, X e Y presentano una relazione lineare forte.
11. Esegui l'analisi
Avvia l'analisi in modalità scientifica. La Session di riferimento registra:
Run mode = recalculate
Windows = 12
FFT window = hann
Detrend = mean
NFFT = 4096
Frequency step ≈ 1 Hz
Workers = serial
Parallel state = completedIl risultato viene pubblicato come Dataset derivato:
cross_spectral.source.cross_spectral.v0002.v0003.tset_00112. Il Dataset derivato
Il Dataset pubblicato contiene 2049 bin one-sided e raccoglie in un solo oggetto scientifico tutte le quantità necessarie.
| Gruppo | Variabili principali |
|---|---|
| Asse | frequency |
| Auto-spettri | input_psd, output_psd, versioni dB |
| Cross-spectrum | real, imaginary, magnitude, phase |
| H1 | real, imaginary, magnitude, gain dB, phase, unwrapped phase |
| H2 | real, imaginary, magnitude, gain dB, phase, unwrapped phase |
| Relazione lineare | coherence |
Questo è importante: i grafici non sono l'unico risultato. Il risultato scientifico riusabile è il Dataset derivato.
13. Risultato 1 — transfer magnitude
Il valore teorico è:
Il grafico resta quasi perfettamente centrato su questo valore. Le escursioni nei bin ad altissima frequenza e bassissima energia non indicano una reale variazione del gain: lì Sxx è estremamente piccolo e il rapporto diventa sensibile alla precisione numerica.
14. Risultato 2 — transfer phase
Poiché l'uscita non ha ritardo né inversione, la fase attesa è 0°. Anche qui i piccoli picchi nei bin quasi privi di energia non vanno interpretati come dinamica fisica.
15. Risultato 3 — coherence
Nei toni di verifica la coerenza è numericamente indistinguibile da 1. Questo è coerente con output_V = 2.5 × input_V.
16. Risultato 4 — input/output PSD
Una moltiplicazione di ampiezza per 2.5 moltiplica la potenza per 2.5² = 6.25. In dB la distanza fra le due PSD è quindi ancora:
17. Verifica quantitativa ai tre toni
I valori seguenti sono letti direttamente dal Dataset HDF5 pubblicato nella Session fornita:
| f [Hz] | |H1| | |H2| | H1 gain [dB] | H1 phase [°] | Coherence |
|---|---|---|---|---|---|
| 64 | 2.500000 | 2.500000 | 7.958800 | ≈ 0 | 1.000000 |
| 256 | 2.500000 | 2.500000 | 7.958800 | ≈ 0 | 1.000000 |
| 640 | 2.500000 | 2.500000 | 7.958800 | ≈ 0 | 1.000000 |
Puoi scaricare anche la tabella numerica: validation_points.csv.
18. Report e provenance
Il modulo scrive un report leggibile che fissa sorgente, Variable ID, Temporal Set, configurazione FFT, convenzione del cross-spectrum, unità, provider di storage e stato dell'esecuzione.
Cross-Spectral & Transfer Function Analysis
===========================================
Module version: 1.1.2
Source Dataset: cross_spectral.source
Time variable: v0001
Input X: input_V (v0002)
Output Y: output_V (v0003)
Temporal Set: tset_001 (12 windows)
FFT window: hann
Detrend: mean
NFFT: 4096
Sample rate: 4095.9999999914662 Hz
Frequency step: 0.99999999999791656 Hz
Cross-spectrum convention: Sxy = mean(conj(X) * Y)
H1 = Sxy / Sxx
H2 = Syy / conj(Sxy)
Coherence = |Sxy|^2 / (Sxx*Syy)
Transfer unit: 1
Input PSD unit: V^2/Hz
Output PSD unit: V^2/Hz
Source provider: csv
Output provider: hdf5
Published Dataset: cross_spectral.source.cross_spectral.v0002.v0003.tset_001
Explicit-time relative interval deviation: 3.07196e-07
Workers requested: serial
Parallel state: completedQueste informazioni permettono di distinguere una figura semplicemente “simile” da un risultato riproducibile.
19. Rerender oppure ricalcolo?
| Modifica | Cosa fare | Perché |
|---|---|---|
| Titolo, legenda, intervallo asse, layout, stile | Rerender | Il Dataset scientifico non cambia. |
| Scelta H1/H2 da visualizzare | Rerender | Entrambi sono già pubblicati nel Dataset. |
| Window Hann → altra window | Recalculate | Cambia la stima spettrale. |
| Detrend, NFFT, Temporal Set | Recalculate | Cambia il calcolo scientifico. |
| Input/Output Variable ID | Recalculate | Cambiano i dati analizzati. |
Questa distinzione è uno dei punti più importanti del workflow GX-TXT: presentation state e scientific state non sono la stessa cosa.
20. Come cambia il problema con dati reali
Questo Dataset è volutamente ideale. In laboratorio troverai invece una combinazione di:
- rumore sul canale di ingresso e/o uscita;
- ritardo e fase dipendenti dalla frequenza;
- gain non costante;
- componenti non correlate;
- nonlinearità;
- leakage e segnali non coerenti con la finestra;
- drift o non stazionarietà fra finestre;
- sincronizzazione imperfetta.
In quel caso H1 e H2 possono divergere, la coerenza può scendere e il significato fisico deve essere valutato insieme alla PSD e al livello di eccitazione.
21. Errori di interpretazione da evitare
- Leggere H(f) dove l'ingresso non eccita il sistema: un rapporto numerico può esistere anche quando il denominatore contiene quasi solo rumore.
- Usare la coerenza come prova di causalità: non lo è.
- Confrontare due segnali non sincronizzati come se fossero sample-aligned: questa analisi richiede una relazione temporale definita.
- Confondere PSD e amplitude spectrum: le unità e la normalizzazione sono diverse.
- Rerenderizzare dopo aver cambiato NFFT/window e credere di avere un nuovo risultato: quelle sono impostazioni scientifiche e richiedono ricalcolo.
22. Esercizi utili
- Conferma manualmente che
20·log10(2.5)coincide con il gain pubblicato. - Riduci il numero di finestre e osserva come cambia la stabilità della stima.
- Cambia la weighting window e confronta i lobi attorno ai tre toni.
- Aggiungi rumore soltanto a
output_Ve confronta H1/H2. - Aggiungi rumore soltanto a
input_Ve ripeti il confronto. - Introduci un ritardo noto nell'uscita e verifica la pendenza della fase.
- Modifica soltanto il range X di un grafico e verifica che sia sufficiente il rerender.
23. File del tutorial
24. Collegamenti
- Analisi spettrale — panoramica dei moduli e manuale tecnico.
- SIGNAL_API_v1 — primitive riusabili per signal/system mathematics.
- NUMERIC_API_v1 — servizi numerici condivisi.
- Scientific Dataset Plot — presentazione persistente dei Dataset scientifici.