kwave.utils.filters module

apply_filter(signal, Fs, cutoff_f, filter_type, zero_phase=False, transition_width=0.1, stop_band_atten=60)

Filters an input signal using a FIR filter with Kaiser window coefficients based on the specified cut-off frequency and filter type. Both causal and zero phase filters can be applied.

Parameters:

• signal (ndarray) – The input signal.

• Fs (float) – The sampling frequency of the signal.

• cutoff_f (float) – The cut-off frequency of the filter.

• filter_type (str) – The type of filter to apply, either ‘HighPass’, ‘LowPass’ or ‘BandPass’.

• zero_phase (bool | None) – Whether to apply a zero-phase filter. Defaults to False.

• transition_width (float | None) – The transition width of the filter, as a proportion of the sampling frequency. Defaults to 0.1.

• stop_band_atten (int | None) – The stop-band attenuation of the filter in dB. Defaults to 60.

Returns:

The filtered signal.

Return type:

ndarray

brenner_sharpness(im)

extract_amp_phase(data, Fs, source_freq, dim='auto', fft_padding=3, window='Hanning')

Extract the amplitude and phase information at a specified frequency from a vector or matrix of time series data.

The amplitude and phase are extracted from the frequency spectrum, which is calculated using a windowed and zero padded FFT. The values are extracted at the frequency closest to source_freq. By default, the time dimension is set to the highest non-singleton dimension.

Parameters:

• data (ndarray) – Matrix of time signals [s]

• Fs (float) – Sampling frequency [Hz]

• source_freq (float) – Frequency at which the amplitude and phase should be extracted [Hz]

• dim (Tuple[str, int]) – The time dimension of the input data. If ‘auto’, the highest non-singleton dimension is used.

• fft_padding (int) – The amount of zero padding to apply to the FFT.

• window (str) – The windowing function to use for the FFT.

Returns:

A tuple of the amplitude, phase and frequency of the extracted signal.

Return type:

Tuple[ndarray, ndarray, ndarray]

filter_time_series(kgrid, medium, signal, ppw=3, rppw=0, stop_band_atten=60, transition_width=0.1, zerophase=False, plot_spectrums=False, plot_signals=False)

Filters a time-domain signal using the Kaiser windowing method.

The filter is designed to attenuate high-frequency noise in the signal while preserving the signal’s important features. The filter design parameters can be adjusted to trade off between the amount of noise reduction and the amount of signal distortion.

Parameters:

• kgrid (kWaveGrid) – The kWaveGrid grid.

• medium (kWaveMedium) – The kWavemedium.

• signal (ndarray) – The time-domain signal to filter.

• ppw (int | None) – The minimum number of points per wavelength in the signal. This determines the minimum frequency that will be passed through the filter. Higher values of ppw result in a lower cut-off frequency and more noise reduction, but may also result in more signal distortion. Defaults to 3.

• rppw (int | None) – The number of points per wavelength in the smoothing ramp applied to the beginning of the signal. This can be used to reduce ringing artifacts caused by the sudden transition from the filtered signal to the unfiltered signal. Defaults to 0.

• stop_band_atten (int | None) – The stop-band attenuation in dB. This determines the steepness of the filter’s transition from the pass-band to the stop-band. Higher values result in a steeper transition and more noise reduction, but may also result in more signal distortion. Defaults to 60.

• transition_width (float | None) – The transition width as a proportion of the sampling frequency. This determines the width of the transition region between the pass-band and the stop-band. Smaller values result in a narrower transition and more noise reduction, but may also result in more signal distortion. Defaults to 0.1.

• zerophase (bool | None) – Whether to implement the filter as a zero-phase filter. Zero-phase filtering can be used to preserve the phase information in the signal, which can be important for some applications. However, it may also result in more signal distortion. Defaults to False.

• plot_spectrums (bool | None) – Whether to plot the spectrums of the input and filtered signals. Defaults to False.

• plot_signals (bool | None) – Whether to plot the input and filtered signals. Defaults to False.

Raises:

• ValueError – Checks correctness of passed arguments.

• NotImplementedError – Cannot currently plot anything.

Returns:

The filtered signal.

Return type:

ndarray

fwhm(f, x)

fwhm calculates the Full Width at Half Maximum (FWHM) of a positive 1D input function f(x) with spacing given by x.

Parameters:

• f – f(x)

• x – x

Returns:

FWHM of f(x) along with the position of the leading and trailing edges as a tuple

gaussian_filter(signal, Fs, frequency, bandwidth)

Applies a frequency domain Gaussian filter with the specified center frequency and percentage bandwidth to the input signal. If the input signal is given as a matrix, the filter is applied to each matrix row.

Parameters:

• signal (ndarray | List[float]) – Signal to filter [channel, samples]

• Fs (float) – Sampling frequency [Hz]

• frequency (float) – Center frequency of filter [Hz]

• bandwidth (float) – Bandwidth of filter in percentage

Returns:

The filtered signal

Return type:

ndarray | List[float]

sharpness(im, mode='Brenner')

Returns a scalar metric related to the sharpness of a 2D or 3D image matrix.

Parameters:

• im (ndarray) – The image matrix.

• metric – The metric to use. Defaults to “Brenner”.

• mode (str | None)

Returns:

A scalar sharpness metric.

Raises:

AssertionError – If im is not a NumPy array.

Return type:

float

References

B. E. Treeby, T. K. Varslot, E. Z. Zhang, J. G. Laufer, and P. C. Beard, “Automatic sound speed selection in photoacoustic image reconstruction using an autofocus approach,” J. Biomed. Opt., vol. 16, no. 9, p. 090501, 2011.

single_sided_correction(func_fft, fft_len, dim)

Correct the single-sided magnitude by multiplying the symmetric points by 2.

The DC and Nyquist components are unique and are not multiplied by 2. The Nyquist component only exists for even numbered FFT lengths.

Parameters:

• func_fft (ndarray) – The FFT of the function to be corrected.

• fft_len (int) – The length of the FFT.

• dim (int) – The number of dimensions of func_fft.

Returns:

The corrected FFT of the function.

Return type:

ndarray

smooth(a, restore_max=False, window_type='Blackman')

Smooths a matrix.

Parameters:

• a (ndarray) – The spatial distribution to smooth.

• restore_max (bool | None) – Boolean controlling whether the maximum value is restored after smoothing. Defaults to False.

• window_type (str | None) – Shape of the smoothing window. Any valid inputs to get_win are supported. Defaults to ‘Blackman’.

Returns:

The smoothed matrix.

Return type:

a_sm

spect(func, Fs, dim='auto', fft_len=0, power_two=False, unwrap_phase=False, window='Rectangular')

Calculates the spectrum of a signal.

Parameters:

• func (ndarray) – The signal to analyse.

• Fs (float) – The sampling frequency in Hz.

• dim (int | str | None) – The dimension over which the spectrum is calculated. Defaults to ‘auto’.

• fft_len (int | None) – The length of the FFT. If the set length is smaller than the signal length, the default value is used instead (default = signal length).

• power_two (bool | None) – Whether the FFT length is forced to be the next highest power of 2 (default = False).

• unwrap_phase (bool | None) – Whether to unwrap the phase spectrum (default = False).

• window (str | None) – (str) The window type used to filter the signal before the FFT is taken (default = ‘Rectangular’). Any valid input types for get_win may be used.

Returns:

Frequency array func_as: Single-sided amplitude spectrum func_ps: Single-sided phase spectrum

Return type:

f

Raises:

ValueError – If the input signal is scalar or has more than 4 dimensions.

tenenbaum_sharpness(im)