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
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.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.
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.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.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.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.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.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.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).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 throughexecute_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
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: