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_times), or (n_nodes, n_nodes, 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.
- Parameters:
- data
np.ndarray
([epochs], n_estimated_nodes, [freqs], [times]) The connectivity data that is a raveled array of
(n_estimated_nodes, ...)
shape. Then_estimated_nodes
is equal ton_nodes_in * n_nodes_out
if one is computing the full connectivity, or a subset of nodes equal to the length ofindices
passed in.- times
list
|np.ndarray
The times at which the connectivity data is computed over.
- n_nodes
int
The number of nodes in the dataset used to compute connectivity. This should be equal to the number of signals in the original dataset.
- names
list
|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 ton_nodes
.- indices
tuple
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.- method
str
, optional The method name used to compute connectivity.
- n_epochs_used
int
, optional The number of epochs used in the computation of connectivity, by default None.
- **kwargs
dict
Extra connectivity parameters. These may include
freqs
for spectral connectivity, and/ortimes
for connectivity over time. In addition, these may include extra parameters that are stored as xarrayattrs
.
- data
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 timet=0
. Epochs can mean separate trials, where the beginning of the trial implies t=0. These Epochs may also be discontiguous.- 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
- append(epoch_conn)#
Append another connectivity structure.
- Parameters:
- epoch_conninstance of
Connectivity
The Epoched Connectivity class to append.
- epoch_conninstance of
- Returns:
- selfinstance of
Connectivity
The altered Epoched Connectivity class.
- selfinstance of
- property attrs#
Xarray attributes of connectivity.
See
xarray
’sattrs
.
- 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)
- combine‘mean’ | ‘median’ |
- Returns:
- conninstance of
Connectivity
The combined connectivity data structure.
- conninstance of
- 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
str
, 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’ ifindices
were defined as a list of tuples, ordense
if indices is ‘all’. Multivariate connectivity data cannot be returned in a dense form.
- output
- Returns:
- data
np.ndarray
The output connectivity data.
- data
- property indices#
Indices of connectivity data.
- 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_names
list
ofstr
Node names. The order corresponds to the order in con.
- indices
tuple
ofarray
|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_lines
int
|None
If not None, only the n_lines strongest connections (strength=abs(con)) are drawn.
- node_angles
array
, 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_width
float
|None
Width of each node in degrees. If None, the minimum angle between any two nodes is used as the width.
- node_height
float
The relative height of the colored bar labeling each node. Default 1.0 is the standard height.
- node_colors
list
oftuple
|list
ofstr
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.
- facecolor
str
Color to use for background. See matplotlib.colors.
- textcolor
str
Color to use for text. See matplotlib.colors.
- node_edgecolor
str
Color to use for lines around nodes. See matplotlib.colors.
- linewidth
float
Line width to use for connections.
- colormap
str
| instance ofmatplotlib.colors.LinearSegmentedColormap
Colormap to use for coloring the connections.
- vmin
float
|None
Minimum value for colormap. If None, it is determined automatically.
- vmax
float
|None
Maximum value for colormap. If None, it is determined automatically.
- colorbarbool
Display a colorbar or not.
- title
str
The figure title.
- colorbar_size
float
Size of the colorbar.
- colorbar_pos
tuple
, shape (2,) Position of the colorbar.
- fontsize_title
int
Font size to use for title.
- fontsize_names
int
Font size to use for node names.
- fontsize_colorbar
int
Font size to use for colorbar.
- padding
float
Space to add around figure to accommodate long labels.
- axinstance of matplotlib
PolarAxes
|None
The axes to use to plot the connectivity circle.
- fig
None
| instance ofmatplotlib.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.
- subplot
int
|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_linewidth
float
Line with for nodes.
- showbool
Show figure if True.
- node_names
- Returns:
- figinstance of
matplotlib.figure.Figure
The figure handle.
- axinstance of
matplotlib.projections.polar.PolarAxes
The subplot handle.
- figinstance of
Notes
This code is based on a circle graph example by Nicolas P. Rougier
By default,
matplotlib.pyplot.savefig()
does not takefacecolor
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 viamatplotlib.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:
- data
array
Epoched or continuous data set. Has shape (n_epochs, n_signals, n_times) or (n_signals, n_times).
- data
- Returns:
- predicted
array
Data as predicted by the VAR model of shape same as
data
.
- predicted
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:
- mapping
dict
Mapping from original node names (keys) to new node names (values).
- mapping
- save(fname)#
Save connectivity data to disk.
Can later be loaded using the function
mne_connectivity.read_connectivity()
.- Parameters:
- fname
str
|pathlib.Path
The filepath to save the data. Data is saved as netCDF files (
.nc
extension).
- fname
- 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_samples
int
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_state
None
|int
| instance ofRandomState
If
random_state
is anint
, it will be used as a seed forRandomState
. IfNone
, the seed will be obtained from the operating system (seeRandomState
for details). Default isNone
.
- n_samples
- Returns:
- data
array
, shape (n_samples, n_channels) Generated data.
- 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