meegsim.simulate.SourceSimulator#

class meegsim.simulate.SourceSimulator(src)[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.

Methods

`add_noise_sources`(location[, waveform, ...])	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, random_state])	Simulate a configuration of defined sources.

add_noise_sources(location, waveform=<function one_over_f_noise>, 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.
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, location_params={}, waveform_params={}, snr_params={}, extents=None, names=None)[source]#

Add patch sources to the simulation.

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).

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. 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.

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.

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, location_params={}, waveform_params={}, snr_params={}, names=None)[source]#

Add point sources to the simulation.

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(): 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. 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.
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: 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.

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, 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.
fwdmne.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.
random_stateint or None (default): The random state can be provided to obtain reproducible configurations. If None (default), the simulated data will differ between function calls.

Returns:

scSourceConfiguration: The source configuration, which contains the defined sources and their corresponding waveforms.