tensorpac.PreferredPhase

class tensorpac.PreferredPhase(f_pha=[2, 4], f_amp=[60, 200], dcomplex='hilbert', cycle=(3, 6), width=7, verbose=None)

Compute the Preferred Phase (PP).

The preferred phase is defined as the phase at which the amplitude is maximum.

Parameters

f_pha, f_amplist/tuple/array | def: [2, 4] and [60, 200]

Frequency vector for the phase and amplitude. Here you can use several forms to define those vectors :

• Basic list/tuple (ex: [2, 4] or [8, 12]…)

• List of frequency bands (ex: [[2, 4], [5, 7]]…)

• Dynamic definition : (start, stop, width, step)

• Range definition (ex : np.arange(3) => [[0, 1], [1, 2]])

dcomplex{‘wavelet’, ‘hilbert’}

Method for the complex definition. Use either ‘hilbert’ or ‘wavelet’.

cycletuple | (3, 6)

Control the number of cycles for filtering (only if dcomplex is ‘hilbert’). Should be a tuple of integers where the first one refers to the number of cycles for the phase and the second for the amplitude.

widthint | 7

Width of the Morlet’s wavelet.

__init__(f_pha=[2, 4], f_amp=[60, 200], dcomplex='hilbert', cycle=(3, 6), width=7, verbose=None)

Check and initialize.

Methods

__init__([f_pha, f_amp, dcomplex, cycle, …])	Check and initialize.
filter(sf, x[, ftype, keepfilt, edges, n_jobs])	Filt the data in the specified frequency bands.
filterfit(sf, x_pha[, x_amp, edges, n_bins, …])	Extract phases, amplitudes and compute the preferred phase (PP).
fit(pha, amp[, n_bins])	Compute the preferred-phase.
pacplot(pac, xvec, yvec[, xlabel, ylabel, …])	Main plotting pac function.
polar(amp, xvec, yvec[, interp])	Polar representation.
savefig(filename[, dpi])	Save the figure.
show()	Display the figure.

Attributes

cycle	Get the cycle value.
dcomplex	Get the dcomplex value.
f_amp	Vector of amplitudes of shape (n_amp, 2).
f_pha	Vector of phases of shape (n_pha, 2).
width	Get the width value.
xvec	Vector of phases of shape (n_pha,) use for plotting.
yvec	Vector of amplitudes of shape (n_amp,) use for plotting.

filter(sf, x, ftype='phase', keepfilt=False, edges=None, n_jobs=-1)

Filt the data in the specified frequency bands.

Parameters

sffloat

The sampling frequency.

xarray_like

Array of data of shape (n_epochs, n_times)

ftype{‘phase’, ‘amplitude’}

Specify if you want to extract phase (‘phase’) or the amplitude (‘amplitude’).

n_jobsint | -1

Number of jobs to compute PAC in parallel. For very large data, set this parameter to 1 in order to prevent large memory usage.

keepfiltbool | False

Specify if you only want the filtered data (True). This parameter is only available with dcomplex=’hilbert’ and not wavelet.

edgesint | None

Number of samples to discard to avoid edge effects due to filtering

Returns

xfiltarray_like

The filtered data of shape (n_freqs, n_epochs, n_times)

filterfit(sf, x_pha, x_amp=None, edges=None, n_bins=12, verbose=None)

Extract phases, amplitudes and compute the preferred phase (PP).

Parameters

sffloat

The sampling frequency.

x_pha, x_amparray_like

Array of data for computing PP. x_pha is the data used for extracting phases and x_amp, amplitudes. Both arrays must have the same shapes (i.e n_epochs, n_times). If you want to compute local PP i.e. on the same electrode, x=x_pha=x_amp. For distant coupling, x_pha and x_amp could be different but still must to have the same shape.

n_binsint | 72

Number of bins for bining the amplitude according to phase slices.

edgesint | None

Number of samples to discard to avoid edge effects due to filtering

Returns

binned_amparray_like

The binned amplitude according to the phase of shape (n_bins, n_amp, n_pha, n_epochs)

pparray_like

The prefered phase where the amplitude is maximum of shape (namp, npha, n_epochs)

polarvecarray_like

The phase vector for the polar plot of shape (n_bins,)

fit(pha, amp, n_bins=72)

Compute the preferred-phase.

Parameters

pha, amparray_like

Respectively the phase of slower oscillations of shape (n_pha, n_epochs, n_times) and the amplitude of faster oscillations of shape (n_pha, n_epochs, n_times).

n_binsint | 72

Number of bins for bining the amplitude according to phase slices.

Returns

binned_amparray_like

The binned amplitude according to the phase of shape (n_bins, n_amp, n_pha, n_epochs)

pparray_like

The prefered phase where the amplitude is maximum of shape (namp, npha, n_epochs)

polarvecarray_like

The phase vector for the polar plot of shape (n_bins,)

pacplot(pac, xvec, yvec, xlabel='', ylabel='', cblabel='', title='', fz_labels=12, fz_title=13, fz_cblabel=12, cmap='viridis', vmin=None, vmax=None, under=None, over=None, bad=None, pvalues=None, p=0.05, interp=None, rmaxis=False, dpaxis=False, plotas='imshow', ncontours=5, levels=None, levelcmap='Reds', polar=False, colorbar=True, y=1.02, subplot=111)

Main plotting pac function.

This method can be used to plot any 2D array.

Parameters

pacarray_like

A 2D array.

xvecarray_like

The vector to use for the x-axis.

yvecarray_like

The vector to use for the y-axis.

xlabelstring | ‘’

Label for the x-axis.

ylabelstring | ‘’

Label for the y-axis.

cblabelstring | ‘’

Label for the colorbar.

titlestring | ‘’

Title of the plot.

fz_labelsfloat | 12

Font size of the y- and x-labels

fz_titlefloat | 13

Font size of the title

fz_cblabelfloat | 12

Font size of the colorbar label

yfloat | 1.02

Title location.

cmapstring | ‘viridis’

Name of one Matplotlib’s colomap.

vminfloat | None

Threshold under which set the color to the uner parameter.

vmaxfloat | None

Threshold over which set the color in the over parameter.

understring | ‘gray’

Color for values under the vmin parameter.

overstring | ‘red’

Color for values over the vmax parameter.

badstring | None

Color for non-significant values.

pvaluesarray_like | None

P-values to use for masking PAC values. The shape of this parameter must be the same as the shape as pac.

pfloat | .05

If pvalues is pass, use this threshold for masking non-significant PAC.

interptuple | None

Tuple for controlling the 2D interpolation. For example, (.1, .1) will multiply the number of row and columns by 10.

rmaxisbool | False

Remove unecessary axis.

dpaxisbool | False

Despine axis.

plotas{‘imshow’, ‘contour’, ‘pcolor’}

Choose how to display the comodulogram, either using imshow (‘imshow’) or contours (‘contour’). If you choose ‘contour’, use the ncontours parameter for controlling the number of contours.

ncontoursint | 5

Number of contours if plotas is ‘contour’.

levelslist | None

Add significency levels. This parameter must be a sorted list of p-values to use as levels.

levelcmapstring | Reds

Colormap of signifiency levels.

Returns

gca: axes

The current matplotlib axes.

polar(amp, xvec, yvec, interp=None, **kwargs)

Polar representation.

This method is used to visualize amplitude as a function of phase using a polar (circle) representation.

Parameters

amparray_like

2D array.

xvecarray_like

Vector for the x-axis.

yvecarray_like

Vector for the y-axis (phases).

interpfloat | None

Interplation factor.

kwargsdict

Further arguments are passed to the pacplot() method.

Returns

gcaaxes

The current matplotlib axes.

savefig(filename, dpi=600)

Save the figure.

Parameters

filenamestring

The name of the figure to save.

dpiint | 600

DPI of the figure.

show()

Display the figure.

property cycle

Get the cycle value.

property dcomplex

Get the dcomplex value.

property f_amp

Vector of amplitudes of shape (n_amp, 2).

property f_pha

Vector of phases of shape (n_pha, 2).

property width

Get the width value.

property xvec

Vector of phases of shape (n_pha,) use for plotting.

property yvec

Vector of amplitudes of shape (n_amp,) use for plotting.