tensorpac.EventRelatedPac¶

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

Compute the Event Related Phase-Amplitude Coupling (ERPAC).

The traditional PAC approach is computed across time, hence this means that you can’t observe PAC changes across time. In contrast, the ERPAC is computed across epochs (or trials) which preserves the time dimension.

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)[source]¶: 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, method, …])	Extract phases, amplitudes and compute ERPAC.
`fit`(pha, amp[, method, smooth, n_jobs, …])	Compute the Event-Related Phase-Amplitude Coupling (ERPAC).
`infer_pvalues`([p, mcp])	Infer p-values based on surrogate distribution.
`pacplot`(pac, xvec, yvec[, xlabel, ylabel, …])	Main plotting pac function.
`savefig`(filename[, dpi])	Save the figure.
`show`()	Display the figure.

Attributes

`cycle`	Get the cycle value.
`dcomplex`	Get the dcomplex value.
`erpac`	Array of event-related PAC of shape ().
`f_amp`	Vector of amplitudes of shape (n_amp, 2).
`f_pha`	Vector of phases of shape (n_pha, 2).
`pvalues`	Array of p-values of shape (n_amp, n_pha, n_times).
`surrogates`	Array of surrogates of shape (n_perm, n_amp, n_pha, n_times).
`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, method='circular', smooth=None, n_perm=None, p=0.05, mcp='fdr', edges=None, n_jobs=-1, verbose=None)[source]¶

Extract phases, amplitudes and compute ERPAC.

Parameters

sffloat: The sampling frequency.
x_pha, x_amparray_like: Array of data for computing ERPAC. 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 ERPAC 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.
method{‘circular’, ‘gc’}: Name of the method for computing erpac. Use ‘circular’ for reproducing [12] or ‘gc’ for a Gaussian-Copula based erpac.
smoothint | None: Half number of time-points to use to produce a smoothing. Only active with the Gaussian-Copula (‘gc’) method [6].
n_permint | None: Number of permutations to compute for assessing p-values for the gaussian-copula (‘gc’) method. Statistics are performed by randomly swapping phase trials
pfloat | 0.05: Statistical threshold for the gaussian-copula (‘gc’) method
mcp{‘fdr’, ‘bonferroni’}: Correct the p-values for multiple comparisons. This is needed when using the circular ERPAC ([12]). Note that the correction is performed using MNE-Python.
edgesint | None: Number of samples to discard to avoid edge effects due to filtering

Returns

erpacarray_like: The ERPAC estimation of shape (n_amp, n_pha, n_times)

fit(pha, amp, method='circular', smooth=None, n_jobs=-1, n_perm=None, p=0.05, mcp='fdr', verbose=None)[source]¶

Compute the Event-Related Phase-Amplitude Coupling (ERPAC).

The ERPAC [12] is used to measure PAC across trials and is interesting for real-time estimation.

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).
method{‘circular’, ‘gc’}: Name of the method for computing erpac. Use ‘circular’ for reproducing [12] or ‘gc’ for a Gaussian-Copula based erpac [6].
smoothint | None: Half number of time-points to use to produce a smoothing. Only active with the Gaussian-Copula (‘gc’) method.
n_permint | None: Number of permutations to compute for assessing p-values for the gaussian-copula (‘gc’) method. Statistics are performed by randomly swapping phase trials
pfloat | 0.05: Statistical threshold for the gaussian-copula (‘gc’) method
mcp{‘fdr’, ‘bonferroni’}: Correct the p-values for multiple comparisons. This is needed when using the circular ERPAC ([12]). Note that the correction is performed using MNE-Python.

Returns

erpacarray_like: The ERPAC estimation of shape (n_amp, n_pha, n_times)

infer_pvalues(p=0.05, mcp='fdr')[source]¶

Infer p-values based on surrogate distribution.

Parameters

pfloat | 0.05: Statistical threshold
mcp{‘fdr’, ‘bonferroni’}: Correct the p-values for multiple comparisons. This is needed when using the circular ERPAC ([12]). Note that the correction is performed using MNE-Python.

Returns

pvaluesarray_like: Array of p-values of shape (n_amp, n_pha, n_times)

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.

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 erpac¶: Array of event-related PAC of shape ().

property f_amp¶: Vector of amplitudes of shape (n_amp, 2).

property f_pha¶: Vector of phases of shape (n_pha, 2).

property pvalues¶: Array of p-values of shape (n_amp, n_pha, n_times).

property surrogates¶: Array of surrogates of shape (n_perm, n_amp, n_pha, n_times).

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.