Skip to main content
GISQAPipeline is the main entry point to Spec2Vec. It is a high-level class that wraps both pointwise (texture and stat) and pairwise feature (spatial) extraction into a clean API, letting you go from a list of raw arrays to a labelled pandas DataFrame in a single method call. You instantiate it once and then call whichever extraction method fits your workflow — there is no configuration file to edit and no subclassing required.

Pointwise pipeline

The pointwise pipeline extracts scalar features from each signal or spectrogram independently, with no reference to other signals. It is fast, self-contained, and requires no external data beyond the input arrays themselves.

Method signature

Parameters

list[str]
required
A list of string identifiers for each signal. These become the values in the label column of the returned DataFrame and are used to track which row corresponds to which input. The list must have the same length as spec_images.
list[np.ndarray]
required
A list of NumPy arrays to process. Each element can be a 1D array (raw time-series) or a 2D array (spectrogram or scalogram). All arrays in the list may have different shapes — the pipeline processes them one at a time.
int
default:"1"
Set to 1 to enable Hilbert curve flattening for 2D spectrogram inputs. The pipeline automatically selects the standard Hilbert curve for square power-of-2 images and the generalised Gilbertised curve for rectangular images. Set to 0 when passing 1D time-series arrays directly.
int
default:"1"
Set to 1 to normalise the flattened signal to the range [-1, 1] before computing statistical features (mean, variance, kurtosis, etc.). Normalisation is performed with MinMaxScaler. Normalising statistical features can improve comparability across signals with different amplitude scales. Enabled by default.
int
default:"0"
Set to 1 to normalise the flattened signal before computing entropy and fractal features (permutation entropy, DFA, etc.). Note that some entropy measures — particularly svd_entropy_antropy — are sensitive to the amplitude scaling of the input, so evaluate whether normalisation helps or hurts for your specific dataset.
int
default:"1"
When 1 (the default), the pipeline returns only the five most discriminating features identified across geophysical datasets: detrended_fluctuation_antropy, fisher_shannon_ordpy, Lempel-Ziv complexity, svd_entropy_antropy, and approximate_entropy_antropy. Set to 0 to compute all available features. When metrics_list is also provided, metrics_list takes precedence regardless of this flag.
int
default:"7"
The embedding dimension (dx) passed to all ordpy feature computations. Controls the length of ordinal patterns evaluated (pattern length = ordpydx). Recommended range: 4–8. Higher values capture longer-range correlations but increase computation time and require longer input signals.
int
default:"5"
The embedding dimension (dx) passed to all antropy entropy and fractal computations. Affects permutation entropy, SVD entropy, approximate entropy, and sample entropy. Recommended range: 4–6. Must be consistent across your dataset for results to be comparable.
list[str] | None
default:"None"
An explicit list of feature names to compute. When provided, only the listed features are extracted — all others are skipped, which substantially speeds up processing on large datasets. Feature names must use the canonical suffixed form: _antropy, _ordpy, or the plain TSFEL name (e.g., 'Lempel-Ziv complexity'). When None, all features are computed (unless is_best_features=1).
np.ndarray | None
default:"None"
Pre-computed Hilbert curve index array of shape (N_pixels, 2), where each row is a (row, col) coordinate. If you are processing a large batch of spectrograms that all have the same shape, pass a pre-computed index here to avoid re-running the curve generation on every call. Generate it once with HelperFunc.gilbertize_image_optimized(width=H, height=W).

Full worked example


Pairwise pipeline

The pairwise pipeline, accessed through execute_pairwise_pipleine(), compares a target spectrogram against a pre-built noise reference bank to extract spatial zone metrics. It provides discriminative features for noisy real-world data.
The method is spelled execute_pairwise_pipleine (note the transposed letters in “pipeline”) — this matches the current source exactly. Use this spelling when calling the method in your own code.

The three sub-steps

1

Histogram alignment

The amplitude distribution of the target spectrogram is compared against every entry in the noise bank using cross-correlation and differential evolution optimization. The noise entry whose aligned distribution best matches the target is selected as the reference. The optimal scaling factor stretches the noise distribution to overlap with the target, effectively isolating the signal of interest from background noise.
2

GMM labeling

A Gaussian Mixture Model (GMM) is fitted to the residual distribution — the portion of the spectrogram that exceeds the noise threshold. The GMM components define cut thresholds along the intensity axis, and every pixel in the spectrogram is assigned an integer energy label (0 = noise floor, 1 = low signal, 2 = moderate signal, and so on).
3

GLSZM spatial zone metrics

The labeled spectrogram is analysed using a Gray-Level Size Zone Matrix (GLSZM) from the pyradiomics library. This quantifies how energy patches are spatially distributed — whether high-energy pixels form large coherent zones or are scattered as small isolated spots. Outputs include Small Area Emphasis, Large Area Emphasis, Gray Level Non-Uniformity Normalized, Size Zone Non-Uniformity Normalized, Large Area High Gray Level Emphasis, and a custom Weighted Zone Size Percentage. A second-pass refinement removes small speckle zones before recomputing, yielding _stg1 and _stg2 variants of every metric.

When to use pairwise vs pointwise

The pairwise pipeline requires a pre-built noise bank in HDF5 format. You can generate one using GISQAPipeline.compute_imgbank_dict() or compute_noisebnk_metrics(). Without it, the histogram alignment step has no reference to align against. The DAS application notebook shows exactly how to generate a noise reference and use for spatial metrics computation.

Normalization options

Two independent normalization flags let you control whether the flattened signal trace is rescaled before metric computation. is_normalize_stat defaults to 1 (enabled) while is_normalize_entropy defaults to 0 (disabled). You can set them independently — for example, is_normalize_stat=0, is_normalize_entropy=0 disables both. For random forest types applications these normalization steps are not needed and recommended to be set to 0.

Feature selection

Spec2Vec offers two complementary ways to control which features are returned, letting you trade completeness for speed.

Using is_best_features

Setting is_best_features=1 returns exactly five features that have been empirically validated as the top discriminators across multiple geophysical signal datasets:

Using metrics_list

For fine-grained control, pass an explicit list of feature names. Only those features — and the computations required to produce them — will be executed. This is the recommended approach for production pipelines:
When metrics_list is provided, is_best_features is ignored. The pipeline computes only what you asked for and returns those columns plus label.

Complete end-to-end example

The example below walks through signal generation, spectrogram computation, and pointwise feature extraction in a single script — the minimal reproducible workflow for Spec2Vec.