
Two-stage feature extraction
Spec2Vec organises its metric computation into two complementary stages. You can run either stage independently or chain them together depending on how much contextual information you have about the noise environment.1
Stage 1 β Pointwise metrics (for Textural and Statistical Features)
Scalar features are extracted directly from a single signal or its spectrogram in isolation. The pipeline flattens the 2D time-frequency representation (TFR) into a 1D trace using a Hilbert space-filling curve to preserve spatial locality, then computes entropy measures, fractal dimensions, and statistical moments on that trace.What you get: a one-row DataFrame of named scalars β permutation entropy, Higuchi fractal dimension, root mean square, Lempel-Ziv complexity, and dozens more β derived entirely from the signal itself, with no external reference needed.
2
Stage 2 β Pairwise metrics (for Spatial Features)
Spatial features are extracted by comparing the target spectrogram against a pre-built noise reference bank β a library of spectrograms from known noise processes (white, pink, red, blue, violet noise, and others). One can also supply their own pre-computed noise reference files. The comparison involves three sub-operations:
- Histogram alignment β the targetβs amplitude distribution is aligned to the closest noise reference via cross-correlation and optimization, isolating the signal-of-interest from background noise.
- GMM labeling β a Gaussian Mixture Model fits the residual (signal minus noise) distribution and assigns integer energy-level labels to each pixel in the TFR.
- GLSZM spatial zone metrics β a Gray-Level Size Zone Matrix quantifies how large and how localized high-energy patches are in the labeled TFR. Outputs include Small Area Emphasis, Large Area Emphasis, Gray Level Non-Uniformity, and more.
For most quick-start workflows you only need Stage 1. Stage 2 requires that you first build or supply a noise bank (an HDF5 file), and it is better suited for production pipelines where you need maximum discriminative power on noisy real-world data.
Input types
Spec2Vec accepts signals at two levels of pre-processing:Raw 1D time-series
Pass a NumPy array directly to
compute_pointwise_metrics_from_spec() with is_hilbertize=0. The pipeline flattens the 1D signal and computes all metrics without a spectrogram step.2D time-frequency representations
Pass a 2D spectrogram (STFT or CWT scalogram) with
is_hilbertize=1. The Hilbert curve flattening step is activated, converting the image into a spatially coherent 1D trace before metric extraction.stft_basic_spectogram) and CWT scalograms (cwt_simple) are supported natively inside utils/spectograms_lib.py. You can also supply any externally generated 2D array .
Output
GISQAPipeline.compute_pointwise_metrics_from_spec() returns a pandas DataFrame where:
- Each row corresponds to one input signal (identified by its entry in
spec_names). - Each column is a named feature such as
permutation_entropy_antropy,detrended_fluctuation_antropy, orLempel-Ziv complexityetc.. - A
labelcolumn carries the signal name for traceability.
Interpretability advantage
Traditional deep-learning approaches encode signals into latent vectors whose dimensions are abstract and interchangeable. Spec2Vec takes the opposite approach: every dimension in its embedding vector corresponds to a mathematically defined, physically grounded quantity.
This makes Spec2Vec particularly valuable in scientific settings where a reviewer or stakeholder needs to understand why two signals were placed in the same cluster.
Repository layout
utils/ folder is the only directory you need to import for embedding generation. Domain application folders each contain their own app_readme.md, notebooks, and data subdirectories that demonstrate end-to-end workflows on specific signal types.