Prerequisites
This guide assumes you have already installed Spec2Vec and its dependencies. If you have not done that yet, follow the Installation guide first and make sure your conda environment is activated before running the code below.
1
Import Spec2Vec
Start by importing NumPy and the two Spec2Vec modules you will use: the
GISQAPipeline class for feature extraction and stft_basic_spectogram for generating time-frequency representations.2
Create a test signal
Generate two synthetic signals — each is a sinusoidal burst shaped by a Gaussian envelope. The signals differ in frequency (35 Hz vs. 20 Hz) and in when the burst peaks (4 s vs. 1 s), so they represent two clearly distinct signal types.
3
Extract pointwise features from raw 1D signals
Instantiate The returned
GISQAPipeline and call compute_pointwise_metrics_from_spec() with your signal names and arrays. Setting is_hilbertize=0 tells Spec2Vec to treat each input as a 1D sequence rather than a 2D image — no Hilbert curve traversal is needed for raw waveforms.features_df is a pandas DataFrame with one row per signal. Each column is a named spectral feature — entropy measures, complexity indices, statistical moments, and more. You can pass this DataFrame directly to sklearn for clustering or dimensionality reduction.4
Extract features from a 2D spectrogram
For richer characterization, you can first convert a waveform into a Short-Time Fourier Transform (STFT) spectrogram (or ay TFR) and then extract features from the resulting 2D image. Setting Passing a
is_hilbertize=1 activates Hilbert curve flattening, which traverses the 2D spectrogram along a space-filling curve before computing features — preserving the spatial structure of the image.metrics_list restricts computation to only the named features, which is useful when you want a lightweight embedding or when you already know which features are most discriminative for your application.5
Example Notebook
You can refer to the example_spec2vec_usage.ipynb notebook and start right away.
What’s Next
Pipeline Concepts
Dive deeper into how GISQAPipeline orchestrates pointwise and pairwise operations under the hood.
Feature Catalog
Browse the full list of available spectral features and learn what each one measures.
ESEC Catalog Clustering
See how Spec2Vec is used to cluster tectonic and non-tectonic earthquake waveforms.
DAS Array Analysis
Explore processing and characterization workflows for fiber-optic DAS array data.