mne_connectivity.EpochTemporalConnectivity#

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

Connectivity class with epoch and time dimensions.

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

Parameters:

dataarray, shape (n_epochs, n_connections[, n_components], n_times): The connectivity data. n_connections is equal to n_nodes * n_nodes if indices='all', n_nodes * (n_nodes - 1) / 2 if indices is 'lower' or 'upper', or the length of the arrays in indices if a tuple of arrays.
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 | 'lower' | 'upper' | 'all': The indices of channels connectivity was computed between. If a tuple, then contains two array-likes, where the first array represents the channel indices of the seeds, and the second array represents the channel indices of the targets. For multivariate methods, the seed and target indices should consist of nested arrays containing the channel indices for each multivariate connection. If 'lower', connectivity represents the lower-triangular part of the connectivity matrix. If 'upper', connectivity represents the upper-triangular part of the connectivity matrix. If 'all', connectivity represents all connections. Indices for multivarate methods should only be specified as a tuple of arrays.
methodstr | None: The method name used to compute connectivity (default None).
eventsarray of int, shape (n_events, 3) | None: The events array. Default is None.
event_iddict | None: Mapping from condition descriptions (strings) to integer event codes. Default is None.
**kwargsdict: Extra connectivity parameters, like components for multivariate connectivity with multiple components per connection, or extra parameters to be stored as xarray attrs.

Attributes:

attrs: Xarray attributes of connectivity.
companion: Generate block companion matrix for a vector autoregressive (VAR) model.
coords: The coordinates of the xarray data.
dims: The dimensions of the xarray data.
event_id: Mapping from condition descriptions (strings) to integer event codes.
events: The events array, for those event types found in event_id.
indices: Indices of connectivity data.
method: The method used to compute connectivity.
n_epochs: The number of epochs the connectivity data varies over.
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 epoched connectivity structure, in place.
`combine_epochs`([method])	Aggregate connectivity data over epochs.
`combine_times`([method, tmin, tmax])	Aggregate connectivity data over times.
`copy`()	Return a deep copy of the connectivity container.
`get_data`([output, missing])	Get connectivity data as a numpy array.
`plot_circle`(**kwargs)	Visualize connectivity as a circular graph.
`predict`(data)	Predict samples on data using the vector autoregressive (VAR) model.
`rename_nodes`(mapping)	Rename nodes.
`save`(fname)	Save connectivity data to disk.
`simulate`(n_samples[, noise_func, random_state])	Simulate data using the vector autoregressive (VAR) model.

eigvals
is_stable

See also

mne_connectivity.envelope_correlation
mne_connectivity.vector_auto_regression

append(epoch_conn)#

Append another epoched connectivity structure, in place.

Parameters:

epoch_conninstance of EpochConnectivity or EpochTemporalConnectivity or EpochSpectralConnectivity or EpochSpectroTemporalConnectivity: The connectivity container to append. Must be of the same type as the current container instance.

Returns:

selfinstance of EpochConnectivity or EpochTemporalConnectivity or EpochSpectralConnectivity or EpochSpectroTemporalConnectivity: The altered connectivity container with the new epochs appended. The instance type matches that of the current container instance.

property attrs#

Xarray attributes of connectivity.

See xarray’s attrs.

combine_epochs(method='mean')#

Aggregate connectivity data over epochs.

Parameters:

method'mean' | 'median' | callable(): How to aggregate the data across epochs. If callable, must take a NumPy array of shape (n_epochs, ...) as input and return an array collapsed over the epoch dimension. Default is 'mean'.

Returns:

coninstance of Connectivity or SpectralConnectivity or TemporalConnectivity or SpectroTemporalConnectivity: The connectivity data aggregated over the epoch dimension. Instance type reflects that of the current connectivity instance, without the epoch dimension.

Notes

Passing in np.median is considered unsafe for complex data. Pass the string "median" instead to compute the marginal median (i.e., the median of the real and imaginary components separately). See discussion here: scipy/scipy#12676

combine_times(method='mean', tmin=None, tmax=None)#

Aggregate connectivity data over times.

Parameters:

method'mean' | 'median' | callable(): How to aggregate the data across times. If callable, must take a NumPy array of shape (..., n_times) as input and return an array collapsed over the time dimension. Default is 'mean'.
tmin, tmaxfloat | None: First and last times to aggregate over, in seconds. If None use the first or last times in the data, respectively. Default is None.

Returns:

coninstance of Connectivity or EpochConnectivity or SpectralConnectivity or EpochSpectralConnectivity: The connectivity data aggregated over the time dimension. Instance type reflects that of the current connectivity instance, without the time dimension.

Notes

Passing in np.median is considered unsafe for complex data. Pass the string "median" instead to compute the marginal median (i.e., the median of the real and imaginary components separately). See discussion here: scipy/scipy#12676

property companion#

Generate block companion matrix for a vector autoregressive (VAR) model.

Returns the data matrix if the VAR model order (i.e., the number of lags) is 1.

property coords#: The coordinates of the xarray data.

copy()#: Return a deep copy of the connectivity container.

property dims#: The dimensions of the xarray data.

property event_id#: Mapping from condition descriptions (strings) to integer event codes.

property events#: The events array, for those event types found in event_id.

get_data(output='compact', missing='raise')#

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_connections, ...) array.
'dense' will return each connectivity matrix as a (..., n_nodes, n_nodes, ...) array.
'compact' (default) will return 'raveled' if indices is a tuple of arrays, or 'dense' if indices is 'all', 'lower', or 'upper'.

missing'raise' | float

How to handle missing values in the dense connectivity matrix when these cannot be filled in (see notes for more information). If 'raise', an error is raised. If a float, the missing values are filled with that float. Ignored if output='raveled'. Default is 'raise'.

Returns:

dataarray: The output connectivity data.
multivariate_nodestuple of array: Returned if the connectivity data is multivariate with self.indices defined as a tuple of arrays, and output='dense'. Used to map from the original set of indices to the dense matrix space. See notes for more information.

Notes

Handling missing values for dense outputs

If indices is not 'all' and output='dense', there may be missing values from the full connectivity matrix that need to be filled in:

When indices is 'lower' or 'upper', the missing values will try to be inferred based on the existing ones, falling back to the behaviour determined by the missing parameter if they cannot be inferred.
When indices is a tuple and indices represents a subset of the full connectivity matrix, the missing values will not be inferred, and the behaviour is determined by the missing parameter.
When indices is a tuple and indices represents the full connectivity matrix, there are no missing values to fill in.

Handling dense outputs for multivariate connectivity

Because multivariate connectivity data can involve multiple channels per connection, it is not possible to represent the data in a dense matrix form where each row/column represent a single channel.

Instead, the multivariate data is mapped into a new space, based on the set of channels that define each node. E.g., the multivariate indices:

(
    [[0, 1], [0, 1], [2, 3]],  # seeds
    [[2, 3], [4, 5], [4, 5]]   # targets
)

contains the following sets of channels: [0, 1] (node 0); [2, 3] (node 1); and [4, 5] (node 2). Based on this, the multivariate indices can be mapped to a new space with indices:

(
    [0, 0, 1],  # seeds
    [1, 2, 2]   # targets
)

For a dense connectivity matrix, this would return a (3, 3) upper-triangular array.

To ensure the mapping from the original multivariate indices to the new dense matrix space is traceable, multivariate_nodes is returned, which contains the (unmasked form) of each node in the position where it exists in the dense matrix space. For the above example, multivariate_nodes would be [[0, 1], [2, 3], [4, 5]].

property indices#

Indices of connectivity data.

Returns:

indices'all' | 'lower' | 'upper' | tuple of list: Either 'all' for all-to-all connectivity, 'lower' for lower-triangular connectivity, 'upper' for upper-triangular connectivity, or a tuple of lists representing the seed and target nodes that connectivity was computed between.

property method#: The method used to compute connectivity.

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

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 data using the vector autoregressive (VAR) model.

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

Parameters:

dataarray, shape ([n_epochs,] n_signals, n_times): Epoched or continuous data. If the VAR model is time-varying (i.e., there are different models per epoch), then the data should also be epoched, with one epoch per VAR model. n_signals should match the number of signals in the VAR model.

Returns:

predictedarray, shape ([n_epochs,] n_signals, n_times): Data as predicted by the VAR model, of the same shape as data.

Notes

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

To compute residual covariances from epoched data:

# compute the covariance of the residuals
# rows are observations, columns are variables
t = residuals.shape[0]  # n_epochs
sampled_residuals = np.concatenate(
    np.split(residuals[:, :, lags:], t, 0), axis=2
).squeeze(0)
residuals_cov = 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 data using the vector autoregressive (VAR) model.

Parameters:

n_samplesint: Number of samples to generate.
noise_funccallable() | None: The function used to create the generating noise process. Each call to this function should return an array of shape (n_nodes,). If None, Gaussian white noise with zero mean and unit variance is used.
random_stateint | array_like of int | SeedSequence | BitGenerator | Generator | None: Seed passed to numpy.random.default_rng() to generate the default Gaussian noise when noise_func is None. If None (default), a new numpy.random.Generator seeded from entropy is used.

Returns:

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

Notes

If the VAR model is time-varying (i.e., there are different models per epoch), the data is simulated from the average of these models.

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

property xarray#: Xarray of the connectivity data.