dsp

dsp.py - Digital Signal Processing module for DAS4Whales

This module provides various functions for digital signal processing of DAS strain data.

Authors: Léa Bouffaut, Quentin Goestchel Date: 2023-2024-2025

das4whales.dsp.bp_filt(data, fs, fmin, fmax)

bp_filt - perform bandpass filtering on an array of DAS data

Parameters:

• data (array-like) – array containing wave signal from DAS data

• fs (float) – sampling frequency

• fmin (float) – minimum frequency for the passband

• fmax (float) – maximum frequency for the passband

Returns:

tr_filt – bandpass filtered data

Return type:

array-like

das4whales.dsp.butterworth_filter(filterspec, fs)

Designs and applies a Butterworth filter.

Parameters:

filterspectuple

A tuple containing the filter order, critical frequency, and filter type.

fsfloat

The sampling frequency.

Returns:

: filter_sos : np.ndarray

The second-order sections (SOS) representation of the Butterworth filter.

das4whales.dsp.calc_snr_median(trace)

Calculate the Signal-to-Noise Ratio (SNR) for a given input trace.

This function computes the SNR for the input trace. The SNR is calculated as the ratio of the square of the envelope of the trace to the square of the median of the trace.

Parameters:

trace (np.ndarray) – The input trace for which the SNR is to be calculated.

Returns:

The Signal-to-Noise Ratio (SNR) value for the input trace.

Return type:

np.ndarray

das4whales.dsp.fk_filt(data, tint, fs, xint, dx, c_min, c_max, display_filter=False)

fk_filt - perform fk filtering on an array of DAS data

Parameters:

• data (array-like) – array containing wave signal from DAS data

• tint (float) – decimation time interval between considered samples

• fs (float) – sampling frequency

• xint (float) – decimation space interval between considered samples

• dx (float) – spatial resolution

• c_min (float) – minimum phase speed for the pass-band filter in f-k domain

• c_max (float) – maximum phase speed for the pass-band filter in f-k domain

Returns:

• f (array-like) – vector of frequencies

• k (array-like) – vector of wavenumbers

• g (array-like) – 2D designed gaussian filter

• data_fft_g (array-like) – 2D Fourier transformed data, filtered by g

• data_g.real (array-like) – Real value of spatiotemporal filtered data

das4whales.dsp.fk_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400, cp_min=1450, cp_max=3400, cs_max=3500, display_filter=False)

Designs a f-k filter for DAS strain data Keeps by default data with propagation speed [1450-3400] m/s

The transition band is inspired and adapted from Yi Lin’s matlab fk function https://github.com/nicklinyi/seismic_utils/blob/master/fkfilter.m

Parameters:

• trace_shape (tuple) – A tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample].

• selected_channels (list) – A list of the selected channels number [start, end, step].

• dx (float) – Channel spacing (m).

• fs (float) – Sampling frequency (Hz).

• cs_min (float, optional) – Minimum selected sound speeds for the f-k passband filtering (m/s). Default is 1400 m/s.

• cp_min (float, optional) – Minimum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 1450 m/s.

• cp_max (float, optional) – Maximum selected sound speeds for the f-k passband filtering (m/s). Default is 3400 m/s.

• cs_max (float, optional) – Maximum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 3500 m/s.

Returns:

fk_filter_matrix – A [channel x time sample] numpy array containing the f-k-filter.

Return type:

ndarray

das4whales.dsp.fk_filter_design_old(trace_shape, selected_channels, dx, fs, cs_min=1400, cp_min=1450, cp_max=3400, cs_max=3500, display_filter=False)

Designs a f-k filter for DAS strain data Keeps by default data with propagation speed [1450-3400] m/s

The transition band is inspired and adapted from Yi Lin’s matlab fk function https://github.com/nicklinyi/seismic_utils/blob/master/fkfilter.m

Parameters:

• trace_shape (tuple) – A tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample].

• selected_channels (list) – A list of the selected channels number [start, end, step].

• dx (float) – Channel spacing (m).

• fs (float) – Sampling frequency (Hz).

• cs_min (float, optional) – Minimum selected sound speeds for the f-k passband filtering (m/s). Default is 1400 m/s.

• cp_min (float, optional) – Minimum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 1450 m/s.

• cp_max (float, optional) – Maximum selected sound speeds for the f-k passband filtering (m/s). Default is 3400 m/s.

• cs_max (float, optional) – Maximum selected sound speed for the f-k stopband filtering, values should frame [c_min and c_max] (m/s). Default is 3500 m/s.

Returns:

fk_filter_matrix – A [channel x time sample] numpy array containing the f-k-filter.

Return type:

ndarray

Deprecated since version 0.1.0: This will be removed in 0.2.0. Use hybrid_filter_design instead

das4whales.dsp.fk_filter_filt(trace, fk_filter_matrix, tapering=False)

Applies a pre-calculated f-k filter to DAS strain data.

Parameters:

• trace (np.ndarray) – A [channel x time sample] nparray containing the strain data in the spatio-temporal domain.

• fk_filter_matrix (np.ndarray) – A [channel x time sample] nparray containing the f-k-filter.

• tapering (bool, optional) – Flag indicating whether to apply tapering to the data. Default is False.

Returns:

A [channel x time sample] nparray containing the f-k-filtered strain data in the spatio-temporal domain.

Return type:

np.ndarray

das4whales.dsp.fk_filter_sparsefilt(trace, fk_filter_matrix, tapering=False)

Applies a pre-calculated f-k filter to DAS strain data

Parameters:

• trace (np.ndarray) – A [channel x time sample] nparray containing the strain data in the spatio-temporal domain.

• fk_filter_matrix (np.ndarray) – A [channel x time sample] nparray containing the f-k-filter.

Returns:

A [channel x time sample] nparray containing the f-k-filtered strain data in the spatio-temporal domain.

Return type:

np.ndarray

das4whales.dsp.get_fx(trace, nfft)

Apply a fast Fourier transform (FFT) to each channel of the strain data matrix.

Parameters:

• trace (ndarray) – A 2D array of shape (channel, time sample) containing the strain data in the spatio-temporal domain.

• nfft (int) – Number of time samples used for the FFT.

Returns:

A 2D array of shape (channel, freq. sample) containing the strain data in the spatio-spectral domain.

Return type:

ndarray

das4whales.dsp.get_spectrogram(waveform, fs, nfft=128, overlap_pct=0.8)

Get the spectrogram of a single channel

Parameters:

• waveform (ndarray) – Single channel temporal signal.

• fs (float) – The sampling frequency (Hz).

• nfft (int) – Number of time samples used for the STFT. Default is 128.

• overlap_pct (float) – Percentage of overlap in the spectrogram. Default is 0.8.

Return type:

Tuple[ndarray, ndarray, ndarray]

Returns:

• p (np.ndarray) – Spectrogram in dB scale (normalized by max).

• tt (np.ndarray) – Time vector.

• ff (ndarray) – Frequency vector.

das4whales.dsp.hybrid_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400.0, cp_min=1450.0, fmin=15.0, fmax=25.0, display_filter=False)

Designs an infinite wave speed bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• cs_min (float, optional) – lower minimum selected sound speeds for the f-k highpass filtering (m/s), by default 1400 m/s

• cp_min (float, optional) – higher minimum selected sound speed for the f-k highpass filtering, by default 1450 m/s

• fmin (float, optional) – minimum frequency for the passband, by default 15

• fmax (float, optional) – maximum frequency for the passband, by default 25

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.hybrid_gs_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400.0, cp_min=1450.0, fmin=15.0, fmax=25.0, display_filter=False)

Designs a bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• cs_min (float, optional) – lower minimum selected sound speeds for the f-k highpass filtering (m/s), by default 1400 m/s

• cp_min (float, optional) – higher minimum selected sound speed for the f-k highpass filtering, by default 1450 m/s

• fmin (float, optional) – minimum frequency for the passband, by default 15

• fmax (float, optional) – maximum frequency for the passband, by default 25

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.hybrid_ninf_filter_design(trace_shape, selected_channels, dx, fs, cs_min=1400.0, cp_min=1450.0, cp_max=3400, cs_max=3500, fmin=15.0, fmax=25.0, display_filter=False)

Designs a bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• cs_min (float, optional) – lower minimum selected sound speeds for the f-k highpass filtering (m/s), by default 1400 m/s

• cp_min (float, optional) – higher minimum selected sound speed for the f-k highpass filtering, by default 1450 m/s

• fmin (float, optional) – minimum frequency for the passband, by default 15

• fmax (float, optional) – maximum frequency for the passband, by default 25

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.hybrid_ninf_gs_filter_design(trace_shape, selected_channels, dx, fs, fk_params, display_filter=False)

Designs a bandpass f-k hybrid filter for DAS strain data

Keeps by default data with propagation speed above 1450 m/s between [15 - 25] Hz (designed for fin whales)

Parameters:

• trace_shape (tuple) – tuple with the dimensions of the strain data in the spatio-temporal domain such as trace_shape = (trace.shape[0], trace.shape[1]) where dimensions are [channel x time sample]

• selected_channels (list) – list of the selected channels number [start, end, step]

• dx (float) – channel spacing (m)

• fs (float) – sampling frequency (Hz)

• fk_params (dict) – dictionary containing the parameters for the f-k filter design

• display_filter (bool, optional) – option for filter display, by default False

Returns:

fk_filter_matrix – [channel x time sample] a scipy sparse array containing the f-k-filter

Return type:

array-like

das4whales.dsp.instant_freq(channel, fs)

Compute the instantaneous frequency

Parameters:

• channel (np.ndarray) – 1D time series channel trace

• fs (float) – sampling frequency

Returns:

instantaneous frequency along time[1:]

Return type:

np.ndarray

das4whales.dsp.moving_average(signal, window_size)

das4whales.dsp.moving_average_matrix(matrix, window_size)

das4whales.dsp.normalize_median(trace)

Normalize the input trace by its median.

Parameters:

trace (np.ndarray) – A 2D array of shape (channel, time sample) containing the strain data in the spatio-temporal domain.

Returns:

A 2D array of shape (channel, time sample) containing the normalized strain data.

Return type:

np.ndarray

das4whales.dsp.normalize_std(trace)

Normalize the input trace by its standard deviation.

Parameters:

trace (np.ndarray) – A 2D array of shape (channel, time sample) containing the strain data in the spatio-temporal domain.

Returns:

A 2D array of shape (channel, time sample) containing the normalized strain data.

Return type:

np.ndarray

das4whales.dsp.resample(tr, fs, desired_fs)

Resample a multi-channel signal to a desired sampling frequency.

Parameters:

• tr (ndarray) – Input signal with shape (n_channels, n_samples), where n_channels is the number of channels and n_samples is the number of time samples.

• fs (int) – Original sampling frequency of the input signal (in Hz).

• desired_fs (int) – Desired sampling frequency after resampling (in Hz).

Returns:

A tuple containing: - tr_downsampled (ndarray): Downsampled signal with shape (n_channels, n_samples_downsampled). - fs_downsampled (int): Sampling frequency after downsampling (equals desired_fs). - tx_downsampled (ndarray): New time vector corresponding to the downsampled signal,

with shape (n_samples_downsampled,).

Return type:

Tuple[ndarray, int, ndarray]

das4whales.dsp.snr_tr_array(trace)

Calculate the 2D Signal-to-Noise Ratio (SNR) array for a given input trace.

This function computes the SNR for each element in the input 2D trace array. The SNR is calculated as the ratio of the square of the trace values to the square of the standard deviation of the trace along the second axis (time).

Parameters:

trace (numpy.ndarray) – The input 2D trace array for which the SNR is to be calculated.

Returns:

A 2D array containing the Signal-to-Noise Ratio (SNR) values for each element in the input trace.

Return type:

numpy.ndarray

das4whales.dsp.taper_data(trace)

Apply a Tukey window to each line (time series) of the input matrix.

Parameters:

trace (np.ndarray) – 2D numpy array, where each column represents a time series.

Returns:

Tapered matrix with the same shape as the input.

Return type:

np.ndarray

das4whales.dsp.taper_data2d(data, taper_type='tukey')

Applies tapering (windowing) to the data in both space (channels) and time (samples) domains.

Parameters:

• data (ndarray) – 2D numpy array representing the spatio-temporal data with dimensions [channels x samples].

• taper_type (str, optional) – Type of tapering window to apply. Options are ‘hanning’, ‘hamming’, or ‘tukey’. Default is ‘tukey’.

Returns:

tapered_data – The tapered data array with the same shape as input data.

Return type:

ndarray