If you are using an MRI system which cannot generate correct Nifti file types with image orientation information, you may still use mrTools by Spoofing nifti xform info.

Under the Plots menu option in the GUI, choose 'Interrogate Overlay.' This will open a field in the lower left hand corner of the GUI that specifies which interrogator will run when you use your mouse to click on a voxel. The default interrogator is timecoursePlot. You can write your own code (it's useful to use eventRelatedPlot.m or timecoursePlot.m as a starting point) and type its name in the GUI field instead. Then your code will run when you click on a voxel.

If you want to analyze data for a single experiment that was run across more than one scanning day/sessions, you can do the following:

1. Do preprocessing and alignment for each session separately, let's call them S1, S2.
   1. Run mrInit, motion comp/slice time correction, link the stim files (for MGL)
   2. Align both sessions to the same base volume anatomy using mrAlign
2. Make the umbrella session and import groups, let's call the umbrella session S12
   1. In Matlab call makeEmptyMLRDir('S12','defaultGroup=MotionComp') at the same directory level of S1 and S2. This creates a new session directory S12 that contains other directories necessary for MLR, including MotionComp. These directories are all empty. Note calling makeEmptyMLR('S12') will work too; it makes S12 with Raw group instead of MotionComp (you might add the latter manually later). Note also at this point you can move S1 and S2 into S12 (e.g., by using unix command mv); this will make the sub-sessions reside in the umbrella session, or just leave them as is. Either way, make sure you know which is which.
   2. Change directory to S12 and launch mrLoadRet. From the GUI, go to File→Import→Group, select the S1 from the pop-up window, and click 'OK', this will lead to a prompt asking you which group from S1 you want to import to the MotionComp group in S12. Select MotionComp in S1 and click Ok, then select which scan in S1/MotionComp you want to import. Select them and click Ok. By default, MLR will import those scans to S12 by making symbolic links in S12/MotionComp/TSeries to S1/MotionComp/TSeries. In other words, don't delete S1, as it contains the actual data. Similarly, import the scans from S2/MotionComp to S12/MotionComp. You should also want to copy the inplane anatomy from S1/Anatomy to S12/Anatomy.
3. Check quality:
   1. Concatenate two scans, one from each session, without detrending (set filterType to 0) nor converting to percent signal (uncheck the percentSignal box), but with using the warp. This is for easy visual inspection as the image is clearer in the viewer. When you concatenate scans with different alignment, a 'warp' checkbox in the diaglog box is automatically checked as MLR is smart to detect xform changed among the scans (because you aligned the two sessions separately and they're different). Lastly, a dialog box appears in which you select 'warpBaseScan'; select the first scan in S1 that you're concatenating. Note: This procedure assumes you will use S1 as the reference coordinate frame. You can also use S2 as the reference; just use appropriate 'warpBaseScan'. Note 2: Often warping using nearest interpolation does not return good results. This might depend on how similarly the slices were placed across sessions. Using linear interpolation for warping seem to return better results than nearest. Spline does not work for me (Franco) at all, it crashes. Spline also crashes for Dan (5/20/15). Cubic is much slower and it does not seem to have much of an improvement compared to linear.
   2. Check that the alignment is good by doing Plots→Display EPI Images. Compare the last frame of the first session to the first frame of the second session (e.g., if there are N frames per session, compare frame N to frame N+1 in your concatenated scan). If things worked, you should not see obvious movement when you toggle between the two frames.
4. If the alignment is not good, try this alternative: Align the 2D-inplanes from S2 to the 2D-inplanes of S1, then align the EPIs for S2 and save the alignments. Then re-import S2, and test again.
5. Concatenate across sessions: Once you're sure the alignments are good, you can concatenate all the data. You should now turn on the detrending filter (if you want it) as well as the warp. The same procedure can be applied to more than 2 sessions. After concatenation, you essentially have one time series just as if everything is collected in the same session. All MGL stim files should also be imported automatically and you can do your desired analysis.

mr3to4 creates the necessary links to transition a mrLoadRet 3 directory into a mrLoadRet 4 directory. It does not change any of the files, and you can always go back to using mrLoadRet 3 by calling mr4to3.

First, run:

mr3to4

Then, you need to convert the alignment:

1. Run mrAlign (version 4.5).
2. Open up your volume anatomy (from wherever you have it) and inplanes from (Raw/Anatomy/Inplane)
   1. You may need to set the base coordinate frame for the volume anatomy (see the mrAlign section above). You may also need to replace the .hdr file
3. Import your bestRotVol.mat using Import from mrAlign-4.2
4. Confirm that the alignment is good, if not, compute Alignment
5. Save your alignment
6. Now Load up the inplane anatomy from Raw/Anatomy/Inplane as your destination
7. Load up any epi from Raw/Pfiles_preMC and use it as your source. If you have any problem loading up a file (e.g. the nifti header is somehow mangled), you can try to load up one of the test online epi images.
8. Initialize alignment from headers
9. Confirm that it looks ok
10. Save the alignment to mrLoadRet-4.5 by using File/export/mrLoadRet-4.5. You will prompted to choose which groups to export to. This will update the nifti headers in the time series files as well as the mrSession variable (no need to run mrUpdateNiftiHdr).
11. Close mrAlign
12. Make sure that the mrSession is now set to the version 4

mr3to4(4);

1. Now you can run mrLoadRet version 4

mrLoadRet

After you do these steps, if you are still having problems with the nifti headers in the motion comp group, there are several things you can do to fix the headers. The way you may notice that you have a problem is that if you run an analysis like corAnal or eventRelated, the analysis will run properly but nothing will display. You may also notice that if you use the interrogator that the voxel numbers it comes up with in the bottom left are clearly wrong. Finally, if you import an ROI and then ROI/Show/Coordinates you will see that the coordinates are similarly wrong. These all probably occur because the nifti qform/sform is corrupted. You can test explicitly for the correct transformation by checking that the scanXform and the baseXform are such that they indicate the correct scale factor between your epi and anatomy data. You can check this out explicitly, either by examining the sforms by goining into Edit/Scan/Info and Edit/Base anatomy/info or looking directly at Edit/Scan/Transforms/scan2base, or do the following from the command line:

scanNum = 1; % for instance, if you are checking scan 1 in group 3
groupNum = 3;
v = mrLoadRet;
baseXform = viewGet(v,'baseXform');
scanXform = viewGet(v,'scanXform',scanNum,groupNum);
inv(scanXform) * baseXform

For a scale factor of 2 between the base anatomy and epi this should give:

ans =
   0.5000    0.0000   -0.0000    0.0000
  -0.0000    0.5000    0.0000   -0.0000
   0.0000    0.0000    1.0000   -0.0000
        0         0         0    1.0000

If you have a problem, here are possible solutions:

If you know what the alignment information is, e.g. if it is supposed to look like the above, then just input that by hand in Edit/Scan/Transforms/scan2base.

You can do this by following the directions above in mr3to4 or in the mrAlign information. Basically you will load the inplae anatomy as the destination and one epi (make sure it is one that has not been corrupted by any FSL alignment tools) to the source. Choose Align from Header, check things are ok, and then export alignment to mrLoadRet-4.5.

Assuming that in your original Pfiles_preMC you have the original nifti files with good nifti headers (i.e. straight from the magnet with the sform set by mrAlign in the above steps), you could rerun motion compensation using mrLoadRet's motion compensation (it works better anyway). Then rerun all the analyses concatTSeries/eventRelated or corAnal on these newly motion compensated files.

Another possibility is to try to rerun mrFixNiftiHdr if you think you might have done some of the above steps out of order:

mrUpdateNiftiHdr
mrFixNiftiHdr(2);

Yet another possibility is that you could go in by hand and copy the nifti headers from Pfiles_preMC to the matching files in Pfiles (just copy the .hdr files not the .img files!)–usually this will involve changing the names of the headers from headername.hdr to hearname_mcf.hdr as well (you have to match the header name in the Pfiles directory). and then run

mrUpdateNiftiHdr

Just for good measure you may want to do a clear all. Then rerun your corAnal or concatTSeries/eventRelated….

Finally, if you just want to look at your nifti headers to see if they look ok, you can get them by doing Edit/Scan/Info or from the command line doing:

v = newView('Volume');
viewGet(v,'niftiHdr',1,2)

This will get the header for scan 1 in group 2. In particular, you may want to check that the qform and sform fields match the one in the raw group (group 1). If they don't match, then mrFixNiftiHdr(2) did not work properly. Try it again, or try one of the other procedures listed above. Or you could try to explicitly set the header with an appropriate one by doing:

viewSet(v,'niftiHdr',hdr,1,2);

To make it permanent, you will have to resave your session file

saveSession

Starting with a valid mrLoadRet4 directory structure, you can create the appropriate directories and links so that mrLoadRet3 can be run as well. This is a temporary hack to ease the transition between mrLoadRet3.1 and mrLoadRet4. Nothing will be changed in your mrLoadRet4 directory, it will just create extra directories and make links to the data files. If you have done MotionComp, then it will link the files in MotionComp to Raw/Pfiles, otherwise it will link to the Raw files. If you have a bestRotVol.mat it will install that alignment. It will create a mrLoadRet3 style mrSESSION file and save that as mrSESSION3.mat it will also make a copy of the mrSession.mat (version 4) file in mrSession4.mat.

When you want to run mrLoadRet3, and you have already called this function with no arguments, you can run:

mr4to3(3)

to switch the mrSession file to the version 3 file and:

mr4to3(4)

to switch the mrSession file back to the version 4 file.

To switch between the two manually, you just have to have the correct mrSession file. For mrLoadRet-3.1, remove your mrSession.mat file, and copy mrSESSION3.mat to mrSESSION.mat. For mrLoadRet-4.5, remove mrSESSION.mat and copy mrSession4.mat to mrSession.mat. This is what mr4to3 and mr3to4 do when you call them with an argument of 3 or 4.

You can use FreeSurfer to segment your 3D anatomies into a inner and outer surface and import those into MLR.

Install a copy of FreeSurfer on your machine. You can do this by downloading from the website:

http://surfer.nmr.mgh.harvard.edu/

Or, copy the folder /Applications/freesurfer from a computer that has installed FreeSurfer to your Applications folder (make sure the computer has the same processor type – i.e. Intel or G5).

Next, set up your environment variables properly. You can do this by adding to your .cshrc.mine file the following lines:

  setenv FREESURFER_HOME /Applications/freesurfer
  if (-d $FREESURFER_HOME) then
    setenv SUBJECTS_DIR    /Volumes/CBIV2/Heegerlab/anatomy
    setenv MINC_BIN_DIR     ${FREESURFER_HOME}/mni/bin
    setenv MINC_LIB_DIR     ${FREESURFER_HOME}/mni/lib
    setenv MNI_INSTALL_DIR /Applications/freesurfer/mni
    source $FREESURFER_HOME/SetUpFreeSurfer.csh >/dev/null
  endif

Make sure to change the SUBJECTS_DIR in the above to the directory where you keep the anatomies.

If you are using a bash shell (which is the default on Mac OSX) the following is the correct code to be added to your .bashrc file:

export FREESURFER_HOME='/Applications/freesurfer'
if [ -d $FREESURFER_HOME ]; then
 export SUBJECTS_DIR='/Volumes/CBIV2/Heegerlab/anatomy'
 export MINC_BIN_DIR=$FREESURFER_HOME/mni/bin
 export MINC_LIB_DIR=$FREESURFER_HOME/mni/lib 
 export MNI_INSTALL_DIR=$FREESURFER_HOME/mni
 source $FREESURFER_HOME/SetUpFreeSurfer.sh >/dev/null
fi

Linux users (Ubuntu) should change FREESURFER_HOME to /usr/local/freesurfer. The *CentosOS 4 x86_64* installation is suggested on Ubuntu 9.10 (Karmic Koala) 64-bit.

You may also need a free license to use FreeSurfer.

To run a segmentation, use the following command

recon-all -subject fp -i fp19750105/FP-centered.hdr -all

Where fp is a directory name that you want to be created, and fp19750105/FP-centered.hdr is the name of your 3D volume

When the segmentation is done, FreeSurfer should have made a whole bunch of directories. In particular, under mri you can see some new volumes that it has made in its own format under mri. This is not very important, but if you want to take a look at them, you can use the command:

tkmedit fp rawavg.mgz

The real happiness is the surfaces generated in the folder surf. You should see some surface for the left and right hemispheres named lh.* and rh.*. In particular, we are interested in the pial surface (lh.pial), the white matter surface (lh.smoothwm), and the inflated surface (lh.inflated). It should have also created a 3D anatomy file in mri/T1.mgz.

We next need to convert this to the surfRelax format that MLR needs. To do this cd into the directory that freeSurfer made and run mlrImportFreeSurfer:

» cd fp

>> mlrImportFreeSurfer

The default parameters should be good (just click OK) and it should do the conversion and save everything in the directory surfRelax. After this all the files needed to work with surfaces and flat maps will be saved inside the folder:

>> surfRelax

The canonical (BASE) anatomy will be saved in such folder with the file name format:

fp_mprage_pp.img/.hdr

This file should be used for all subsequent alignments. To import the brain surfaces just created open:

1. Align a session to the BASE anatomy (both inplane anatomy and functional images); this step should be generally done on a retinotopy scan that will be used to define the visual areas;
2. Open a mrLoadRet session.
3. Import the surface using the menu item: File/Base Anatomy/Import Surface
4. Save the imported surface in the current session (e.g., in the retinotopy session): File/Base Anatomy/Save
5. Create the a flat map using the surface (see flat maps primer).

Caret segmentations do not produce an inner and outer surface, instead Caret creates a single mid-cortical surface. We therefore tend to stick to SurfRelax or FreeSurfer for segmentations. Nonetheless, we have some functions that can read and write Caret format surfaces.

Download Caret from here. You will need a free registration.

Run the command on the surface you want to convert:

mlrSurf2Caret('jg_left_GM.off')

It will first bring up the surface viewer, which allows you to check the associated files (you should make sure that you have the right surface and the right 3D anatomy file). Then click OK.

Next it will ask you to set the Anterior Commissure point (if you don't already have Talairach info set for that base volume). Go find the AC, and place the red dot on it:

Then select setPoint AC and then click OK:

This should create a few files that Caret needs to load in your surface:

filename_fiducial.coord
filename_fiducial.topo
filename.spec
filename.hdr
filename.img

Now, open up Caret and choose File/Open Spec File from the menu and select the spec file you just created using mlrSurf2Caret:

You should now be able to see your surface in caret:

Use the command loadSurfCaret (which works like loadSurfOFF):

surf = loadSurfCaret('duh_fiducial.coord','duh_fiducial.topo');

To change the name of a group, you can use viewSet. If you are running MLR, then do something like:

v = newView;
v = viewSet(v,'renameGroup','groupNameYouWant','MotionComp');
deleteView(v);

This will rename the group 'MotionComp' to 'groupNameYouWant'

There are several ways to customize mrTools to your site.

1. You can use mrSetPref to set some preferences for fields set by mrInit. see here
2. You can customize the GUI using plugins
3. You can set site-specific information using auxParams, explained below.

auxParams are site-specific information that you may want to add about your scans that are specific to your site. For example, they could be the name of an associated file (like eye tracking data), or a specific field (like number of receive coils). You can add the information with the following viewSet:

v = viewSet(v,'auxParam','paramName',paramValue);
saveSession;

You can get the value:

paramValue = viewGet(v,'auxParam','paramName');

There is new GLM code from Julien Besle and Denis Schluppeck from Nottingham University. This has now been incorporated into the main mrTools trunk, so you should just be able to svn update your repository and use it. There is a tutorial which explains how to use it.

Note that there were many changes to the repository as part of Julien's update. If something is broken and you want to go back to the version before the merge of the Nottingham branch with the trunk, you can do:

svn checkout -r 2810 https://cbi.nyu.edu/svn/mrTools/trunk mrTools

The remaining instructions here should now be obsolete, but are retained here in case one still wants to checkout the mrToolsNottingham branch where the GLM code was developed (this branch will no longer be updated, but contains a few commit logs - for functions that already existed in the main branch - that are not available in the trunk, due to complications with merging the two).

Get the mrToolsNottingham branch in the same directory where you have your regular mrTools directory so you can switch back and forth:

svn checkout https://cbi.nyu.edu/svn/mrTools/branches/nottingham mrToolsNottingham

Now you should have two directories, one for mrToolsNottingham and one for mrTools in the same directory. To switch back and forth you can use the command nott.m which you can get from:

svn export http://gru.brain.riken.jp/svn/matlab/nott.m

Using this command in matlab, you can use the nott branch by doing:

nott nott

and back to the main by doing:

nott main

To use the GLM code, you will have to select the plugin “GLM_v2” which you get by running:

mlrPlugin

and clicking on the checkbox. The next time you run mrTools you should get extra items in the viewer.

Every time you run motionComp it will now save your settings so the next time you run it will come up with the params set to what you had them before. Note that if you hit cancel on the GUI then the parameters will not be saved. To remove your settings and go back to the default defaults, you can set the preference:

mrSetPref('motionCompDefaultParams',[]);

Set the preference for nii extension in Edit/Preferences or by running:

mrEditPrefs

Alternatively set the niftiHeaderExtension to nii directly via command line:

mrSetPref('niftiFileExtension','.nii');

You can set your own list of colors for ROIs which will show up in the drop down list boxes when you edit properties for ROIs by setting the colorNames mrSetPref to a cell array of cell arrays in which each element is a a pair of string name of color and triple of color. For example:

mrSetPref('colorNames',{{'mycolor',[0.2 0.9 0.9]},{'mycolor2',[0.1 0.1 0.1]}});

You should restart mrLoadRet for these changes to take full effect.

Here is a random set of colors that you can add.

mrSetPref('colorNames',{{'indigo',[75/255 0 130/255]},{'violet',[127/255 0 255/255]},{'navy',[0 0 0.5]},{'olive',[0.5 0.5 0]},{'coral',[255 127 80/255]},{'orange red',[255 69 0]/255},{'chartreuse',[127 255 0]/255},{'dark green',[0 100 0]/255},{'sea green',[46 138 87]/255},{'turquoise',[64 224 208]/255},{'steel blue',[70 130 180]/255},{'deep pink',[255 20 147]/255},{'brown',[165 42 42]/255},{'saddle brown',[139 69 19]/255},{'sandy brown',[244 164 96]/255}})

If you want to make them permanent then, you should add a true as the last argument.

mrSetPref('colorNames',{{'mycolor',[0.2 0.9 0.9]},{'mycolor2',[0.1 0.1 0.1]}},true);

Some times you might want to trigger an event for multiple parts of a trial. Like, for instance, you have two segments with randomization in the trial and you want an event for each one of those segments. It is possible to run this via scripting (see here for more info on scripting event-related analyses). Here is an example:

v = newView;
% set our group to the group we want to run the event-related analysis on
v = viewSet(v,'curGroup','Concatenation');
% now we will get a default set of parameters for scan 1
[v params] = eventRelated(v,[],'justGetParams=1','defaultParams=1','scanList=1');
% This will have a field called stimvolVarInfo which contains the settings for the variable
% you can examine what it looks like - it should have fields for taskNum, segmentNum and varname
% and possibly phaseNum
params.scanParams{1}.stimvolVarInfo
% we will make our own
stimvolVarInfo{1}.taskNum = 1;
stimvolVarInfo{1}.segmentNum = 1;
stimvolVarInfo{1}.varname = 'myVariable';
% now lets make the one for the other segment
stimvolVarInfo{2}.taskNum = 1;
stimvolVarInfo{2}.segmentNum = 3;
stimvolVarInfo{2}.varname = 'myVariable';
% the varname and taskNum are the same in this case, but could be anything that you choose.
% so, now lets put it back into the params. Note the {1} here is for the 1st scan, so if you
% were doing multiple or different numbers of scans you would have to change that accordingly
params.scanParams{1}.stimvolVarInfo = stimvolVarInfo;
% and run it
v = eventRelated(v,params);