Skip to main content
In this guide you will generate two synthetic 1D signals, extract a full set of pointwise spectral features from the raw waveforms, then go one step further and extract features from a 2D STFT spectrogram. By the end you will have a pandas DataFrame of interpretable spectral fingerprints ready for clustering, classification, or visualization — all in fewer than 30 lines of Python.

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 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.
The returned 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 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.
Passing a 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.