make_meeg_categorical

mvpy.dataset.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()