tensorpac.Pac

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

Compute Phase-Amplitude Coupling (PAC).

Computing PAC is assessed in three steps : compute the real PAC, compute surrogates and finally, because PAC is very sensible to the noise, correct the real PAC by the surrogates. This implementation is modular i.e. it lets you choose among a large range of possible combinations.

Parameters

idpactuple/list | (1, 1, 3)

Choose the combination of methods to use in order to extract PAC. This tuple must be composed of three integers where each one them refer

• First digit : refer to the pac method

  • 1 : Mean Vector Length (MVL) [4] (see tensorpac.methods.mean_vector_length())

  • 2 : Modulation Index (MI) [11] (see tensorpac.methods.modulation_index())

  • 3 : Heights Ratio (HR) [9] (see tensorpac.methods.heights_ratio())

  • 4 : ndPAC [13] (see tensorpac.methods.norm_direct_pac())

  • 5 : Phase-Locking Value (PLV) [10][8] (see tensorpac.methods.phase_locking_value())

  • 6 : Gaussian Copula PAC (GCPAC) [6] (see tensorpac.methods.gauss_cop_pac())

• Second digit : refer to the method for computing surrogates

  • 0 : No surrogates

  • 1 : Swap phase / amplitude across trials [11] (see tensorpac.methods.swap_pha_amp())

  • 2 : Swap amplitude time blocks [2] (see tensorpac.methods.swap_blocks())

  • 3 : Time lag [4] (see tensorpac.methods.time_lag())

• Third digit : refer to the normalization method for correction

  • 0 : No normalization

  • 1 : Substract the mean of surrogates

  • 2 : Divide by the mean of surrogates

  • 3 : Substract then divide by the mean of surrogates

  • 4 : Z-score

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]])

• Using a string. f_pha and f_amp can be ‘lres’, ‘mres’, ‘hres’ respectively for low, middle and high resolution vectors. In that case, it uses the definition proposed by Bahramisharif et al. 2013 [2] i.e f_pha = [f - f / 4, f + f / 4] and f_amp = [f - f / 8, f + f / 8]

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 [2].

widthint | 7

Width of the Morlet’s wavelet.

n_binsint | 18

Number of bins for the KLD and HR PAC method [11][9]

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

Check and initialize.

Methods

__init__([idpac, f_pha, f_amp, dcomplex, …])	Check and initialize.
comodulogram(pac[, xlabel, ylabel, cblabel])	Plot PAC using comodulogram.
filter(sf, x[, ftype, keepfilt, edges, n_jobs])	Filt the data in the specified frequency bands.
filterfit(sf, x_pha[, x_amp, n_perm, p, …])	Filt the data then compute PAC on it.
fit(pha, amp[, n_perm, p, mcp, n_jobs, …])	Compute PAC on filtered data.
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.
triplot(pac, fvec, tridx[, xlabel, ylabel, …])	Triangular plot.

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).
idpac	Get the idpac value.
pac	Array of un-normalized PAC of shape (n_amp, n_pha, n_epochs).
pvalues	Array of p-values of shape (n_amp, n_pha).
surrogates	Array of surrogates of shape (n_perm, n_amp, n_pha, n_epochs).
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.

comodulogram(pac, xlabel='Frequency for phase (hz)', ylabel='Frequency for amplitude (hz)', cblabel='PAC values', **kwargs)

Plot PAC using comodulogram.

Parameters

pacarray_like

PAC array of shape (namp, pha)

xlabelstring | ‘Frequency for phase (hz)’

Label for the phase axis.

ylabelstring | ‘Frequency for amplitude (hz)’

Label for the amplitude axis.

cblabelstring | ‘PAC values’

Colorbar.

kwargsdict

Further arguments are passed to the pacplot() method.

Returns

gcaaxes

The current matplotlib axes.

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, n_perm=200, p=0.05, mcp='maxstat', edges=None, n_jobs=-1, random_state=None, verbose=None)

Filt the data then compute PAC on it.

Parameters

sffloat

The sampling frequency.

x_pha, x_amparray_like

Array of data for computing PAC. x_pha is the data used for extracting phases and x_amp, amplitudes. Both arrays must have the same shapes. If you want to compute PAC locally 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_permint | 200

Number of surrogates to compute.

pfloat | 0.05

Statistical threshold

mcp{‘fdr’, ‘bonferroni’}

Correct the p-values for multiple comparisons. Use either :

• ‘maxstat’ : maximum statistics

• ‘fdr’ : FDR correction (need MNE-Python)

• ‘bonferroni’ : Bonferroni correction (need MNE-Python)

edgesint | None

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

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.

random_stateint | None

Fix the random state of the machine for reproducible results.

Returns

pacarray_like

Phase-Amplitude Coupling measure of shape (namp, npha, …).

Attributes

pacarray_like

Unormalized Phase-Amplitude Coupling measure of shape (n_amp, n_pha, n_epochs)

pvaluesarray_like

Array of p-values of shape (n_amp, n_pha)

surrogatesarray_like

Array of surrogates of shape (n_perm, n_amp, n_pha, n_epochs)

fit(pha, amp, n_perm=200, p=0.05, mcp='maxstat', n_jobs=-1, random_state=None, verbose=None)

Compute PAC on filtered data.

Parameters

phaarray_like

Array of phases of shape (n_pha, n_epochs, n_times). Angles should be in rad.

amparray_like

Array of amplitudes of shape (n_amp, n_epochs, n_times).

n_permint | 200

Number of surrogates to compute.

pfloat | 0.05

Statistical threshold

mcp{‘fdr’, ‘bonferroni’}

Correct the p-values for multiple comparisons. Use either :

• ‘maxstat’ : maximum statistics

• ‘fdr’ : FDR correction (need MNE-Python)

• ‘bonferroni’ : Bonferroni correction (need MNE-Python)

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.

random_stateint | None

Fix the random state of the machine for reproducible results.

Returns

pacarray_like

Phase-Amplitude Coupling measure of shape (n_amp, n_pha, n_epochs)

Attributes

pacarray_like

Unormalized Phase-Amplitude Coupling measure of shape (n_amp, n_pha, n_epochs)

pvaluesarray_like

Array of p-values of shape (n_amp, n_pha)

surrogatesarray_like

Array of surrogates of shape (n_perm, n_amp, n_pha, n_epochs)

infer_pvalues(p=0.05, mcp='maxstat')

Infer p-values based on surrogate distribution.

Parameters

pfloat | 0.05

Significiency threshold

Returns

pvaluesarray_like

Array of p-values of shape (n_amp, n_pha)

mcp{‘fdr’, ‘bonferroni’}

Correct the p-values for multiple comparisons. Use either :

• ‘maxstat’ : maximum statistics

• ‘fdr’ : FDR correction (need MNE-Python)

• ‘bonferroni’ : Bonferroni correction (need MNE-Python)

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.

triplot(pac, fvec, tridx, xlabel='Starting frequency (hz)', ylabel='Ending frequency (hz)', cblabel='PAC values', bad='lightgray', **kwargs)

Triangular plot.

The triplot method is used to find the [starting, ending] frequency either for the phase or for the amplitude.

Parameters

pacarray_like

Pac array of shape (namp, npha)

fvecarray_like

The frequency vector returned by the pac_trivec function.

tridxarray_like

The index vector used to build the triangle. This argument is also returned by the pac_trivec function.

xlabelstring | ‘Starting frequency (hz)’

Label for the phase axis.

ylabelstring | ‘Ending frequency (hz)’

Label for the amplitude axis.

cblabelstring | ‘PAC values’

Colorbar.

badstring | ‘lightgray’

Color for non-significant values.

kwargsdict

Further arguments are passed to the pacplot() method.

Returns

gcaaxes

The current matplotlib axes.

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 idpac

Get the idpac value.

property pac

Array of un-normalized PAC of shape (n_amp, n_pha, n_epochs).

property pvalues

Array of p-values of shape (n_amp, n_pha).

property surrogates

Array of surrogates of shape (n_perm, n_amp, n_pha, n_epochs).

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.