GISQAPipeline. Both functions live in a single module — import them as shown below.
Note: other than STFT and CWT there are other TFR generation functions such as MODWT, MOWPT which can also be used to generate 2D time-frequency/mode representations of a signal.
Import
stft_basic_spectogram
Computes a Short-Time Fourier Transform (STFT) spectrogram usingscipy.signal.spectrogram. The output is a 2D matrix of shape (n_freq, n_time) ready to pass directly into GISQAPipeline.compute_pointwise_metrics_from_spec() with is_hilbertize=1.
Parameters
Number of samples per STFT segment. Controls the trade-off between time and frequency resolution: larger values give finer frequency resolution but coarser time resolution. Common choices for 100 Hz signals are
32, 64, or 128.Fractional overlap between consecutive STFT segments (e.g.,
0.5 for 50% overlap, 0.75 for 75%). Higher overlap produces smoother time resolution at the cost of increased output size.Window function to apply to each segment. Any window accepted by
scipy.signal.get_window() is valid, such as 'hann', 'hamming', or 'blackman'.Minimum frequency (Hz) to retain in the output spectrogram. Frequency bins below this value are discarded.
Maximum frequency (Hz) to retain in the output spectrogram. Frequency bins above this value are discarded. Should not exceed the Nyquist frequency (
sr / 2).When
True, applies MinMaxScaler to rescale all spectrogram values into normalize_range before the log transform step. Disable this if you want to preserve the original magnitude scale.When
True, converts the magnitude spectrogram to a decibel scale using 10 * log10(values). This compresses the dynamic range and is recommended for most geophysical signals.The
(min, max) range used by MinMaxScaler during normalization. The non-zero lower bound prevents log10(0) errors when powerlog=True.Lower percentile for clipping the spectrogram. Values below this percentile are set to the percentile value, suppressing low-energy background noise.
Upper percentile for clipping the spectrogram. Values above this percentile are capped, reducing the influence of transient amplitude spikes.
Returns
2D spectrogram matrix of shape
(n_freq, n_time). Pass this directly as an element of spec_images in compute_pointwise_metrics_from_spec().cwt_simple
Computes a Continuous Wavelet Transform (CWT) scalogram usingpywt.cwt. Unlike the STFT, the CWT uses frequency-adaptive window sizes: short windows for high-frequency components and long windows for low-frequency components. This multi-resolution property makes it well-suited for non-stationary signals with transient features. The function returns the real-valued magnitude of the complex wavelet coefficients.
Parameters
1D input time-series signal. Must be one-dimensional — the function will raise an
AssertionError if a 2D array is passed.Sampling rate in Hz. Used to compute the time vector and sampling period when
dt is None.Sampling period in seconds. When
None, it is computed automatically from sr. Provide an explicit value if your signal has an irregular or non-standard sampling period.Dictionary specifying the scale (frequency) range to compute. The
'start' and 'end' keys define the minimum and maximum scale values; 'num' defines the step size (for 'linear' mode) or number of points (for 'log' mode). Adjust 'end' to match the Nyquist frequency of your signal.Name of the continuous wavelet in PyWavelets syntax. The complex Morlet wavelet
'cmor1.5-1.0' is the default and is well-suited for oscillatory geophysical signals. Other valid choices include 'mexh' (Mexican hat) or 'morl' (Morlet).Lower percentile for clipping the output scalogram. Values below this percentile are set to the percentile value.
Minimum frequency (Hz) to retain in the output. Rows corresponding to lower frequencies are removed.
Maximum frequency (Hz) to retain. When
None, all frequencies up to the maximum scale are kept.Frequency scale spacing. Use
'linear' for uniform spacing across the frequency axis or 'log' for logarithmically spaced scales (useful when you want equal resolution per octave, as in musical or seismic analysis).When
True, applies 10 * log10 to the magnitude scalogram. Defaults to False for CWT because log scaling is less common in wavelet-based analysis.When set, reduces the time axis of the scalogram by keeping every
decimate_factor-th column. Useful for very long signals where the CWT output would otherwise be too large to process efficiently.Returns
2D real-valued magnitude scalogram of shape
(n_scales, n_time). This is the array you pass into GISQAPipeline.Raw complex CWT coefficient matrix before magnitude extraction. Useful if you need phase information for custom downstream processing.