From signal to spectrogram
Before any metrics are computed, a 1D time-series must be mapped into a 2D time-frequency representation (TFR). Spec2Vec supports two transforms out of the box, both available inutils/spectograms_lib.py:
STFT spectrogram
stft_basic_spectogram() uses SciPy’s Short-Time Fourier Transform to produce a magnitude or decibel-scale spectrogram. Key parameters include the window length (nperseg), fractional overlap, window function, and frequency bounds [f_min, f_max]. This is the recommended starting point for most geophysical waveforms.CWT scalogram
cwt_simple() uses PyWavelets to compute a Continuous Wavelet Transform scalogram. It supports arbitrary mother wavelets (e.g., cmor1.5-1.0) and both linear and logarithmic frequency scales. CWT captures transient features at multiple resolutions and is preferred for non-stationary signals.f, a time array t, and the 2D spectrogram matrix spectro. cwt_simple() additionally returns a fourth value — cwtmatr_cmplx, the raw complex CWT coefficient matrix — so unpack it as f, t, spectro, cwtmatr_cmplx = cwt_simple(...) if you need the phase information, or use f, t, spectro, _ = cwt_simple(...) to discard it. The spectro matrix is the input to the fingerprinting pipeline.
Hilbert curve flattening
Feature extractors from theantropy, ordpy, and tsfel libraries all operate on 1D arrays. A naïve row-by-row or column-by-column flattening of a 2D spectrogram destroys spatial relationships: pixels that are adjacent in frequency are no longer adjacent in the 1D array when a new row begins.
Spec2Vec solves this with a Hilbert space-filling curve (or its generalised variant, the Gilbertised curve, for non-square images). A space-filling curve visits every pixel in the 2D grid exactly once while maximising the probability that pixels that are spatially close in 2D remain close in the resulting 1D trace.
1
Determine image geometry
If the spectrogram is square with power-of-2 dimensions, the standard Hilbert curve is used (
_hilbertize_sym_data). For rectangular spectrograms — the common case with STFT — the generalised Gilbertised algorithm (_ghilbertize_asym_data) is applied instead.2
Build the curve index
A lookup array
locs of shape (N_pixels, 2) is generated, mapping each position along the 1D trace to its (row, col) coordinate in the 2D spectrogram.3
Sample the spectrogram
The spectrogram is indexed as
spec[locs[:,0], locs[:,1]] to produce a 1D array of length N_pixels = height × width. This trace is then fed to all metric extractors.is_hilbertize=1 when calling compute_pointwise_metrics_from_spec(). For raw 1D time-series inputs, set is_hilbertize=0 — the signal is used directly without a flattening step.
If you are processing a large batch of spectrograms that all have the same shape, you can pre-compute the Hilbert locations once using
HelperFunc.gilbertize_image_optimized() and pass the result as hilbert_locs to skip recomputation on every call.Metric categories
Once the spectrogram has been flattened to a 1D trace, three families of metrics are computed in parallel.Information-theoretic & entropy
These metrics quantify disorder, predictability, and structural complexity in the signal. A white-noise spectrogram will have near-maximum permutation entropy; a narrowband monochromatic tone will have very low entropy. This family includes measures from both
antropy (e.g., permutation entropy, SVD entropy, approximate entropy, sample entropy, Hjorth mobility/complexity) and ordpy (e.g., Fisher–Shannon information, Rényi complexity-entropy, Tsallis complexity-entropy, weighted permutation entropy, missing ordinal patterns).Complexity & fractal dimension
These metrics quantify self-similarity and roughness of the signal trace. Higher fractal dimension indicates a rougher, more complex waveform. This family includes Petrosian FD, Katz FD, Higuchi FD, detrended fluctuation analysis (DFA), and Lempel-Ziv complexity — all computed via
antropy and tsfel.Statistical moments & distribution
These metrics capture the amplitude distribution of spectrogram pixel values: mean, variance, skewness, kurtosis, root mean square, interquartile range, ECDF percentiles, histogram mode, and more. They are computed via
tsfel and describe the overall energy budget and shape of the amplitude distribution.Entropy & ordpy features in detail
Fractal & complexity features in detail
Best features
When you setis_best_features=1, Spec2Vec returns only the five features that can be helpful in discriminating across different geophysical signal datasets:
is_best_features=0 and optionally pass a metrics_list to select exactly the features you need.
The resulting vector
After all three metric families are computed, the results fromantropy, ordpy, and tsfel are horizontally concatenated into a single-row pandas DataFrame. That row is your signal’s spectral fingerprint — a fixed-length numerical identity that can be used directly as input to:
- Clustering — k-means, HDBSCAN, Gaussian Mixture Models
- Dimensionality reduction — UMAP, PCA, t-SNE for visualisation
- Classification — any scikit-learn classifier (Random Forest, SVM, etc.)
- Anomaly detection — distance-based outlier scores in feature space
- Feature importance analysis — SHAP values to identify which metrics drive cluster separation
detrended_fluctuation_antropy tells you directly how much the long-range correlation structure of the waveform influenced a particular classification decision.