mvpy.dataset package

Submodules

mvpy.dataset.make_meeg_categorical module

Functions to generate examples of M-/EEG data with continuous predictors that are drawn from categorical classes.

Functional interface.

mvpy.dataset.make_meeg_categorical.make_meeg_categorical(n_trials: int = 120, n_channels: int = 64, t_padding: float = 1.0, t_baseline: float = 0.25, t_duration: float = 1.0, t_length: float = 2.0, fs: int = 200, n_background: int = 50, n_features: int = 1, n_cycles: int = 2, n_classes: int = 2, temperature: float = 1.0, sigma: float = 0.2, snr: float = 0.1, gamma: float = 1.0, phi: float = 0.5, backend: str = 'torch', device: str = 'cpu') → tuple[ndarray | Tensor, ndarray | Tensor]

Create an M-EEG dataset based on continuous time-varying stimuli that group together into features and classes.

Parameters:

n_trialsint, default=120

How many trials to simulate?

n_channelsint, default=64

How many channels to simulate?

t_paddingfloat, default=1.0

How much padding to use (in seconds)? Padding is cut off before returning, but allows background brain signals to stabilise.

t_baselinefloat, default=0.25

How much time (in seconds) should pass before stimulus turns on?

t_durationfloat, default=1.0

How much time (in seconds) should pass before stimulus turns off?

t_lengthfloat, default=2.0

How much time (in seconds) should we simulate per trial?

fsint, default=200

Sampling frequency (in Hz).

n_backgroundint, default=50

How many background sources to simulate?

n_featuresint, default=1

How many features should we simulate (each with their own classes)?

n_cyclesint, default=2

How many cycles should each TRF include?

n_classesint, default=2

How many classes should we simulate per feature?

temperaturefloat, default=1.0

When computing the sensitivity of each class to each source feature, what temperature should we use for softmax?

sigmafloat, default=0.2

When simulating individual trials, how much uncertainty (in unit standard deviations) should there be about any trial’s class membership?

snrfloat, default=0.1

What should the signal to noise ratio be? Here, SNR is defined as \(\frac{P_{f}}{P_{b}}\) where \(P\) is power and \(f\) and \(b\) refer to features and background, respectively.

gammafloat, default=1.0

What gamma should we use in the radial basis kernel applied over channels when creating channel covariances?

phifloat, default=0.5

What phi to use when generating auto-correlated stimulus signals? In the AR1 process, this determines the decay of signals, where \(X[t+1] = \phi X[t] + E[t+1]\), but applies only to background signals.

backendstr, default=’torch’

Which backend to use (numpy or torch)?

devicestr, default=’cpu’

What device to use?

Returns:

XUnion[np.ndarray, torch.Tensor]

Simulated class labels of shape (n_trials, n_features, n_timepoints).

yUnion[np.ndarray, torch.Tensor]

Simulated neural responses of shape (n_trials, n_channels, n_timepoints).

Examples

>>> import torch
>>> import matplotlib.pyplot as plt
>>> from mvpy.dataset import make_meeg_layout, make_meeg_colours, make_meeg_categorical
>>> n_channels = 64
>>> ch_pos = make_meeg_layout(n_channels)
>>> ch_col = make_meeg_colours(ch_pos).cpu().numpy()
>>> X, y = make_meeg_categorical(n_channels = n_channels, n_features = 1, n_classes = 2)
>>> print(X.shape, y.shape, ch_pos.shape)
torch.Size([120, 1, 400]) torch.Size([120, 64, 400]) torch.Size([64, 3])
>>> fig, ax = plt.subplots(1, 3, figsize = (12.0, 4.0))
>>> t = torch.arange(-0.25, 1.75, 1 / 200)
>>> for i in range(n_channels):
>>>     mask_0 = ~X[:,0,0].bool()
>>>     mask_1 = ~mask_0
>>>     ax[0].plot(t, y[mask_0,i,:].mean(0), c = ch_col[i])
>>>     ax[1].plot(t, y[mask_1,i,:].mean(0), c = ch_col[i])
>>> ax[0].set_ylabel(fr'Amplitude (a.u.)')
>>> ax[0].set_xlabel(fr'Time ($s$)')
>>> ax[0].set_title(fr'M-/EEG signal for class$_0$')
>>> ax[1].set_ylabel(fr'Amplitude (a.u.)')
>>> ax[1].set_xlabel(fr'Time ($s$)')
>>> ax[1].set_title(fr'M-/EEG signal for class$_1$')
>>> ax[2].scatter(ch_pos[:,0], ch_pos[:,1], c = ch_col, marker = 'o', s = 250.0)
>>> ax[2].axis('off')
>>> ax[2].set_title(fr'Channel positions')
>>> fig.tight_layout()

The torch package contains data structures for multi-dimensional

Python part of the warnings subsystem.

mvpy.dataset.make_meeg_colours module

Functions to generate a layout of M-/EEG sensors.

mvpy.dataset.make_meeg_colours.make_meeg_colours(ch_pos: ndarray | Tensor) → ndarray | Tensor

Create spatial colours for sensor layout.

Parameters:

ch_posUnion[np.ndarray, torch.Tensor]

Channel positons of shape (n_channels, n_dims) where n_dims is (x, y, z).

Returns:

coloursUnion[np.ndarray, torch.Tensor]

The sensor colours of shape (n_channels, rgb).

This module provides access to the mathematical functions

The torch package contains data structures for multi-dimensional

mvpy.dataset.make_meeg_continuous module

Functions to generate examples of M-/EEG data with continuous predictors.

Functional interface.

mvpy.dataset.make_meeg_continuous.make_meeg_continuous(n_trials: int = 120, n_channels: int = 64, t_padding: float = 1.0, t_baseline: float = 0.25, t_duration: float = 1.0, t_length: float = 2.0, fs: int = 200, n_background: int = 50, n_features: int = 3, n_cycles: int = 2, snr: float = 0.1, gamma: float = 1.0, phi: float = 0.5, return_Xyß: bool = False, backend: str = 'torch', device: str = 'cpu') → tuple[ndarray | Tensor, ndarray | Tensor]

Create an M-EEG dataset based on continuous time-varying stimuli.

Parameters:

n_trialsint, default=120

How many trials to simulate?

n_channelsint, default=64

How many channels to simulate?

t_paddingfloat, default=1.0

How much padding to use (in seconds)? Padding is cut off before returning, but allows background brain signals to stabilise.

t_baselinefloat, default=0.25

How much time (in seconds) should pass before stimulus turns on?

t_durationfloat, default=1.0

How much time (in seconds) should pass before stimulus turns off?

t_lengthfloat, default=2.0

How much time (in seconds) should we simulate per trial?

fsint, default=200

Sampling frequency (in Hz).

n_backgroundint, default=50

How many background sources to simulate?

n_featuresint, default=3

How many feature sources to simulate?

n_cyclesint, default=2

How many cycles should each TRF include?

snrfloat, default=0.1

What should the signal to noise ratio be? Here, SNR is defined as \(\frac{P_{f}}{P_{b}}\) where \(P\) is power and \(f\) and \(b\) refer to features and background, respectively.

gammafloat, default=1.0

What gamma should we use in the radial basis kernel applied over channels when creating channel covariances?

phifloat, default=0.5

What phi to use when generating auto-correlated stimulus signals? In the AR1 process, this determines the decay of signals, where \(X[t+1] = \phi X[t] + E[t+1]\).

return_Xyßbool, default=False

Should we return X, y and ß?

backendstr, default=’torch’

Which backend to use (numpy or torch)?

devicestr, default=’cpu’

What device to use?

Returns:

XUnion[np.ndarray, torch.Tensor]

Simulated signals of shape (n_trials, n_features, n_timepoints).

yUnion[np.ndarray, torch.Tensor]

Simulated neural responses of shape (n_trials, n_channels, n_timepoints).

ßOptional[Union[np.ndarray, torch.Tensor]]

Simulated temporal response functions of shape (n_channels, n_features, n_trf).

Examples

>>> import torch
>>> import matplotlib.pyplot as plt
>>> from mvpy.dataset import make_meeg_layout, make_meeg_colours, make_meeg_continuous
>>> n_channels = 64
>>> ch_pos = make_meeg_layout(n_channels)
>>> ch_col = make_meeg_colours(ch_pos)
>>> X, y = make_meeg_continuous(n_channels = n_channels)
>>> print(X.shape, y.shape, ch_pos.shape)
torch.Size([120, 3, 400]) torch.Size([120, 64, 400]) torch.Size([64, 3])
>>> fig, ax = plt.subplots(1, 2, figsize = (8.0, 4.0))
>>> t = torch.arange(-0.25, 1.75, 1 / 200)
>>> for i in range(n_channels):
>>>     ax[0].plot(t, y[:,i,:].mean(0), c = ch_col[i])
>>> ax[0].set_ylabel(fr'Amplitude (a.u.)')
>>> ax[0].set_xlabel(fr'Time ($s$)')
>>> ax[0].set_title(fr'M-/EEG signal')
>>> ax[1].scatter(ch_pos[:,0], ch_pos[:,1], c = ch_col, marker = 'o', s = 250.0)
>>> ax[1].axis('off')
>>> ax[1].set_title(fr'Channel positions')
>>> fig.tight_layout()

The torch package contains data structures for multi-dimensional

Python part of the warnings subsystem.

mvpy.dataset.make_meeg_discrete module

Functions to generate examples of M-/EEG data with continuous predictors.

Functional interface.

mvpy.dataset.make_meeg_discrete.make_meeg_discrete(n_trials: int = 120, n_channels: int = 64, t_padding: float = 1.0, t_baseline: float = 0.25, t_duration: float = 1.0, t_length: float = 2.0, fs: int = 200, n_background: int = 50, n_features: int = 3, n_cycles: int = 2, snr: float = 0.1, gamma: float = 1.0, phi: float = 0.5, poisson: bool = True, variable: bool = True, lambda_min: float = 0.001, lambda_max: float = 0.1, return_Xyß: bool = False, backend: str = 'torch', device: str = 'cpu') → tuple[ndarray | Tensor, ndarray | Tensor]

Create an M-EEG dataset based on stimuli defined as discrete events.

Parameters:

n_trialsint, default=120

How many trials to simulate?

n_channelsint, default=64

How many channels to simulate?

t_paddingfloat, default=1.0

How much padding to use (in seconds)? Padding is cut off before returning, but allows background brain signals to stabilise.

t_baselinefloat, default=0.25

How much time (in seconds) should pass before stimulus turns on?

t_durationfloat, default=1.0

How much time (in seconds) should pass before stimulus turns off?

t_lengthfloat, default=2.0

How much time (in seconds) should we simulate per trial?

fsint, default=200

Sampling frequency (in Hz).

n_backgroundint, default=50

How many background sources to simulate?

n_featuresint, default=3

How many feature sources to simulate?

n_cyclesint, default=2

How many cycles should each TRF include?

snrfloat, default=0.1

What should the signal to noise ratio be? Here, SNR is defined as \(\frac{P_{f}}{P_{b}}\) where \(P\) is power and \(f\) and \(b\) refer to features and background, respectively.

gammafloat, default=1.0

What gamma should we use in the radial basis kernel applied over channels when creating channel covariances?

phifloat, default=0.5

What phi to use when generating auto-correlated stimulus signals? In the AR1 process, this determines the decay of signals, where \(X[t+1] = \phi X[t] + E[t+1]\) and applies only to background features here.

poissonbool, default=True

Should we sample impulses from a Poisson distribution? If False, only one impulse is placed at stimulus onset.

variablebool, default=True

Should each feature be sampled from a different Poisson distribution, allowing for variability in event rates? Only used if Poisson sampling is enabled.

lambda_minfloat, default=1e-3

Minimum rate for sampling from Poisson distribution.

lambda_maxfloat, default=0.1

Maximum rate for sampling from Poisson distribution.

return_Xyßbool, default=False

Should we return X, y and ß?

backendstr, default=’torch’

Which backend to use (numpy or torch)?

devicestr, default=’cpu’

What device to use?

Returns:

XUnion[np.ndarray, torch.Tensor]

Simulated signals of shape (n_trials, n_features, n_timepoints).

yUnion[np.ndarray, torch.Tensor]

Simulated neural responses of shape (n_trials, n_channels, n_timepoints).

ßOptional[Union[np.ndarray, torch.Tensor]]

Simulated temporal response functions of shape (n_channels, n_features, n_trf).

Examples

>>> import torch
>>> import matplotlib.pyplot as plt
>>> from mvpy.dataset import make_meeg_layout, make_meeg_colours, make_meeg_discrete
>>> n_channels = 64
>>> ch_pos = make_meeg_layout(n_channels)
>>> ch_col = make_meeg_colours(ch_pos)
>>> X, y = make_meeg_discrete(n_channels = n_channels)
>>> print(X.shape, y.shape, ch_pos.shape)
torch.Size([120, 3, 400]) torch.Size([120, 64, 400]) torch.Size([64, 3])
>>> fig, ax = plt.subplots(1, 2, figsize = (8.0, 4.0))
>>> t = torch.arange(-0.25, 1.75, 1 / 200)
>>> for i in range(n_channels):
>>>     ax[0].plot(t, y[:,i,:].mean(0), c = ch_col[i])
>>> ax[0].set_ylabel(fr'Amplitude (a.u.)')
>>> ax[0].set_xlabel(fr'Time ($s$)')
>>> ax[0].set_title(fr'M-/EEG signal')
>>> ax[1].scatter(ch_pos[:,0], ch_pos[:,1], c = ch_col, marker = 'o', s = 250.0)
>>> ax[1].axis('off')
>>> ax[1].set_title(fr'Channel positions')
>>> fig.tight_layout()

The torch package contains data structures for multi-dimensional

Python part of the warnings subsystem.

mvpy.dataset.make_meeg_layout module

Functions to generate a layout of M-/EEG sensors.

mvpy.dataset.make_meeg_layout.make_meeg_layout(n_channels: int, backend: str = 'torch', device: str = 'cpu') → ndarray | Tensor

Create a concentric channel layout for M-EEG sensors.

Parameters:

n_channelsint

Number of channels/sensors.

backendstr, default=’torch’

Which backend to use (torch or numpy)?

devicestr, default=’cpu’

Which device to use?

Returns:

layoutUnion[np.ndarray, torch.Tensor]

The sensor layout of shape (n_channels, n_directions) where n_directions corresponds to three, i.e. (x, y, z).

This module provides access to the mathematical functions

The torch package contains data structures for multi-dimensional

Module contents