GISQAPipeline is the primary interface for extracting spectral features from signals in Spec2Vec. It wraps both the pointwise (statistical, entropy, fractal) and pairwise (spatial zone) metric pipelines into a single, high-level object that you instantiate once and reuse across your entire analysis.
Import
compute_pointwise_metrics_from_spec
Computes pointwise feature metrics for a batch of signals or spectrograms and returns the results as a tidyDataFrame. Each row corresponds to one input signal; each column is a named feature.
Parameters
Names or labels for each input signal. Must be the same length as
spec_images. Each name becomes the identifying label for that signal’s row in the output DataFrame.List of input arrays. Each element can be either a 1D time-series array or a 2D spectrogram array (frequency × time). All arrays in the list may have different shapes.
Set to
1 to apply Hilbert curve (space-filling curve) flattening before feature extraction. This is required for 2D spectrogram inputs so that the image is reduced to a 1D sequence while preserving spatial locality. Set to 0 when passing raw 1D time-series arrays.Set to
1 to normalize all statistical and textural features to the [0, 1] range using MinMaxScaler. Set to 0 to return raw feature values.Set to
1 to normalize entropy-based features to [0, 1]. Entropy features are often already bounded by their mathematical definition, so normalization is optional.Set to
1 to return only the top five most discriminating features: detrended_fluctuation_antropy, fisher_shannon_ordpy, 0_Lempel-Ziv complexity, svd_entropy_antropy, and approximate_entropy_antropy. Set to 0 to return the full feature set (50+ features).An explicit list of feature names to compute, for example:When
None, all available features are computed (subject to is_best_features). Providing a subset substantially reduces runtime.Returns
A
DataFrame where rows are indexed by position (with a label column containing spec_names) and columns are feature names. Shape is (len(spec_names), n_features).execute_pairwise_pipleine
Runs the full pairwise spatial feature extraction pipeline for a single spectrogram image against a noise reference bank. The pipeline performs histogram alignment, Gaussian Mixture Model (GMM) labeling, and Gray-Level Size Zone Matrix (GLSZM) spatial metric computation in two refinement stages.Parameters
Time axis array for the spectrogram, as returned by
stft_basic_spectogram() or cwt_simple().List of group keys inside the HDF5 file to use as reference noise templates. Each key corresponds to a noise type/configuration that was stored when the bank was built.
List of keys in the noise bank that correspond to binary mask entries (i.e., images with only two intensity levels). The binary images will be converted to a normal distribution to optimize the histogram alignment. This is only required if the noise-bank contains binary images.
Number of histogram bins used for distribution alignment between the target spectrogram and each noise reference template.
Percentile threshold for estimating the noise floor during histogram alignment. Pixels below this threshold in the realigned histogram are treated as noise.
When
True, performs only the correlation-based histogram alignment step and skips the exponential optimization. Useful for a fast first-pass inspection of the noise fit quality.Number of Gaussian components for GMM fitting. Controls the maximum number of distinct energy zones the pipeline attempts to identify in the spectrogram.
Minimum mean separation between adjacent GMM components. Components whose means are closer than this threshold are merged to prevent over-segmentation. Defaults to 0.05.
Normalization strategy applied to the spectrogram before GMM fitting. Pass
'full' to normalize across the entire image (recommended), or 'columns' to normalize each column independently.Minimum number of contiguous pixels required to form a valid size zone in the GLSZM computation. Zones smaller than this threshold are treated as speckle noise and filtered out in stage 2.
Label string written into the
label column of the returned metrics DataFrame and used as the base filename for saved plots.Directory path for saving intermediate visualization plots. Created automatically if it does not exist.
When
True, saves diagnostic plots covering the original spectrogram, aligned distributions, GMM cuts, labeled spectrograms, size zone variance, and the noise-filtered result. When False the Feature generation process works faster.When provided, skips the automatic nearest-neighbour search and uses this key directly as the noise reference template. Useful when you already know the best-matching noise type for your signal class.
Dictionary controlling the exponential optimization used during histogram alignment. Keys are
'type', 'start', 'end', and 'slope'. Defaults to {'type': 'exponential', 'start': 0.1, 'end': 100, 'slope': 10}. One can play with these parameters while keeping the save_all_plots=True to understand what works best.Percentile range
(lower, upper) used when scaling the spectrogram pixel values during noise filtering. Defaults to 1 and 100. Should only be updated if need to eliminate extr speckle noise in the 2D representation.Returns
DataFrame containing stage-1 and stage-2 GLSZM spatial zone metrics. Stage-1 columns are suffixed _stg1; stage-2 (speckle-filtered) columns are suffixed _stg2. Also includes a label column.Dictionary with keys
t_plot, f_plot, labeled_spec_image, arguments_dict, refined_labeled_spec_image, and spec_image_noise_cleaned. Useful for downstream visualization or further analysis.The following functions are useful only when Spatial Metrics Computations are needed for a specific application.
compute_imgbank_dict
Generates a dictionary of noise spectrogram banks from a list of noise type labels and corresponding noise arrays. You can pass the result directly tocompute_noisebnk_metrics() or save it to HDF5 for Spatial feature extractions pipeline. For a full end to end pipeline please refer to reference_noisebankprep.ipynb file.
Parameters
List of spectrogram (or spatial structure) types to generate. Supported values include
'stft', 'cwt', 'perlin_noise', 'erdos_renyi_graph', 'Gaussian', 'Exponential', and 'pspy_fractal_noise'. For standard geophysical workflows, use ['stft'] or ['cwt'].List of colored noise color strings to generate spectrograms for. Supported values:
'white', 'pink', 'red', 'blue', 'violet', 'f3', 'f4'. Ignored for non-time-series spec types.Duration in seconds for each generated noise segment. Combined with
Fs to set the total number of samples (L = Fs × time_in_sec).Number of independent noise realizations to generate per noise type and spectrogram configuration. More realizations provide a more stable reference distribution.
Sampling period in seconds. When
None, it is computed from Fs. Pass an explicit value only when your signal has a non-standard sampling period.If provided, the generated bank is written to this HDF5 file path. The file can then be passed as
noisebnk_path to execute_pairwise_pipleine().Target image dimensions
(height, width) for interpolating all spectrograms to a common resolution. Useful when mixing STFT windows of different sizes.Returns
Dictionary mapping noise group names (e.g.,
'white_stft_w64_olap0.5') to sub-dictionaries containing 'image' (shape [realizations, 1, H, W]), 'hilbert_image', 'time_series', 'f', and 't' arrays.compute_noisebnk_metrics
Extracts pointwise feature metrics for every entry in a noise reference bank. You can provide either a path to an existing HDF5 bank or the in-memory dictionary returned bycompute_imgbank_dict(). The result is a DataFrame in the same format as compute_pointwise_metrics_from_spec(), suitable for use as a reference distribution in downstream pointwise feature-difference analysis.
Parameters
Path to an HDF5 noise bank file. If provided, the file is opened and iterated over. Takes priority over
img_bank_dict when both are supplied.In-memory bank dictionary as returned by
compute_imgbank_dict(). Used when noise_bnk_path is empty.Maximum number of noise realizations to process per noise group. Useful for controlling runtime during exploratory analysis.
Return only the top 5 discriminating features. Set to
0 to compute the full feature set for comprehensive noise characterization.If provided, the resulting
DataFrame is saved to this CSV path after each noise group completes, acting as a checkpoint.Set to
1 to print a progress message to stdout after each noise group finishes processing.