Analysis Module¶
Analysis functions for frequency domain analysis, transfer functions, and modal analysis.
FFT Analysis¶
calculate_fft ¶
Parameters:
-
time_data(<TimeData> object) –time series data
-
time_range(list or ndarray, default:None) –2x1 numpy array to specify data segment to use
-
window(str, default:None) –window function name (e.g., 'hann', 'hamming', 'blackman'), or None for rectangular (boxcar) window
Transfer Functions¶
calculate_tf ¶
Parameters:
-
time_data(<TimeData> object) –time series data
-
ch_in(int, default:0) –index of input channel
-
time_range(list or ndarray, default:None) –2x1 numpy array to specify data segment to use
-
window(None or str, default:None) –apply filter to data before fft or not
-
N_frames(int, default:1) –number of frames to average over
-
overlap(float, default:0.5) –frame overlap fraction between 0 and 1
calculate_tf_averaged ¶
Calculates transfer function averaged across an ensemble of separate
measurements. Note that this expects a
Takes each time series as an independent measurement: the
cross-spectra are averaged across the ensemble, then the H1
estimator Pxy[ch_in, ch_out] / Pxy[ch_in, ch_in] is formed —
the same phase convention as calculate_tf.
Intended for averaged transfer functions from separate measurements, e.g. impulse hammer tests.
Does not average data across sub-frames.
Parameters:
-
time_data_list(<TimeDataList> object) –a list of time series data
-
ch_in(int, default:0) –index of input channel
-
time_range(list or ndarray, default:None) –2x1 numpy array to specify data segment to use
-
window(None or str, default:None) –type of window to use, default is None.
Cross-Spectrum Analysis¶
calculate_cross_spectrum_matrix ¶
Compute the full cross-spectrum matrix and coherence matrix of a
multi-channel TimeData block using Welch's method.
Equivalent to looping scipy.signal.csd (with scaling='spectrum')
and scipy.signal.coherence over every channel pair, but vectorised:
each segment is FFT'd once across all channels, and the cross-spectrum
matrix is formed as a tensor outer product conj(X[:,f,i]) * X[:,f,j]
averaged over segments. Output is byte-equivalent to the scipy reference
to within FFT round-off.
The DC bin (and, for an even segment length, the Nyquist bin) of the
coherence matrix is undefined under a boxcar window: constant detrending
zeroes each segment's mean, so the auto-spectra there are pure round-off
and Cxy is a 0/0 ratio. It is returned as 0 in that degenerate case
rather than NaN; treat it as "no information at DC", not a real coherence.
Memory: the per-segment windows are built with as_strided directly at
the final (N_chans, N_seg, nperseg) shape rather than via
sliding_window_view + slicing. The latter materialises an intermediate
whose nominal size is N_chans * (N_samples - nperseg + 1) * nperseg;
on a 32-bit build (pyodide/WASM, npy_intp = int32) numpy rejects that
view with "array is too big" for a large nperseg on a long, high-rate
record, even though it is only a view. The direct stride keeps the nominal
size at N_chans * N_seg * nperseg and is numerically byte-identical.
Parameters:
-
time_data(<TimeData> object) –time series data
-
time_range(list or ndarray, default:None) –2x1 numpy array to specify data segment to use
-
window(None or str, default:None) –window function name; None defaults to 'boxcar'
-
N_frames(int, default:1) –number of frames to average over
-
overlap(float, default:0.5) –frame overlap fraction between 0 and 1
calculate_cross_spectra_averaged ¶
Calculates cross spectra averaged across ensemble of time_data_list. Note that
this expects a
Takes each time series as an independent measurement.
Intended for averaged transfer functions from separate measurements, e.g. impulse hammer tests.
Does not average data across sub-frames.
Parameters:
-
time_data_list(<TimeDataList> object) –a list of time series data
-
time_range(list or ndarray, default:None) –2x1 numpy array to specify data segment to use
-
window(None or str, default:None) –type of window to use, default is None.
Time-Frequency Analysis¶
calculate_sonogram ¶
Calculates a complex STFT spectrogram (sonogram) for every channel of
a
Channel calibration factors and units are copied from the source, and
id_link is set to the source's unique_id (same provenance
convention as the other calculate_* functions).
Parameters:
-
time_data(<TimeData> object) –time series data
-
nperseg(int, default:None) –STFT segment length; defaults to ~1/50th of the time series so roughly 50 segments span the data
-
noverlap(int, default:None) –overlap between segments, default
nperseg // 2
Modal Analysis¶
calculate_damping_from_sono ¶
Calculate damping from sonogram data.
Parameters:
-
time_data(<TimeData> object) –time series data
-
n_chan(int, default:1) –channel index to analyze, default is 1
-
nperseg(int, default:None) –number of samples per segment for spectrogram
-
start_time(float, default:None) –start time for analysis
Returns:
-
fn(ndarray) –array of natural frequencies (Hz)
-
Qn(ndarray) –array of Q factors (1/(2*zeta))
-
fit_data(dict) –dict containing data needed for plotting the fits: - 't': time axis - 'fits': list of dicts, each with keys: - 't_fit': time values for the fit region - 'real_fit': fitted real part values - 'real_data': actual real part data values - 'f_peak': peak frequency (Hz) - 'Qn': Q factor for this mode
Signal Processing¶
clean_impulse ¶
Sets all data outside of impulse to zero.
Pulse width is estimated by assuming half cosine impulse, using width of half peak amplitude.
Data before peak is unchanged. Data after estimated end of impulse is ramped to zero using half cosine pulse of width 10x estimated pulse width.
best_match ¶
Parameters:
-
tf_data_list(<TfDataList> object) –transfer function data
-
freq_range(list or ndarray, default:None) –2x1 numpy array to specify data segment to use
-
set_ref(int, default:0) –reference set index, default is 0
-
ch_ref(int, default:0) –reference channel index, default is 0