Bandpass-filter spectral analysis (spynal.spectra.bandfilter)

Band-pass filtering & Hilbert transform-based spectral analysis

bandfilter_spectrum(data, smp_rate, axis=0, data_type='lfp', spec_type='complex', freqs=((2, 8), (10, 32), (40, 100)), removeDC=True, filt='butter', order=4, params=None, buffer=0, **kwargs)

Computes band-filtered and Hilbert-transformed signal from data for given frequency band(s), then reduces it to 1D frequency spectra by averaging across time.

Not really the best way to compute 1D frequency spectra, but included for completeness.

Only parameters differing from spectrum() are described here.

NOTE: Can specify filter implictly using (freqs,`filt`,`order`) OR explicitly using params.

If params is input, freqs, filt, and order are ignored.

Parameters:

  • freqs (array-like, shape=(n_freqbands,2), default: ((2,8),(10,32),(40,100))) – List of (low,high) cut frequencies for each band to use. Set low cut = 0 for low-pass, set high cut >= smp_rate/2 for high-pass, otherwise assumes band-pass. Default samples ~ theta, alpha/beta, gamma.

  • filt (str, default: 'butter' (Butterworth)) – Name of filter to use. See set_filter_params() for all options

  • order (int, default: 4) – Filter order

  • params (dict) –

    Parameters that explicitly define filter for each freq band.

    Alternative method for explicitly setting parameters defining freq band filters, which are precomputed with set_filter_params() (or elsewhere). Input either freqs/filt/order OR params. If params are not explicitly input, we compute them from freqs/filt/order. If params are explicitly input, freqs/filt/order are ignored.

    One of two forms: ‘ba’ or ‘zpk’, with key/values as follows:

    • b,aarray-like, shape=(n_freqbands,) of array-like (n_params[band,])

      Numerator b and denominator a polynomials of the filter for each band

    • z,p,k :

      Zeros, poles, and system gain of the IIR filter transfer function

  • buffer (float, default: 0 (no buffer)) – Time (s) to trim off each end of time dimension of data. Removes symmetric buffer previously added (outside of here) to prevent edge effects.

  • **kwargs – Any other kwargs passed directly to set_filter_params()

Returns:

  • spec (ndarray, shape=(…,n_freqbands,…), dtype=complex or floats) – Band-filtered, (optionally) Hilbert-transformed data, transformed to requested spectral type, and averaged across the time axis to 1D frequency spectra. Same shape as input data, but with frequency axis replacing time axis. dtype is complex if spec_type is ‘complex’, float otherwise.

  • freqs (ndarray, shape=(n_freqbands,2)) – List of (low,high) cut frequencies (Hz) for each band used

bandfilter_spectrogram(data, smp_rate, axis=0, data_type='lfp', spec_type='complex', freqs=((2, 8), (10, 32), (40, 100)), removeDC=True, filt='butter', order=4, params=None, buffer=0, downsmp=1, **kwargs)

Computes zero-phase band-filtered and Hilbert-transformed signal from data for given frequency band(s).

Function aliased as bandfilter().

Only parameters differing from spectrogram() are described here.

NOTE: Can specify filter implictly using (freqs,`filt`,`order`) OR explicitly using params.

If params is input, freqs, filt, and order are ignored.

Parameters:

  • freqs (array-like, shape=(n_freqbands,2), default: ((2,8),(10,32),(40,100))) – List of (low,high) cut frequencies for each band to use. Set low cut = 0 for low-pass, set high cut >= smp_rate/2 for high-pass, otherwise assumes band-pass. Default samples ~ theta, alpha/beta, gamma.

  • filt (str, default: 'butter' (Butterworth)) – Name of filter to use. See set_filter_params() for all options

  • order (int, default: 4) – Filter order

  • params (dict, default: (computed from freqs/filt/order)) –

    Parameters that explicitly define filter for each freq band.

    Alternative method for explicitly setting parameters defining freq band filters, which are precomputed with set_filter_params() (or elsewhere). Input either freqs/filt/order OR params. If params are not explicitly input, we compute them from freqs/filt/order. If params are explicitly input, freqs/filt/order are ignored.

    One of two forms: ‘ba’ or ‘zpk’, with key/values as follows:

    • b,aarray-like, shape=(n_freqbands,) of array-like (n_params[band,])

      Numerator b and denominator a polynomials of the filter for each band

    • z,p,k :

      Zeros, poles, and system gain of the IIR filter transfer function

  • buffer (float, default: 0 (no buffer)) – Time (s) to trim off each end of time dimension of data. Removes symmetric buffer previously added (outside of here) to prevent edge effects.

  • **kwargs – Any other kwargs passed directly to set_filter_params()

Returns:

  • spec (ndarray, shape=(…,n_freqbands,n_timepts_out,…), dtype=complex or float.) – Band-filtered, (optionally) Hilbert-transformed “spectrogram” of data, transformed to requested spectral type. Same shape as input data, but with frequency axis prepended immediately before time axis. dtype is complex if spec_type is ‘complex’, float otherwise.

  • freqs (ndarray, shape=(n_freqbands,2)) – List of (low,high) cut frequencies (Hz) for each band used in spec.

  • timepts (ndarray, shape=(n_timepts_out,)) – List of timepoints in spec (in s, referenced to start of data).

bandfilter(data, smp_rate, axis=0, data_type='lfp', spec_type='complex', freqs=((2, 8), (10, 32), (40, 100)), removeDC=True, filt='butter', order=4, params=None, buffer=0, downsmp=1, **kwargs)

Alias of bandfilter_spectrogram(). See there for details.

set_filter_params(bands, smp_rate, filt='butter', order=4, form='ba', return_dict=False, **kwargs)

Sets coefficients for desired filter(s) using scipy.signal “Matlab-style IIR filter design” functions

NOTE: If return_dict is False, outputs are returned as a tuple, as described below; else, outputs are packaged in a single dict, with param names as keys.

Parameters:

  • bands (array-like, shape=(n_freqbands,2)) – List of (low,high) cut frequencies for each band to use. Set low cut = 0 for low-pass, set high cut >= smp_rate/2 for high-pass, otherwise assumes band-pass

  • smp_rate (scalar) – Data sampling rate (Hz)

  • filt (str, default: 'butter' (Butterworth)) – Name of filter to use. See set_filter_params() for all options

  • order (int, default: 4) – Filter order

  • form ({'ba','zpk'}, default: ‘ba’) – Type of parameters to output: - ‘ba’: numerator(b), denominator (a) - ‘zpk’: Zeros (z), poles (p), and system gain (k) of the IIR filter transfer function

  • return_dict (bool, default: False) – If True, params returned in a dict; else as standard series (tuple) of output variables

  • **kwargs – Any additional kwargs passed directly to filter function

Returns:

  • b,a (list, shape=(n_freqbands,) of list, shape=(n_params[band,])) – Numerator b and denominator a polynomials of the filter for each band. Returned if form == ‘ba’.

  • z,p,k (list, shape=(n_freqbands,) of list, shape=(n_params[band,])) – Zeros, poles, and system gain of IIR transfer function. Returned if form == ‘zpk’.

Examples

params = set_filter_params(bands, smp_rate, form=’ba’, return_dict=True)

b,a = set_filter_params(bands, smp_rate, form=’ba’, return_dict=False)

z,p,k = set_filter_params(bands, smp_rate, form=’zpk’, return_dict=False)