Data Simulation

class sails.simulate.AbstractSigGen(extraargs=None)

Abstract base class for signal generation

generate_signal(meg_reader)

Generate a custom signal for embedding in a dataset

Parameters:meg_reader – MEG data for which to generate signal Returns:numpy array of shape (samples). Note that samples must be equal to the value of meg_reader.num_samples Return type:type

get_num_sources()

Helper function for returning number of sources in simulation.

This is typically overloaded when defining a signal generator class.

Returns:type – Number of sources in simulated signal. If not override, returns 1 Return type:int

parse_arguments(extraargs)

Helper function for processing extra-arguments passed to a signal-generator.

Currently only looks for snr_dB for noise levels but can be overloaded by a specific class to processes more arguments.

Parameters:extraargs (dict) – keyword arguments passed to signal generator.

class sails.simulate.AbstractLagSigGen(extraargs=None)

Generic class for making lagged signals

generate_basesignal(nsamples)

Function defining the starting signal which will be lagged throughout the network

This is an abstracted function and should be overloaded when creating a new class.

Parameters:nsamples (int) – The number of samples to generate

generate_noise(nsamples)

Function defining the additive noise added at each lag

Parameters:nsamples (int) – The number of samples to generate Returns:A vector of white noise Return type:ndarray

generate_signal(sample_rate=None, num_samples=None, noise_dB=None)

Method for generating a set of time courses based on either the structure of a meg_reader object or passed parameters and the self.generate_parameters method defined in this class

Returns a timeseries of dimension [samples x signals]

Parameters:

• sample_rate (float) – The sample rate to generate the signal at (Default value = None)
• num_samples – The number of samples to generate (Default value = None)
• noise_dB (float) – Noise level of the additive noise (Default value = None)

Returns:

A simulated time-series [nchannels x nsamples x nrealisations]

Return type:

ndarray

get_lags()

Method returning the lagging of the signal through the system. Should

Returns:dimension refers to the source node and the second dimension the target node. Each non-zero value indicates that the signal in the first dimension will be added into the signal in the second dimension at the specified weight. Return type:type

get_num_sources()

parse_arguments(extraargs)

Helper function for processing extra-arguments passed to a signal-generator.

Currently only looks for snr_dB for noise levels but can be overloaded by a specific class to processes more arguments.

Parameters:extraargs (dict) – keyword arguments passed to signal generator.

class sails.simulate.AbstractMVARSigGen(extraargs=None)

Generic class for making MVAR signals

check_stability()

Checks the stability of the parameter matrix by the magnitude of the largest eigenvalue of the first lag in the parameter matrix (see [Lutkephol2006] chapter 1)

Returns:The stability index of the simulated signal Return type:float

Notes

The stability index of a simulation should be strictly less than 1. If this exceeds 1 then the simulated signal is likely to tend to infinity or zero.

generate_model()

Returns a LinearModel containing containing the true model parameters.

generate_parameters()

Method to generate the parameters of the MVAR system. Should return a [nsignals x nsignals x nlags] parameter matrix in which the first dimension refers to the source node and the second dimension the target node

This is an abstract method and should be overloaded when creating a specific class.

generate_signal(sample_rate=None, num_samples=None, noise_dB=None, num_realisations=1)

Method for generating a set of time courses based on either the structure of a meg_reader object or passed parameters and the self.generate_parameters method defined in this class

Returns a timeseries of dimension [nchannels x nsamples x nrealisations]

Parameters:

• sample_rate (float) – The sample rate of the simulated data (Default value = None)
• num_samples (int) – The number of samples to generate (Default value = None)
• noise_dB (float) – The level of additive noise to add to the simulationo (Default value = None)
• num_realisations (int) – Number of realisations to generate (Default value = 1)

Returns:

The simulated dataset of size [nchannels x nsamples x nrealisations]

Return type:

ndarray

get_num_sources()

parse_arguments(extraargs)

Helper function for processing extra-arguments passed to a signal-generator.

Currently only looks for snr_dB for noise levels but can be overloaded by a specific class to processes more arguments.

Parameters:extraargs (dict) – keyword arguments passed to signal generator.

class sails.simulate.Baccala2001_fig1(extraargs=None)

This class implements [Baccala2001] figure 1.

generate_parameters()

Create the autoregressive parameters for [Baccala2001] figure 1.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Baccala2001_fig2(extraargs=None)

This class implements [Baccala2001] figure 2.

generate_parameters()

Create the autoregressive parameters for [Baccala2001] figure 2.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Baccala2001_fig3(extraargs=None)

This class implements [Baccala2001] figure 3.

generate_parameters()

Create the autoregressive parameters for [Baccala2001] figure 3.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Baccala2001_fig4(extraargs=None)

This class implements [Baccala2001] figure 4.

generate_parameters()

Create the autoregressive parameters for [Baccala2001] figure 4.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Baccala2001_fig5(extraargs=None)

This class implements [Baccala2001] figure 5.

generate_parameters()

Create the autoregressive parameters for [Baccala2001] figure 5.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Fasoula2013_eqn26(extraargs=None)

This class implements [Fasoula2013] equation 26.

generate_parameters()

Create the autoregressive parameters for [Fasoula2013] eqn 26.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Schelter2006_fig1(extraargs=None)

This class implements [Schelter2006] figure 1.

generate_parameters()

Create the autoregressive parameters for [Schelter2006] fig 1.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.PascualMarqui2014_fig3(extraargs=None)

This class implements [Pascual-Marqui2014] figure 3.

generate_parameters()

Create the autoregressive parameters for [Pascual-Marqui2014] fig 3.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.Korzeniewska2003Lag(extraargs=None)

Generate realisations of the time-lagged network defined in [Korzeniewska2003] figure 1.

generate_basesignal(nsamples)

Generate oscillatory signal to be propagated through the network. This creates a single resonance at one-half of the Nyquist frequency via direct pole placement.

Note: the original base-signal in the paper is a realisation from an AR model. I couldn’t find the parameters for this mode, so use pole placement here. The spectral profile will be different to the paper, but the connectivity patterns are the same.

Parameters:nsamples (int) – The number of samples to generate Returns:Vector containing generated base signal. Return type:ndarray

get_lags()

Return the lagged influences between time-series in the simulated defined in [Korzeniewska2003] figure 1.

get_num_sources()

Return the number of sources in the simulation

class sails.simulate.SailsTutorialExample(extraargs=None)

generate_basesignal(f, r, sample_rate, num_samples)

Generate a simple signal by pole placement

Parameters:

• f (float) – The peak frequency of the resonance to simulate
• r (float ( 0 < r < 1 )) – The pole magnitude of the resonance to simulate
• sample_rate (float) – The sample rate to generate data at
• num_samples (int) – The number of data samples to generate

Returns:

A vector containing a simulated resonance

Return type:

ndarray

Notes

The parameter r controls both the sharpness and magnitude of the generated resonance. Values close to 1 will generate exponentially sharper and larger peaks.

generate_signal(f1, f2, sample_rate, num_samples, noise_dB=None, num_realisations=1, magnitude_noise=0.02)

Method for generating a set of time courses based on either the structure of a meg_reader object or passed parameters and the self.generate_parameters method defined in this class

Returns a timeseries of dimension [samples x signals x realisations]

Parameters:

• f1 (float) – The frequency of the first signal
• f2 (float) – The frequency of the second signal
• sample_rate (float) – The sample rate of the simulated signal
• num_samples (int) – The number of samples to simulate
• num_realisations (int) – The number of realisations to simulate (Default value = 1)
• magnitude_noise (float) – The variance of additive white noise (Default value = .02)

Returns:

The simulated signal of size [nchannels x num_samples x num_realisations]

Return type:

ndarray

get_connection_weights(form='vector')

Define the connectivity within the simulated system.

Parameters:form ({'vector' || 'matrix'}) – Which form of to return the connections is (Default value = ‘vector’) Returns:

• weight1 – vector or matrix defining connectivity for resonance 1
• weight2 – vector or matrix defining connectivity for resonance 2

get_num_sources()

Return the number of sources in the simulation