Skip to main content
Spec2Vec includes a suite of utilities for generating colored noise time-series and simple synthetic signals. These tools serve two primary purposes: building noise reference banks for pairwise metric extraction, and generating labeled synthetic datasets for prototyping and benchmarking your analysis pipeline. The core generators live in noise_lib.py, and higher-level signal models are in simple_synth_data_models.py.

Import


ColoredNoiseGenerator (Class)

ColoredNoiseGenerator generates time-series of different spectral colors by shaping white Gaussian noise in the frequency domain. Instantiate it with the desired number of samples N, then call any color method.
The method for Brownian (red) noise is brownian(), not red(). When you pass 'red' to noiselist in compute_imgbank_dict(), the pipeline internally calls gen.brownian() on your behalf.
The table below summarizes the spectral shape of each noise color and its typical geophysical context.
All ColoredNoiseGenerator methods return a numpy array of length N. The output is not amplitude-normalized by default. If you need unit-scale signals for spectrogram generation, normalize with sklearn.preprocessing.MinMaxScaler(feature_range=(-1, 1)) before computing the STFT or CWT.

white_noise_series (function)

Generates a simple white noise time-series drawn from a normal distribution. This is a standalone function — use it when you need a quick white noise segment without instantiating ColoredNoiseGenerator.

Parameters

int
required
Length of the time series (number of samples).
float
default:"1"
Amplitude multiplier applied to the noise output.
float
default:"0"
Mean of the normal distribution.
float
default:"1"
Standard deviation of the normal distribution.

Returns

np.ndarray
1D array of length L containing the generated white noise signal.

ar_driven_noise_series (function)

Generates a noise time-series from a linear autoregressive (AR) system driven by white noise. The AR coefficients a_k define the resonant structure of the output signal. You can use this to synthesize signals with known spectral shapes (e.g., narrow-band resonances) for testing your pipeline.

Parameters

float
default:"2"
Length of the time series in seconds.
int
default:"1000"
Sampling rate of the output time series in Hz.
float
default:"1"
Variance of the driving white noise.
list or np.ndarray
default:"[1, -2.2137, 2.9403, -2.1697, 0.9606]"
Autoregressive coefficients. The first element must be 1. The roots of the characteristic polynomial defined by a_k must all lie inside the unit circle for the system to be stable.
float or None
default:"None"
Minimum frequency (Hz) for PSD computation. When None, defaults to 0.
float or None
default:"None"
Maximum frequency (Hz) for PSD computation. When None, defaults to the Nyquist frequency.

Returns

np.ndarray
The synthesized time-series signal.
np.ndarray
Corresponding time vector.
np.ndarray
Complex Fourier series of the signal.
np.ndarray
Frequency vector matching the spectral length.
np.ndarray
Power Spectral Density array at the returned frequency bins. Compare this against the empirical spectrogram as a sanity check.

psd_driven_noise_series (function)

Synthesizes a noise time-series directly from a custom PSD curve you supply. Use this when you have a measured or modeled PSD and want to generate realizations of a signal with that exact spectral shape.

Parameters

np.ndarray
required
A vector of uniformly separated frequencies (Hz) over which the PSD is defined.
np.ndarray
required
A vector of PSD values corresponding to f.
float
default:"2"
Total length of the desired signal in seconds.
int
default:"1000"
Sampling rate of the desired signal in Hz.
float or None
default:"None"
Minimum frequency to compute. Defaults to 0 when None.
float or None
default:"None"
Maximum frequency to compute. Defaults to the Nyquist frequency when None.

Returns

np.ndarray
Time vector for the synthesized signal.
np.ndarray
The synthesized real time-series signal.
np.ndarray
Frequency vector matching the signal’s spectral length.
np.ndarray
Complex Fourier series of the signal.
np.ndarray
Power Spectral Density interpolated at the output frequency bins.

Building a Noise Bank

Pairwise metric extraction requires a noise reference bank: a collection of spectrogram images computed from multiple realizations of different noise types. The bank defines the statistical “background” against which your target signal’s amplitude distribution is aligned before GMM labeling and GLSZM zone metric computation. Use GISQAPipeline.compute_imgbank_dict() to build a bank programmatically. Pass spec_types=['stft'] and a list of noise color strings in noiselist. The method generates total_realizations independent noise realizations per noise color and STFT parameter combination, converts each to a spectrogram, and stores all images in a structured dictionary.
Each key in the returned dictionary corresponds to one noise type and STFT window configuration. The values are sub-dictionaries with the following fields:
The noise bank must be built at the same spectrogram resolution (height × width) as the target spectrograms you plan to analyze. If you process signals with multiple resolutions, build a separate bank for each resolution or use the interp_size parameter in compute_imgbank_dict() to standardize all images to a common shape.


Simple Synthetic Signal Models

simple_synth_data_models.py provides functions for constructing controlled synthetic time-series. These are useful for generating labeled training sets, validating your pipeline on signals with known properties, and designing sensitivity tests.

Additive processes

An additive signal is the superposition of multiple sinusoidal components:

Multiplicative processes

A multiplicative signal encodes amplitude modulation between frequency components. Two formulations are available:
  • Type 1: x(t) = sin(A) · sin(B) · ··· · sin(N) — pure product of sinusoids
  • Type 2: x(t) = sin(A) · (1 + ε · sin(B)) — carrier modulated by a low-frequency envelope (requires exactly two frequencies with w[0] > w[1])
gen_multiplicative_synthetic_signal requires w and a to be numpy arrays (not plain lists) and type is a positional argument.

Autoregressive processes

Autoregressive (AR) signals are generated from a linear filter driven by white noise, where the denominator polynomial A(z) determines the resonant frequencies and decay rates of the system. Use ar_driven_noise_series() from noise_lib.py for this purpose.
The AR coefficients a_k must define a stable system (all roots of the characteristic polynomial inside the unit circle). The function also returns the theoretical PSD, which you can compare against the empirical spectrogram as a sanity check.