Skip to main content
Spec2Vec includes built-in functions to convert 1D time-series signals into 2D time-frequency representations (TFRs). These representations expose the frequency content of your signal as a function of time and are the recommended input format when you want to extract richer spatial and textural features using the Hilbert curve flattening path in 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 using scipy.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

np.ndarray
required
The 1D input time-series signal to transform.
int or float
required
Sampling rate of the signal in Hz.
int
required
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.
float
required
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.
str or tuple
required
Window function to apply to each segment. Any window accepted by scipy.signal.get_window() is valid, such as 'hann', 'hamming', or 'blackman'.
float
required
Minimum frequency (Hz) to retain in the output spectrogram. Frequency bins below this value are discarded.
float
required
Maximum frequency (Hz) to retain in the output spectrogram. Frequency bins above this value are discarded. Should not exceed the Nyquist frequency (sr / 2).
bool
default:"True"
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.
bool
default:"True"
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.
tuple
default:"(1e-8, 1)"
The (min, max) range used by MinMaxScaler during normalization. The non-zero lower bound prevents log10(0) errors when powerlog=True.
int
default:"5"
Lower percentile for clipping the spectrogram. Values below this percentile are set to the percentile value, suppressing low-energy background noise.
int
default:"100"
Upper percentile for clipping the spectrogram. Values above this percentile are capped, reducing the influence of transient amplitude spikes.

Returns

np.ndarray
1D frequency array in Hz, shaped (n_freq,). Frequencies are returned in ascending order.
np.ndarray
1D time array in seconds, shaped (n_time,).
np.ndarray
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 using pywt.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

np.ndarray
required
1D input time-series signal. Must be one-dimensional — the function will raise an AssertionError if a 2D array is passed.
int
default:"1000"
Sampling rate in Hz. Used to compute the time vector and sampling period when dt is None.
float or None
default:"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.
dict
default:"{'start': 1, 'end': 512, 'num': 100}"
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.
str
default:"'cmor1.5-1.0'"
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).
int
default:"2"
Lower percentile for clipping the output scalogram. Values below this percentile are set to the percentile value.
int
default:"98"
Upper percentile for clipping the output scalogram.
int
default:"0"
Minimum frequency (Hz) to retain in the output. Rows corresponding to lower frequencies are removed.
int or None
default:"None"
Maximum frequency (Hz) to retain. When None, all frequencies up to the maximum scale are kept.
bool
default:"True"
When True, applies MinMaxScaler to rescale values into normalize_range.
str
default:"'linear'"
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).
bool
default:"False"
When True, applies 10 * log10 to the magnitude scalogram. Defaults to False for CWT because log scaling is less common in wavelet-based analysis.
tuple
default:"(1e-8, 1)"
The (min, max) range for MinMaxScaler normalization.
int or None
default:"None"
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

np.ndarray
1D frequency array in Hz, shaped (n_scales,), in ascending order.
np.ndarray
1D time array in seconds, shaped (n_time,).
np.ndarray
2D real-valued magnitude scalogram of shape (n_scales, n_time). This is the array you pass into GISQAPipeline.
np.ndarray
Raw complex CWT coefficient matrix before magnitude extraction. Useful if you need phase information for custom downstream processing.

Choosing Between STFT and CWT

Use stft_basic_spectogram when your signal is approximately stationary, you need fast processing of large batches, or you want fixed time–frequency resolution across the entire signal. STFT is significantly faster than CWT and produces rectangular spectrogram tiles that are easy to compare across signals.Use cwt_simple when your signal contains transient or non-stationary features — for example, earthquake P-wave arrivals, DAS glitches, or short-duration acoustic pulses — where capturing the instantaneous frequency content at multiple time scales is important. CWT provides higher time resolution at high frequencies and higher frequency resolution at low frequencies, at the cost of longer compute time.