> ## Documentation Index
> Fetch the complete documentation index at: https://spec2vec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Your First Spectral Fingerprint with Spec2Vec

> Extract spectral fingerprints from raw 1D waveforms and 2D STFT spectrograms using Spec2Vec's GISQAPipeline in a few lines of Python.

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

> [!NOTE]
>
> This guide assumes you have already installed Spec2Vec and its dependencies. If you have not done that yet, follow the [Installation](https://spec2vec.mintlify.site/installation.md) 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.

```python theme={null}
## Update For Google Colab
# sys.path.append('/content/drive/MyDrive/')

## Update For Local
sys.path.append('/path/to/my/all_projects') ## e.g. sys.path.append('/data/sswar_files/0_PUBLISHED_CODES')

import numpy as np
from SPEC2VEC.utils.gisqa_compute_updated import GISQAPipeline
from SPEC2VEC.utils.spectograms_lib import stft_basic_spectogram
```

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

```python theme={null}
sr = 100  # Sampling rate in Hz
t = 5     # Duration in seconds
x = np.linspace(0, t, sr * t)

# 35 Hz burst peaking near t = 4 s
y1 = np.sin(2 * np.pi * 35 * x) * np.exp(-((x - 4) ** 2) / (2 * 0.3 ** 2))

# 20 Hz burst peaking near t = 1 s
y2 = np.sin(2 * np.pi * 20 * x) * np.exp(-((x - 1) ** 2) / (2 * 0.3 ** 2))
```

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

```python theme={null}
giq = GISQAPipeline()

features_df = giq.compute_pointwise_metrics_from_spec(
    ['signal_1', 'signal_2'],
    [y1, y2],
    is_hilbertize=0,
    is_normalize_stat=0,
    is_normalize_entropy=0,
    is_best_features=0,
    ordpydx=4,
    antropydx=4,
    metrics_list=None,
    hilbert_locs=None
)

print(features_df)
```

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.

```python theme={null}
# Generate an STFT spectrogram from y1
f, t_arr, stft = stft_basic_spectogram(
    y1, sr, nperseg=64, overlap=0.5,
    window='hann', f_min=0, f_max=50,
    max_normalize=False, powerlog=False,
    vmin_percentile=2, vmax_percentile=98
)

# Extract features from the 2D spectrogram
features_df_2d = giq.compute_pointwise_metrics_from_spec(
    ['signal_1'],
    [stft],
    is_hilbertize=1,
    is_normalize_stat=0,
    is_normalize_entropy=0,
    is_best_features=0,
    ordpydx=5,
    antropydx=5,
    metrics_list=[
        'permutation_entropy_antropy',
        'spectral_entropy_antropy',
        'svd_entropy_antropy',
        'detrended_fluctuation_antropy'
    ],
    hilbert_locs=None
)

print(features_df_2d)
```

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](https://github.com/URseismology/Spec2Vec/blob/main/other_useful_notebooks/example_spec2vec_usage.ipynb) notebook and start right away.

## What's Next

> [card] [Pipeline Concepts](https://spec2vec.mintlify.site/concepts/pipeline.md)
>
> Dive deeper into how GISQAPipeline orchestrates pointwise and pairwise operations under the hood.

> [card] [Feature Catalog](https://spec2vec.mintlify.site/concepts/feature-catalog.md)
>
> Browse the full list of available spectral features and learn what each one measures.

> [card] [ESEC Catalog Clustering](https://spec2vec.mintlify.site/applications/esec-clustering.md)
>
> See how Spec2Vec is used to cluster tectonic and non-tectonic earthquake waveforms.

> [card] [DAS Array Analysis](https://spec2vec.mintlify.site/applications/das.md)
>
> Explore processing and characterization workflows for fiber-optic DAS array data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.