phase_utils module¶

phase_utils.bp_filter_1d(x, fs, ftype, wn, order=4, do_plot=1, ax_list=[])¶

Band Pass Filtering for 1D input data

Parameters:	x : list | numpy array input array to filter fs : int Sampling Frequency (Hz) ftype : str Filter type - ‘butter’, ‘elliptic’ or ‘fir’ wn : list | numpy array Normalized cut off frequency order : int Filter order do_plot : int | bool If 1, plot the frequency response ax_list : list | numpy array List of axis for plotting
Returns:	y : numpy array Output filtered (b, a) : tuple Filter coefficients

phase_utils.compute_analytical_signal(x_filtered, fs, return_errors=[])¶

Compute the analytical signal of the band-pass filter x_filtered and return the analytical amplitude, phase (wrap and unwrap) and frequency.

Parameters:

x_filtered : numpy array Filtered signal (should be narrow-band) - Real signal from which the analytical signal is calculated fs : int Sampling frequency (Hz) return_errors : int | bool | None If 1, return the error measures

Returns:

ie : numpy array Instantaneous Enveloppe ip : numpy array Instantaneous Phase \(\phi(t)\) ifreq : numpy array Instantaneous Frequency ip_wrap : numpy array Instantaneous Phase wrapped between [-pi, pi] var_ratio : numpy array Ratio of the variation of the phase with the variation of the enveloppe - returned if return_errors=True error_sig : numpy array Error signal defined as \(H[cos(\phi(t))] - sin(\phi(t))\) - returned if return_errors=True

phase_utils.compute_robust_estimation(x_raw, fs, fmin, fmax, f_tolerance, noise_tolerance, n_monte_carlo=20, do_plot=0, superpose=1, ftype='elliptic', forder=4, do_fplot=0, return_errors=0)¶

Compute the robust estimation of the phase using the method described in [1].

Parameters:

x_raw : array Input raw signal fs : int Sampling Frequency (Hz) fmin : int Low cut-off frequency (Hz) fmax : int High cut-off frequency (Hz) f_tolerance : float Tolerance of the cut-off frequencies. A random number in the interval [-f_tolerance/2, +f_tolerance/2] will be added to the cut-off frequencies noise_tolerance : float Random noise from a uniform distribution in [-noise_tolerance/2, +noise_tolerance/2] will be added to the signal x_raw n_monte_carlo : int Number of monte carlo repetition do_plot : int | bool If True, plot the results superpose : int | bool If True, superpose all the phase estimates ftype : str Filter type: ‘butter’ : Butterworth filter ‘elliptic’ (default) : Elliptic filter ‘fir’ : Finite Impulse Response filter forder : int Filter order - default : 4 do_fplot : int | bool If 1, plot the frequency response return_errors : int | bool If 1, returns also the errors measures

Returns:

ie : numpy array Instantaneous Enveloppe ip : numpy array Instantaneous Phase \(\phi(t)\) ifreq : numpy array Instantaneous Frequency ip_wrap : numpy array Instantaneous Phase wrapped between [-pi, pi] var_ratio : numpy array Ratio of the variation of the phase with the variation of the enveloppe - returned if return_errors=True error_sig : numpy array Error signal defined as \(H[cos(\phi(t))] - sin(\phi(t))\) - returned if return_errors=True

References

[1]	(1, 2) Esmaeil Seraj and Reza Sameni. Robust electroencephalogram phase estimation with applications in brain-computer interface systems. 9 February 2017.

phase_utils.itpc(x_trials, fs, filt_cf, filt_bw, f_tolerance=[], noise_tolerance=[], n_monte_carlo=20, ftype='elliptic', forder=4, do_plot=0, contour_plot=1, n_contours=10)¶

Compute and plot the Inter-Trial Phase Clustering

Parameters:

x_trials : numpy array - shape (n_pnts, n_trials) 2D numpy array containing the trials for one channel fs : int Sampling frequency (Hz) filt_cf : numpy array Filters center frequencies filt_bw : numpy array | int Filters bandwidth f_tolerance : float | array | None (default: none) Tolerance of the cut-off frequencies. A random number in the interval [-f_tolerance/2, +f_tolerance/2] will be added to the cut-off frequencies. If none, f_tolerance is set to filt_bw / 100 for each filter. noise_tolerance : float | None (default: none) Random noise from a uniform distribution in [-noise_tolerance/2, +noise_tolerance/2] will be added to the signal x_raw. If none, noise_tolerance is set to np.std(x_trials) / 30. n_monte_carlo : int Number of monte carlo repetition ftype : str Filter type: ‘butter’ : Butterworth filter ‘elliptic’ (default) : Elliptic filter ‘fir’ : Finite Impulse Response filter forder : int Filter order - default : 4 do_plot : int | bool If 1, plot the ITPC (default: 0) contour_plot : int | bool If 1 , plot the contours (contourf function) else use the pcolormesh function (default: 1) n_contours : int If contour_plot=1, number of levels in contourf function

Returns:

itpc_mat : array [n_freqs*n_pnts] ITPC result matrix ip_var_mean : array [n_freqs*n_pnts] Mean of the variance of the instantaneous phase across the Monte Carlo repetitions ie_mat_mean : array [n_freqs*n_pnts] Mean of the instantaneous enveloppe across the Monte Carlo repetitions

phase_utils.plot_analytical_signal(x, fs)¶

Compute the analytical signal from the signal x and plot the instantaneous enveloppe, phase and frequency

Parameters:	x : array input signal (should be narrow-band) fs : int sampling frequency (Hz)

phase_utils.plot_complex_trajectory(x, ax=[])¶

Plot the complex trajectory of real input signal x. This may help visualize the narrow-band behaviour of the signal.

Parameters:	x : array input real signal ax : list | none axis list