simulate_fmri_experiment

nideconv.simulate.simulate_fmri_experiment(conditions=None, TR=1.0, n_subjects=1, n_runs=1, n_trials=40, run_duration=300, oversample=20, noise_level=1.0, n_rois=1, kernel='double_gamma', kernel_pars={})

Simulates an fMRI experiment and returns a pandas DataFrame with the resulting time series in an analysis-ready format.

By default a single run of a single subject is simulated, but a larger number of subjects, runs, and ROIs can also be simulated.

Parameters:

conditions : list of dictionaries or None

Can be used to customize different conditions. Every conditions is represented as a dictionary in this list and has the following form:

[{'name':'Condition A',
  'mu_group':1,
  'std_group':0.1},
  {'name':'Condition B',
  'mu_group':1,
  'std_group':0.1}]

mu_group indicates the mean amplitude of the response to this condition across subjects. std_group indicates the standard deviation of this amplitude across subjects.

Potentially, customized onsets can also be used as follows:

{'name':'Condition A',
 'mu_group':1,
 'std_group':0.1
 'onsets':[10, 20, 30]}

TR : float

Indicates the time between volume acquistisions in seconds (Inverse of the sample rate).

n_subjects : int

Number of subjects.

n_runs : int

Number of runs per subject.

n_trials : int

Number of trials per condition per run. Only used when no custom onsets are provided (see conditions).

run_duration : float

Duration of a single run in seconds.

noise_level : float

Standard deviation of Gaussian noise added to time series.

n_rois : int

Number of regions-of-interest. Determines the number of columns of data.

Returns:

data : DataFrame

Contains simulated time series with subj_idx, run and time (s) as index. Columns correspond to different ROIs

onsets : DataFrame

Contains used event onsets with subj_idx, run and trial type as index.

parameters : DataFrame

Contains parameters (amplitude) of the different event type.

Other Parameters:  

oversample : int

Determines how many times the kernel is oversampled before convolution. Should usually not be changed.

kernel : str

Sets which kernel to use for response function. Currently only ‘double_hrf’ can be used.

Examples

By default, simulate_fmri_experiment simulates a 5 minute run with 40 trials for one subject

>>> data, onsets, params = simulate_fmri_experiment()
>>> print(data.head())
                    area 1
subj_idx run t            
1        1   0.0 -1.280023
             1.0  0.908086
             2.0  0.850847
             3.0 -1.010475
             4.0 -0.299650
>>> print(data.onsets)
                              onset
subj_idx run trial_type
1        1   A            94.317361
             A           106.547084
             A           198.175115
             A            34.941112
             A            31.323272
>>> print(params)
                        amplitude
subj_idx trial_type
1        A                 1.0
         B                 2.0

With n_subjects we can increase the number of subjects

>>> data, onsets, params = simulate_fmri_experiment(n_subjects=20)
>>> data.index.get_level_values('subj_idx').unique()
Int64Index([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
            20],
           dtype='int64', name='subj_idx')