mne_connectivity.TemporalConnectivity#

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

Temporal connectivity class.

This is an array of shape (n_connections, [n_components,] n_times), or (n_nodes, n_nodes, [n_components,] n_times). This describes how connectivity varies over time. It describes sample-by-sample time-varying connectivity (usually on the order of milliseconds). Here time (t=0) is the same for all connectivity measures. n_components is an optional dimension for multivariate methods where each connection has multiple components of connectivity.

Parameters:

dataarray, shape ([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 has computed the full connectivity, or a subset of nodes equal to the length of the arrays in indices passed in.
timeslist | array: 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.
namesarray_like | 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 array_like | 'all' | 'symmetric' | 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 contains two array-likes where the first array represents the “in nodes” (seeds), and the second array represents the “out nodes” (targets).
methodstr | None: The method name used to compute connectivity (default None).
n_epochs_usedint | None: The number of epochs used in the computation of connectivity (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.
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

Notes

mne_connectivity.EpochConnectivity is a similar connectivity class to this one. However, that describes one connectivity snapshot for each epoch. These epochs might be chunks of time that have different meaning for time t=0. Epochs can mean separate trials, where the beginning of the trial implies t=0. These epochs may also be discontiguous.

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. Instance type reflects that of the input instance, without the epoch dimension.

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.

get_data(output='compact')#

Get connectivity data as a numpy array.

Parameters:

output'compact' | 'raveled' | 'dense'

How to format the output:

'raveled' will represent each connectivity matrix as a (..., n_nodes_in * n_nodes_out, ...) array
'dense' will return each connectivity matrix as a (..., n_nodes_in, n_nodes_out, ...) array
'compact' (default) will return 'raveled' if indices were defined as a tuple of arrays, or 'dense' if indices='all'

Multivariate connectivity data cannot be returned in a dense form.

Returns:

dataarray: The output connectivity data.

property indices#

Indices of connectivity data.

Returns:

indices'all' | 'symmetric' | tuple of list: Either 'all' for all-to-all connectivity, 'symmetric' for symmetric connectivity, or a tuple of lists representing the node-to-nodes that connectivity was computed for.

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_like | 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.projections.polar.PolarAxes | None: The axes to use to plot the connectivity circle.
interactivebool: When enabled, left-click on a node to show only connections to that node. Right-click shows all connections.
node_linewidthfloat: Line width 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, shape ([n_epochs,] n_signals, n_times): Epoched or continuous data set.

Returns:

predictedarray, shape ([n_epochs,] n_signals, n_times): 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 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_funccallable() | None: This function is used to create the generating noise process. If 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 numpy.random.RandomState. If None, the seed will be obtained from the operating system (see numpy.random.RandomState for details). Default is None.

Returns:

dataarray, shape (n_samples, n_channels): Generated data.

property times#: The time points of the connectivity data.

property xarray#: Xarray of the connectivity data.

Examples using `mne_connectivity.TemporalConnectivity`#

Compute envelope correlations in volume source space

mne_connectivity.TemporalConnectivity#

Examples using mne_connectivity.TemporalConnectivity#

Examples using `mne_connectivity.TemporalConnectivity`#