Selxavg3-sess

Before you begin

Ensure that your BOLD data has the correct timing info. See Freesurfer BOLD files for information on changing the TR for your data. If your BOLD data files are not named 'f.nii', you likely have missed a step.

Running selxavg3-sess

This command runs a GLM regression on the BOLD time series for each run separately. This creates a 3D file that stores a statistic for each voxel for each experimental run that indicates how well the activity for that voxel conformed with a predicted time series associated with each of your experimental conditions. Assuming you have run all the previous steps in the FS-FAST overview, there will be one, two or three analysis directories in your $SUBJECTS_DIR, generated by mkanalysis-sess. These directories will contain all the information to perform surface-space analyses in your left/right or mni305 (voxel-space, for subcortical regions which are not included in the surface models) models. If you have configured contrasts using mkcontrast-sess, then selxavg3-sess will perform the statistical condition contrasts you had specified in that step.

Batch mode

If you want to run the same analysis on multiple participants in batch mode, you must first create a plain text file containing all the participant IDs (i.e., the folder names) for those you wish to analyze. If you ran preproc-sess in batch mode, then you can simply reuse the sessid file you created for that purpose. See the preproc-sess instructions for creating that file. Batch mode uses the -sf switch, which is the same as the switch used for running preproc-sess in batch mode.

selxavg3-sess -sf <sessid_file> -analysis <analysis_dir>

Individual mode

Alternatively, you may run the analysis on one participant at the time using the -s switch, and providing a single participant ID name.

selxavg3-sess -s <sessid> -analysis <analysis_dir>

Example

Here, we are going to run selxavg3-sess on a single participant (FS_0001) for the analysis configuration found in the folder $SUBJECTS_DIR/LDT.sm6.lh

selxavg3-sess -s FS_0001 -analysis LDT.sm6.lh

Note that the analysis folder indicated in this example is configured only for the left hemisphere. You would most likely want to run this command a second time, but specify the configuration for the right hemisphere.

Troubleshooting

ERROR: fast_selxavg3()

ERROR: fast_selxavg3() failed\n

Leading up to the error message, we see a message Subscript indices must either be real positive integers or logicals.

When we see messages that refer to indices in the context of an error message, this is often symptomatic of a mismatch between the amount of data available, and the data access request. For example, if only 252 volumes of data are present (numbered 1, 2, ..., 252) but a script or function is asked to access volume 253 or volume 0, then this will likely generate an error.

If the same processing steps work fine with some data, but generate the above error for a particular dataset, check to see that there isn't something funny with the data. One potential culprit is the early termination of the BOLD sequence. For the LDT, which is self-paced, there were a few runs where the MRI acquisition stopped before the task ended. In this case, the timestamps for that data will make reference to points in time outside of the scope of the MRI data.

Solution

Try manually editing the .par file by removing timestamps outside of the MRI acquisition. You will have to do some math (TR × Number of Volumes) to figure out what the last valid timestamp would be.

editfslhd f.nii

For FS_0092, we see

nt = '252'
...
dt = '2.047'

So the latest possible timepoint is 515.8. Any .par file events past this point are not in the data.

Also, while editing the .par file, ensure that any NaN values are set to a real number, which, now that I think of it, is another potential culprit (since NaN is neither a real positive integer or logical). The FSTSExtractor.m script uses RT as the event duration, but this value is set to NaN if the participant didn't respond. Set the NaN value to 0, but also set the weight (the last column) to 0 so that these null events aren't modeled.

An update to the FSTSExtractor function will need to be made so that this problem doesn't pop up, but in the meantime, ensuring that the .par file timestamps are sensible and contain no NaN values fixes this problem. A fast way to find any NaN values:

grep "NaN" `find ./ -name "LDT.par"`

Check your results

You can look at the contrast results in the surface model in tksurfer. First, load the surface you want to overlay your results on. All of our examples have been done using the self surface, but it is possible to instead map data to the fsaverage template, which facilitates comparisons between individuals.

tksurfer FS_T1_501 lh pial

Next, you will load the relevant statistical overlay. This file will be found in the subject folder in the bold subdirectory, which has an analysis folder for each analysis that you ran with selxavg3-sess. In this example, there are two folders:

• $SUBJECTS_DIR
  • FS_T1_501
    • bold
      • booth500.sm6.lh
      • booth500.sm6.rh

In each of these analysis folders are several compressed .nii.gz files. The statistical overlay you will want to overlay will depend on your interests, but most likely you will want to open up a diagnostic (i.e., easily interpretable) contrast map, which you will find in subdirectories within each of the analysis directories. In my case, I had run a word_vs_fix contrast which generated a t-statistic and f-statistic map. I chose to load the t-map for my left-hemisphere surface. To do so, I did the following:

1. File>Load Overlay...
2. Browse to $SUBJECTS_DIR/FS_T1_501/bold/booth500.sm6.lh/word_vs_fix/t.nii.gz
3. Additional Registration information may be required to map each of the voxels on to your surface space.
   • When mapping voxels onto a self surface, it's safe to select the Find registration in data directory
   • When mapping voxels onto fsaverage, you can select the Compute Identity Matrix registration option.
4. Click the OK button. In a moment you should see hot- and cold- colored blobs overlaid on the surface model. Depending on the nature of the contrast and your experience, you might be able to use this overlay to assess whether the data look reasonable. For example a contrast between button-press trials and rest should probably show a robust activation in left motor cortex (assuming right-handed participants).