mne_connectivity.SpectroTemporalConnectivity#

class mne_connectivity.SpectroTemporalConnectivity(data, freqs, times, n_nodes, names=None, indices='all', method=None, spec_method=None, n_epochs_used=None, **kwargs)[source]#

Spectrotemporal connectivity class.

This class stores connectivity data that varies over both frequency and time. The temporal part describes sample-by-sample time-varying connectivity (usually on the order of milliseconds). Note the difference relative to Epochs.

The underlying data is an array of shape (n_connections, [n_components], n_freqs, n_times), or (n_nodes, n_nodes, [n_components], n_freqs, n_times). n_components is an optional dimension for multivariate methods where each connection has multiple components of connectivity.

Parameters:

datanp.ndarray ([epochs], n_estimated_nodes, [components], [freqs], [times]): The connectivity data that is a raveled array of (n_estimated_nodes, ...) shape. The n_estimated_nodes is equal to n_nodes_in * n_nodes_out if one is computing the full connectivity, or a subset of nodes equal to the length of indices passed in.
freqslist | np.ndarray: The frequencies at which the connectivity data is computed over. If the frequencies are “frequency bands” (i.e. gamma band), then these are the median of those bands.
timeslist | np.ndarray: The times at which the connectivity data is computed over.
n_nodesint: The number of nodes in the dataset used to compute connectivity. This should be equal to the number of signals in the original dataset.
nameslist | np.ndarray | None: The names of the nodes of the dataset used to compute connectivity. If ‘None’ (default), then names will be a list of integers from 0 to n_nodes. If a list of names, then it must be equal in length to n_nodes.
indicestuple of arrays | str | None: The indices of relevant connectivity data. If 'all' (default), then data is connectivity between all nodes. If 'symmetric', then data is symmetric connectivity between all nodes. If a tuple, then the first list represents the “in nodes”, and the second list represents the “out nodes”. See “Notes” for more information.
methodstr, optional: The method name used to compute connectivity.
spec_methodstr, optional: The type of method used to compute spectral analysis, by default None.
n_epochs_usedint, optional: The number of epochs used in the computation of connectivity, by default None.
**kwargsdict: Extra connectivity parameters. These may include freqs for spectral connectivity, times for connectivity over time, or components for multivariate connectivity with multiple components per connection. In addition, these may include extra parameters that are stored as xarray attrs.

Attributes:

attrs: Xarray attributes of connectivity.
companion: Generate block companion matrix.
coords: The coordinates of the xarray data.
dims: The dimensions of the xarray data.
freqs: The frequency points of the connectivity data.
indices: Indices of connectivity data.
method: The method used to compute connectivity.
n_epochs: The number of epochs the connectivity data varies over.
n_epochs_used: Number of epochs used in computation of connectivity.
n_nodes: The number of nodes in the original dataset.
names: Node names.
shape: Shape of raveled connectivity.
times: The time points of the connectivity data.
xarray: Xarray of the connectivity data.

Methods

`append`(epoch_conn)	Append another connectivity structure.
`combine`([combine])	Combine connectivity data over epochs.
`get_data`([output])	Get connectivity data as a numpy array.
`plot_circle`(**kwargs)	Visualize connectivity as a circular graph.
`predict`(data)	Predict samples on actual data.
`rename_nodes`(mapping)	Rename nodes.
`save`(fname)	Save connectivity data to disk.
`simulate`(n_samples[, noise_func, random_state])	Simulate vector autoregressive (VAR) model.

copy
eigvals
get_epoch_annotations
is_stable

See also

mne_connectivity.phase_slope_index
mne_connectivity.spectral_connectivity_epochs

append(epoch_conn)#

Append another connectivity structure.

Parameters:

epoch_conninstance of Connectivity: The Epoched Connectivity class to append.

Returns:

selfinstance of Connectivity: The altered Epoched Connectivity class.

property attrs#

Xarray attributes of connectivity.

See xarray’s attrs.

combine(combine='mean')#

Combine connectivity data over epochs.

Parameters:

combine‘mean’ | ‘median’ | callable()

How to combine correlation estimates across epochs. Default is ‘mean’. If callable, it must accept one positional input. For example:

combine = lambda data: np.median(data, axis=0)

Returns:

conninstance of Connectivity: The combined connectivity data structure.

property companion#

Generate block companion matrix.

Returns the data matrix if the model is VAR(1).

property coords#: The coordinates of the xarray data.

property dims#: The dimensions of the xarray data.

property freqs#

The frequency points of the connectivity data.

If these are computed over a frequency band, it will be the median frequency of the frequency band.

get_data(output='compact')#

Get connectivity data as a numpy array.

Parameters:

outputstr, optional: How to format the output, by default ‘raveled’, which will represent each connectivity matrix as a (n_nodes_in * n_nodes_out,) list. If ‘dense’, then will return each connectivity matrix as a 2D array. If ‘compact’ (default) then will return ‘raveled’ if indices were defined as a list of tuples, or dense if indices is ‘all’. Multivariate connectivity data cannot be returned in a dense form.

Returns:

datanp.ndarray: The output connectivity data.

property indices#

Indices of connectivity data.

Returns:

indicesstr | tuple of lists: Either ‘all’ for all-to-all connectivity, ‘symmetric’ for symmetric all-to-all connectivity, or a tuple of lists representing the node-to-nodes that connectivity was computed.

property method#: The method used to compute connectivity.

property n_epochs#: The number of epochs the connectivity data varies over.

property n_epochs_used#

Number of epochs used in computation of connectivity.

Can be ‘None’, if there was no epochs used. This is equivalent to the number of epochs, if there is no combining of epochs.

property n_nodes#

The number of nodes in the original dataset.

Even if indices defines a subset of nodes that were computed, this should be the total number of nodes in the original dataset.

property names#: Node names.

plot_circle(**kwargs)#

Visualize connectivity as a circular graph.

Parameters:

node_nameslist of str

Node names. The order corresponds to the order in con.

indicestuple of array | None

Two arrays with indices of connections for which the connections strengths are defined in con. Only needed if con is a 1D array.

n_linesint | None

If not None, only the n_lines strongest connections (strength=abs(con)) are drawn.

node_anglesarray, shape (n_node_names,) | None

Array with node positions in degrees. If None, the nodes are equally spaced on the circle. See mne.viz.circular_layout.

node_widthfloat | None

Width of each node in degrees. If None, the minimum angle between any two nodes is used as the width.

node_heightfloat

The relative height of the colored bar labeling each node. Default 1.0 is the standard height.

node_colorslist of tuple | list of str

List with the color to use for each node. If fewer colors than nodes are provided, the colors will be repeated. Any color supported by matplotlib can be used, e.g., RGBA tuples, named colors.

facecolorstr

Color to use for background. See matplotlib.colors.

textcolorstr

Color to use for text. See matplotlib.colors.

node_edgecolorstr

Color to use for lines around nodes. See matplotlib.colors.

linewidthfloat

Line width to use for connections.

colormapstr | instance of matplotlib.colors.LinearSegmentedColormap

Colormap to use for coloring the connections.

vminfloat | None

Minimum value for colormap. If None, it is determined automatically.

vmaxfloat | None

Maximum value for colormap. If None, it is determined automatically.

colorbarbool

Display a colorbar or not.

titlestr

The figure title.

colorbar_sizefloat

Size of the colorbar.

colorbar_postuple, shape (2,)

Position of the colorbar.

fontsize_titleint

Font size to use for title.

fontsize_namesint

Font size to use for node names.

fontsize_colorbarint

Font size to use for colorbar.

paddingfloat

Space to add around figure to accommodate long labels.

axinstance of matplotlib PolarAxes | None

The axes to use to plot the connectivity circle.

figNone | instance of matplotlib.figure.Figure

The figure to use. If None, a new figure with the specified background color will be created.

Deprecated: will be removed in version 0.5.

subplotint | tuple, shape (3,)

Location of the subplot when creating figures with multiple plots. E.g. 121 or (1, 2, 1) for 1 row, 2 columns, plot 1. See matplotlib.pyplot.subplot.

Deprecated: will be removed in version 0.5.

interactivebool

When enabled, left-click on a node to show only connections to that node. Right-click shows all connections.

node_linewidthfloat

Line with for nodes.

showbool

Show figure if True.

Returns:

figinstance of matplotlib.figure.Figure: The figure handle.
axinstance of matplotlib.projections.polar.PolarAxes: The subplot handle.

Notes

This code is based on a circle graph example by Nicolas P. Rougier

By default, matplotlib.pyplot.savefig() does not take facecolor into account when saving, even if set when a figure is generated. This can be addressed via, e.g.:

>>> fig.savefig(fname_fig, facecolor='black') 

If facecolor is not set via matplotlib.pyplot.savefig(), the figure labels, title, and legend may be cut off in the output figure.

predict(data)#

Predict samples on actual data.

The result of this function is used for calculating the residuals.

Parameters:

dataarray: Epoched or continuous data set. Has shape (n_epochs, n_signals, n_times) or (n_signals, n_times).

Returns:

predictedarray: Data as predicted by the VAR model of shape same as data.

Notes

Residuals are obtained by r = x - var.predict(x).

To compute residual covariances:

# compute the covariance of the residuals
# row are observations, columns are variables
t = residuals.shape[0]
sampled_residuals = np.concatenate(
    np.split(residuals[:, :, lags:], t, 0),
    axis=2
).squeeze(0)
rescov = np.cov(sampled_residuals)

rename_nodes(mapping)#

Rename nodes.

Parameters:

mappingdict: Mapping from original node names (keys) to new node names (values).

save(fname)#

Save connectivity data to disk.

Can later be loaded using the function mne_connectivity.read_connectivity().

Parameters:

fnamestr | pathlib.Path: The filepath to save the data. Data is saved as netCDF files (.nc extension).

property shape#: Shape of raveled connectivity.

simulate(n_samples, noise_func=None, random_state=None)#

Simulate vector autoregressive (VAR) model.

This function generates data from the VAR model.

Parameters:

n_samplesint: Number of samples to generate.
noise_funcfunc, optional: This function is used to create the generating noise process. If set to None, Gaussian white noise with zero mean and unit variance is used.
random_stateNone | int | instance of RandomState: If random_state is an int, it will be used as a seed for RandomState. If None, the seed will be obtained from the operating system (see RandomState for details). Default is None.

Returns: