1 What is QDECR?

QDECR is a tool that can be used to perform surface-based vertex-wise analyses in R.

2 Requirements

In order to run QDECR you need to have several things ready:

  • A Unix system. [see 2.1]
  • Freesurfer installed. [see 2.2]
  • Your images processed through Freesurfer with the -qcache flag. [see 2.3]
  • R installed. [see 2.4]
  • A lot of other R packages that will be installed automatically. [see 2.4 or 3]
  • Make sure your target template (usually fsaverage) is in your SUBJECTS_DIR (directory with all your Freesurfer output). [see 2.5]

We also highly suggest:

  • Set FREESURFER_HOME and SUBJECTS_DIR; both can be set manually in QDECR, but it is more convenient. [see 4.1]
  • Magick++; this is required for a specific plotting function (qdecr_snap) that you may or may not need. [see 2.6]
  • Get a better BLAS library like OpenBLAS [see 2.7]

2.1 Unix

  • Unix: QDECR runs best with Unix.
  • Windows: QDECR does not work on Windows. We rely on two functions from the Freesurfer suite that require Unix/Mac, and we use one function for parallel computing that does not work in Windows. Getting QDECR to work on Windows is not a strong priority for us.
  • Mac: In theory, QDECR should also work on Mac, but we have not tested it yet.

2.2 Install Freesurfer

To install Freesurfer, follow this tutorial, but change the wget command to the most up-to-date version of Freesurfer (the tutorial downloads Freesurfer 5.3.0 which is NOT the newest version).

An error may pop up down the line. Try opening freeview on the command line:

slamballais@scs:~$ freeview
freeview.bin:  error while loading shared libraries: libpng12.so.0: cannot open shared object file: No such file or directory.

For Ubuntu 16.10 and higher this is a problem, as libpng12.so.0 does not support those. There is an easy workaround:

wget -q -O /tmp/libpng12.deb http://mirrors.kernel.org/ubuntu/pool/main/libp/libpng/libpng12-0_1.2.54-1ubuntu1_amd64.deb \
  && sudo dpkg -i /tmp/libpng12.deb \
  && rm /tmp/libpng12.deb

2.3 Run -qcache

Make sure that your subjects are run through Freesurfer with the -qcache flag, like this:

recon-all -s <subject-id> -qcache

Full instructions can be found on the Freesurfer QDEC page, under the header “pre-smoothed fsaverage surfaces”.

2.4 Install R

To install R on Ubuntu 18.04, follow this tutorial and run step 1 of this tutorial.

QDECR relies on a lot of other R packages. These will be automatically installed when you install QDECR in R (see step 1.3).

2.5 Target template in SUBJECTS_DIR

We need a target template to work with. After running recon-all, Freesurfer will make a symbolic link to fsaverage in SUBJECTS_DIR for you. However, if you imported data (e.g. if you download data) then you need to create that symbolic link yourself. This can be done easily through:

ln -sf $FREESURFER_HOME/subjects/fsaverage $SUBJECTS_DIR/

2.6 Suggestion: Magick++

Magick is a tool for image manipulation and is easy to install as described here.

For Debian/Ubuntu:

sudo apt-get install libmagick++-dev

Consequently, in R:


2.7 Suggestion: OpenBLAS

QDECR has to do a lot of linear algebra to run vertex-wise analyses. The good news is that we can speed that up by getting a better back-end library for linear algebra. You’ll have to install a BLAS library such as OpenBLAS. For Ubuntu 18.04, that would be:

sudo apt-get install libopenblas-base

More information on BLAS libraries in R can be found here.

3 Installing QDECR

First, we need to install the devtools package if it is not there yet:

if (!requireNamespace("devtools"))

Next, we have to grab the code from Github using the install_github() function:


This should also download all dependent packages! This can take a while.

Finally, we can choose to attach the package to make it easier to use:


4 Other preparations

4.1 Global variables

QDECR assumes that you have set several global variables, namely SUBJECTS_DIR and FREESURFER_HOME. This is typically done when you configure Freesurfer, as described here.

If you haven’t set the global variables yet and will use QDECR on from the command line, then you can modify your .bashrc file. The .bashrc file runs every time you open a terminal. Simply run:

echo 'export FREESURFER_HOME=/usr/local/freesurfer' >> ~/.bashrc 
echo 'source $FREESURFER_HOME/SetUpFreeSurfer.sh' >> ~/.bashrc

If you want to directly use RStudio instead (so if you do not open it from the command line), use:

echo 'export FREESURFER_HOME=/usr/local/freesurfer' >> ~/.profile
echo 'source $FREESURFER_HOME/SetUpFreeSurfer.sh' >> ~/.profile

You can check whether these variables are set by running the following R code:


If these return empty strings, we highly recommend that you set up these variables (as described here. However, QDECR also has some arguments that allow you to set them directly.


The Freesurfer output directories should all be located in the same place, ideally the path that is stored by SUBJECTS_DIR (but this is optional). As of version 0.7.0 it is not possible to run analyses on participants spread over multiple directories.

4.3 Shared memory (/dev/shm)

We highly recommend using shared memory for QDECR! As QDECR relies on file-backed matrices, we need to read and write a significant number of times to files. To avoid super slow analyses, it is advised to specify dir_tmp = /dev/shm in QDECR (see the next vignette).

[Next vignette: 2. Quick start]