AFNI program: 3dMEMA

Output of -help


Usage:
------ 
 3dMEMA is a program for performing Mixed Effects Meta Analysis at group level 
 that models both within- and across- subjects variability, thereby requiring
 both regression coefficients, or general linear contrasts among them, and the 
 corresponding t-statistics from each subject as input.  To get accurate 
 t-statistics, 3dREMLfit should be used for the linear regression (a GLS
 regression program using an ARMA(1,1) model for the noise), rather than
 3dDeconvolve.

 It's required to install R (https://www.r-project.org/), plus 'snow' package
 if parallel computing is desirable. Version 1.0.1, Dec 21, 2016. If you want to
 cite the analysis approach, use the following at this moment:

   Chen, G., Saad, Z.S., Nath, A.R., Beauchamp, M.S., Cox, R.W., 2012. 
   FMRI group analysis combining effect estimates and their variances. 
   NeuroImage 60, 747–765. https://doi.org/10.1016/j.neuroimage.2011.12.060
 
 The basic usage of 3dMEMA is to derive group effects of a condition, contrast,
 or linear combination (GLT) of multiple conditions. It can be used to analyze
 data from one, two, or multiple groups. However, if there are more than two
 groups or more than one subject-grouping variables (e.g., sex, adolescent/adults,
 genotypes, etc.) involved in the analysis, dummy coding (zeros and ones) the 
 variables as covariates is required, and extremely caution should be exercised 
 in doing so because different coding strategy may lead to different 
 interpretation. In addition, covariates (quantiative variables) can be 
 incorporated in the model, but centering and potential interactions with other 
 effects in the model should be considered. 
 
 Basically, 3dMEMA can run one-sample, two-sample, and all types of BETWEEN-SUBJECTS
 ANOVA and ANCOVA. Within-subject variables mostly cannot be modeled, but there are 
 a few exceptions. For instance, paired-test can be performed through feeding the 
 contrast of the two conditions as input. Multi-way ANOVA can be analyzed under the
 following two scenarios: 1) all factors have only two levels (e.g., 2 X 2 repeated-
 measures ANOVA) can be analyzed; or 1) there is only one within-subject (or 
 repeated-measures) factor and it contains two levels only. See more details at
 
 https://afni.nimh.nih.gov/sscc/gangc/MEMA.html

 Notice:  When comparing two groups, option "-groups groupA groupB" has to be
 present, and the output includes the difference of groupB - groupA, which is
 consistent with most AFNI convention except for 3dttest++ where groupA - groupB is
 rendered.

Example 1 --- One-sample type (one regression coefficient or general linear 
contrast from each subject in a group):
--------------------------------
      3dMEMA   -prefix ex1  \
               -jobs 4      \
               -set  happy  \
                  ac   ac+tlrc'[14]'   ac+tlrc'[15]'  \
                  ejk  ejk+tlrc'[14]'  ejk+tlrc'[15]' \
                  ...
                  ss   ss+tlrc'[14]'   ss+tlrc'[15]' \
               -max_zeros 4    \
               -model_outliers \        
               -residual_Z        

      3dMEMA   -prefix ex1  \
               -jobs 4      \
               -set  happy  \
                  ac   ac+tlrc'[happy#0_Coef]'   ac+tlrc'[happy#0_Tstat]'  \
                  ejk  ejk+tlrc'[happy#0_Coef]'  ejk+tlrc'[happy#0_Tstat]' \
                  ...
                  ss   ss+tlrc'[happy#0_Coef]'   ss+tlrc'[happy#0_Tstat]' \
               -missing_data 0  \
               -HKtest         \        
               -model_outliers \        
               -residual_Z     

Example 2 --- Two-sample type (one regression coefficient or general linear
contrast from each subject in two groups with the contrast being the 2nd group 
subtracing the 1st one), heteroskedasticity (different cross-subjects variability 
between the two groups), outlier modeling, covariates centering, no payment no 
interest till Memorial Day next year. Notice that option -groups has to be
present in this case, and the output includes the difference of the second group
versus the first one.
-------------------------------------------------------------------------
   3dMEMA   -prefix ex3  \
            -jobs 4      \
            -groups horses goats  \
            -set   healthy_horses \
                ac   ac_sad_B+tlrc.BRIK   ac_sad_T+tlrc.BRIK  \
                ejk  ejk_sad_B+tlrc.BRIK  ejk_sad_T+tlrc.BRIK \
                ...
                ss   ss_sad_B+tlrc.BRIK   ss_sad_T+tlrc.BRIK  \
            -set   healthy_goats \
                jp   jp_sad_B+tlrc.BRIK   jp_sad_T+tlrc.BRIK  \
                mb   mb_sad_B+tlrc.BRIK   mb_sad_T+tlrc.BRIK  \
                ...
                trr  trr_sad_B+tlrc.BRIK  trr_sad_T+tlrc.BRIK \
            -n_nonzero 18   \
            -HKtest         \
            -model_outliers \
            -unequal_variance \
            -residual_Z     \
            -covariates CovFile.txt \
            -covariates_center age = 25 13 weight = 100 150  \
            -covariates_model center=different slope=same   
   
   where file CovFile.txt looks something like this:  
   
      name  age  weight
      ejk   93    117
      jcp   3     34
      ss    12    200   
      ac    12    130
      jp    65    130
      mb    25    630
      trr   18    187
      delb  9     67
      tony  12    4000


Example 3 --- Paired type (difference of two regression coefficients or 
general linear contrasts from each subject in a group). One scenario of 
general linear combinations is to test linear or higher order trend at 
individual level, and then take the trend information to group level.
---------------------------------
   3dMEMA   -prefix ex2  \
            -jobs 4      \
            -missing_data happyMiss+tlrc sadMiss+tlrc \
            -set happy-sad \
                ac   ac_hap-sad_B+tlrc   ac_hap-sad_T+tlrc   \
                ejk  ejk_hap-sad_B+tlrc  ejk_hap-sad_T+tlrc  \
                ...
                ss   ss_hap-sad_B+tlrc   ss_hap-sad_T+tlrc   \
            

Options in alphabetical order:
------------------------------

   -cio: Use AFNI's C io functions

   -conditions COND1 [COND2]: Name of 1 or 2 conditions, tasks, or GLTs.
                            Default is one condition named 'c1'

   -contrast_name: (no help available)

   -covariates COVAR_FILE: Specify the name of a text file containing
                         a table for the covariate(s). Each column in the
                         file is treated as a separate covariate, and each
                         row contains the values of these covariates for
                         each subject. Option -unequal_variance may not be
                         used in the presence of covariates with two groups.
      To avoid confusion, it is best you format COVAR_FILE in this manner
      with BOTH row and column names: 
         subj  age   weight
         Jane   25   300
         Joe    22   313
         ...    ..   ...
      This way, there is no amiguity as to which values are attributed to
      which subject, nor to the label of the covariate(s). The word 'subj'
      must be the first word of the first row. You can still get at the  
      values of the columns of such a file with AFNI's 1dcat -ok_text, 
      which will treat the first row, and first column, as all 0s.
      Alternate, but less recommended ways to specify the covariates:
      (column names only)
         age   weight
         25   300
         22   313
         ..   ...
      or
      (no row and column names)
         25   300
         22   313
         ..   ...

   -covariates_center COV_1=CEN_1 [COV_2=CEN_2 ... ]: (for 1 group) 
   -covariates_center COV_1=CEN_1.A CEN_1.B [COV_2=CEN_2.A CEN_2.B ... ]: 
                                                     (for 2 groups) 
     where COV_K is the name assigned to the K-th covariate, 
     either from the header of the covariates file, or from the option
     -covariates_name. This makes clear which center belongs to which
     covariate. When two groups are used, you need to specify a center for
     each of the groups (CEN_K.A, CEN_K.B).
     Example: If you had covariates age, and weight, you would use:
            -covariates_center age = 78 55 weight = 165 198
     If you want all covariates centered about their own mean, 
     just use -covariates_center mean. Be alert: Default is mean centering!
     If no centering is desired (e.g.,the covariate values have been
     pre-centered), set the center value as 0 with -covariates_center.

   -covariates_model center=different/same slope=different/same:
          Specify whether to use the same or different intercepts
          for each of the covariates. Similarly for the slope.

   -covariates_name COV_1 [... COV_N]: Specify the name of each of the N
              covariates. This is only needed if the covariates' file 
              has no header. The default is to name the covariates
              cov1, cov2, ... 

   -dbgArgs: This option will enable R to save the parameters in a
         file called .3dMEMA.dbg.AFNI.args in the current directory
          so that debugging can be performed.

   -equal_variance: Assume same cross-subjects variability between GROUP1
                  and GROUP2 (homoskedasticity). (Default)

   -groups GROUP1 [GROUP2]: Name of 1 or 2 groups. This option must be used
                          when comparing two groups. Default is one group
                          named 'G1'. The labels here are used to name
                          the sub-bricks in the output. When there are
                          two groups, the 1st and 2nd labels here are
                          associated with the 1st and 2nd datasets
                          specified respectively through option -set,
                          and their group difference is the second group
                          minus the first one, similar to 3dttest but
                          different from 3dttest++.

   -help: this help message

   -HKtest: Perform Hartung-Knapp adjustment for the output t-statistic. 
          This approach is more robust when the number of subjects
          is small, and is generally preferred. -KHtest is the default 
          with t-statistic output.

   -jobs NJOBS: On a multi-processor machine, parallel computing will speed 
             up the program significantly.
             Choose 1 for a single-processor computer.

   -mask MASK: Process voxels inside this mask only.
             Default is no masking.

   -max_zeros MM: Do not compute statistics at any voxel that has 
                more than MM zero beta coefficients or GLTs. Voxels around
                the edges of the group brain will not have data from
                some of the subjects. Therefore, some of their beta's or
                GLTs and t-stats are masked with 0. 3dMEMA can handle
                missing data at those voxels but obviously too much
                missing data is not good. Setting -max_zeros to 0.25
                means process data only at voxels where no more than 1/4
                of the data is missing. The default value is 0 (no
                missing values allowed). MM can be a positive integer
                less than the number of subjects, or a fraction 
                between 0 and 1. Alternatively option -missing_data
                can be used to handle missing data.

   -missing_data: This option corrects for inflated statistics for the voxels where
               some subjects do not have any data available due to imperfect
               spatial alignment or other reasons. The absence of this option
               means no missing data will be assumed. Two formats of option
               setting exist as shown below.
   -missing_data 0: With this format the zero value at a voxel of each subject
                 will be interpreted as missing data.
   -missing_data File1 [File2]: Information about missing data is specified
                               with file of 1 or 2 groups (the number 1 or 2
                               and file order should be consistent with those
                               in option -groups). The voxel value of each file
                               indicates the number of sujects with missing data
                               in that group. 

   -model_outliers: Model outlier betas with a Laplace distribution of
                  of subject-specific error.
                  Default is -no_model_outliers

   -n_nonzero NN: Do not compute statistics at any voxel that has 
                less than NN non-zero beta values. This options is
                complimentary to -max_zeroes, and matches an option in
                the interactive 3dMEMA mode. NN is basically (number of
                unique subjects - MM). Alternatively option -missing_data
                can be used to handle missing data.

   -no_HKtest: Do not make the Hartung-Knapp adjustment. -KHtest is 
          the default with t-statistic output.

   -no_model_outliers: No modeling of outlier betas/GLTs (Default).

   -no_residual_Z: Do not output residuals and their  Z values (Default).

   -prefix PREFIX: Output prefix (just prefix, no view+suffix needed)

   -residual_Z: Output residuals and their Z values used in identifying
              outliers at voxel level.
              Default is -no_residual_Z

   -Rio: Use R's io functions

   -set SETNAME                         \
               SUBJ_1 BETA_DSET T_DSET \
               SUBJ_2 BETA_DSET T_DSET \
               ...   ...       ...     \
               SUBJ_N BETA_DSET T_DSET \
      Specify the data for one of two test variables (either group,
              contrast/GLTs) A & B. 
      SETNAME is the name assigned to the set, which is only for the
              user's information, and not used by the program. When
              there are two groups, the 1st and 2nd datasets are
              associated with the 1st and 2nd labels specified
              through option -set, and the group difference is
              the second group minus the first one, similar to
              3dttest but different from 3dttest++.
      SUBJ_K is the label for the subject K whose datasets will be 
             listed next
      BETA_DSET is the name of the dataset of the beta coefficient or GLT.
      T_DSET is the name of the dataset containing the Tstat 
             corresponding to BETA_DSET. 
         To specify BETA_DSET, and T_DSET, you can use the standard AFNI 
         notation, which, in addition to sub-brick indices, now allows for
         the use of sub-brick labels as selectors
      e.g: -set Placebo Jane pb05.Jane.Regression+tlrc'[face#0_Beta]'  \
                             pb05.Jane.Regression+tlrc'[face#0_Tstat]' \

   -show_allowed_options: list of allowed options

   -unequal_variance: Model cross-subjects variability difference between
                    GROUP1 and GROUP2 (heteroskedasticity). This option
                    may NOT be invoked when covariate is present in the
                    model. Default is -equal_variance (homoskedasticity).
                    This option may not be useded when covariates are
                    involved in the model.

   -verb VERB: VERB is an integer specifying verbosity level.
             0 for quiet (Default). 1 or more: talkative.

#######################################################################
Please consider citing the following if this program is useful for you:

   Chen, G., Saad, Z.S., Nath, A.R., Beauchamp, M.S., Cox, R.W., 2012. 
   FMRI group analysis combining effect estimates and their variances. 
   NeuroImage 60, 747–765. https://doi.org/10.1016/j.neuroimage.2011.12.060

#######################################################################
This page auto-generated on Tue Dec 17 06:53:08 PM EST 2024