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

# GISQAPipeline: Spec2Vec Pointwise and Pairwise Features

> Use GISQAPipeline to extract named spectral features from signals or spectrograms, with controls for normalization, embedding depth, and feature selection.

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

```python theme={null}
from SPEC2VEC.utils.gisqa_compute_updated import GISQAPipeline

giq = GISQAPipeline()
```

***

## 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

```python theme={null}
df = giq.compute_pointwise_metrics_from_spec(
    spec_names,
    spec_images,
    is_hilbertize=1,
    is_normalize_stat=0,   # 1: normalise statistical features
    is_normalize_entropy=0,
    is_best_features=0,    # 1: return only the top 5 features
    ordpydx=6,
    antropydx=6,
    metrics_list=None,
    hilbert_locs=None
)
```

### Parameters

**spec\_names** `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`.

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

**is\_hilbertize** `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.

**is\_normalize\_stat** `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.

**is\_normalize\_entropy** `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.

**is\_best\_features** `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.

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

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

**metrics\_list** `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`).

**hilbert\_locs** `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

```python theme={null}
import numpy as np
from SPEC2VEC.utils.gisqa_compute_updated import GISQAPipeline
from SPEC2VEC.utils.spectograms_lib import stft_basic_spectogram

# --- Generate two synthetic signals ---
sr = 100      # Sampling rate in Hz
t_len = 5     # Duration in seconds
x = np.linspace(0, t_len, sr * t_len)

y1 = np.sin(2 * np.pi * 35 * x) * np.exp(-((x - 4) ** 2) / (2 * 0.3 ** 2))
y2 = np.sin(2 * np.pi * 20 * x) * np.exp(-((x - 1) ** 2) / (2 * 0.3 ** 2))

# --- Compute STFT spectrograms ---
f, t_arr, stft1 = 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
)
_, _, stft2 = stft_basic_spectogram(
    y2, 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 pointwise features ---
giq = GISQAPipeline()
df = giq.compute_pointwise_metrics_from_spec(
    ['signal_35hz', 'signal_20hz'],
    [stft1, stft2],
    is_hilbertize=1,       # Enable Hilbert curve for 2D input
    is_normalize_stat=1,   # default: normalise statistical features
    is_normalize_entropy=0,
    is_best_features=0,    # override default to compute all features
    ordpydx=7,
    antropydx=5,
    metrics_list=None,
    hilbert_locs=None
)

print(df.shape)            # (2, N_features + 1)
print(df.columns.tolist()) # All feature names plus 'label'
```

***

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

> [!NOTE]
>
> 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

| Consideration | Pointwise | Pairwise |
| - | - | - |
| Requires noise bank | No | Yes (HDF5 file) |
| Computation time | Fast | Slow (optimisation loop) |
| Works on 1D time-series | Yes | No (needs 2D spectrogram) |
| Captures spatial structure | Indirectly | Explicitly |

> [!WARNING]
>
> 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:

```python theme={null}
df = giq.compute_pointwise_metrics_from_spec(
    spec_names, spec_images,
    is_hilbertize=1,
    is_best_features=1,     # this is the default — returns only the top 5
    ordpydx=7, antropydx=5,
    is_normalize_stat=1, is_normalize_entropy=0,
    metrics_list=None, hilbert_locs=None
)
# df will have 6 columns: the 5 best features + 'label'
```

### 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:

```python theme={null}
metrics_to_compute = [
    'detrended_fluctuation_antropy',
    'svd_entropy_antropy',
    'fisher_shannon_ordpy',
    'Lempel-Ziv complexity',
    'Kurtosis',
    'Root mean square',
]

df = giq.compute_pointwise_metrics_from_spec(
    spec_names, spec_images,
    is_hilbertize=1,
    metrics_list=metrics_to_compute,
    ordpydx=7, antropydx=5,
    is_normalize_stat=1, is_normalize_entropy=0,
    is_best_features=0, hilbert_locs=None
)
```

> [!TIP]
>
> 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.

```python theme={null}
import numpy as np
from SPEC2VEC.utils.gisqa_compute_updated import GISQAPipeline
from SPEC2VEC.utils.spectograms_lib import stft_basic_spectogram

# --- Synthetic signal: Gaussian-windowed sine burst ---
sr = 100
t = 5
x = np.linspace(0, t, sr * t)
y = np.sin(2 * np.pi * 35 * x) * np.exp(-((x - 4) ** 2) / (2 * 0.3 ** 2))

# --- Compute spectrogram ---
f, t_arr, stft = stft_basic_spectogram(
    y, sr, 64, 0.5, 'hann', 0, 50,
    max_normalize=False, powerlog=False,
    vmin_percentile=2, vmax_percentile=98
)

# --- Extract features ---
giq = GISQAPipeline()
df = giq.compute_pointwise_metrics_from_spec(
    ['my_signal'], [stft],
    is_hilbertize=1,
    is_normalize_stat=1,   # default: normalise statistical features
    is_normalize_entropy=0,
    is_best_features=0,    # override default to compute all features
    ordpydx=7,
    antropydx=5,
    metrics_list=None,
    hilbert_locs=None
)

print(df.shape)            # (1, N_features)
print(df.columns.tolist()) # List of feature names
```


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