Usage notes (by Ajay Satpute)

This page contains the step-by-step instructions (with varying degree of detail) for how to perform different tasks (see table of contents) using NeuroElf.

1. when using NIftI (.nii files), make sure the files are not zipped
2. in the naming of files, the placement of the first underscore is critical, make sure it comes AFTER the subject ID or number, and BEFORE the individual run number or task (see the mdm.ComputeGLM method for more details)
3. it is necessary to have a separate folder for each run for spm5_preprojobs to work correctly

1. may need to co-register the functionals to the structurals, or to reset the structural images so the AC is at (0,0,0); to do the latter, open SPM, use display, open the structural image, put the cursor to the rough AC location, and then enter the values from the mm position in the various fields (translation), if AC position is good, play around with rotation (pitch, yaw, roll, etc.) until the orientation is correct (AC/PC in one plane, left and right hemisphere separated by X=0 midplane), repeat if necessary; or, you can just try the preprocessing steps and see if the normalization looks reasonable with the check_reg function in SPM
2. open the NeuroElf GUI (entering neuroelf_gui in Matlab)
3. open the SPM preprocessing configuration under the Tools menu
4. check the “force to single precision” box
5. select one subject's folder
6. change folder name to a pattern
7. adapt the pattern fields, then search for run folders
8. if this fails, the subject's folder (pattern) field needs to be changed (type a space at the end and remove it) before you can use the search button again
9. remove subjects that are already processed or not to be processed at all
10. select the number of volumes to drop from the beginning of the run
11. fill all other fields correctly (slice timing, realignment, normalization, smoothing)
12. select the fmriquality checkbox (see below for checking the quality)
13. run

1. first use some method to view the final preprocessed files (e.g. swr*.nii files) and ensure they are in normalized space (for instance, use check_reg in SPM)
2. check the quality of the functional data by opening the fmri quality file, which is outputted if you select the option during the preprocessing step; the file is named according to the first functional input file name with *_fq.mat
   1. load this file in matlab (it’s a structure)
   2. input this structure into the function fmriqasheet
   3. this outputs a figure with three sections: the top shows the signal averaged within each slice over time, look for bumps, etc; the middle row is the spatial and temporal SNR image, and the bottom row has a histogram of the spatial SNR image, giving a rough estimate of the peak SNR (all subjects should have comparable SNR values!)
   4. a simple way to do this for all your files is to:

ajay_checkquality.m

% possibly adapt patterns to select specific files!
fqfiles = findfiles(pwd, '*fq*mat');
for i = 1:length(fqfiles),
  clear q; %clear out any residual q structures. 
  load(fqfiles{i}); %loads next structure
  fmriqasheet(q); %brings up the quality sheet
  getchar; %waits for keypress in the command window before bringing up next one
end

1. check the motion parameters
   1. enter the function showspmrparams.m at the command line.
   2. it will prompt you for a directory
   3. click on the outermost directory for a given subject, and the function will search through and find the motion parameters files from there.
   4. the function will concatenate the motion parameters in the display, with a vertical dashed line placed between sessions.
   5. note that you should not click on the outermost directory for the study, as then it will concatenate all subjects' motion parameters, and also may output things a bit incorrectly as everything will be patched to the first subject's first run.

1. the SPM preprocessing dialog (Run) should also create VTC files at the end (basically the preprocessed image files in another format that allows for rapid processing of data), which you can simply check by using the File → Open menu option in NeuroElf

1. Jochen: The blue bars (boxes, really) represent a spike-detection algorithm that I have implemented together with Katherine Duncan (Daphna's new post-doc, who was working at NYU before). She found that in the fourier spectrum (original acquisition space) there are sometimes artefacts that produce “wave-like” patterns in voxel space (per slice, not full-brain). To detect these artefacts, the mean of the time series is subtracted from each slice and then the FFT is computed; if then the FFT image contains large “spikes” (single frequency/phase pairs that indicate energy too large to be explained by regular deviations), a blue box is printed for those slice timepoints. I would not be overly worried about single boxes, nor about a “series of boxes” in top (or bottom) slices where almost no brain data is collected; given that the true signal portion is very low, the detection threshold adapts and then finds more “noise” components in the image (quite normal). However, if you see a volume with several boxes (such as in the range of 120 to 140 on the volume/time axis), that might be a sign of a real problem… You can then (normal) click on the slice timecourse (blue box) to bring up a secondary window that shows three rows of data: the actual data (including the timepoint before and after the one you clicked on), the mean-removed data, and at the bottom the FFT of the mean-removed data. The detection works on the data of the last row (but you can then observe the effect of this artefact in image space, to see how bothered you are by it).

1. The preprocessed data are transformed from NII to VTC in the final step.
2. VTC formats have an advantage in speed of processing for later steps because they put time as the first dimension in the 4D image matrix.
3. VTC axes are not in the same exact ordering as NII axes: it goes time, Y, X, Z.
4. The defaults set the bounding box of the image to cover the MNI brain.
5. The defaults use 3mm voxel sizes, timepointsx66x52x47 size… note that the 66 is in the y direction…

1. How to put your design into a prt file.
2. How to visually inspect your prt file.

ajay_showsdms.m

prt = xff('nameofprtfile'); %load up your prt file
%next, transform this into an sdm object with a few options:
%nvol refers to number of volumes
%prtr refers to the TR in ms
%rcond refers to which condition is a rest condition, you must specify this as empty '[]' if you don't want it to take anything out as a rest condition
%otherwise it takes out I think last column as a rest condition (or perhaps the column labeled as 'rest', not sure).
sdmfile = prt.CreateSDM(struct('nvol',260,'prtr',2000,'rcond',[])); 
sdmfile.ShowDesign %outputs a figure of your design!

1. first you need to make .prt files, which are object-structures that contain the design information
   1. they contain the onsets and offsets for each condition in milliseconds
   2. should be scripted (to transfer information from logfiles or .mat files)
2. then, generate an mdm container in Matlab

   ajay_new_mdm.m

   mdm = xff('new:mdm');

3. fill the mdm container with the .prt files and the corresponding .vtc files
   1. you can get help on mdm with mdm.Help('ComputeGLM')
   2. you can use findfiles to locate the relevant files

      ajay_findprtvtcs.m

      % possibly adapt patterns to select specific files!
      prts = findfiles(pwd, '*.prt');
      vtcs = findfiles(pwd, '*.vtc');

   3. make sure they match up (number of files, pairing!)
   4. then store in the MDM file

      ajay_fillmdm.m

      % as an example:
      % mdm.XTC_RTC = {'nameoffile.vtc','nameoffile.prt'};
      % to store the lists we found (findfiles) use
      mdm.XTC_RTC = [vtcs(:), prts(:)];
      % the final result must have two columns:
      % - first column the VTC filenames
      % - second column the PRT filenames

   5. verify any options in the mdm container (time course transformation, etc.)
   6. save the mdm with mdm.SaveAs('SK_firstry.mdm');
4. compute the glm (with filter settings):

   ajay_computeglm.m

   glm = mdm.ComputeGLM(struct('tfilter', 100,'tfilttype', 'fourier');

5. you may prefer to use 'gct' filter instead… in fact, this may be preferred.
6. to run a FIR model:

   ajay_computefirglm.m

   glm = mdm.ComputeGLM(struct('tfilter', 100,'tfilttype', 'fourier','ndcreg',12));

   1. the struct allows you to add optional commands and options (such as filtering)
7. save the glm output:

   ajav_saveglm.m

   glm.SaveAs;

   which opens a dialog box if no filename is given

8. IMPORTANT!: when you have MEMORY issues (running out of memory), add the
   1. 'outfile' (output GLM filename) and
   2. 'transio' (set to true) options
   3. this will create the GLM with transparent IO access, so that even very large models can be estimated without problems

1. when making the prt files, change a couple flags:
   1. first

      ajay_parametricprts.m

      % set FileVersion and ParametricWeights fields
      prt.FileVersion = 3;
      prt.ParametricWeights = 1;

   2. when entering the on offsets, enter a three column matrix instead of a two column one with the parametric weights as the third column
   3. demean and/or scale the parametric weights (consider whether you want to use the mean within a run, or across all runs depending on your q)

1. making your VOI:
   1. load a VMP, select a contrast, threshold correctly, cluster table (button), find the cluster of interest (click the nearest-cluster-peak button, third from the top, next to the clusters listbox)
   2. in the clusters listbox delete all other clusters (trashcan button)
   3. optionally restrict to sphere around peak (second button from the top)
   4. click on the save-clusters button (disk icon)
2. reload this VOI on the command line:

   1. ajay_loadvoiforppi.m

      % load a VOI object
      xvoi = xff('*.voi');
       
      % potentially edit it, e.g. remove voxels that are not medial enough
      xvoi.VOI.Voxels(abs(xvoi.VOI.Voxels(:, 1)) > 10, :) = [];
      xvoi.VOI.NrOfVoxels = size(xvoi.VOI.Voxels, 1);
       
      % maybe rename the VOI for later use
      xvoi.VOI.Name = 'dmPFC_E_vs_P';
       
      % and save again
      xvoi.Save;

3. with loading a VOI in the GUI (open folder icon), you can manually edit which voxels are included by:
   1. click on “Mark voxels in selected VOIs in current VMR” (top button)
      1. color code: default is 240 for VOIs in brain voyager
      2. resolution- pick the original VTC resolution for visualization, or pick 1 for actually drawing/selecting voxels to be included/excluded
      3. use the 2D/3D drawing tool (see also my notes on creating a mask)
      4. re-save the VOI
4. make sure the correct voi is loaded
5. load the MDM you want to use
6. compute the GLM

   1. ajay_runppiglm.m

      % we pass in two extra options
      % - ppivoi (the VOI object we loaded)
      % - ppicond a cell array with either names of conditions
      %   or contrasts to interact the VOI timecourse with
      glm = mdm.ComputeGLM(struct( ...
          'ppivoi',    xvoi, ...
          'ppicond',   {{'ECL + ECM + ECH + EDL + EDM + EDH > PCL + PCM + PCH + PDL + PDM + PDH'}}, ...
          'outfile',   'CatEmot_noparam_split_allSsfixed_dmPFC_PPI_E_vs_P.glm', ...
          'showsdms',  'image', ...
          'tfilter',   220, ...
          'tfilttype', 'fourier'));
       
      % after computation, visualize
      glm.Browse

To combine two RFX GLMs (which must have the same regressor names and order, as well as disjunct subject IDs), simply

1. load the two GLM files
2. use the JoinRFX method
3. and save the result:

ajay_joinrfxglms.m

% load 2 GLMs
glm1 = xff('*.glm', 'First GLM to join...');
glm2 = xff('*.glm', 'Second GLM to join...');
 
% then join the GLMs
joinedglm = glm1.JoinRFX(glm2);
 
% and save
joinedglm.SaveAs;

If you have two GLM files with the same regressor names and order and want to copy the contrast (and group, covariates, etc.) definitions from one to the other, here's what you can do:

ajay_copyglmspecs.m

% load the GLM you want to copy the specs from with transio access
sourceglm = xff('model_with_configuration.glm', 't');
 
% load the GLM you want to copy the specs to (also with transio)
targetglm = xff('model_without_configuration.glm', 't');
 
% copy the parts of the RunTimeVars you want to keep
rtv = sourceglm.RunTimeVars;
targetglm.RunTimeVars.Contrasts = rtv.Contrasts;
targetglm.RunTimeVars.ContrastColors = rtv.ContrastColors;
targetglm.RunTimeVars.CovariatesData = rtv.CovariatesData;
targetglm.RunTimeVars.CovariatesNames = rtv.CovariatesNames;
targetglm.RunTimeVars.Groups = rtv.Groups;
 
% save the RunTimeVars of the target GLM
targetglm.SaveRunTimeVars;

Open the Contrast manager (under the Analysis menu). Make sure all subjects of interest for the contrast are highlighted (default for first time opening the dialog: all subjects selected), or define groups (only works for contrasts at the moment, when running correlations, the current selection is used).

1. use the plus button to create/add a contrast
   1. enter a name
   2. then set the weights either by clicking the 1/-1 buttons or selecting all conditions and clicking the X… button and entering a weight for each selected condition
   3. for contrast weights it is best if all positive and negative weights (separately) add up to an absolute value of 1 (so that the contrast value in the beta plotter is still in the same metric!)
2. make sure no covariate is selected (otherwise correlation!)
3. select the type of regression (OLS, robust, or both)
4. choose the correct VMP (if already one or more loaded) as target
5. click compute current or compute all

1. for correlations with behavior (or other non fMRI measure)
   1. generate a .mat file that has two variables in it: one should be a matrix with a value or NaN for each subject (one row for each subject, one column for each measure), the other variable in the .mat file should be a cell array with the names of the measures in it
   2. use the NeuroElf GUI's contrast manager to load this up (press the little file button at the bottom right); the measures should appear in the little box on the bottom right
2. for correlations with cluster extracts
   1. either create a list of clusters (Clustertable button) or load a VOI file with pre-defined clusters (or you can draw and define an anatomical cluster also, e.g. a sphere around a coordinate)
   2. in the contrast manager, first (create and) select the contrast for which the cluster extract should be generated, then press the button with the greenish VOI icon
   3. the extracted values are now in the covariates list
3. select the covariate(s) of interest
4. select the type of regression (OLS, robust, or both)
5. choose the correlation options (rank correlation, adding multiple regressors to one matrix instead of separate regressions)
6. choose the correct VMP (if already one or more loaded) as target
7. click compute current or compute all

This is not yet implemented as a standard option in the contrast manager and requires scripting on the command line.

1. can be difficult because most correlations in imaging samples are non-independent; the correlations either share a single common variable (e.g. correlating two predictors with a criterion) and NeuroElf does not store the contrast maps required to calculate non-independent correlations (which are different than the beta values/maps which it does store in the glm file)
2. first you must get access to the actual contrast maps (one map per subject, representing the weighted sum of beta maps in the contrast)
   1. load the GLM into a container (if it is already loaded use syntax

      ajay_getobject.m

      % get list of objects
      x = xff
       
      % then select from the list (in example: 7th object)
      glm = x(7);

      otherwise load from disk

      ajay_loadglm.m

      % load a GLM file
      glm = xff('*.glm');

   2. read the help output of glm.Help('RFX_conmaps')
   3. get the order of predictors using glm.SubjectPredictors to figure out the contrast vector in the next step
   4. then get the contrast maps for two different contrasts

      ajay_getconmaps.m

      % two contrasts A > B and C > D
      c1 = glm.RFX_conmaps([ 1,-1, 0, 0]);
      c2 = glm.RFX_conmaps([ 0, 0, 1,-1]);

3. now get the covariate info (hopefully in the glm already under the RunTimeVars field):
   1. display glm.RunTimeVars.CovariatesNames
   2. select the covariate

      ajay_selectcovfromrtv.m

      % select 4th covariate
      bv = glm.RunTimeVars.CovariatesData(:, 4);

   3. alternatively load it from a .mat file or create a new variable
4. then reshape and replicate so that it has the same size as the maps
   1. get the output of size(c1) (for instance [62, 56, 66, 16])
   2. apply reshape and repmat:

      ajay_reshaperepmatbv.m

      bv = reshape(bv, [1,1,1,16]);
      bv = repmat(bv, [66,52,56]); %use the size of ec to determine these values

5. calculate the difference in correlations

   ajay_depcorrt_exmp.m

   % use the contrast maps and the bv
   difft = depcorrt(c1, bv, c2, bv);
    
   % remove invalid outcomes
   difft(isinf(difft) | isnan(difft)) = 0;

6. now put this matrix into a vmp container so we can visualize it
   1. steal a container from the current GLM
      1. run a dummy contrast in the contrast manager (any t-contrast will do), and store into a new VMP!
      2. use the list of objects again:

         ajay_getvmpaccess.m

         % show loaded objects
         x = xff
          
         % select vmp (9th object)
         vmp = x(9);
          
         % then set the data
         vmp.Map.VMPData = single(difft);
          
         % and set the name and DF1 parameters (DF1 = N - 3, see depcorrt!)
         vmp.Map.Name = 'Differential correlation (A>B, tas_desc) > (C>D, tas_desc)';
         vmp.Map.DF1 = 13;

7. should be ready to go! (simply switch back and forth to the object in the GUI to update the map) but you may want to save it, too

1. Note: neuroelf uses a smoothing estimation procedure similar to the way AFNI does it. It will ask you whether you want to estimate the smoothing from the data first, and then estimate and run it.
2. create a mask of the voxels you want to include (can be based, e.g. on your stat image or anatomically defined), in many cases, you can just load up the colin_brain_ICBMnorm.vmr for a whole-brain mask, but be sure to click on VMP mask with VMR! Otherwise alphasim will run over the entire box of data (i.e. not just the brain).
   1. for functionally defined
      1. create cluster table
      2. select all clusters
      3. use the VMP → Mask with VOI clusters menu item
   2. for anatomically defined
      1. paint mask (see the Drawing/creating a mask section)
      2. use the VMP → Mask with VMR menu item
3. click the alphasim button
   1. select a smoothing kernel size depending on your data (preprocessing options)
   2. creates a tabular output in the console showing the FWE p<0.05 levels for different raw probabilities

1. you can also use FDR correction by clicking on VMP → apply FDR.
2. then, it will auto threshold the maps with FDR correction while k-thresh is off.
3. if k-thresh is on, it will use AlphaSim results.

1. load up your stats in the form of a VMP (you can import stats from other packages using the import command, too)
2. highlight two maps in the “Available Maps” section
3. click on the function button (the “f” button)
4. enter “conjval($1,$1)” as your formula and make sure that the remaining options look okay
5. the output will be of a conjunction map that takes the minimum value of the two maps
6. run alphasim from the command line in matlab, e.g. alphasim([58,40,46], struct('fwhm', [4, 4, 4], 'conj', 2, 'thr', [0.005]))
7. you'll probably need to verify:
   1. the matrix size
   2. the fwhm which is used as an estimate of your smoothing for alphasim (your smoothing kernel divided by 3, so if it's 12, then it would be [4,4,4]) (provides one-tailed values)
8. use these thresholds in your neuroelf window

1. open BrainVoyager
2. load the colin.vmr (or any VMR for that matter)
3. load the pre-existing GLM file
   1. use the Analysis → Overlay General Linear Model → Load GLM… button
4. click on RFX ANCOVA
5. create (or load) the design (.ads file)
   1. for well-named conditions (according to a pattern!), auto-assigned condition names can be used (after verification!), otherwise assign to factors
6. click “Go”
7. to get the contrasts you want, use the Analysis → Overlay ANCOVA menu, and choose or defined the test/contrast of interest
8. in the Overlay Volume Maps dialog click the Save VMP button
9. then reload the VMP in NeuroElf
   1. cluster tables, etc. from here

1. Let's say you want to extract beta's from several vois, e.g. from blobs in a contrast map, for plotting or further analysis.
2. First, load up your glm and voi in matlab (create your voi file using the save clusters as voi button)
3. If you need to make a voi, try something like:

   ajay_create_vois.m

   voi = xff('new:voi');
   voi.VOI(1).Name = 'test';
   voi.VOI(1) = [];
   voi.AddSphericalVOI([0,0,0], 2);

1. Then…

   ajay_get_betas_in_glm_from_voi.m

   voi_betas = glm.VOIBetas(voi);
   %or to get all the beta maps not limited to a voi
   betas = glm.GLMData.Subject(S).BetaMaps(:,:,:,:); 

1. glm.SubjectPredictors provides names of predictors
2. glm.Study provides details about files that go into the glm, e.g. vtcs., sdms, etc.
3. glm.Study(1).RunTimeVars contains more information, including info about glm that is applied to data
4. To view the design matrix including filters: plot(ztrans(g1.Study(1).RunTimeVars.SDMMatrix))
5. To get a sense of the correlations between regressors including the filters
6. mdm.Handles.SDMs{1}.PredictorNames' :this lists out the predictor names for the columns.
7. plot(mdm.Handles.SDMs{1}.SDMMatrix) :this plots the matrix.
8. corrcoef(mdm.Handles.SDMs{1}.SDMMatrix(:, [2:2:24,25:32])) : this, e.g., calculates correlations between regressors.

For outputting many slices for several maps, this section describes how to script the output visuals at the command line.

1. load up your VMP and threshold it (height threshold)
2. open and select the surface mesh you want to use (see the File → Colin-27 → SRFs menu, e.g. start with the left hemisphere)
3. select the VMP → Create SMP menu item
4. save the new SMP under a good name (remove the asterisk and fill in something useful!!)
5. to set new stats on a surface, always start from the top, as that’s how it syncs:
   1. Loaded Object - left hemisphere
   2. Available Stats - left hemisphere ones
   3. select the particular stat you want, and then threshold it appropriately
6. then do the same for the right hemisphere
7. to differentiate between translational motion and rotational motion in the GUI, hold shift (translation) or depress shift (rotation); to re-center the image, hit the r key after clicking into the viewer
8. for setting up hi-resolution stuff
   1. first, set up what you want to see using the lower resolution SRF files (much faster to find a good perspective, zoom, etc.)
   2. then, repeat these steps with the hiresolution ones for figures
   3. smoothing values (as a starting suggestion) for hires: 400 iterations, and force between .4 and .6

1. load up your VMP and threshold it (height and cluster threshold)
2. load one of the “segback” files from the File → Colin-27 → VMRs → Backprojected from surfaces menu section
3. optionally also load the according high-resolution brain/head image from the High-resolution VMRs section (e.g. for semi-transparent head display)
   1. set the contrast using the vertical bar on the right of the neuroelf_gui
      1. move the top bar down to the top peak for the white matter
      2. move the bottom bar up to about half way from the bottom to the next peak (gray matter peak)
4. optionally also set the contrast of the segback object in the same way (this object will determine the transparency = black or opaqueness = white for the actual rendered data)
5. to select a “viewpoint” (angles), load any surface (best a low-resolution one from the File → Colin-27 → SRFs → Low-resolution Icosahedron section), visualize and rotate until the desired viewpoint is achieved
6. if used for display, make sure the hires_brain/head object is the selected VMR in the “loaded objects” box
   1. in case you wish to display the head semi-transparent, fill the background of the seg-back VMR with a value slightly above the lower contrast bar's value
7. click the render button (which will bring up the rendering UI)
8. if desired, change the background and sampling colors, as well as the color blending mechanism (only useful if the hue of dark and bright colors hugely differs)
9. for slicing alpha object: choose the seg-back VMR
10. slice-sampling determines, relative to the mid-point of the sampling space, what range of distances you want to be part of the rendering
    1. more positive means further away and more negative means closer to the camera/viewer
    2. has nothing to do with the X-axes of the dataset per se
    3. play around with it, depends a little on rotation/angle, a full range (to cover the entire space with maximum rotation) would be from around +200 to -200, but for normal brain shots a range of +75 to -75 is usually enough (and the default is just slightly larger)
11. stepsize: when trying to find a good rendering setup, start with higher values (-2 or -1) and once the image looks good (also in a smaller resolution, see below), lower to -0.2 mm
12. rotation is copied from the surface stuff you did earlier
13. distance from origin does not refer to a zooming featuer; imagine holding the brain in your hand nearer or farther but then using a zoom lens; the larger the distance the more orthogonal the space is sampled in the third dimension, and smaller values will compress the size for further away slices (don’t need to mess with it too much)
14. rendering resolution: start small first, say around 256, then move up to around ~2500 (300 DPI letter size approximate for publication; for posters, perhaps even higher) –but, it’ll take time! 2000 takes around 15 minutes or more
15. smooth border: to reduce jagged edges in your blobs, particularly when you mask or use a very large cluster size thresholds; start with ~2mm and move up as needed to say 10mm. The effect of this however, is to reduce your stats value with increasing smoothing values (so you might have to lower the threshold for the visualization)
16. anatomical alpha: indicates how much opacity per anatomical slice; is related to stepsize (e.g. if 2mm of tissue should be completely opaque, but .5 mm should be somewhat opaque, and the stepsize if -0.5mm, alpha must be ~0.3; in general, use a higher alpha when stepsize is higher, and lower when stepsize is lower)
17. statistical alpha: opacity of the blobs. This should be higher than the anatomical alpha in (absolute) value; 1 is the max, fully opaque. -1 scales based on the thresholding where the lower threshold is completely transparent and the upper threshold is completely opaque (as set in the neuroelf_gui). For a higher absolute (but negative) value than -1 (e.g. -2) the lower values start to gain opaqueness
18. to restrict stats to voxels with brain data, keep the multiplication box checked; potentially alter the minimum anatomical value to increase/decrease visibility of stats around the border of the data
19. higher interpolation (cubic/sinc) takes longer but gives also better quality output (mostly useful for higher resolution renderings); only set to sinc for final shot!

Jochen Email

1. download and install the latest snapshot: http://neuroelf.net/NE_14032023.zip
2. then use “neuroelf_setup” and “neuroelf_makefiles all” (without quotes)
3. when you next open the NeuroElf GUI, load the following VMR/anatomical from the File → Colin menu: colin_brain_rendskull_ICBMnorm.vmr and colin_hires_ICBMnorm.vmr
4. in the main UI, ensure that the colin_hires_ICBMnorm.vmr is selected
5. use the render button (below the surface view button) on the right side to switch to render view
6. in the newly open render UI, select the colin_brain_rendskull_ICBMnorm.vmr dataset as the “Alpha volume” (transparency information; dropdown close to the top)
7. once the rendering is complete, you can use the same controls as for the surface view (mouse; with shift to translate and alt to zoom; and also cursor keys)

When you want to add a stats map (or several maps), please know that each map will be resampled into the resolution of the anatomical prior to rendering, so to display 3 stats maps (at the same time) on top of the high-res colin brain, you probably need between 2 and 3 GB free memory! Also, for stats maps, I suggest changing them to “stats-dependent transparency” (pressing the “n” key while in the slice-view, THEN selecting the map/s you want to show, and then switching to render view)

1. load one of the colin_brain (or your own) VMR datasets
2. some things to know: for VMR objects values between 0-225 are greyscale; values between 226 and 255 are special color codes (they are used for blobs, masks, segmentation, etc.)
3. if you paint, use a value above 225 (default is already 240)
4. click on the pencil icon (probably pencil 3D icon)
   1. set the radius size ~10mm
   2. best to work with spheroid shape (most intuitive)
   3. color code range- to figure this out, use the cursor to determine the approximate range of values for the stuff you’re interested in (e.g. with the colin_brain_ICBMnorm.vmr file, grey matter has a range of approximately 100-150, and white matter approximately 170-200)
5. draw your mask on the colin brain
6. press the “u” key to toggle between drawing on these voxels and removing drawing on these voxels (to correct errors)
7. once you’ve made your mask, you can save your mask file by clicking File → Save As
   1. BUT this will save the mask values and the values of all the other voxels (i.e. the entire brain, not just the mask, allowing for further refinements)
8. to apply the mask, click the green arrow button, the third icon from the bottom on the left side of the slice display, which will eliminate all non-mask voxels
9. then, mask the files you wish to mask with the vmr, e.g. using the GLM → Mask with VMR menu item
10. you can then show the full intensities (lower threshold at 0) but your GLM should be masked!
11. you can also do the same to run Alphasim on this (which then uses the restricted search space)

1. Open the vmp.
2. Select the statistic that you're interested in and threshold.
3. Get the cluster table (click the icon).
   1. If you want to join multiple cluster tables together:
   2. Click on: File → options → cluster table → add to existing table
   3. Then repeat the first two steps (i.e. select the vmp object you want, thresholding, and get cluster table).
4. Click on File → New Slicing Object → VMR
5. Highlight all the VOIs desired.
6. Click on the mark clusters in current voi in vmr (top button in Cluster/VOI menu options)
7. If smoothing is desired, set resolution of stats to 2 or 3 (approx), and change code to 200 instead of 240.
   1. Click on smooth volume (grey S in the display menu).
   2. Set kernel to say, 3 (approx).
8. If no smoothing, leave at 240 and use as is.
9. If smoothed, then reset contrast/brightness values.
10. Click on the C/B button in the lower right display menu.
11. Set from 0 to max value used (e.g. 200)
12. Then use the slider on the right to set the actual boundary for the cluster sizes.
13. Finally, vmp → mask with vmr

1. Starting with your meta-analysis in an xls sheet…
2. The header row must have: Study, x, y, z
3. Study must be a string… to ensure this, add a dummy string prior to each study name e.g. 's_<study name>'
4. It should also have: CoordSys with “T88” or “MNI” tokens, it will be converted to MNI during import
5. The header row may optionally and usefully have: N (nr of subjects), FixedRandom (0/1 coding of FFX or RFX)
6. Should also have header variables for contrast info…
7. Should only use NaN for columns with numeric values (don't use NaN with string columns)
8. If a column has 'yes' and 'no' values only, it will be recoded into 1/0. BUT, if you have 'yes' and 'no' and other kinds of codes (e.g. 'maybe', 'missing', 'both', or what have you), you should recode the 'yes' and 'no' to something else.
9. Make sure you have a place holder for empty cells or missing values (and not NaNs unless it's a numeric column). E.g. “MISSING”
10. Do not have any empty columns included.
11. Now save your data as a .csv file from Excel.
12. Rename as a .txt file.
13. Open up the .txt file in matlab, delete anything weird (e.g. trailing commas), then re-save it.
14. I recommend trying to load it up using the command line instead of in the gui until you get it down- that way you can trouble shoot. It's not too hard to trouble shoot if you have some basic matlab skills so don't be intimidated. The command is something like: plp = importplpfrommkdadb(infile, opts); where infile is the name of your txt file as a string and opts can be empty []. Once you get that to work and produce a plp, then you're in business.
15. After performing a contrast, you'll see some results stored as multiple VMPs in the GUI. One VMP has each study and its contributing points and the statistical maps at the end. Another VMP has only the statistical maps.
16. You'll then want to threshold it. Among the statistical maps, there will be three: a proportion map, a z-stat map, and a third baseline map. The maps should already be cluster-level thresholded (based on whatever number you put in as the sampling distribution, e.g. 5,000 in the meta-analysis dialogue box). To access these corrected thresholds, click on the promotion map, one-tailed, and check mark the k-extent box. Then, click on the p value and the k-extent should be auto-filled.
17. For statistical maps involving a single condition (e.g. “positive valence”), interpretation is relatively straight forward.
18. But, for statistical maps involving comparisons between conditions (e.g. “positive vs. negative valence”), the interpretation is more complicated. This is particularly the case if there are many more contrast maps for one condition over another (which is often the case). E.g. if I had 200 contrasts for negative, but only 100 for positive. In this situation, inference may best involve three phases: 1. look at each individual map alone, 2. look at the difference map using a difference in proportion, 3. look at the 'label shuffling' approach implemented in neuroelf.

It's annoying, but NeuroElf's command line interface doesn't allow the usual Matlab syntax to access the members of a multi-dim struct as in

vtcs = {glm.Study.NameOfAnalyzedFile};

instead, what you have to do is a two step procedure:

ajay_scopeobjectinfo.m

% if glm is a GLM object, first get a variable that's the struct
study = glm.Study;
 
% then do the access
vtcs = {study.NameOfAnalyzedFile};

NeuroElf accommodates both T88 and MNI formats, and has a toggle feature to be able to go back and forth between them. If you use the standard SPM5 preprocessing options, the data will be normalized to MNI space. Then, keep in mind the following two toggles in the gui [icbm2tal] and [TDclient]. Rules:

1. If icbm2tal is on, it will transform coordinates from MNI into T88 space in the output boxes on the left of the gui.
2. If you want to use the TDclient, make sure icbm2tal is clicked on.

Verify the parameters for you GLM. In the command line, once you load the glm (E.g. by using »glm = xff('*.glm')), you can ensure the parameters (e.g. motion correction as covariates, percent signal change transform, filter type and implementation, etc.) using the following two locations in the glm object.

1. glm.Study(1).RunTimeVars.Predictors'
2. glm.RunTimeVars

Sometimes we may want to run multiple glms changing one or another option. If so, BE SURE TO DO THESE TWO THINGS:

1. clear the object between analyses. glm.ClearObject; mdm.ClearObject;
2. 'bless' the command where you run the mdm: glm = bless(mdm.ComputeGLM(opts));

A second potential error when making a glm is to not set the options structure correctly. Specifically, for realignment parameters or any other cell array input into the opts structure, you must enclose it in curly brackets:

1. CORRECT: struct('tfilter',200,'tfilttype','dct','motpars',{rps})
2. INCORRECT: struct('tfilter',200,'tfilttype','dct','motpars',rps)
3. where rps is a cell array pointing to files name for realignment parameters
4. VERIFY YOUR GLM using the methods indicated above.

If your scripting is running inordinately slow, it may be because NeuroElf is loading, closing, and re-loading relevant data for a given step in your code. For example, when obtaining the betas from a glm for a set of vois, if you iterate across the vois to load the GLM, then it may reload all the GLM data each time. This is because NeuroElf runs efficiently by not loading up all the data unless it really needs to, but if you're coding, then you need to specify that. Use the following:

 >>glm.LoadTransIOData

Neuroelf has export functions in the gui menus. The default options for some of these didn't work well for FSLview. To deal with this, be sure to use a recent version of NeuroElf (12/12/12 or later).

1. vmp.ExportNifti('NIFTI_FILE.nii', true);
2. where the second argument, true, makes the output be written in TAL order, such that it complies with FSL's internal preference.
3. also works with vtc, glm, etc.