frites.simulations.sim_ground_truth#

frites.simulations.sim_ground_truth(n_subjects, n_epochs, gtype='tri', perc=100, p_pos=1.0, gt_as_cov=False, gt_only=False, random_state=None, verbose=None)[source]#

Spatio-temporal ground truth simulation.

This function can be used to simulate the data coming from multiple subjects with specific ground-truth arrays with clusters distributed over time ad space. This function typically returned two outputs :

  • The simulated data (i.e. the brain data and a continuous external variable)

  • The ground-truth array which specify where the effects are and the strength of the effects

The outputs of this function can be used to compare different statistical models and methods for correcting for multiple comparisons.

Parameters
n_subjects, n_epochspython:int

Number of subjects and trials

gtype{‘tri’, ‘tri_r’, ‘diffuse’, ‘focal’}

Ground-truth type. Choose either :

  • ‘tri’ or ‘tri_r’ : spatially diffuse effects

  • ‘diffuse’ : weak effect spatially diffuse

  • ‘focal’ : strong and spatially focalized effect

percpython:int | 100

Percentage of subjects having the effect (equivalent to inter-subject consistency). For example, if n_subjects=10 and perc is 80%, 8 subjects out of the 10 will have the effect. This parameters can be useful to investigate how many subjects are necessary to retrieve the effect.

p_pospython:float | 1.

Proportion of positive correlation. A value of 1 indicates that all of the subjects have positive correlations between the simulated brain data and the regressor. Conversely, a value of 0. indicates that all of the subjects have negative correlations. In between, for example with a value 0.5 indicates that half of the subjects will have positive correlations and the other half, negative correlations.

gt_as_covbool | python:False

Specify whether the returned ground-truth array should contained boolean values indicating whether there is an effect or not at a specific time-space bin (False). If True, the ground-truth array will contained the values used for covariance.

gt_onlybool | python:False

Specify whether only the ground-truth should be returned

random_statepython:int | python:None

Fix the random state of the machine. This parameter can be useful for having reproducible results. If None, the seed is randomly picked.

Returns
dapython:list

List containing the simulated data coming from multiple subjects. Each element of the list represents a single subject of shape (n_epoch, n_roi, n_times). This argument is returned if gt_only is set to False.

gtnumpy:array_like

Ground-truth array of shape (n_roi, n_times)

Examples using frites.simulations.sim_ground_truth#

Generate spatio-temporal ground-truths

Generate spatio-temporal ground-truths