This documentation is for development version 0.18.dev0.

mne.simulation.simulate_raw

mne.simulation.simulate_raw(raw, stc, trans, src, bem, cov='simple', blink=False, ecg=False, chpi=False, head_pos=None, mindist=1.0, interp='cos2', iir_filter=None, n_jobs=1, random_state=None, use_cps=True, forward=None, duration=None, verbose=None)[source]

Simulate raw data.

Head movements can optionally be simulated using the head_pos parameter.

Parameters:
raw : instance of Raw | instance of Info

The raw template to use for simulation. The info, times, and first_samp properties will be used. Can be info if duration is also supplied, in which case first_samp will be set to zero.

stc : instance of SourceEstimate

The source estimate to use to simulate data. Must have the same sample rate as the raw data.

trans : dict | str | None

Either a transformation filename (usually made using mne_analyze) or an info dict (usually opened using read_trans()). If string, an ending of fif or fif.gz will be assumed to be in FIF format, any other ending will be assumed to be a text file with a 4x4 transformation matrix (like the –trans MNE-C option). If trans is None, an identity transform will be used.

src : str | instance of SourceSpaces

Source space corresponding to the stc. If string, should be a source space filename. Can also be an instance of loaded or generated SourceSpaces.

bem : str | dict

BEM solution corresponding to the stc. If string, should be a BEM solution filename (e.g., “sample-5120-5120-5120-bem-sol.fif”).

cov : instance of Covariance | str | dict of float | None

The sensor covariance matrix used to generate noise. If string, should be a filename or ‘simple’. If ‘simple’, an ad hoc covariance matrix will be generated with default values. If dict, an ad hoc covariance matrix will be generated with the values specified by the dict entries. If None, no noise will be added.

blink : bool

If true, add simulated blink artifacts. See Notes for details.

ecg : bool

If true, add simulated ECG artifacts. See Notes for details.

chpi : bool

If true, simulate continuous head position indicator information. Valid cHPI information must encoded in raw.info['hpi_meas'] to use this option.

head_pos : None | str | dict | tuple | array

Name of the position estimates file. Should be in the format of the files produced by maxfilter. If dict, keys should be the time points and entries should be 4x4 dev_head_t matrices. If None, the original head position (from info['dev_head_t']) will be used. If tuple, should have the same format as data returned by head_pos_to_trans_rot_t. If array, should be of the form returned by mne.chpi.read_head_pos().

mindist : float

Minimum distance between sources and the inner skull boundary to use during forward calculation.

interp : str

Either ‘hann’, ‘cos2’, ‘linear’, or ‘zero’, the type of forward-solution interpolation to use between forward solutions at different head positions.

iir_filter : None | array

IIR filter coefficients (denominator) e.g. [1, -1, 0.2].

n_jobs : int

Number of jobs to use.

random_state : None | int | ~numpy.random.RandomState

The random generator state used for blink, ECG, and sensor noise randomization.

use_cps : None | bool (default True)

Whether to use cortical patch statistics to define normal orientations. Only used when surf_ori and/or force_fixed are True.

forward : instance of Forward | None

The forward operator to use. If None (default) it will be computed using bem, trans, and src.

New in version 0.17.

duration : float | None

The duration to simulate. Can be None to use the duration of raw. Must be supplied if raw is an instance of mne.Info.

New in version 0.18.

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:
raw : instance of Raw

The simulated raw file.

Notes

Events coded with the position number (starting at 1) will be stored in the trigger channel (if available) at times corresponding to t=0 in the stc.

The resulting SNR will be determined by the structure of the noise covariance, the amplitudes of stc, and the head position(s) provided.

The blink and ECG artifacts are generated by 1) placing impulses at random times of activation, and 2) convolving with activation kernel functions. In both cases, the scale-factors of the activation functions (and for the resulting EOG and ECG channel traces) were chosen based on visual inspection to yield amplitudes generally consistent with those seen in experimental data. Noisy versions of the blink and ECG activations will be stored in the first EOG and ECG channel in the raw file, respectively, if they exist.

For blink artifacts:

  1. Random activation times are drawn from an inhomogeneous poisson process whose blink rate oscillates between 4.5 blinks/minute and 17 blinks/minute based on the low (reading) and high (resting) blink rates from [1].
  2. The activation kernel is a 250 ms Hanning window.
  3. Two activated dipoles are located in the z=0 plane (in head coordinates) at ±30 degrees away from the y axis (nasion).
  4. Activations affect MEG and EEG channels.

For ECG artifacts:

  1. Random inter-beat intervals are drawn from a uniform distribution of times corresponding to 40 and 80 beats per minute.
  2. The activation function is the sum of three Hanning windows with varying durations and scales to make a more complex waveform.
  3. The activated dipole is located one (estimated) head radius to the left (-x) of head center and three head radii below (+z) head center; this dipole is oriented in the +x direction.
  4. Activations only affect MEG channels.

If you have a mne.Info that you want to use with no associated mne.io.Raw instance, consider creating a dummy one using mne.io.RawArray.

New in version 0.10.0.

References

[1](1, 2) Bentivoglio et al. “Analysis of blink rate patterns in normal subjects” Movement Disorders, 1997 Nov;12(6):1028-34.

Examples using mne.simulation.simulate_raw