New program 3dLMEr for linear mixed-effects modeling

The linear mixed-effects modeling program 3dLME has been around for many years. However, one bottleneck of 3dLME has become suffocating: the limited adaptivity of random-effects specifications. A new program 3dLMEr has been just created to expand the adaptivity of 3dLME.

3dLMEr is a revised and advanced version of its elder brother 3dLME in the sense that the former is much more flexible in specifying the random-effects components than the latter. In addition, 3dLMEr uses the R package ‘lmerTest’ 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 (change the variable ‘group’ in the table to ‘subject’ in the neuroimaging context) :

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 the option -gltCode -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 lable 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 through -gltCode) are stored in the output as Z-statisc while main effects, interactions and the composite effects (specified through -gltCode) 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 not related to the real number of factor levels and is adopted simply for convenience because of the varying DFs due to the Satterthwaite approximation.

Hi Gang,

Thank you for the post, I'd like to try 3dLMEr on my pilot data.

In my study, I have three factors: a) within-subject fixed factor--modality (A vs AV); b) within-subject fixed factor--word (MLvs.VL); & c) random factor--subjects (5 subjects so far).
I am mostly interested in the interaction effect between factor a & b.
Here is what I did using 3dLMEr:

Step #1 in R:
install.packages("lmerTest")
install.packages("lme4")
install.packages("phia")
install.packages("snow")

packages were installed successfully in R

Step #2 try running the following script in tcsh:
3dLMEr -prefix group_MouthvsVoice_rh -jobs 4
-model "1"
-ICCb
-dataTable
Subj MOD WORD InputFile
RL A ML RL_rh_Loc_sm.niml.dset'[4]'
RL AV ML RL_rh_Loc_sm.niml.dset'[10]'
RL A VL RL_rh_Loc_sm.niml.dset'[1]'
RL AV VL RL_rh_Loc_sm.niml.dset'[7]'
RM A ML RM_rh_Loc_sm.niml.dset'[4]'
RM AV ML RM_rh_Loc_sm.niml.dset'[10]'
RM A VL RM_rh_Loc_sm.niml.dset'[1]'
RM AV VL RM_rh_Loc_sm.niml.dset'[7]'
RN A ML RN_rh_Loc_sm.niml.dset'[4]'
RN AV ML RN_rh_Loc_sm.niml.dset'[10]'
RN A VL RN_rh_Loc_sm.niml.dset'[1]'
RN AV VL RN_rh_Loc_sm.niml.dset'[7]'
RO A ML RO_rh_Loc_sm.niml.dset'[4]'
RO AV ML RO_rh_Loc_sm.niml.dset'[10]'
RO A VL RO_rh_Loc_sm.niml.dset'[1]'
RO AV VL RO_rh_Loc_sm.niml.dset'[7]'
RP A ML RP_rh_Loc_sm.niml.dset'[4]'
RP AV ML RP_rh_Loc_sm.niml.dset'[10]'
RP A VL RP_rh_Loc_sm.niml.dset'[1]'
RP AV VL RP_rh_Loc_sm.niml.dset'[7]'

I got the error: 3dLMEr: Command not found.
Can you help please?

Thanks,

Yue

Yue,

It seems that you have a dataset with a 2 x 2 within-subject (or repeated-measures) ANOVA structure. There are multiple ways to build a model, especially when there is no missing data.

I am mostly interested in the interaction effect between factor a & b.

  1. If you are ONLY interested in the interaction effect between the two factor, you can obtain the interaction effect for each subject, and then perform a one-sample t-test with 3dttest++.

  2. Perform a 2 x 2 ANOVA with 3dANOVA3 -type 4 or with 3dMVM

  3. If you want to use 3dLMEr, make sure you have the most recent version of AFNI. And try

3dLMEr ... -model "MOD+WORD+(1|Subj)"
(there is no option -ICCb in 3dLMEr)

Hi Gang,

Thanks for the reply.

I am still trying to run 3dLMEr, after updating to the most recent afni version, I still got the error of :
3dLMEr: Command not found.

My afni version is:
Precompiled binary macos_10.12_local: Dec 27 2019 (Version AFNI_19.3.18 ‘Nero’)

I have made sure the packages were installed in R, and I don’t know why the command is still not found.

Thanks,

Yue

This new program looks great. Just going through the documentation, a couple of notes:

  • The -formula lines in the examples appear to be missing closing quotes

  • In the documentation for the new @table syntax in the -dataTable section, item 4), there is the sentence:

    Backslash is also not needed at the end of each line, but it would cause any problem if it is present.

    Are we missing a not between ‘would’ and ‘cause’ in that sentence?

    Also it is unclear to me how this relates to the earlier sentence in that paragraph:

    Do not forget to include a backslash at the end of each row.

How are a ‘row’ and a ‘line’ different in this context?

Thanks much,
Andrew

Andrew,

Thanks a lot for reporting the issues.

The -formula lines in the examples appear to be missing closing quotes

I have fixed this in the next official release.

the documentation for the new @table syntax

I have reworded the paragraph, and hopefully it's cleaner now:

     4) When the table is part of the script, a backslash is needed at the end
     of each 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.

Thanks, that reads much clearer to me.

Best,
Andrew

Hi Gang,

It seems like the -resid option from 3dLME has been removed, or is not yet implemented, in 3dLMEr. Is there a way to get residuals from 3dLMEr? I’m asking because I would like to do multiple comparison correction on the output, by feeding residuals into 3dFWHMx -acf. Is there another way?

Thanks,
Andrew

Andrew,

First of all, many thanks for fixing those issues in 3dLME and 3dLMEr through github.

It seems like the -resid option from 3dLME has been removed

I don't recall that I ever removed the option. The option remains available in the version on my computer.

Is there a way to get residuals from 3dLMEr?

Do you still need the option in 3dLMEr if it's available in 3dLME?

Sorry, my wording was unclear – what I meant was that the ‘-resid’ option from 3dLME is not available in 3dLMEr. I noticed that the documentation for ‘-resid’ is present in 3dLMEr’s code, but is commented out – I guess I was hoping you might say, “Oh yes! I’ve already re-implemented -resid in my copy of 3dLMEr, let me just push it up to github.” :slight_smile:

Best,
Andrew

Sorry for having misread your message, Andrew!

I guess I was hoping you might say, "Oh yes! I've already re-implemented -resid in my
copy of 3dLMEr, let me just push it up to github."

Can I offer a watered-down version: my hands are tied at the moment; is it OK if I touch it up in a couple of weeks?

Haha, yes, that’s fair enough, thanks Gang. In the meantime I have used my lower-level residual files for 3dFWHMx, so I think I’m all set.

Best,
Andrew

Hello!

I’m having trouble trying to get rid of this error:

Error in if (ii < dimx) ii ← ii + 1 else if (jj < dimy) { :
missing value where TRUE/FALSE needed
Execution halted

Any help would be appreciated.

Here is the command I’m running:

3dLMEr
-prefix ${PREFIX}
-jobs ${JOBS}
-mask ${MASK}
-model ‘group+(1|Subj)’
-gltCode dyslexia ‘group : 1dyslexia’
-gltCode control 'group : 1
control’
-gltCode control-dyslexia ‘group : 1control -1dyslexia’
-dataTable
Subj group InputFile
Luke_Nih_C001 control ${FUNC_DIR}/Luke_Nih_C001/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C002 dyslexia ${FUNC_DIR}/Luke_Nih_C002/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C003 control ${FUNC_DIR}/Luke_Nih_C003/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C004 control ${FUNC_DIR}/Luke_Nih_C004/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C005 control ${FUNC_DIR}/Luke_Nih_C005/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C006 control ${FUNC_DIR}/Luke_Nih_C006/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C007 control ${FUNC_DIR}/Luke_Nih_C007/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C008 control ${FUNC_DIR}/Luke_Nih_C008/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C009 control ${FUNC_DIR}/Luke_Nih_C009/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C010 control ${FUNC_DIR}/Luke_Nih_C010/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C011 control ${FUNC_DIR}/Luke_Nih_C011/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C012 control ${FUNC_DIR}/Luke_Nih_C012/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C013 control ${FUNC_DIR}/Luke_Nih_C013/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C014 control ${FUNC_DIR}/Luke_Nih_C014/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C016 control ${FUNC_DIR}/Luke_Nih_C016/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C017 control ${FUNC_DIR}/Luke_Nih_C017/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C018 control ${FUNC_DIR}/Luke_Nih_C018/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C019 control ${FUNC_DIR}/Luke_Nih_C019/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C020 control ${FUNC_DIR}/Luke_Nih_C020/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C021 control ${FUNC_DIR}/Luke_Nih_C021/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C022 control ${FUNC_DIR}/Luke_Nih_C022/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_C023 control ${FUNC_DIR}/Luke_Nih_C023/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D001 dyslexia ${FUNC_DIR}/Luke_Nih_D001/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D003 dyslexia ${FUNC_DIR}/Luke_Nih_D003/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D006 dyslexia ${FUNC_DIR}/Luke_Nih_D006/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D007 dyslexia ${FUNC_DIR}/Luke_Nih_D007/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D008 dyslexia ${FUNC_DIR}/Luke_Nih_D008/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D009 dyslexia ${FUNC_DIR}/Luke_Nih_D009/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D010 dyslexia ${FUNC_DIR}/Luke_Nih_D010/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D011 dyslexia ${FUNC_DIR}/Luke_Nih_D011/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D012 dyslexia ${FUNC_DIR}/Luke_Nih_D012/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D013 dyslexia ${FUNC_DIR}/Luke_Nih_D013/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D014 dyslexia ${FUNC_DIR}/Luke_Nih_D014/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D015 dyslexia ${FUNC_DIR}/Luke_Nih_D015/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D016 dyslexia ${FUNC_DIR}/Luke_Nih_D016/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D017 dyslexia ${FUNC_DIR}/Luke_Nih_D017/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D018 dyslexia ${FUNC_DIR}/Luke_Nih_D018/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D019 dyslexia ${FUNC_DIR}/Luke_Nih_D019/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D020 dyslexia ${FUNC_DIR}/Luke_Nih_D020/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D021 dyslexia ${FUNC_DIR}/Luke_Nih_D021/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D022 dyslexia ${FUNC_DIR}/Luke_Nih_D022/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D023 dyslexia ${FUNC_DIR}/Luke_Nih_D023/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D025 dyslexia ${FUNC_DIR}/Luke_Nih_D025/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D026 dyslexia ${FUNC_DIR}/Luke_Nih_D026/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’
Luke_Nih_D027 dyslexia ${FUNC_DIR}/Luke_Nih_D027/predictability/predictability_blur5_ANTS_resampled+tlrc’[3]’

Thanks!
-Ben

Hi Ben, the error message is quite opaque to me. What AFNI version and OS are you running?

Hi Gang,

I am running AFNI 20.2.05 on a Linux Redhat Fedora, version 7.6. I am also running R 3.4.3.

Thanks for taking a look!

Ben, update your R and then run the following command:

afni_system_check.py -check_all

See if the R update would fix the issue.

Looks like I’m missing ‘brms’ in my installation of R. I’ll have to fix that I guess.

Here’s the whole output in case you’re curious:

-------------------------------- general ---------------------------------
architecture: 64bit ELF
system: Linux
release: 3.10.0-957.56.1.el7.x86_64
version: #1 SMP Fri Jun 19 05:28:11 EDT 2020
distribution: Red Hat Enterprise Linux Server 7.6 Maipo
number of CPUs: 40
apparent login shell: bash
shell RC file: .bashrc (exists)

--------------------- AFNI and related program tests ---------------------
which afni : /fslhome/ben88/abin/afni
afni version : Precompiled binary linux_openmp_64: Aug 4 2020
: AFNI_20.2.09 ‘Aulus Vitellius’
AFNI_version.txt : AFNI_20.2.09, linux_openmp_64, Aug 04 2020
which python : /bin/python
python version : 2.7.5
which R : /apps/r/4.0.0/gcc-9.2.0_intel-mkl-2020.0.166/bin/R
R version : R version 4.0.0 (2020-04-24) – “Arbor Day”
which tcsh : /usr/local/bin/tcsh

instances of various programs found in PATH:
afni : 1 (/zhome/ben88/abin/afni)
R : 1 (/zapps7/r/4.0.0/gcc-9.2.0_intel-mkl-2020.0.166/bin/R)
python : 1 (/usr/bin/python2.7)
python2 : 1 (/usr/bin/python2.7)
python3 : 1 (/usr/bin/python3.6)

testing ability to start various programs…
afni : success
suma : success
3dSkullStrip : success
uber_subject.py : success
3dAllineate : success
3dRSFC : success
SurfMesh : success
3dClustSim : success
3dMVM : success

checking for R packages…
rPkgsInstall -pkgs ALL -check : FAILURE

    oo Warning:
       These packages are not installed on the computer: brms!

R RHOME : /apps/r/4.0.0/gcc-9.2.0_intel-mkl-2020.0.166/lib64/R

checking for $HOME files…
.afnirc : found
.sumarc : found
.afni/help/all_progs.COMP : found

------------------------------ python libs -------------------------------
++ module loaded: PyQt4
module file : /usr/lib64/python2.7/site-packages/PyQt4/init.pyc

** failed to load module matplotlib.pyplot
– matplotlib.pyplot is not required, but is desirable

-------------------------------- env vars --------------------------------
PATH = /apps/r/4.0.0/gcc-9.2.0_intel-mkl-2020.0.166/bin:/fslhome/ben88/apps/fsl/bin:/fslhome/ben88/apps/freesurfer/bin:/fslhome/ben88/apps/freesurfer/fsfast/bin:/fslhome/ben88/apps/freesurfer/tktools:/fslhome/ben88/apps/freesurfer/mni/bin:/fslhome/ben88/apps/install/bin:/apps/lmod/lmod/libexec:/usr/lib64/qt-3.3/bin:/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/opt/dell/srvadmin/bin:/bin:/fslhome/ben88/abin:/fslhome/ben88/abin

PYTHONPATH =
R_LIBS = /fslhome/ben88/R

LD_LIBRARY_PATH =
DYLD_LIBRARY_PATH =
DYLD_FALLBACK_LIBRARY_PATH =

------------------------------ data checks -------------------------------
data dir : missing AFNI_data6
data dir : missing AFNI_demos
data dir : missing suma_demo
data dir : missing afni_handouts
atlas : found TT_N27+tlrc under /fslhome/ben88/abin

------------------------------ OS specific -------------------------------
which yum : /bin/yum
yum version : 3.4.3

========================= summary, please fix: =========================

  • just be aware: login shell ‘bash’, but our code examples use ‘tcsh’
  • missing R packages (see rPkgsInstall)
  • insufficient data for AFNI bootcamp

Ben,

You do have some issue with the R package ‘brms’. However, the 3dLMEr failure is unrelated to ‘brms’. It seems that you just have two groups of subjects. In that case, you can use 3dttest++ instead.

Hi Gang,

Thank you for your work on this. We’d like to use 3dLMEr to test functional activation differences between groups during an emotional faces task. There are three groups (ADHD-P, ADHD-D, and ADHD-NA), three emotional trial conditions (pos, neg, neut), and a few covariates we want to include in our model (age, sex, handedness, site, and co-morbidities). Basically, we want to test differences in trial-type activation between groups while controlling for the listed covariates within a specified mask. I looked through the examples in the documentation, but am uncertain about how to set up the “-model” and “-gltCode” parts of the script for our data.

Is this the right idea for how I’d set up this part of the script?

-model ‘emotion+group+(1|Subj)+(1|age)+(1|sex)+(1|handedness)+(1|site)+(1|comorbid)’

-gltCode adhd.p ‘group : 1adhd-p’
-gltCode adhd.d 'group : 1
adhd-d’
-gltCode adhd.na ‘group : 1adhd-na’
-gltCode pos 'emotion : 1
pos’
-gltCode neg ‘emotion : 1neg’
-gltCode pos 'emotion : 1
neut’ \

-gltCode adhd.p-adhd.d ‘group : 1adhd.p -1adhd.d’
-gltCode adhd.p-adhd.na ‘group : 1adhd.p -1adhd.na’
-gltCode adhd.d-adhd.na ‘group : 1adhd.d -1adhd.na’ \

I think it’s this last chunk that I’m most uncertain about. How do I introduce the three emotion conditions into each of the three group differences? Would I end up with 9 total lines for this 3x3 setup?

Huge thanks in advance for your time and help! It’s greatly appreciated.

Best,
Amar

Amar,

-model 'emotion+group+(1|Subj)+(1|age)+(1|sex)+(1|handedness)+(1|site)+(1|comorbid)'

I would try something like

-model 'emotion*group+age+sex+handedness+site+comorbid(1|Subj)'

Do you want to compare the groups at the overall average age across the three groups? 9.2. When and how to center a variable? — AFNI, SUMA and FATCAT: v24.1.02

I think it's this last chunk that I'm most uncertain about.

Is it a dot (.) or dash (-) in those three group labels?

-gltCode adhd.p-adhd.d 'group : 1adhd.p -1adhd.d'
-gltCode adhd.p-adhd.na 'group : 1adhd.p -1adhd.na'
-gltCode adhd.d-adhd.na 'group : 1adhd.d -1adhd.na' \

How do I introduce the three emotion conditions into each of the three group differences? Would I end up with 9 total lines for this 3x3 setup?

Depending on how many comparisons you want to infer, you can do something like

-gltCode adhd.p-adhd.d 'group : 1adhd.p -1adhd.d emotion : 1pos'
-gltCode adhd.p-adhd.d 'group : 1
adhd.p emotion : 1pos -1neg' \