AFNI program: 3dLMEr

Output of -help



             ================== Welcome to 3dLMEr ==================
       Program for Voxelwise Linear Mixed-Effects (LME) Analysis
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Version 0.0.6, Aug 15, 2020
Author: Gang Chen (gangchen@mail.nih.gov)
Website - https://afni.nimh.nih.gov/gangchen_homepage
SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA
#+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Introduction
------

 Linear Mixed-Effects (LME) analysis adopts the traditional approach that
 differentiates two types of effects: fixed effects capture the population-
 level components while random effects characterize the lower-level components
 such as subjects, families, scanning sites, etc.

 3dLMEr is a revised and advanced version of its older brother 3dLME in the sense
 that the former is much more flexible in specifying the random-effects components
 than the latter. Also, 3dLMEr uses the R package 'lme4' while 3dLME was written
 with the R package 'nlme', and the statistic values for main effects and
 interactions are approximated with the Satterthwaite's approach. The greater
 flexibility of 3dLMEr lies in its adoption of random-effects notations by the R
 package 'lme4', as nicely summarized in the following table:

 http://afni.nimh.nih.gov/sscc/staff/gangc/pub/lmerNotations.pdf
 (adopted from https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html)

 Similar to 3dLME, all the main effects and interactions are automatically available
 in the output while simple effects that tease apart those main effects and
 interactions would have to be requested through options -gltCode or -glfCode. Also,
 the 3dLMEr interface is largely similar to 3dLME except

 1) the random-effects components are incorporated as part of the model
 specification, and thus the user is fully responsible in properly formulating the
 model structure through '-model ...' (option -ranEeff in 3dLME is no longer
 necessary for 3dLMEr);

 2) the specifications for simple and composite effects through -gltCode and
 -glfCode are slightly simplified (the label for each effect is part of -gltCode
 and -glfCode, and no more -gltLabel is needed); and

 3) all the statistic values for simple effects (specified by the user through -gltCode
 and -glfCode) are stored in the output as Z-statistic while main effects, interactions
 and the composite effects (automatically generated by 3dLMEr) are represented in the
 output as chi-square with 2 degrees of freedom. The fixed number of DFs (i.e., 2) for
 the chi-square statistic, regardless of the specific situation, is adopted for
 convenience because of the varying DFs due to the Satterthwaite approximation.

 If you want to cite the analysis approach, use the following reference:

 Chen, G., Saad, Z.S., Britton, J.C., Pine, D.S., Cox, R.W. (2013). Linear
 Mixed-Effects Modeling Approach to FMRI Group Analysis. NeuroImage 73:176-190.
 http://dx.doi.org/10.1016/j.neuroimage.2013.01.047

 Input files can be in AFNI, NIfTI, surface (niml.dset) or 1D format. To obtain
 the output int the same format of the input, append a proper suffix to the
 output specification option -prefix (e.g., .nii, .niml.dset or .1D for NIfTI,
 surface or 1D).

 3dLMEr allows for the incorporation of various types of explanatory variables
 including categorical (between- and within-subject factors) and
 quantitative variables (e.g., age, behavioral data). The burden of properly
 specifying the structure of lower-level effects is placed on the user's
 shoulder, so familiarize yourself with the following FAQ in case you want some
 clarifications: https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html

 Whenever a quantitative variable is involved, it is required to explicitly
 declare the variable through option -qVars. In addition, be mindful about the
 centering issue of each quantitive quantitative variable: you have to decide
 which makes more sense in the research context - global centering or within-
 condition (or within-group) centering? Here is some background and discussion
 about the issue:
 https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/center.html

 The following exemplifying scripts are good demonstrations. More examples will
 be added in the future if I could crowdsource more scenarios from the users
 (including you the reader). In case you find one example similar to your data
 structure, use the example(s) as a template and then build up your own script.

 In addition to R installation, the following R packages need to be installed
 first before running 3dLMEr: "lmerTest", "phia" and "snow". To install these R
 packages, run the following command at the terminal:

 rPkgsInstall -pkgs "lmerTest,phia,snow"

 Alternatively you may install them in R:

 install.packages("lmerTest")
 install.packages("phia")
 install.packages("snow")

 Once the 3dLMEr command script is constructed, it can be run by copying and
 pasting to the terminal. Alternatively (and probably better) you save the
 script as a text file, for example, called LME.txt, and execute it with the
 following (assuming on tc shell),

 nohup tcsh -x LME.txt &

 or,

 nohup tcsh -x LME.txt > diary.txt &

 or,

 nohup tcsh -x LME.txt |& tee diary.txt &

 The advantage of the latter commands is that the progression is saved into
 the text file diary.txt and, if anything goes awry, can be examined later.

Example 1 --- Simplest case: LME analysis for one group of subjects each of
  which has three effects associated with three emotions (pos, neg and neu),
  and the effects of interest are the comparisons among the three emotions
  at the populaton level (missing data allowed). This data structure is usually
  considered as one-way repeated-measures (or within-subject) ANOVA if no
  missing data occurred. The LME model is typically formulated with a random
  intercept in this case. With the option -bounds, values beyond [-2, 2] will
  be treated as outliers and considered as missing. If you want to set a range, 
  choose the bounds that make sense with your input data. 

-------------------------------------------------------------------------
    3dLMEr -prefix LME -jobs 12                                     \
         -mask myMask+tlrc                                          \
          -model  'emotion+(1|Subj)'                                \
          -bounds  -2 2                                             \
          -gltCode pos      'emotion : 1*pos'                       \
          -gltCode neg      'emotion : 1*neg'                       \
          -gltCode neu      'emotion : 1*neu'                       \
          -gltCode pos-neg  'emotion : 1*pos -1*neg'                \
          -gltCode pos-neu  'emotion : 1*pos -1*neu'                \
          -gltCode neg-neu  'emotion : 1*neg -1*neu'                \
          -gltCode em-eff1  'emotion : 0.5*pos +0.5*neg -1*neu'     \
          -glfCode em-eff2  'emotion : 1*pos -1*neg & 1*pos -1*neu' \
          -dataTable                              \
          Subj emotion  InputFile                   \
          s1    pos     s1_pos+tlrc               \
          s1    neg     s1_neg+tlrc               \
          s1    neu     s1_neu+tlrc               \
          s2    pos     s2_pos+tlrc               \
          s2    neg     s2_neg+tlrc               \
          s2    pos     s2_neu+tlrc               \
          ...
          s20   pos     s20_pos+tlrc              \
          s20   neg     s20_neg+tlrc              \
          s20   neu     s20_neu+tlrc              \
          ...
   

Example 2 --- LME analysis for one group of subjects each of  which has
  three effects associated with three emotions (pos, neg and neu), and the
  effects of interest are the comparisons among the three emotions  at the
  population level. In addition, reaction time (RT) is available per emotion
  from each subject. An LME model can be formulated to include both random
  intercept and random slope. Be careful about the centering issue about any 
  quantitative variable: you have to decide which makes more sense - global
  centering or within-condition (or within-group) centering?

-------------------------------------------------------------------------
    3dLMEr -prefix LME -jobs 12                   \
          -mask myMask+tlrc                       \
          -model  'emotion*RT+(RT|Subj)'          \
          -bounds -2 2                            \
          -qVars  'RT'                            \
          -qVarCenters 0                          \
          -gltCode pos      'emotion : 1*pos'                       \
          -gltCode neg      'emotion : 1*neg'                       \
          -gltCode neu      'emotion : 1*neu'                       \
          -gltCode pos-neg  'emotion : 1*pos -1*neg'                \
          -gltCode pos-neu  'emotion : 1*pos -1*neu'                \
          -gltCode neg-neu  'emotion : 1*neg -1*neu'                \
          -gltCode em-eff1  'emotion : 0.5*pos +0.5*neg -1*neu'     \
          -glfCode em-eff2  'emotion : 1*pos -1*neg & 1*pos -1*neu' \
          -dataTable                              \
          Subj emotion  RT  InputFile             \
          s1    pos     23   s1_pos+tlrc          \
          s1    neg     34   s1_neg+tlrc          \
          s1    neu     28   s1_neu+tlrc          \
          s2    pos     31   s2_pos+tlrc          \
          s2    neg     22   s2_neg+tlrc          \
          s2    pos     29   s2_neu+tlrc          \
          ...   
          s20   pos     12   s20_pos+tlrc         \
          s20   neg     20   s20_neg+tlrc         \
          s20   neu     30   s20_neu+tlrc         \
          ...
   

Example 3 --- LME analysis for one group of subjects each of which has three
  effects associated with three emotions (pos, neg and neu), and the effects
  of interest are the comparisons among the three emotions  at the populaton
  level. As the data were acquired across 12 scanning sites,  we set up an LME
  model with a crossed random-effects structure, one for cross-subjects and one
  for cross-sites variability.

-------------------------------------------------------------------------
    3dLMEr -prefix LME -jobs 12                       \
          -mask myMask+tlrc                           \
          -model  'emotion+(1|Subj)+(1|site)'         \
          -bounds -2 2                                \
          -gltCode pos      'emotion : 1*pos'                       \
          -gltCode neg      'emotion : 1*neg'                       \
          -gltCode neu      'emotion : 1*neu'                       \
          -gltCode pos-neg  'emotion : 1*pos -1*neg'                \
          -gltCode pos-neu  'emotion : 1*pos -1*neu'                \
          -gltCode neg-neu  'emotion : 1*neg -1*neu'                \
          -gltCode em-eff1  'emotion : 0.5*pos +0.5*neg -1*neu'     \
          -glfCode em-eff2  'emotion : 1*pos -1*neg & 1*pos -1*neu' \
          -dataTable                                  \
          Subj emotion  site  InputFile               \
          s1    pos     site1   s1_pos+tlrc           \
          s1    neg     site1   s1_neg+tlrc           \
          s1    neu     site2   s1_neu+tlrc           \
          s2    pos     site1   s2_pos+tlrc           \
          s2    neg     site2   s2_neg+tlrc           \
          s2    pos     site3   s2_neu+tlrc           \
          ...
          s80   pos     site12  s80_pos+tlrc          \
          s80   neg     site12  s80_neg+tlrc          \
          s80   neu     site10  s80_neu+tlrc          \
          ...
   

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

   -bounds lb ub: This option is for outlier removal. Two numbers are expected from
         the user: the lower bound (lb) and the upper bound (ub). The input data will
         be confined within [lb, ub]: any values in the input data that are beyond
         the bounds will be removed and treated as missing. Make sure the first number
         less than the second. You do not have to use this option to censor your data!

   -cio: Use AFNI's C io functions, which is the default. Alternatively -Rio
         can be used.

   -dataTable TABLE: List the data structure with a header as the first line.

         NOTE:

         1) This option has to occur last in the script; that is, no other
         options are allowed thereafter. Each line should end with a backslash
         except for the last line.

         2) The order of the columns should not matter except that the last
         column has to be the one for input files, 'InputFile'. Unlike 3dLME, the
         subject column (Subj in 3dLME) does not have to be the first column;
         and it does not have to include a subject ID column under some situations
         Each row should contain only one input file in the table of long format
         (cf. wide format) as defined in R. Input files can be in AFNI, NIfTI or
         surface format. AFNI files can be specified with sub-brick selector (square
         brackets [] within quotes) specified with a number or label.

         3) It is fine to have variables (or columns) in the table that are
         not modeled in the analysis.

         4) When the table is part of the script, a backslash is needed at the end
         of each line (except for the last line) to indicate the continuation to the
         next line. Alternatively, one can save the context of the table as a separate
         file, e.g., calling it table.txt, and then in the script specify the data
         with '-dataTable @table.txt'. However, when the table is provided as a
         separate file, do NOT put any quotes around the square brackets for each
         sub-brick,otherwise the program would not properly read the files, unlike the
         situation when quotes are required if the table is included as part of the
         script. Backslash is also not needed at the end of each line, but it would
         not cause any problem if present. This option of separating the table from
         the script is useful: (a) when there are many input files so that the program
         complains with an 'Arg list too long' error; (b) when you want to try
         different models with the same dataset.

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

   -glfCode label CODING: Specify a general linear F-style (GLF) formulation
         with the weights among factor levels in which two or more null
         relationships (e.g., A-B=0 and B-C=0) are innvolved. The symbolic
         coding has to be within (single or double) quotes. For example, the
         coding '-glfCode AvBvc 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos''
         examines the main effect of Condition at the positive Emotion with
         the output labeled as AvBvC. Similarly the coding '-glfCode CondByEmo'
         'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos -1*neg' looks
         for the interaction between the three levels of Condition and the
         two levels of Emotion and the resulting sub-brick is labeled as
         'CondByEmo'.

         NOTE:

         1) The weights for a variable do not have to add up to 0.

         2) When a quantitative variable is present, other effects are
         tested at the center value of the covariate unless the covariate
         value is specified as, for example, 'Group : 1*Old Age : 2', where
         the Old Group is tested at the Age of 2 above the center.

         3)  The absence of a categorical variable in a coding means the
         levels of that factor are averaged (or collapsed) for the GLF.

         4) The appearance of a categorical variable has to be followed
         by the linear combination of its levels.

   -gltCode label weights: Specify the label and weights of interest in a general
       linear t-style (GLT) formulation in which only one null relationship is
       involved (cf. -glfCode). The weights should be surrounded with quotes. For
       example, the specification '-gltCode AvB 'Condition : 1*A -1*B' compares A
       and B with a label 'AvB' for the output sub-bricks.  

   -help: this help message

   -IF var_name: var_name is used to specify the column name that is designated for
        input files of effect estimate. The default (when this option is not invoked
        is 'InputFile', in which case the column header has to be exactly as 'InputFile'
        This input file for effect estimates has to be the last column.

   -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.

   -model FORMULA: Specify the model structure for all the variables. The
         expression FORMULA with more than one variable has to be surrounded
         within (single or double) quotes. Variable names in the formula
         should be consistent with the ones used in the header of -dataTable.
         In the LME context the simplest model is "1+(1|Subj)" in
         which the random effect from each of the two subjects in a pair is
         symmetrically incorporated in the model. Each random-effects factor is
         specified within parentheses per formula convention in R. Any
         effects of interest and confounding variables (quantitative or
         categorical variables) can be added as fixed effects without parentheses.

   -prefix PREFIX: Output file name. For AFNI format, provide prefix only,
         with no view+suffix needed. Filename for NIfTI format should have
         .nii attached (otherwise the output would be saved in AFNI format).

   -qVarCenters VALUES: Specify centering values for quantitative variables
         identified under -qVars. Multiple centers are separated by 
         commas (,) without any other characters such as spaces and should
         be surrounded within (single or double) quotes. The order of the
         values should match that of the quantitative variables in -qVars.
         Default (absence of option -qVarCenters) means centering on the
         average of the variable across ALL subjects regardless their
         grouping. If within-group centering is desirable, center the
         variable YOURSELF first before the values are fed into -dataTable.

   -qVars variable_list: Identify quantitative variables (or covariates) with
         this option. The list with more than one variable has to be
         separated with comma (,) without any other characters such as
         spaces and should be surrounded within (single or double) quotes.
         For example, -qVars "Age,IQ"
         WARNINGS:
         1) Centering a quantitative variable through -qVarsCenters is
         very critical when other fixed effects are of interest.
         2) Between-subjects covariates are generally acceptable.
         However EXTREME caution should be taken when the groups
         differ substantially in the average value of the covariate.
         

   -Rio: Use R's io functions. The alternative is -cio.

   -show_allowed_options: list of allowed options


This page auto-generated on Mon Oct 19 20:23:18 EDT 2020