meegsim.simulate.SourceSimulator#

class meegsim.simulate.SourceSimulator(src, snr_mode='global', base_std=1e-09)[source]#

This class can be used to create configurations of sources of activity (e.g., narrowband oscillation or 1/f noise).

Attributes:

srcmne.SourceSpaces

The source space that contains all candidate source locations.

snr_mode{‘global’, ‘local’}

The desired mode for the adjustment of the signal-to-noise ratio (SNR).

Note

If 'global' (default), the total power of all point/patch sources is adjusted relative to the total power of all noise sources. The target value of SNR should be provided in the snr_global argument of simulate(). The spatial distribution of source activity can be controlled using the std argument when adding sources.
If 'local', the power of each point/patch source is adjusted relative to the total power of all noise sources. The target value(s) of SNR should be provided in the snr argument when adding sources to the simulation via either add_point_sources() or add_patch_sources()

base_stdfloat, optional

The source activity is scaled by the base standard deviation before projecting to sensor space. By default, it is equal to \(10^{-9}\), corresponding to the dipolar moment of 1 nAm.

Methods

`add_noise_sources`(location[, waveform, std, ...])	Add noise sources to the simulation.
`add_patch_sources`(location, waveform[, snr, ...])	Add patch sources to the simulation.
`add_point_sources`(location, waveform[, snr, ...])	Add point sources to the simulation.
`set_coupling`(coupling, **common_params)	Set coupling between sources that were added to the simulator.
`simulate`(sfreq, duration[, fwd, snr_global, ...])	Simulate a configuration of defined sources.

add_noise_sources(location, waveform=<function one_over_f_noise>, std=1.0, location_params={}, waveform_params={})[source]#

Add noise sources to the simulation. If an adjustment of SNR is needed at some point, these sources will be considered as noise.

Parameters:

locationlist or callable()

Locations of sources can be either specified directly as a list of tuples (index of the src, vertno) or as a function that returns such a list. In the first case, source locations will be the same for every configuration. In the second case, configurations might differ (e.g., if the function returns a random location).

waveformarray or callable()

Waveform provided either directly as an array or as a function. By default, 1/f noise with the slope of 1 is used for all noise sources.

stdfloat, array, or SourceEstimate, optional

Desired standard deviation of the source activity, provided via one of the following options:

a single value that applies to all sources
an array with one value per source
a SourceEstimate object that contains values of all vertices of the source space. In this case, the value will be adjusted for each source automatically based on its location.

By default, 1 is used so the variance of all noise sources is the same.

location_paramsdict, optional

Keyword arguments that will be passed to location if a function is provided.

waveform_paramsdict, optional

Keyword arguments that will be passed to waveform if a function is provided.

Returns:

nameslist: Autogenerated names for the noise sources. The format is ‘auto-ngN-sM’, where N is the index of the noise source group, and M is the index of the source in the group.

Notes

Noise patches are currently not supported.

add_patch_sources(location, waveform, snr=None, std=1.0, location_params={}, waveform_params={}, snr_params={}, extents=None, subject=None, subjects_dir=None, names=None)[source]#

Add patch sources to the simulation.

Parameters:

locationlist or callable()

Depending on the value of the extents argument, locations are interpreted either as set of vertices belonging to the patch (default) or centers of patches.

waveformarray or callable()

Waveforms of source activity provided either directly in an array (fixed for every configuration) or as a function that generates the waveforms (might differ between configurations if the generation is random). For each vertex in the patch, the same waveform is currently used.

snrNone (default), float, or array

SNR values for the defined sources, only used if snr_mode is set to 'local'. Can be None (no adjustment of SNR, default), a single value that is used for all sources or an array with one SNR value per source.

stdfloat, array, or SourceEstimate, optional

Desired standard deviation of the total source activity of the patch (invariant to the number of vertices in the patch), provided via one of the following options:

a single value that applies to all sources
an array with one value per source
a SourceEstimate object that contains values of all vertices of the source space. In this case, the value will be adjusted for each source automatically based on the location of its center of mass.

This parameter can be used in combination with the global SNR mode to set an arbitrary spatial distribution of source activity. By default, 1 is used so the variance of all sources is the same. If the value of snr is specified, this parameter will effectively be ignored.

location_paramsdict, optional

Keyword arguments that will be passed to location if a function is provided.

waveform_paramsdict, optional

Keyword arguments that will be passed to waveform if a function is provided.

snr_paramsdict, optional

Additional parameters required for the adjustment of SNR. Specify fmin and fmax here to define the frequency band which should used for calculating the SNR.

extentsNone (default), float, or list

Extents (radius, in mm) of each patch. If None (default), location must contain all vertices belonging to the patch(es). If specified, patch are grown (using mne.grow_labels()) from vertices specified in location according to the provided values of extent. If a single number is provided, all patch sources have the same extent.

subjectstr, optional

Subject name, only used when growing patch sources from the central vertex. If None (default), it is derived from the src object provided when initializing the simulator.

subject_dirstr, optional

Path to the directory with FreeSurfer output, only used when growing patch sources from the central vertex. If None (default), it is resolved automatically by MNE-Python. Provide the path explicitly if errors arise.

nameslist, optional

A list of names for each source. If not specified, the names will be autogenerated using the format ‘auto-sgN-sM’, where N is the index of the source group, and M is the index of the source in the group.

Returns:

nameslist: A list of (provided or autogenerated) names for each source

add_point_sources(location, waveform, snr=None, std=1.0, location_params={}, waveform_params={}, snr_params={}, names=None)[source]#

Add point sources to the simulation.

Parameters:

locationlist or callable()

waveformarray or callable()

Waveforms of source activity provided either directly in an array (fixed for every configuration) or as a function that generates the waveforms (but differ between configurations if the generation is random).

snrNone, float, or array, optional

SNR values for the defined sources, only used if snr_mode is set to 'local'. Can be None (no adjustment of SNR), a single value that is used for all sources or an array with one SNR value per source.

stdfloat, array, or SourceEstimate, optional

Desired standard deviation of the source activity, provided via one of the following options:

a single value that applies to all sources
an array with one value per source
a SourceEstimate object that contains values of all vertices of the source space. In this case, the value will be adjusted for each source automatically based on its location.

location_paramsdict, optional

Keyword arguments that will be passed to location if a function is provided.

waveform_paramsdict, optional

Keyword arguments that will be passed to waveform if a function is provided.

snr_paramsdict, optional

Additional parameters required for the adjustment of SNR. Specify fmin and fmax here to define the frequency band which should used for calculating the SNR.

nameslist, optional

Returns:

nameslist: A list of (provided or autogenerated) names for each source.

set_coupling(coupling, **common_params)[source]#

Set coupling between sources that were added to the simulator.

Parameters:

couplingtuple or dict

Provide a tuple (u, v) to define one pair of coupled sources or a dictionary to define multiple coupling edges at once. u and v are the names of sources that should be coupled. Both sources should be added to the simulation prior to setting the coupling.

If used, the dictionary should contain tuples (u, v) as keys, while the values should be dictionaries with keyword arguments of the coupling method. Use this dictionary to define coupling parameters that are specific for a given edge. Such definitions will also override the common parameters (described below).

**common_paramsdict, optional

Additional coupling parameters that apply to each edge defined in the coupling dictionary or the single edge if a tuple was provided.

Notes

For the information on required coupling parameters, please refer to the documentation of the corresponding coupling method(s).

Examples

Adding a single connectivity edge:

>>> from meegsim.coupling import ppc_von_mises
...
... sim.set_coupling(('s1', 's2'), method=ppc_von_mises,
...                  kappa=1, phase_lag=0, fmin=8, fmax=12)

Adding multiple connectivity edges at once:

>>> from meegsim.coupling import ppc_von_mises
...
... sim.set_coupling(coupling={
...     ('s1', 's2'): dict(kappa=1, phase_lag=np.pi/3, fmin=10),
...     ('s2', 's3'): dict(kappa=0.5, phase_lag=-np.pi/6)
... }, method=ppc_von_mises, fmin=8, fmax=12)

In the example above, method and fmax values apply to both coupling edges, while kappa and phase_lag are edge-specific. fmin is defined as a common parameter but also has a different value for the edge ('s1', 's2'). Therefore, it will be set to 6 for the edge ('s1', 's2') and to 8 for the edge ('s2', 's3').

simulate(sfreq, duration, fwd=None, snr_global=None, snr_params={}, random_state=None)[source]#

Simulate a configuration of defined sources.

Parameters:

sfreqfloat: The sampling frequency of the simulated data, in Hz.
durationfloat: Duration of the simulated data, in seconds.
fwdNone or Forward, optional: The forward model, only to be used for the adjustment of SNR. If no adjustment is performed, the forward model is not required.
snr_globalfloat or None, optional: The value of global SNR, only used if the snr_mode is set to 'global'. If None (default), no adjustment of global SNR is performed.
snr_paramsdict, optional: Additional parameters required for the adjustment of global SNR. Specify fmin and fmax here to define the frequency band which should used for calculating the SNR.
random_stateint or None, optional: The random state can be provided to obtain reproducible configurations. If None (default), the simulated data will differ between function calls.

Returns: