Usage of the R-package Rfmrieeg

For installing the R-packageRfmrieeg, the provided version of the package source1_must

be saved to a local folder. Having launched R and having changed the working directory

to the corresponding folder (viasetwd()), the package can easily be installed using the

command:

R> install.packages("Rfmrieeg", repos=NULL, type="source")

Note that installing from source can take several minutes. If working on windows without

an installation of the Rtools collection2_{, the windows binaries in thezipformat can be}

used and installed by using:

R> install.packages("Rfmrieeg", repos=NULL)

Note that installation from a local repository requires the R-packagesRniftilib(Granert,

2012),lattice(Plummer et al., 2006) andcoda(Sarkar, 2008) to be already installed. In

a next step, the package needs to be loaded into the current R session:

R> library("Rfmrieeg")

Loading required package: coda Loading required package: lattice Loading required package: Rniftilib

To view the documentation on provided functions, e.g.RfmrieegMain_{, or the package}

itself use the help command, for example?RfmrieegMain_or?Rfmrieeg_.

The packageRfmrieeg_{provides functionality for the entire data analysis process, from}

configuring the algorithm up to MCMC diagnostics and presentation of results.

In the following, the main functionality ofRfmrieegis demonstrated with a subset of the

simulated dataset from Chapter 6.1.1 with small error noise (where an error term∗_i is a

realization fromN(0, σ_i2,∗I)). Subset images have size27×25×5. We take a time series of

200 images. This smaller dataset is part of a test suite, which can be used to test whether 1_{Current version at time of thesis publication:Rfmrieeg_1.0.tar.gz}

2_{These are tools for building R-packages on windows and are available fromhttp://cran.r-project.} org/bin/windows/Rtools/.

the software is properly installed. This test suite is provided by the author upon request and includes the following data files. The EEG data is contained in a 3D NIfTI-1 image nifti_J-RS.nii, the fMRI data is stored in a 4D NIfTI-1 imagenifti_fmrits-RS.nii and the

vector with stimulus times is contained instim-times.txt. For more details on the NIfTI-1

file format see Section 5.3.1.

The following exemplary features for carrying out an analysis are presented: (1) Config-

uring a model run using the S4Configclass, (2) running the algorithm, (3) preparing

results with S4 classResults, and (4) looking at MCMC diagnostics made available by

S4 classDiagnostics. The S4 class system was used for providing the functionality of

object-oriented programming concept within R. Each class, thereby, defines class-specific member variables characterizing their objects and according member functions, which act as the intermediaries for retrieving or modifying the member variable values to ensure data integrity. Thus, setting the values of member variables is normally done via mutator methods to control for side-effects. In the following, we denote these functions as setter functions.

After the R session has been started, the user may (1) define the absolute paths to needed data objects, which are later assigned to the configuration settings, and (2) change the

working directory to a selected folder (viasetwd()_{). If not specified otherwise, results}

outputted by the procedure are saved to the working directory by default. Depending on whether he/she is working on a unix or windows operating system, the paths have to be set in the according correct format. For instance, use

R> pathFMRI.Test <- "Z:/testsuite/nifti_fmrits-RS.nii" R> pathTimes.Test <- "Z:/testsuite/stim-times.txt" R> pathEEG.Test <- "Z:/testsuite/nifti_J-RS.nii" R> setwd("Z:/testsuite/")

when working on a windows system or

R> pathFMRI.Test <- "/home/kalus/testsuite/nifti_fmrits-RS.nii" R> pathTimes.Test <- "/home/kalus/testsuite/stim-times.txt" R> pathEEG.Test <- "/home/kalus/testsuite/nifti_J-RS.nii" R> setwd("/home/kalus/testsuite/")

when working on a unix system. In the following, we report the output from an R session that was run on a windows system. Hence, paths are printed out alike.

Setter function Relates to:

setConfig.fmri() fMRI regression stage arguments setConfig.MCMC() MCMC algorithm specific arguments setConfig.pathResults() Setting the path where a results folder

should be generated setConfig.stimCanonicalBF() or

setConfig.stimGammaBF()

Setting the HRF basis function type and related arguments

Table 5.1: Setter functions for setting arguments common to all model types.

CAR iMRF Ising

setConfig.params.CAR1() setConfig.params.iMRF1() setConfig.paramsIsing() setConfig.params.CAR2() setConfig.params.iMRF2()

setConfig.params.CAR3() setConfig.params.iMRF3() setConfig.params.CAR4() setConfig.params.iMRF4() setConfig.params.CAR5() setConfig.params.iMRF5()

Table 5.2: Setter functions for setting the algorithm type of the model run and according arguments.

As noted in the preceding section, thefmrieeg_{algorithm is run via a configuration file.}

If such a file is not at hand, the S4 classConfig_{can be used to generate one. For this, the}

class handles up to 59 arguments being employed in different model runs. The arguments

of thefmrieeg _{algorithm are hereby the member variables of the} Config_{class. We}

structured the setting of member variables by providing setter functions that subdivide

arguments with regard to content. The setter functionsetConfig.fmri(), for instance,

takes and sets arguments needed to configure solely the fMRI regression stage of the model. See Table 5.1 for an overview of setters for model parameters common to all model runs and Table 5.2 for setter of algorithm specific arguments. If an algorithm type specific setter is called, arguments are set in such a way that the corresponding algorithm is selected. Additionally, these setters take arguments relevant for the specific model type. Which set of arguments a model setter function takes can be inferred from the according help file and

Table C.3 in the Appendix. For a start, the majority offmrieeg_{arguments can be left to}

default values, so that configuring an algorithm run is straightforward. For this, initialize

a newConfig-object and specify arguments that do not have a default value (cf. Table C.1

in the Appendix). Note that warnings are printed if mandatory arguments are not yet set.

R> configObj <- new("Config")

R> configObj <- setConfig.pathResults(configObj)

(i.e. pathNifti, pathStimTimes)."

Note that this call tosetConfig.pathResults()_{sets the results path to the working}

directory. If another directory should be used, the corresponding path has to be passed via

the setter argumentpathResults. If most arguments of the fMRI predictor stage should

be kept to their defaults, only the paths to the actual data have to be specified via

R> configObj <- setConfig.fmri(configObj,pathNifti=pathFMRI.Test, + pathStimTimes=pathTimes.Test)

The setter functions listed in Table 5.2 can then be used to request the fitting of a spe- cific algorithm type as well as to set corresponding model options. If no model set-

ter function is called, RfmrieegMain fits per default an Ising model for uninformed

fMRI activation detection, which can alternatively be requested by using the function

setConfig.paramsIsing(). If another model type is asked for, the corresponding set- ter has to be used. In the following, we would like to fit a gCAR5 model for EEG-enhanced fMRI activation detection and, hence, use

configObj <- setConfig.params.CAR5(configObj,pathEEG=pathEEG.Test, + speedup=FALSE, + tauStart=2, + sigma2ProposalTau=0.25, + tau0Start=25, + sigma2ProposalTau0=3)

to set configurations alike and pass over the path to the 3D EEG image file. To improve convergency, spatial dependency hyperparameters are given non-default values. Note

that,speedup=FALSEselects a gCAR5 model instead of a fCAR5 model, which can be

chosen byspeedup=TRUE. Per default, a gCAR5 model is selected.

As a next step, we write a configuration text-file to thepathResultsdirectory (in this

example the working directory) by using the functionwriteConfig()_{. We append the}

string “_gCAR5” to the filename to indicate its use. This function returns the path to the written file, which can then be used to start the algorithm. We assign the returned string to

variablepathConfigFile.

R> pathConfigFile <- writeConfig(configObj,add2Filename="_gCAR5") [1] "Z:/testsuite/configFile_gCAR5.inp"

The algorithm is started via

R> returnObj <- RfmrieegMain(pathConfigFile)

and returns the path where all results and diagnostic objects are stored:

R> returnObj

[1] "Z:\\testsuite\\results1"

Note that R uses either “\\” or “/” as a separator since “\” is a special character.

To access the results, theResults-class of the package can be used. For using its function-

ality, a newResults-object has to be generated and initialized by passing over the path

to results (e.g. stored inreturnObj) and the configuration objectconfigObj.

R> resObj <- new("Results")

R> resObj <- initResults(resObj,returnObj=returnObj, + configObj=configObj)

The results objects stored in the results folder can easily be accessed and, for example,

an activation map can be written to the folder viacalcActivMap() _{while returning}

the path where it can be found. For plotting, it first has to be read by theRniftilib_-

function nifti.image.read() _{to be loaded again into the current R session. The}

functionplotNifti()can then be used to draw the map. The resulting plot is shown

in Figure 5.2. Note thatplotNifti()provides an option to write out a PDF of the plot.

Depending on the image dimensions and—optionally—on a calculated pleasant value

for the plotting parametermfrow resp. mfcol, width and height of the PDF are then

automatically chosen in such a way that voxels appear as proper squares. If another device type is preferred, the user can calculate optimal graphic dimensions by using function

calcDeviceHeight()_. R> activPath <- calcActivMap(resObj) R> activMap <- nifti.image.read(activPath) R> plotNifti(activMap,pdfoutput=TRUE,pdfName="gCAR5active") null device 1

results1/activMap layers: 1 2 3 4 5

Figure 5.2: Estimated activation map from the exemplary gCAR5 model run.

Besides this, theResults_{class provides functions to plot the parameter map estimates via}

plotMapEst() and to compute a summary of global parameter estimates viasummary(). To determine whether the algorithm shows an acceptable convergency behavior the

Diagnostic-class can be used. Again, a Diagnostic-object has to be generated and initialized for this:

R> diagObj <- new("Diagnostics")

R> diagObj <- initDiagnostics(diagObj,returnObj=returnObj, configObj=configObj)

The functionsummary()prints a six-point summary of global parameter traces.

R> summary(diagObj)

This is a summary of global parameter estimates of the following Rfmrieeg model run.

Used algorithm: gCAR5

Min. 1st Qu. Median Mean 3rd Qu. Max. xi20 10.540 13.350 14.260 14.310 15.180 18.960 tau20 11.450 13.630 14.620 14.950 16.230 20.110 xi2 3.960 4.693 4.938 4.951 5.171 6.658 tau2 1.552 2.361 2.724 2.769 3.162 4.291

Trace plots of parameter trajectories can be obtained via theplot()-function.

R> plot(diagObj,what="global",type="trace")

If requested, this function plots autocorrelation functions and diagnostics of voxelspecific estimates as well. Exemplary trace plots of global parameter trajectories of the gCAR5 run can be found in Figure 5.3.