tensorpac.utils.PeakLockedTF

class tensorpac.utils.PeakLockedTF(x, sf, cue, times=None, f_pha=[5, 7], f_amp='hres', cycle=(3, 6), n_jobs=-1, verbose=None)

Peak-Locked Time-frequency representation.

This class can be used in order to re-align time-frequency representations around a time-point (cue) according to the closest phase peak. This type of visualization can bring out a cyclic behavior of the amplitude at a given phase, potentially indicating the presence of a phase-amplitude coupling. Here’s the detailed pipeline :

• Filter around a single phase frequency bands and across multiple amplitude frequencies

• Use a cue which define the time-point to use for the realignment

• Detect in the filtered phase the closest peak to the cue. This step is repeated to each trial in order to get a list of length (n_epochs) that contains the number of sample (shift) so that if the phase is moved, the peak fall onto the cue. A positive shift indicates that the phase is moved forward while a negative shift is for a backward move

• Apply, to each trial, this shift to the amplitude

• Plot the mean re-aligned amplitudes

Parameters

xarray_like

Array of data of shape (n_epochs, n_times)

sffloat

The sampling frequency

cueint, float

Time-point to use in order to detect the closest phase peak. This parameter works in conjunction with the times input below. Use either :

• An integer and times is None to indicate that you want to realign according to a time-point in sample

• A integer or a float with times the time vector if you want that Tensorpac automatically infer the sample number around which to align

timesarray_like | None

Time vector

f_phatuple, list | [2, 4]

List of two floats describing the frequency bounds for extracting the phase

f_amptuple, list | [60, 80]

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

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

• Using a string : f_amp can be ‘lres’, ‘mres’, ‘hres’ respectively for low, middle and high resolution vectors

cycletuple | (3, 6)

Control the number of cycles for filtering. 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].

__init__(x, sf, cue, times=None, f_pha=[5, 7], f_amp='hres', cycle=(3, 6), n_jobs=-1, verbose=None)

Init.

Methods

__init__(x, sf, cue[, times, f_pha, f_amp, …])	Init.
filter(sf, x[, ftype, keepfilt, edges, n_jobs])	Filt the data in the specified frequency bands.
pacplot(pac, xvec, yvec[, xlabel, ylabel, …])	Main plotting pac function.
plot([zscore, baseline, edges])	Integrated Peak-Locked TF plotting function.
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)

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.

plot(zscore=False, baseline=None, edges=0, **kwargs)

Integrated Peak-Locked TF plotting function.

Parameters

zscorebool | False

Normalize the power by using a z-score normalization. This can be useful in order to compensate the 1 / f effect in the power spectrum. If True, the mean and deviation are computed at the single trial level and across all time points

baselinetuple | None

Baseline period to use in order to apply the z-score correction. Should be in samples.

edgesint | 0

Number of pixels to discard to compensate filtering edge effect (power[edges:-edges]).

kwargsdict | {}

Additional arguments are sent to the tensorpac.utils.PeakLockedTF.pacplot method

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.