NeuroElf wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== alphasim - extended uses ======

===== Motivation =====
Under certain circumstances, the traditional way to employ alphasim does not provide the user with the appropriate cluster-level thresholds to actually correctly achieve the desired false-positive rate (of maps, FWE/Bonferroni-corrected alpha level):

  * the maps that are displayed are the result of a conjunction
  * the maps are correlations (sometimes more severe if the IV is heavily skewed)

===== Requirements =====

==== Conjunction case ====
In case of a conjunction analysis, alphasim currently assumes that the terms entering the contrast themselves are valid statistics (their overall false-positive rate behaves as specified) and are independent (e.g. orthogonal contrasts from separate conditions or groups of subjects).

==== Correlation case ====
To simulate the outcome of a specific correlation, both the maps used (e.g. per-subject contrast maps) and the regressor (independent variable, e.g. behavioral measure with one value per subject, such as a questionnaire score) must be given.

Alternatively, if only the maps are specified, alphasim generates random (normally distributed) regressors, which then tests whether any skewing in the contrast maps leads to increased (or decreased) levels of false positives and thus larger (or smaller) cluster-level thresholds.

===== Function help =====
<code>alphasim  - simulate noise data to estimate cluster threshold

FORMAT:       [at = ] alphasim(ddim [, opts])

Input fields:

      ddim        data dimension (1x3 integer values)
      opts        optional settings
      .clconn     connectivity of clusters, ('face', {'edge'}, 'vertex')
      .conj       conjunction simulation (1x1 double, number of maps)
      .fftconv    boolean flag, use FFT convolution (default: false)
      .fwhm       FWHM kernel sizes (default: [2, 2, 2])
      .mask       boolean mask (size must be == ddim!, default: none)
      .niter      number of iterations, default: 1000
      .pbar       either xprogress or xfigure:XProgress object
      .regmaps    regression maps (e.g. betas, contrasts)
      .regmodel   regression model (all-1s column will be complemented)
      .regrank    rank-transform data before useing regression
      .srf        optional surface (perform surface-based simulation)
      .srfsmp     surface sampling (from, step, to, along normals,
                  default: [-3, 1, 1])
      .srftrf     transformation required to sample surface coordinates
                  derived from bvcoordconv
      .thr        applied (raw) threshold(s), default: p<0.001

Output fields:

      at          optional output table

Note: other than AFNI's AlphaSim, the data is considered to be
      iso-voxel for the default kernel, but that can be altered
      accordingly by changing the kernel!

      to simulate specific regression results, both options, .regmaps
      .regmodel must be set; if only .regmaps is given, random numbers
      (using randn) will be generated instead of permuting the predictor</code>

===== Usage examples =====
==== Conjunction case ====
In this example, we assume that the map to be cluster-level thresholded is the result of the conjunction of two independent t-statistics. Further settings

  * map is 52-by-50-by-62 voxels in size
  * functional resolution is 3mm (iso-voxel)
  * smoothing of the underlying maps was 8mm -> kernel in functional resolution is 8/3 voxel!
  * we hope for very few maps with large clusters, thus we increase the number of iterations
  * alphasim supports settings several threshold (by rescaling the simulated maps)

<code matlab>asim_options = struct( ...
    'conj',  2, ...
    'fwhm',  [8/3, 8/3, 8/3], ...
    'niter', 2500, ...
    'thr',   [0.05, 0.02, 0.01, 0.005, 0.002, 0.001]);
alphasim([52, 50, 62], asim_options);</code>

==== Correlation case ====
=== Only maps are given ===
Following the example above, we simply use a different set of options:

  * maps are given (see [[glm.RFX_conmaps]] for how to obtain those from a RFX-GLM)
  * mask is derived from those maps

<code matlab>asim_cons = glm.RFX_conmaps([0, 1, 0, -1, 0]);
asim_mask = any(asim_cons ~= 0, 4); % this masks voxels for which all subjects have a 0-value
asim_options = struct( ...
    'fwhm',    [8/3, 8/3, 8/3],  ...
    'mask',    any(asim_cons ~= 0, 4), ...
    'niter',   2500, ...
    'regmaps', asim_mask, ...
    'thr',     [0.005, 0.002, 0.001]);
alphasim(size(asim_mask), asim_options);</code>

This will simulate a normally distributed regressor.

=== Maps and regressor are given ===
In addition to the above example, a regressor can be set in asim_options, in which case a permutation-based simulation is performed:

<code matlab>asim_options.regmodel = ...
    [0.25; 0.61; 1.24; -0.07; 0.91; 1.41; 3.11; -0.12; 0.77; 0.49; 0.8; 0.04];
alphasim(size(asim_mask), asim_options);</code>

===== Sample output =====
In the conjunction case, this is the sample output (using only 100 iterations, taking 94 seconds on my MacBook Pro...):

<code>Uncorrected threshold: p<0.050000
------------------------------------------------------------
 Cl Size  Frequency  CumProbCl  p / Voxel  MaxFreq   Alpha 
       1       6367  0.4037925  0.0500000         0  1.00000
       2       3248  0.6097793  0.0435410         0  1.00000
       3       1817  0.7250127  0.0369512         0  1.00000
       4       1161  0.7986428  0.0314214         0  1.00000
       5        804  0.8496322  0.0267104         0  1.00000
       6        602  0.8878108  0.0226323         0  1.00000
       7        411  0.9138762  0.0189681         0  1.00000
       8        290  0.9322679  0.0160495         0  1.00000
       9        233  0.9470446  0.0136960         0  1.00000
      10        207  0.9601725  0.0115687         0  1.00000
      11        137  0.9688610  0.0094688         0  1.00000
      12        105  0.9755200  0.0079401         0  1.00000
      13         86  0.9809741  0.0066619         4  1.00000
      14         59  0.9847159  0.0055277         3  0.96000
      15         46  0.9876332  0.0046898         5  0.93000
      16         35  0.9898529  0.0039898         6  0.88000
      17         41  0.9924531  0.0034217        10  0.82000
      18         20  0.9937215  0.0027147         8  0.72000
      19         19  0.9949264  0.0023495         7  0.64000
      20         19  0.9961314  0.0019832         8  0.57000
      21         10  0.9967656  0.0015978         7  0.49000
      22          8  0.9972730  0.0013847         4  0.42000
      23          7  0.9977169  0.0012062         5  0.38000
      24          4  0.9979706  0.0010429         4  0.33000
      25          6  0.9983511  0.0009455         6  0.29000
      26          8  0.9988584  0.0007933         8  0.23000
      27          2  0.9989853  0.0005823         2  0.15000
      28          4  0.9992390  0.0005275         3  0.13000
      29          1  0.9993024  0.0004139         0  0.10000
      30          1  0.9993658  0.0003845         1  0.10000
      32          1  0.9994292  0.0003540         0  0.09000
      33          3  0.9996195  0.0003216         3  0.09000
      34          1  0.9996829  0.0002211         1  0.06000
      35          1  0.9997463  0.0001867         1  0.05000
      36          2  0.9998732  0.0001512         2  0.04000
      37          1  0.9999366  0.0000781         1  0.02000
      40          1  1.0000000  0.0000406         1  0.01000

 
Uncorrected threshold: p<0.020000
------------------------------------------------------------
 Cl Size  Frequency  CumProbCl  p / Voxel  MaxFreq   Alpha 
       1       2363  0.4895380  0.0200000         0  1.00000
       2       1073  0.7118293  0.0157331         0  1.00000
       3        542  0.8241144  0.0118581         0  1.00000
       4        331  0.8926870  0.0089220         0  1.00000
       5        186  0.9312202  0.0065312         2  1.00000
       6        115  0.9550445  0.0048519        10  0.98000
       7         67  0.9689248  0.0036060         6  0.88000
       8         55  0.9803190  0.0027591        18  0.82000
       9         19  0.9842552  0.0019646        11  0.64000
      10         24  0.9892273  0.0016558        17  0.53000
      11         19  0.9931635  0.0012225         8  0.36000
      12         10  0.9952351  0.0008451         6  0.28000
      13          5  0.9962710  0.0006284         4  0.22000
      14          8  0.9979283  0.0005110         8  0.18000
      16          4  0.9987570  0.0003088         4  0.10000
      17          2  0.9991713  0.0001932         2  0.06000
      18          3  0.9997928  0.0001318         3  0.04000
      19          1  1.0000000  0.0000343         1  0.01000

 
Uncorrected threshold: p<0.010000
------------------------------------------------------------
 Cl Size  Frequency  CumProbCl  p / Voxel  MaxFreq   Alpha 
       1       1176  0.5613365  0.0100000         0  1.00000
       2        480  0.7904535  0.0070754         2  1.00000
       3        199  0.8854415  0.0046879         6  0.98000
       4        103  0.9346062  0.0032032        16  0.92000
       5         51  0.9589499  0.0021786        14  0.76000
       6         45  0.9804296  0.0015444        26  0.62000
       7         17  0.9885442  0.0008729        13  0.36000
       8          9  0.9928401  0.0005770         8  0.23000
       9          5  0.9952267  0.0003979         5  0.15000
      10          4  0.9971360  0.0002860         4  0.10000
      11          2  0.9980907  0.0001865         2  0.06000
      13          3  0.9995227  0.0001318         3  0.04000
      14          1  1.0000000  0.0000348         1  0.01000

 
Uncorrected threshold: p<0.005000
------------------------------------------------------------
 Cl Size  Frequency  CumProbCl  p / Voxel  MaxFreq   Alpha 
       1        508  0.5805714  0.0050000         5  1.00000
       2        212  0.8228571  0.0033388        19  0.95000
       3         90  0.9257143  0.0019523        32  0.76000
       4         27  0.9565714  0.0010693        10  0.44000
       5         22  0.9817143  0.0007162        18  0.34000
       6         10  0.9931429  0.0003564        10  0.16000
       7          2  0.9954286  0.0001602         2  0.06000
       8          1  0.9965714  0.0001145         1  0.04000
       9          3  1.0000000  0.0000883         3  0.03000

 
Uncorrected threshold: p<0.002000
------------------------------------------------------------
 Cl Size  Frequency  CumProbCl  p / Voxel  MaxFreq   Alpha 
       1        196  0.6555184  0.0020000        40  1.00000
       2         66  0.8762542  0.0011588        31  0.60000
       3         24  0.9565217  0.0005923        17  0.29000
       4          7  0.9799331  0.0002833         6  0.12000
       5          2  0.9866221  0.0001631         2  0.06000
       6          1  0.9899666  0.0001202         1  0.04000
       7          2  0.9966555  0.0000944         2  0.03000
       8          1  1.0000000  0.0000343         1  0.01000

 
Uncorrected threshold: p<0.001000
------------------------------------------------------------
 Cl Size  Frequency  CumProbCl  p / Voxel  MaxFreq   Alpha 
       1         81  0.6750000  0.0010000        68  1.00000
       2         28  0.9083333  0.0005424        21  0.32000
       3          7  0.9666667  0.0002260         7  0.11000
       4          2  0.9833333  0.0001073         2  0.04000
       5          1  0.9916667  0.0000621         1  0.02000
       6          1  1.0000000  0.0000339         1  0.01000</code>