Skip to main content
Spec2Vec converts raw geophysical signals into compact, interpretable vector embeddings by systematically computing a suite of information-theoretic, statistical, and spatial metrics across the signal’s time-frequency representation. Rather than relying on a neural network whose internal reasoning is opaque, every number in a Spec2Vec embedding has a name and a physical meaning β€” making results auditable, reproducible, and portable across datasets without retraining.
Flowchart

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:
  1. 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.
  2. 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.
  3. 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.
What you get: spatial descriptors that capture where and how concentrated signal energy is within the time-frequency plane.
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.
Both STFT spectrograms (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, or Lempel-Ziv complexity etc..
  • A label column carries the signal name for traceability.
This tidy tabular output plugs directly into scikit-learn classifiers, UMAP/t-SNE projectors, or any clustering algorithm without further transformation.

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

The 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.