CCN Wiki - User contributions [en]

3D Brain Models

2019-05-29T15:18:54Z

Erica: /* Use srf2obj to create a Blender-Compatible File */

This page is all about turning FreeSurfer surface files into 3D printable models.
Inspiration comes from [https://brainder.org/2012/05/08/importing-freesurfer-cortical-meshes-into-blender/ here]

=Free Surfer=
==Create a WaveFront OBJ File==
Use mris_convert to convert from FreeSurfer binary to ASCII:
mris_convert lh.pial lh.pial.asc
Repeat for both hemispheres

==Rename Files==
mv lh.pial.asc lh.pial.srf
Repeat for both hemispheres

==Use srf2obj to create a Blender-Compatible File==
The srf2obj script requires the installation of gawk if it's not already installed. The script can be found in the '''scripts/Shell''' folder on ubfs, and should be in your path (copy it to your ~/bin directory if you don't already have it).
srf2obj lh.pial.srf > lh.pial.obj

=Blender=
After creating the pial layer hemisphere's in FreeSurfer, you're next going to want to import one file at a time into Blender. Once the file has been imported there should be a gray brain mesh on the screen in Blender. To make working with the mesh easier you can change it's size by going to the bottom left-hand side of the page and change the X, Y, and Z coordinates to 1.0. Once they are all at 1.0 the brain will be much smaller and fit nicely within the provided grid. You can use the rotate and transform tools on the left-hand side of the screen to move and change the direction of the brain. To the best of your ability, try to get the brain level on all planes in a way similar to it's real life orientation. After the first hemisphere is in place do the exact same process with the other hemisphere. Once both halves are of the same size and orientation, try to align them next to each other as best as possible and join the halves into one object by right clicking on one half, then hold shift down and right click on the other. After both hemispheres are selected you just have to press CTRL + J, and the two halves should become one mesh.
===3D Printing===
The 3D printers at UB use a multitude of files, but all of the printers will accept .stl files (which Blender will let you directly export any file as that).
Before printing you will need to fix your STL files using the Netfabb online service (requires a free autodesk account)
https://service.netfabb.com/login.php

3D Brain Models

2019-05-29T15:18:22Z

Erica: /* Free Surfer */

This page is all about turning FreeSurfer surface files into 3D printable models.
Inspiration comes from [https://brainder.org/2012/05/08/importing-freesurfer-cortical-meshes-into-blender/ here]

=Free Surfer=
==Create a WaveFront OBJ File==
Use mris_convert to convert from FreeSurfer binary to ASCII:
mris_convert lh.pial lh.pial.asc
Repeat for both hemispheres

==Rename Files==
mv lh.pial.asc lh.pial.srf
Repeat for both hemispheres

==Use srf2obj to create a Blender-Compatible File==
The srf2obj script requires the installation of gawk if it's not already installed. The script can be found in the '''scripts/Shell''' folder on ubfs, and should be in your path (copy it to your ~/bin directory if you don't already have it).
srf2obj filename

=Blender=
After creating the pial layer hemisphere's in FreeSurfer, you're next going to want to import one file at a time into Blender. Once the file has been imported there should be a gray brain mesh on the screen in Blender. To make working with the mesh easier you can change it's size by going to the bottom left-hand side of the page and change the X, Y, and Z coordinates to 1.0. Once they are all at 1.0 the brain will be much smaller and fit nicely within the provided grid. You can use the rotate and transform tools on the left-hand side of the screen to move and change the direction of the brain. To the best of your ability, try to get the brain level on all planes in a way similar to it's real life orientation. After the first hemisphere is in place do the exact same process with the other hemisphere. Once both halves are of the same size and orientation, try to align them next to each other as best as possible and join the halves into one object by right clicking on one half, then hold shift down and right click on the other. After both hemispheres are selected you just have to press CTRL + J, and the two halves should become one mesh.
===3D Printing===
The 3D printers at UB use a multitude of files, but all of the printers will accept .stl files (which Blender will let you directly export any file as that).
Before printing you will need to fix your STL files using the Netfabb online service (requires a free autodesk account)
https://service.netfabb.com/login.php

Neural Networks in Python

2019-04-26T14:35:09Z

Erica: /* A Simple Feedforward Classifier Network */

=Before You Begin=
We've been using the Keras API with the TensorFlow backend for our simulations. Our code often also uses the numPy and SciKit libraries because I often steal code examples that happen to have been coded using those libraries. When you get started, you will want to make sure that all the requisite libraries are installed. Pip (the Python package installer) has a function called <code>freeze</code> that will list all your installed libraries. This list can be dumped to a text file and used to share the list of Python packages you'll need to run any of the code we've developed:
pip freeze > requirements.txt
Now any lab member can use '''requirements.txt''' to ensure they have the requisite Python packages installed:
pip install -r requirements.txt
I've got the current list of dependencies on ubfs/Scripts/Python/requirements.txt
=A Simple Feedforward Classifier Network=
Keras has defined network templates, but the only one that I've seen well-documented is the '''forward'' model. Fortunately, the forward model is well-suited to the classification task: it takes a set of input values, feeds the values forward over a set of layers, and checks the output values in a set of binary classification units. If the output decision is strictly binary (A vs B), then one output unit will suffice (since it's a zero-sum decision). If 3+ output categories are possible, then there needs to be an output unit for each possible category.

import numpy as np
import keras
import time
import scipy.io as sio
from keras.layers import Input,Dense,Dropout
from keras.models import Model, Sequential, load_model
from keras.regularizers import l1
from keras.optimizers import Adadelta
from sklearn.model_selection import StratifiedKFold as SKF
from sklearn.model_selection import ShuffleSplit as SS

import read_activations as reader

seed=int(time.time())
np.random.seed(seed)

trainfile='av_hi.csv'
traindata=np.genfromtxt(trainfile, delimiter=',')
testdata=(traindata)

x_train=traindata[:,0:-1]
y_cat_code=testdata[:,-1]
#this next line converts the category codes of 1,2,3 into 3 separate output units so that
#a code of 1 maps to {1,0,0}, 2 maps to {0,1,0} and 3 maps to {0,0,1}
y_cat_train=keras.utils.to_categorical(y_cat_code, num_classes=3)

encoding_dim1=96
encoding_dim2=32
input_trials, inodes = x_train.shape

foldnumber=0
fp=open('perflog.txt', 'w')
hfp=open('cat_traininghist.txt', 'w')

kfold = SKF(n_splits=8, shuffle=True, random_state=seed)
for train, test in kfold.split(x_train, y_cat_code):
foldnumber=foldnumber+1
ada=keras.optimizers.Adadelta(lr=1, rho=0.9, decay=1e-6)

#input layer: a series of 1000 floats from 0.0 to 1.0
main_input=Input(shape=(inodes,), dtype='float32', name='input')

#first dropout layer, initially, lets randomly drop 20% of values
dropout_1=Dropout(0.2, input_shape=(inodes,), name='dense_1_drop')(main_input)

#noise layer to mitigate overfitting
noise_1=keras.layers.noise.GaussianNoise(0.05, input_shape=(inodes,), name='dense_1_noise')(dropout_1)

#first hidden layer
dense_1=Dense(encoding_dim1, activation='relu', input_dim=inodes,
name='dense_1', kernel_regularizer=l1(0.00001))(noise_1)

#second hidden layer
dense_2=Dense(encoding_dim2, activation='relu', name='dense_2')(dense_1)
#category output layer
cat_output=Dense(3, activation='softmax', name='cat_output')(dense_2)

#assemble the model
model=Model(inputs=[main_input], outputs=[cat_output])
#compile the model
model.compile(optimizer='adadelta',
loss=['categorical_crossentropy'],
metrics=['accuracy'], loss_weights=[1])

X_train=x_train[train]
X_test=x_train[test]
Y_cat_train=y_cat_train[train]
Y_cat_test=y_cat_train[test]

xrows, xcols = X_test.shape
history=model.fit(X_train, [Y_cat_train],
validation_split=0.2,
epochs=64,
batch_size=32,
shuffle=True,
verbose=0)
trainscore = model.evaluate(X_test, [Y_cat_test], verbose=0)
outstr='%.2f\n' % trainscore[1]
print outstr
fp.write(outstr)
fname='model_' + format(foldnumber, '02') + '.h5'
model.save(fname) #save the trained model

#training history
vals=history.history['val_acc']
strlist= ['{:.3f}'.format(x) for x in vals]
hfp.write('\n' + ','.join(strlist))

print model.summary()
fp.close()
hfp.close()

Connectivity Toolbox

2018-11-07T17:46:45Z

Erica: /* Processing options */

The '''conn''' Functional Connectivity toolbox is a MATLAB-based program that hijacks SPM to do some data de-noising and remove potential artefacts that might skew your connectivity data. It is somewhat geared towards voxel-space analyses, but can support the surface-space analyses that we typically do in our lab. The walkthrough below is geared towards running '''conn''' on your FreeSurfer data.

=Preconditions=
These instructions assume that you have functional and anatomical data organized in the manner that FreeSurfer expects, and that you have completed the autorecon steps on the T1 anatomical file and have generated the surface meshes for your target participants. These instructions will also assume that you have dropped some number of initial volumes from the BOLD runs (usually the first 4) if required. If working from the raw data archived from the CTRC scanner, this will be a required step; if you are working with BOLD data that has already been analyzed, or preprocessed this may already have been done, and you will ''not'' want to drop ''yet another'' initial 4 volumes!

Because conn runs on top of SPM, you need to ensure that SPM is in your MATLAB path. Of course, conn also needs to be in your path. Check that they are using the <code>which</code> command in the MATLAB command window:
>> which spm
/opt/spm12/spm.m
>> which conn
/opt/conn/conn.m

If you see the paths to both .m files, you can run conn from the MATLAB command window:
>> conn

=Setup in CONN=
My goal here isn't going to be to duplicate the [https://web.conn-toolbox.org/resources/manuals conn user manual], and we're not going through an entire functional analysis. But you have to start somewhere, so here we are...

When you launch conn, you will get a nice gui window with a menu bar along the top. We want to start a new project:
'''Project > New (blank)'''
You will get a uiwindow that asks where you want to save the project details. You can save this .mat file wherever you like, though I would recommend somewhere near your $SUBJECTS_DIR for the project. Next you will have to specify parameters for setting up the analysis

==Basic information==
The first uiwindow you need to populate has some general experimental setup information:
===Number of subjects===
Indicate here how many subjects you wish to process. This will tell conn how many datasets to expect. You don't even have to add everyone in the experiment to the analysis: If you have FreeSurfer data for 10 people, but just want to process 1 or two people, then just indicate that there are 1 or 2 subjects.
===Number of session===
By this, they mean functional runs. Our Imagery experiment has 2 visits with 6 functional runs each. If someone completed both visits, they would have 12 sessions worth of data. As with the subjects parameter, you don't have to use all the runs. You might wish to just analyze the 6 runs from the first visit, in which case you would say there are 6 sessions. The program will almost certainly crash if some runs are missing for some participants because it will expect the same amount of data for each participant. You will need to separately process individuals with missing runs.
===Repetition Time (seconds)===
This is our experimental TR. For the Imagery study, our TR is approximately 2 seconds (2.047, to be precise). For other data, the TR may be different, though a 2-second TR is common.

===Acquisition type===
Leave it as the default, Continuous, which means the scanner is continuously acquiring BOLD data throughout the run. It's unlikely that you'll be analyzing data collected using sparse sampling.

==Structural data==
Here is where you have to find the T1 and surface files for your participants, which are found in the 'mri' directory for each participant. They made the program clever enough to do pattern matching, so if you pick a root directory, and then indicate the file pattern for the structural data, it will find all the matching files. For example, if you left-click on your $SUBJECTS_DIR, type in T1.mgz and click the '''Find''' button , it will identify the paths to all the structural files generated by FreeSurfer. From there, you highlight the files you wish to work with and click the Select button (make sure the number of selected files matches the number of highlighted Subjects). If the T1 data have already been preprocessed with FreeSurfer, you should be asked if you wish to also import the segmentation files. Say '''Yes'''.

One thing I will point out is that our FreeSurfer analyses are done in surface space, which doesn't care about where the particular voxels sit in relation to the cube of voxels surrounding the standard MNI template brain. For that reason, your structural and functional data will seldom be even close to aligned with the MNI brain. This isn't usually a problem, but I'm now considering coregistration of the data (but not spatial normalization) as a routine preprocessing step. Stay tuned.

==Functional data==
This works pretty much the same as selecting your structural data. Following our FreeSurfer conventions, you will be working with the f.nii.gz data (the zipped data will be automatically unzipped). Make sure that these data have already had the first 4 volumes dropped and that the slice timing and TR information has already been fixed in the header (see the page on [[Freesurfer BOLD files]]).

==ROIs==
Here we indicate regional sources of variance that will be used to denoise our data. By default conn has selected Grey and White matter, CSF, atlas and networks. We wish to extract the average timeseries for the Grey matter, the Principle Component Analysis signal from White matter and CSF. We can remove the atlas and networks ROIs from the list of ROIs we care about so that we only have the first 3.

There's a checkbox for regressing out covariates before regressing out the PCA noise covariates, but I don't see any reason to use that option.

==Conditions==
This is set up by default to only include a rest condition that spans the entire run, as if it's resting state data. But we're working with task data using a mixed design, where we might add the event or block onsets. The thing is, I don't know that we want to have conn do any funny business with each of our conditions because I'm only using the program for preprocessing, and not analysis. It would be catastrophic to regress out the condition-related signal that you're actually trying to study!

It turns out that you have to have at least 1 condition specified, so you can use the rest condition as a placeholder.

==Covariates (1st-level)==
This would be timeseries related covariates, like motion parameters or perhaps if you wanted to exclude the onsets of button presses based on the runtime RT data. We can leave this blank unless we have a reason to get fancy.

==Covariates (2nd level)==
These are participant-level covariates (e,g. age, task performance, etc.), though if you're studying individual differences, these may be precisely the factors you're interested in, so you wouldn't want to regress those out. The AllSubjects covariate is added by default, but that's fine, because it's just a vector of 1s, and therefore does not covary with anything.

==Processing options==
Almost there!
===Enabled analyses===
Check that we want to do Voxel-to-Voxel analyses
Other analyses maybe checked by default, unless otherwise specified we only care about Voxel-to-Voxel.
===Optional output files===
check that we create confound-corrected beta-maps and confound-corrected time-series (our primary objective for using conn).
===Analysis space (voxel-level) ===
Select ''Volume: same as functionals'' so that conn doesn't resample the data. I made the mistake of saying that analyses would be done in FreeSurfer's fsaverage space, and it totally mangled the data by throwing away all the spatial information about the voxels (it produced a time-series cube, which is decidedly not brain-shaped).

===Analysis mask (voxel-level)===
Select Implicit mask (subject-specific) because our subjects voxels are not guaranteed to fall within the template brainmask.

===Second_Level Analyses===
Second level analyses is another option in the option menu. Unless otherwise specified you can ignore this option.

===BOLD signal units===
Let's use Raw signal.

==Preprocessing==
Click the green Preprocessing button to bring up a uidialogbox to select a processing pipeline. We wish to use the preprocessing pipeline for sufface-based analyses in subject space. This will populate the window of processing steps. Note that we already have our structural segmentation from FreeSurfer, so you can go ahead and remove that last item from the prepopulated list. Click '''Start'''.
===Slice timing window===
You'll be asked for the slice order. Data from the CTRC used '''interleaved top-down'''
===Functional outlier detection===
If ART is in your pipeline (it likely will be if you did what I described above), here is where you set the threshold for detecting "bad" volumes. Intermediate is probably perfectly reasonable.

=Denoising (1st level)=
A bunch of data preprocessing will happen over the next 15 minutes or so (1 subject, 6 runs) after you click DONE on the setup process. A status window gives you updates on what steps in the preprocessing pipeline are executing. Once it's finished, you find yourself in the Denoising step.

In this step, you can remove confounds from your data, and see the effect on the distribution of connectivity values in the window area on the right. Before denoising, there is generally a positive bias on your connectivity values, and you should find the denoised data to be 0-centered and a narrower distribution across all your sessions. You can also see how the sessions differed within individuals, so that's somewhat interesting. Anyways, at this point, we select which confounds we want to remove from our data:
==White Matter==
Removes the WM timeseries ICA, by default set to 5 component decompsition. The number of compoments can be changed (try increasing it from 5 to 10) if the denoised distribution is still biased.
==CSF==
Likewise, this removes the CSF timeseries, also set to a 5 component ICA.
==Realignment==
Regresses out the 6 parameter motion correction parameters and by default adds their first order derivatives (for a total of 12 parameters).
==Scrubbing==
Regresses out whether the data were flagged for outlier scrubbing by ARTRepair
==Effect of Condition (e.g., rest, dummy, task)==
If we're just looking to use conn to remove noise from our data, and especially if we have task-related data, I don't think it makes sense to remove the experimental design from our data as a confound., so highlight this entry right click on the right angle (''>'') bracket that appears between the columns.

==Band-pass filter==
Removes signal that falls outside the high- and low-end of the frequency range. These values are expressed in Hz, or cycles per second. As a postdoc, I saw first hand what happens if you don't give this some consideration. Suppose you have a block design, where each block is, say 40 seconds long. So any signal that is dependent on the block will appear at a frequency that matches the block frequency. If it takes 40 seconds for 1 block to coomplete, then the block frequency, in cycles per second is 1/40 = .025 Hz. The default Band-pass filter window goes from .008 Hz (1/125 seconds) to .09 (1/11 seconds). Our 40 second block signal would be safe within this range, but if you were to change the low-frequency number to .03 (1/30 seconds), then you'd end up filtering out your block signal, which may not be something you want to do.

==Click the Done Button==
Do it to begin the denoising pipeline. Go make yourself a sandwich.

=Obtaining Denoised Time-Series Data=
Your project folder will contain a data/ folder full of output files produced during all the above steps. Of interest are the series of .matc files. '''conn''' ships with a conversion utility, <code>conn_matc2nii</code> that will convert the .matc file for a session into a .nii file:
>> conn_matc2nii('DATA_Subject001_Session001.matc', false)
>> %the second parameter is optional and indicates whether to display a waitbar. By default, this is set to false.

After you execute this command in MATLAB, you'll end up with a file with the same name, except with a .nii extension.
Now, at this point, you probably started off with an f.nii.gz file, and now have a DATA_Subject'xxx'_Session'yyy'.nii file. In order to look at this newly denoised data in FreeSurfer, you will need to run it through the FS-FAST preproc-sess step. There's a good chance the source directory already has an f.nii.gz file, as well as a series of fmcpr.''${direction}''.sm''${smoothing}''.fsaverage.?h.nii.gz files. Assuming you want to hold on to these, I'd make a backup directory in each of the run subdirectories, and move all files to the backup directory (you can keep any .par files here). After you've backed everything up, move the new denoised files into the appropriate directories and rename them to f.nii. When you redo the preproc-sess step, make sure you do not apply slice-time correction, because this has already been applied to the denoised data:

preproc-sess -s FS_0231 -per-run -surface fsaverage lhrh -mni305 -fwhm 4 -fsd bold

The departure from the other wiki entry on preproc-sess is that we do not use the -sliceorder flag on the denoised data. Other than that, just process the denoised functional data like you would any other data. When done, you'll have a set of fmcpr.${smooth}.fsaverage.?h.nii.gz (they will no longer have the word 'down' in the filename, so you may have to modify some of your later analysis or data processing scripts accordingly -- just be on the lookout for ''file not found'' errors, and if they pop up, the first thing you should look for is to see if your command or script was expecting a filename with the slice order). Of course, another option would be to manually rename the preprocessed data when preproc-sess is completed, so that the preprocessed denoised data still includes the sliceorder in the name. I'm not sure how big of a problem this minor change in filename is going to be for our various scripts.

Connectivity Toolbox

2018-11-07T17:41:41Z

Erica: /* Structural data */

The '''conn''' Functional Connectivity toolbox is a MATLAB-based program that hijacks SPM to do some data de-noising and remove potential artefacts that might skew your connectivity data. It is somewhat geared towards voxel-space analyses, but can support the surface-space analyses that we typically do in our lab. The walkthrough below is geared towards running '''conn''' on your FreeSurfer data.

=Preconditions=
These instructions assume that you have functional and anatomical data organized in the manner that FreeSurfer expects, and that you have completed the autorecon steps on the T1 anatomical file and have generated the surface meshes for your target participants. These instructions will also assume that you have dropped some number of initial volumes from the BOLD runs (usually the first 4) if required. If working from the raw data archived from the CTRC scanner, this will be a required step; if you are working with BOLD data that has already been analyzed, or preprocessed this may already have been done, and you will ''not'' want to drop ''yet another'' initial 4 volumes!

Because conn runs on top of SPM, you need to ensure that SPM is in your MATLAB path. Of course, conn also needs to be in your path. Check that they are using the <code>which</code> command in the MATLAB command window:
>> which spm
/opt/spm12/spm.m
>> which conn
/opt/conn/conn.m

If you see the paths to both .m files, you can run conn from the MATLAB command window:
>> conn

=Setup in CONN=
My goal here isn't going to be to duplicate the [https://web.conn-toolbox.org/resources/manuals conn user manual], and we're not going through an entire functional analysis. But you have to start somewhere, so here we are...

When you launch conn, you will get a nice gui window with a menu bar along the top. We want to start a new project:
'''Project > New (blank)'''
You will get a uiwindow that asks where you want to save the project details. You can save this .mat file wherever you like, though I would recommend somewhere near your $SUBJECTS_DIR for the project. Next you will have to specify parameters for setting up the analysis

==Basic information==
The first uiwindow you need to populate has some general experimental setup information:
===Number of subjects===
Indicate here how many subjects you wish to process. This will tell conn how many datasets to expect. You don't even have to add everyone in the experiment to the analysis: If you have FreeSurfer data for 10 people, but just want to process 1 or two people, then just indicate that there are 1 or 2 subjects.
===Number of session===
By this, they mean functional runs. Our Imagery experiment has 2 visits with 6 functional runs each. If someone completed both visits, they would have 12 sessions worth of data. As with the subjects parameter, you don't have to use all the runs. You might wish to just analyze the 6 runs from the first visit, in which case you would say there are 6 sessions. The program will almost certainly crash if some runs are missing for some participants because it will expect the same amount of data for each participant. You will need to separately process individuals with missing runs.
===Repetition Time (seconds)===
This is our experimental TR. For the Imagery study, our TR is approximately 2 seconds (2.047, to be precise). For other data, the TR may be different, though a 2-second TR is common.

===Acquisition type===
Leave it as the default, Continuous, which means the scanner is continuously acquiring BOLD data throughout the run. It's unlikely that you'll be analyzing data collected using sparse sampling.

==Structural data==
Here is where you have to find the T1 and surface files for your participants, which are found in the 'mri' directory for each participant. They made the program clever enough to do pattern matching, so if you pick a root directory, and then indicate the file pattern for the structural data, it will find all the matching files. For example, if you left-click on your $SUBJECTS_DIR, type in T1.mgz and click the '''Find''' button , it will identify the paths to all the structural files generated by FreeSurfer. From there, you highlight the files you wish to work with and click the Select button (make sure the number of selected files matches the number of highlighted Subjects). If the T1 data have already been preprocessed with FreeSurfer, you should be asked if you wish to also import the segmentation files. Say '''Yes'''.

One thing I will point out is that our FreeSurfer analyses are done in surface space, which doesn't care about where the particular voxels sit in relation to the cube of voxels surrounding the standard MNI template brain. For that reason, your structural and functional data will seldom be even close to aligned with the MNI brain. This isn't usually a problem, but I'm now considering coregistration of the data (but not spatial normalization) as a routine preprocessing step. Stay tuned.

==Functional data==
This works pretty much the same as selecting your structural data. Following our FreeSurfer conventions, you will be working with the f.nii.gz data (the zipped data will be automatically unzipped). Make sure that these data have already had the first 4 volumes dropped and that the slice timing and TR information has already been fixed in the header (see the page on [[Freesurfer BOLD files]]).

==ROIs==
Here we indicate regional sources of variance that will be used to denoise our data. By default conn has selected Grey and White matter, CSF, atlas and networks. We wish to extract the average timeseries for the Grey matter, the Principle Component Analysis signal from White matter and CSF. We can remove the atlas and networks ROIs from the list of ROIs we care about so that we only have the first 3.

There's a checkbox for regressing out covariates before regressing out the PCA noise covariates, but I don't see any reason to use that option.

==Conditions==
This is set up by default to only include a rest condition that spans the entire run, as if it's resting state data. But we're working with task data using a mixed design, where we might add the event or block onsets. The thing is, I don't know that we want to have conn do any funny business with each of our conditions because I'm only using the program for preprocessing, and not analysis. It would be catastrophic to regress out the condition-related signal that you're actually trying to study!

It turns out that you have to have at least 1 condition specified, so you can use the rest condition as a placeholder.

==Covariates (1st-level)==
This would be timeseries related covariates, like motion parameters or perhaps if you wanted to exclude the onsets of button presses based on the runtime RT data. We can leave this blank unless we have a reason to get fancy.

==Covariates (2nd level)==
These are participant-level covariates (e,g. age, task performance, etc.), though if you're studying individual differences, these may be precisely the factors you're interested in, so you wouldn't want to regress those out. The AllSubjects covariate is added by default, but that's fine, because it's just a vector of 1s, and therefore does not covary with anything.

==Processing options==
Almost there!
===Enabled analyses===
Check that we want to do Voxel-to-Voxel analyses
===Optional output files===
check that we create confound-corrected beta-maps and confound-corrected time-series (our primary objective for using conn).
===Analysis space (voxel-level) ===
Select ''Volume: same as functionals'' so that conn doesn't resample the data. I made the mistake of saying that analyses would be done in FreeSurfer's fsaverage space, and it totally mangled the data by throwing away all the spatial information about the voxels (it produced a time-series cube, which is decidedly not brain-shaped).

===Analysis mask (voxel-level)===
Select Implicit mask (subject-specific) because our subjects voxels are not guaranteed to fall within the template brainmask.
===BOLD signal units===
Let's use Raw signal.

==Preprocessing==
Click the green Preprocessing button to bring up a uidialogbox to select a processing pipeline. We wish to use the preprocessing pipeline for sufface-based analyses in subject space. This will populate the window of processing steps. Note that we already have our structural segmentation from FreeSurfer, so you can go ahead and remove that last item from the prepopulated list. Click '''Start'''.
===Slice timing window===
You'll be asked for the slice order. Data from the CTRC used '''interleaved top-down'''
===Functional outlier detection===
If ART is in your pipeline (it likely will be if you did what I described above), here is where you set the threshold for detecting "bad" volumes. Intermediate is probably perfectly reasonable.

=Denoising (1st level)=
A bunch of data preprocessing will happen over the next 15 minutes or so (1 subject, 6 runs) after you click DONE on the setup process. A status window gives you updates on what steps in the preprocessing pipeline are executing. Once it's finished, you find yourself in the Denoising step.

In this step, you can remove confounds from your data, and see the effect on the distribution of connectivity values in the window area on the right. Before denoising, there is generally a positive bias on your connectivity values, and you should find the denoised data to be 0-centered and a narrower distribution across all your sessions. You can also see how the sessions differed within individuals, so that's somewhat interesting. Anyways, at this point, we select which confounds we want to remove from our data:
==White Matter==
Removes the WM timeseries ICA, by default set to 5 component decompsition. The number of compoments can be changed (try increasing it from 5 to 10) if the denoised distribution is still biased.
==CSF==
Likewise, this removes the CSF timeseries, also set to a 5 component ICA.
==Realignment==
Regresses out the 6 parameter motion correction parameters and by default adds their first order derivatives (for a total of 12 parameters).
==Scrubbing==
Regresses out whether the data were flagged for outlier scrubbing by ARTRepair
==Effect of Condition (e.g., rest, dummy, task)==
If we're just looking to use conn to remove noise from our data, and especially if we have task-related data, I don't think it makes sense to remove the experimental design from our data as a confound., so highlight this entry right click on the right angle (''>'') bracket that appears between the columns.

==Band-pass filter==
Removes signal that falls outside the high- and low-end of the frequency range. These values are expressed in Hz, or cycles per second. As a postdoc, I saw first hand what happens if you don't give this some consideration. Suppose you have a block design, where each block is, say 40 seconds long. So any signal that is dependent on the block will appear at a frequency that matches the block frequency. If it takes 40 seconds for 1 block to coomplete, then the block frequency, in cycles per second is 1/40 = .025 Hz. The default Band-pass filter window goes from .008 Hz (1/125 seconds) to .09 (1/11 seconds). Our 40 second block signal would be safe within this range, but if you were to change the low-frequency number to .03 (1/30 seconds), then you'd end up filtering out your block signal, which may not be something you want to do.

==Click the Done Button==
Do it to begin the denoising pipeline. Go make yourself a sandwich.

=Obtaining Denoised Time-Series Data=
Your project folder will contain a data/ folder full of output files produced during all the above steps. Of interest are the series of .matc files. '''conn''' ships with a conversion utility, <code>conn_matc2nii</code> that will convert the .matc file for a session into a .nii file:
>> conn_matc2nii('DATA_Subject001_Session001.matc', false)
>> %the second parameter is optional and indicates whether to display a waitbar. By default, this is set to false.

After you execute this command in MATLAB, you'll end up with a file with the same name, except with a .nii extension.
Now, at this point, you probably started off with an f.nii.gz file, and now have a DATA_Subject'xxx'_Session'yyy'.nii file. In order to look at this newly denoised data in FreeSurfer, you will need to run it through the FS-FAST preproc-sess step. There's a good chance the source directory already has an f.nii.gz file, as well as a series of fmcpr.''${direction}''.sm''${smoothing}''.fsaverage.?h.nii.gz files. Assuming you want to hold on to these, I'd make a backup directory in each of the run subdirectories, and move all files to the backup directory (you can keep any .par files here). After you've backed everything up, move the new denoised files into the appropriate directories and rename them to f.nii. When you redo the preproc-sess step, make sure you do not apply slice-time correction, because this has already been applied to the denoised data:

preproc-sess -s FS_0231 -per-run -surface fsaverage lhrh -mni305 -fwhm 4 -fsd bold

The departure from the other wiki entry on preproc-sess is that we do not use the -sliceorder flag on the denoised data. Other than that, just process the denoised functional data like you would any other data. When done, you'll have a set of fmcpr.${smooth}.fsaverage.?h.nii.gz (they will no longer have the word 'down' in the filename, so you may have to modify some of your later analysis or data processing scripts accordingly -- just be on the lookout for ''file not found'' errors, and if they pop up, the first thing you should look for is to see if your command or script was expecting a filename with the slice order). Of course, another option would be to manually rename the preprocessed data when preproc-sess is completed, so that the preprocessed denoised data still includes the sliceorder in the name. I'm not sure how big of a problem this minor change in filename is going to be for our various scripts.

Importing Time Series Into MATLAB

2018-09-18T18:19:39Z

Erica: /* Functionally-assisted loading */

The next step is to load your data matrices. Assuming the time series are plaintext files containing only structured numerical data (e.g., as produced by the gettimecourses.sh script), you can use the <code>load</code> function to import these data.
= Functionally-assisted loading =
The steps described in this subsection have been simplified with the inevitable development of a MATLAB function, <code>loadFSTS.m</code> that can be found in the ubfs Scripts/Matlab folder. If you have copied it to a folder in your MATLAB path, it can be invoked thus:
M=loadFSTS(); %A dialog box will prompt you to select the files you want to open
One convenient feature is the ability to omit specified columns when loading the data (e.g., the '' 'unknown' '' region or the '' 'corpuscallosum' ''). Two optional paired arguments include ''ldrop'' and ''rdrop'', which are matched with arrays corresponding to the columns (regions) to be dropped.

'''NOTE: If using ROI's, you likely only want to remove column 1 (unknown).'''

%Omit columns 1 and 5 from both hemispheres
ldropregions=[1 5];
rdropregions=[1 5];
M=loadFSTS('ldropregions', ldropregions, 'rdropregions', rdropregions);
Of course, you can and should read the help documentation to find out the full capabilities of the function, which I assure you is very clever. But the above functionality will probably get you through 99.99% of the time. Rather than load each time series for each hemisphere into a separate array, loadFSTS will return a single cell array, where each cell contains the merged lh & rh data for each session. Thus, if you open up the lh/rh time series values for 6 fMRI runs, '''''M''''' will be a 6×1 cell array, where '''''M'''''{i} is a ''t timepoints'' × ''r regions'' matrix (''r regions'' is the sum of the regions retained for lh and rh data sets)

If each matrix '''''M'''''{i} is the same size, you can convert the cell array into a 3D matrix, which can facilitate a number of tasks. There are a number of ways to do this. For example:
new_M=cat(3,M{1}, M{2}, ... , M{i}); %concatenates each 2D matrix stored in M along a 3rd dimension
%new_M is now a 3D matrix of size ''t'' × ''r'' regions × ''i'' input series

= Batch FSTS =
list=load('participants.txt');
for p=1:length(list)
%dynamically figure out subject ID
subid=sprintf('FS_%d',list(p));
dirname=[pwd() filesep subid filesep 'bold'];
lfiles=dir([dirname filesep '*lh*.wav.txt']);
lfilenames={lfiles.name};
rfiles=dir([dirname filesep '*rh*.wav.txt']);
rfilenames={rfiles.name};
for n=1:length(lfilenames)
lfilenames{n}=fullfile(dirname, lfilenames{n});
end
for n=1:length(rfilenames)
rfilenames{n}=fullfile(dirname, rfilenames{n});
end

[M, hemis]=loadFSTS('lnames', lfilenames, 'rnames', rfilenames);

=Bulk Functionally-Assisted Loading=
The structure of the Freesurfer directories and some of the existing helper files can be leveraged in a Matlab script to automatically call loadFSTS on all the .wav.txt time series data in a SUBJECTS_DIR. The following code parses the contents of the '''''subjects''''' file (used by preproc-sess, et al.) and a '''''runs''''' file that can be placed in each subject's '''bold''' directory. The code will iterate through each subject to navigate to that subject's functional data (where the .wav.txt files should be located). There, it will parse the '''runs''' file to string together the names of all the .wav.txt files that should be found there. These dynamically-generated file names can be passed as parameters to the '''''loadFSTS()''''' function. The .mat files that are produced will be saved in SUBJECTS_DIR.

%% General Config %%
rootdir=pwd();
annot='myaparc_125';
pattern='fmcpr.down.sm4';
ldrop=[1 5];
rdrop=[1 5];

%% 1. Get the subjects to process %%
fid=fopen('subjects');
Subjects={};
while 1
s = fgetl(fid);
if ~ischar(s)
break
end
Subjects{length(Subjects)+1}=s;
end
fclose(fid);
%% 2. For each subject, get the runs to process %%
for s=1:length(Subjects)
subj=Subjects{s};
dirname=[subj filesep 'bold'];
cd(dirname);

fid=fopen('runs');
Runs={};
while 1
r = fgetl(fid);
if ( ~ischar(r) || length(r)<1 )
break
end
Runs{length(Runs)+1}=r;
end
fclose(fid);
% Cross the subject with each of the runs
lnames=cellfun(@(x) [subj '_lh_' annot '_' x '.' pattern '.wav.txt'], Runs, 'UniformOutput', false);
rnames=cellfun(@(x) [subj '_rh_' annot '_' x '.' pattern '.wav.txt'], Runs, 'UniformOutput', false);
[M, hemis]=loadFSTS('lnames', lnames, 'rnames', rnames, 'ldropregions', ldrop, 'rdropregions', rdrop);
save(fullfile(rootdir, [subj '.' annot '.timeseries.mat']), 'M', 'hemis', 'ldrop', 'rdrop');
cd(rootdir);
end

[[Category: Time Series]]
[[Category: FreeSurfer]]
[[Category: Functional Connectivity]]
[[Category: MATLAB]]
[[Category: MATLAB functions]]

Configure mkanalysis-sess

2018-06-19T14:57:03Z

Erica:

The first step in the first-level analysis is to configure analyses and contrasts. This step describes what preprocessing stages should have been run as well as the parameters needed to construct a design matrix (no data are analyzed yet). This is done with mkanalysis-sess.

A good way to make it clear how you are configuring your analysis is to declare important parameters as shell environment variables, and then use them when calling mkanalysis-sess:

SMOOTHING=4; #FWHM smoothing kernel; rule of thumb is 2 x VoxelSize
REFEVENTDUR=0.8; #How long are the events?
TR=2.047; #What is the TR
NCONDITIONS=3; #How many conditions in the par files
SURFACE=fsaverage; #generally valid options are 'self' or 'fsaverage'
HEMIS=( lh rh ); #for automatically looping over both hemispheres
PARFILE=LDT.par; #What's the name of the .par files in your bold/ directories?
ANROOT="LDT.sm" #base name for the analysis directories

for hemi in "${HEMIS[@]}"
do
mkanalysis-sess \
-fsd bold \
-surface ${SURFACE} ${hemi} \
-fwhm ${SMOOTHING} \
-event-related \
-paradigm ${PARFILE} \
-nconditions ${NCONDITIONS} \
-timewindow 24 \
-spmhrf 2 \
-polyfit 2 \
-mcextreg \
-TR ${TR} \
-refeventdur ${REFEVENTDUR} \
-analysis ${ANROOT}${SMOOTHING}.${hemi} \
-per-run -force
done
The above code could be saved as a script in your ~/bin directory (e.g., mkanalysis.sh) and modified as required for different datasets or parametric choices.

This step creates analysis directories in your $SUBJECTS_DIR containing single files that contain all the information needed for the next step. Your $SUBJECTS_DIR should be your project root directory.

Note that there is also a directive to skip volumes, however it doesn't seem to do what we expect it to, and so we just drop those volumes from the data entirely, and modify the event onsets to account for the dropped volumes.

Participant Screening

2018-03-07T15:21:41Z

Erica: /* Screening Questions */

When a potential participant contacts the lab to participate in one of the on going studies ask them the following questions:

== Screening Questions ==
#Are you right handed?
#Is English your dominant language?
#Are you taking any medications that affect your central nervous system? (e.g. Ritalin, Valium, beta blockers, etc.)
#Are you or may you be pregnant?
#Do you have metallic implants, such as pacemakers, replacement joints, cochlear implants?
#Do you have an aneurism clip, implanted neural stimulator?
#Do you have a vagus nerve stimulator (VNS)?
#Do you have any shrapnel injuries?
#Do you have any ocular foreign bodies (metal shavings, e.g., associated with welding)?
#Do you have a history of metal in head or eyes or other parts of the body?
#Do you have tattoos that contain metal (often found in black inks)?
#Do you have untreatable claustrophobia otherwise requiring anesthesia or antianxiety medications that may alter your ability to perform the tasks during fMRI scanning?
#For safety purposes the MRI scanner has a weight limit of 350 lbs. Do you fall under this limit?

Participant Screening

2018-03-07T15:20:20Z

Erica: /* Screening Questions */

When a potential participant contacts the lab to participate in one of the on going studies ask them the following questions:

== Screening Questions ==
#Are you right handed?
#Are you taking any medications that affect your central nervous system? (e.g. Ritalin, Valium, beta blockers, etc.)
#Are you or may you be pregnant?
#Do you have metallic implants, such as pacemakers, replacement joints, cochlear implants?
#Do you have an aneurism clip, implanted neural stimulator?
#Do you have a vagus nerve stimulator (VNS)?
#Do you have any shrapnel injuries?
#Do you have any ocular foreign bodies (metal shavings, e.g., associated with welding)?
#Do you have a history of metal in head or eyes or other parts of the body?
#Do you have tattoos that contain metal (often found in black inks)?
#Do you have untreatable claustrophobia otherwise requiring anesthesia or antianxiety medications that may alter your ability to perform the tasks during fMRI scanning?
#For safety purposes the MRI scanner has a weight limit of 350 lbs. Do you fall under this limit?

Main Page

2018-02-27T21:20:02Z

Erica: /* Data Analysis */

Welcome to the CCN Lab Wiki.

[[File:cpicard.jpg]]

== Terminal Commands & Other Lab Stuff ==
* [[New Research Staff]]
* [[ubmount | UBFS and ubmount]]
* [[SSH | Using SSH]]
* [[Synching Scripts]]
* [[Connecting to CCR]]
* [[Mess Ups | Times when we messed up]]
* [[Highlight Reel | Times when we rocked it]]
* [[Lab Email]]
* [[Excel Formulas]]
* [[Troubleshooting]]
* [[BASH Tricks]]
* [[Participant Screening]]

== Data Analysis ==
* [[Downloading CRTC Data]]
* [[Behavioral Analyses]]
* [[FreeSurfer | FreeSurfer Pipeline]]
* [[SPM | SPM Pipeline]]
* [[Time Series Analysis]]
* [[Network Analyses]]

== Manuscript Preparation ==
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Rendering_MRIcron Brain Rendering in MRIcron (SPM)]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Producing_Tables_of_Coordinates_(SPM) Producing Tables of Coordinates (SPM)]
* [[Annotation Coordinates| Extracting XYZ coordinates of .annot labels]]
* [http://colorbrewer2.org/ Color schemes (e.g., color keys for graphs, experiment conditions in fMRI renderings, etc.)]
** Above link yoinked from [http://sites.bu.edu/cnrlab/lab-resources/ BU's CNR Lab]

== Experiment A to Z (not necessarily in alphabetical order) ==
* [//ccnlab.psy.buffalo.edu/wiki/index.php/Category:MATLAB_functions MATLAB Functions]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Participant_Triage Participant Triage]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Pre-fMRI_Scanning_Protocol Pre-fMRI Scanning Protocol]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Participant_Instructions Participant Instructions]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=MRI_Prep MRI Prep (Prior to scan date)]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=MRI_Setup MRI Setup]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=MIKENET MIKENET Neural Network C Library Setup]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=TensorFlow TensorFlow OpenSource Python Setup]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Reading_Experiment_IDs IDs for Reading Experiment BOLD]
* [//ccnlab.psy.buffalo.edu/wiki/index.php/CCR Center for Computational Research (CCR)]

== MediaWiki - Guides for Getting started ==

* [//www.mediawiki.org/wiki/Help:Formatting Useful Formatting Guide]
* [//www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [//www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

Main Page

2018-02-27T21:19:14Z

Erica: /* Data Analysis */

Welcome to the CCN Lab Wiki.

[[File:cpicard.jpg]]

== Terminal Commands & Other Lab Stuff ==
* [[New Research Staff]]
* [[ubmount | UBFS and ubmount]]
* [[SSH | Using SSH]]
* [[Synching Scripts]]
* [[Connecting to CCR]]
* [[Mess Ups | Times when we messed up]]
* [[Highlight Reel | Times when we rocked it]]
* [[Lab Email]]
* [[Excel Formulas]]
* [[Troubleshooting]]
* [[BASH Tricks]]
* [[Participant Screening]]

== Data Analysis ==
* [[Downloading CTRC Data]]
* [[Behavioral Analyses]]
* [[FreeSurfer | FreeSurfer Pipeline]]
* [[SPM | SPM Pipeline]]
* [[Time Series Analysis]]
* [[Network Analyses]]

== Manuscript Preparation ==
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Rendering_MRIcron Brain Rendering in MRIcron (SPM)]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Producing_Tables_of_Coordinates_(SPM) Producing Tables of Coordinates (SPM)]
* [[Annotation Coordinates| Extracting XYZ coordinates of .annot labels]]
* [http://colorbrewer2.org/ Color schemes (e.g., color keys for graphs, experiment conditions in fMRI renderings, etc.)]
** Above link yoinked from [http://sites.bu.edu/cnrlab/lab-resources/ BU's CNR Lab]

== Experiment A to Z (not necessarily in alphabetical order) ==
* [//ccnlab.psy.buffalo.edu/wiki/index.php/Category:MATLAB_functions MATLAB Functions]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Participant_Triage Participant Triage]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Pre-fMRI_Scanning_Protocol Pre-fMRI Scanning Protocol]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Participant_Instructions Participant Instructions]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=MRI_Prep MRI Prep (Prior to scan date)]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=MRI_Setup MRI Setup]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=MIKENET MIKENET Neural Network C Library Setup]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=TensorFlow TensorFlow OpenSource Python Setup]
* [//ccnlab.psy.buffalo.edu/wiki/index.php?title=Reading_Experiment_IDs IDs for Reading Experiment BOLD]
* [//ccnlab.psy.buffalo.edu/wiki/index.php/CCR Center for Computational Research (CCR)]

== MediaWiki - Guides for Getting started ==

* [//www.mediawiki.org/wiki/Help:Formatting Useful Formatting Guide]
* [//www.mediawiki.org/wiki/Special:MyLanguage/Manual:Configuration_settings Configuration settings list]
* [//www.mediawiki.org/wiki/Special:MyLanguage/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Consult the [//meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

Participant Screening

2018-02-21T16:01:45Z

Erica: Created page with "When a potential participant contacts the lab to participate in one of the on going studies ask them the following questions: == Screening Questions == #Are you right handed?..."

When a potential participant contacts the lab to participate in one of the on going studies ask them the following questions:

== Screening Questions ==
#Are you right handed?
#Are you or may you be pregnant?
#Do you have metallic implants, such as pacemakers, replacement joints, cochlear implants?
#Do you have an aneurism clip, implanted neural stimulator?
#Do you have a vagus nerve stimulator (VNS)?
#Do you have any shrapnel injuries?
#Do you have any ocular foreign bodies (metal shavings, e.g., associated with welding)?
#Do you have a history of metal in head or eyes or other parts of the body?
#Do you have tattoos that contain metal (often found in black inks)?
#Do you have untreatable claustrophobia otherwise requiring anesthesia or antianxiety medications that may alter your ability to perform the tasks during fMRI scanning?
#For safety purposes the MRI scanner has a weight limit of 350 lbs. Do you fall under this limit?

Main Page

2018-02-21T15:50:00Z

Erica: /* Terminal Commands & Other Lab Stuff */

Mess Ups

2018-02-20T17:55:54Z

Erica: /* Chris' Mess-Ups */

== Honourable Mentions ==
=== Kali ===
Doesn't like Hawaiian pizza

== Chris' Mess-Ups ==
#Didn't get the MPRAGE files.
#Hard-coded a script to always run the same experiment file, ignoring the run-time parameters.
#Bothered the Freesurfer group when the problem was that the FSL environment variables weren't set in my .bashrc file on wernickesarea (but were correct on the other computers)
#Didn't book Psychonomics hotel in time. Inadvertently booked us in a dodgy part of Boston near a couple homeless shelters and possibly a methadone clinic.
#*We walked to the conference each morning.
#Claimed that the regions of the reading network were "literally" apples and oranges.

== Greg's Mess-Ups ==
# Ran the trainer twice.
# Trained the model with the wrong example file.
# Tried to train the retina

== Erica's Mess-Ups ==

[[File:loader3.gif]]

Downloading CRTC Data

2018-02-15T19:18:32Z

Erica:

Our fMRI data is typically posted to the CTRC Owncloud website within one or two days after acquisition (possibly longer if the scan was a Friday). This page describes how to download and organize the data for the first time, and then upload the organized raw data files to the UBFS network directory where any team member can then access them. Note that the data stored on UBFS is intended to be '''copied''' to your local computer hard drive, where you can mangle it to your heart's content without worrying about affecting anyone else's projects or corrupting our only copy of the data.

These directions assume that you have the URL and login/password to access the Owncloud website.

SemCat URL: http://tinyurl.com/blobs-catburgers

LDT URL: http://tinyurl.com/lexitron5000.

==Identify the Subjects==
Internally, we use our own set of Subject IDs, which are generated when a participant enters our experiment. The CTRC does the same thing, meaning that our subject numbers do not line up with those at the CTRC. Moreover, the same participant scanned multiple times will have a new CTRC subject number for each scan. It is imperative that you be able to translate between our subject numbers and those assigned to the fMRI data by the CTRC!

The timestamps for each zipped data set are visible through the Owncloud interface. As a rule of thumb, the most recently acquired data will also be the one with the most recent timestamp. If there is really only one candidate file, it should be fairly easy to identify the files you want. If you need to download older data, or if there are multiple candidates, you can consult the fMRI Log File Google Spreadsheet, which lists the CTRC subject number along with our own internal subject number.

==Download the Data==
Each fMRI session has two associated zip files. You can ignore the ones labeled ''study_files'', as those are stored in a proprietary data format and are useless to us. Instead, you will want to download the NIFTI files to your local hard drive.

==File Organization==
Once the download has finished, you can unzip the files, and copy them to a local directory. Give this directory a name corresponding to our local subject number. For example, if the data belongs to our subject 201, create directory 0201, and move the files into the new directory. The CTRC assigns sequential numbers and other file information to each of these files, and so we generally rename them according to our NIFTI file organization and naming convention.

An important step here is to check whether all expected files are present. We are generally expecting to see the following key files:
# A file with '''MPRAGE''' appearing somewhere in the filename. This is the high-resolution (~1mm voxels) anatomical image. It will likely begin with the prefix 500 or 501, and should be roughly 20MB in size.
#*Create a subdirectory called mri and move this file to the new subfolder, renaming it to "MPRAGE.nii.gz" only change the first part of the filename, leave the extension as is.
#A set of files with '''BOLD''' appearing somewhere in the filename. These files may be prefixed with numbers in the range of 700, 800, 900, etc..
#*These are the most likely to be problematic because sometimes a run will have to be aborted (e.g., the experiment malfunctioned) meaning there will be some dud files.
#*These files should be somewhere in the range of 50MB
#*There should be exactly one of these files for each run that the participant completed. If there are extra files, it is likely that a run was restarted. If there are fewer, this is more troubling, since that means we are missing some data, and this needs to be followed up on with the CTRC (it also makes it ambiguous which runs have missing data)
#*Our LDT and Semantic Imagery experiment have 6 runs. If we have 6 full runs, all is good in the hood.
#*If you are confident that you know that the data are complete, go ahead and create a directory called ''bold''. Under that directory, create run directories called 001, 002, ... etc. (one for each run). Move each of the BOLD files to these run directories, and rename to f.nii.gz
#*For some of the sessions participants complete a test run. Make sure that when you are moving the bold files in to their corresponding folders that your are not starting with these test run BOLD files.
#The scan session may include a T2- or FLAIR image, which helps identify gray matter. The unzipped files may include a file with '''FLAIR''' or '''3D_T2''' in the name. Expect a FLAIR file to be approximately 20MB, and the 3D_T2 file to be over 100MB in sise.
#*If these files exist, copy them to the /mri subdirectory you created in Step 1
*All other files not already moved into the /mri or /bold/xxx directories can go into a third subdirectory called /other

===Multisession Data===
Our Semantic Imagery experiment has two sets of data for some participants. We have been adding the _SESS_1 and _SESS_2 suffix to the subject numbers for these data, and otherwise treating the data as though they belong to completely different subjects. For example, the raw data folder contains ''0183_SESS_1'' and ''0183_SESS_2''.

If a team member wishes to analyze the data for both sessions at once, it will be incumbent on that individual to organize and possibly rename their own local copies of the data. For example, each session of Semantic Imagery should have 6 runs of BOLD files. When analyzing both sessions, as I copy over the SESS_1 data, I rename the MPRAGE file to MPRAGE_1, but otherwise leave the file/folder names intact. Then when I copy over the MPRAGE and the BOLD files for SESS_2, I rename the MPRAGE to MPRAGE_2, and I rename the BOLD folders from 001, 002, ..., 006 to 007, 008, ..., 012, reflecting the fact that the individual has 12 total runs of BOLD data.

Note also that preprocessing multisession data requires a bit of extra work to make sure that the files are all coregistered to the same space. This has nothing to do with how the files are organized; it's just mentioned here to put it on your radar.

==File Archiving==
At this point, the raw data have been organized according to the directory structure below:
*Subject Number
**mri
**bold
***001
***002
***etc.
**other
If this is correct, you can now upload the data to the raw data archive on ubfs/openfmri/ that corresponds to the project that this data belongs to. Be sure to make sure that your folder name matches the format of the existing folders you are moving the data too.

==Runtime Data==
This is a good occasion to make sure that the MATLAB runtime files for this particular session have also been taken off the Experimenter laptop and are also in the project directory on UBFS.

FreeSurfer

2018-02-14T21:43:16Z

Erica: /* Using mri_convert */

Freesurfer is a surface-based fMRI processing and analysis package written for the Unix environment (including Mac OS X, which is based on Unix). The neuroanatomical organization of the brain has the grey matter on the outside surface of the cortex. Aside from the ventral/medial subcortical structures, the interior volume of the brain is predominately white matter axonal tracts. Because neurons metabolize in the cell body, rather than along the axons, we can focus on the grey matter found in the cortical surface because any fMRI signal changes detected in the white matter should theoretically be noise. This is the motivation for surface-based analyses of fMRI.

Freesurfer has a rigid set of assumptions concerning how the input data is organized and labeled. The following instructions will help avoid any violations of these assumptions that might derail your Freesurfer fMRI processing pipeline.

These instructions assume that Freesurfer has already been installed and configured on your workstation.

== Organization ==
Freesurfer data for a collection of subjects is organized into a single project directory, called $SUBJECTS_DIR. Try this in the Linux terminal:
echo $SUBJECTS_DIR
It is likely that you will see something like the following, which is the sample 'bert' dataset that comes with a Freesurfer installation:
/usr/local/freesurfer/subjects

Let us assume that you have been collecting data for some lexical decision task experiment. All the data for all subjects should be stored in a single directory, which you will set as your $SUBJECTS_DIR variable. For example, if we keep all our data in ~/ubfs/cpmcnorg/openfmri/LDT, then we would type the following:
SUBJECTS_DIR=~/ubfs/cpmcnorg/openfmri/LDT
echo $SUBJECTS_DIR
Another trick we can do is to use the Unix <code>pwd</code> command to set the SUBJECTS_DIR to be whatever directory we happen to be in at the moment. The following series of commands will do the same as the previous example command:
cd ~
cd ubfs/cpmcnorg/openfmri
cd LDT
SUBJECTS_DIR=`pwd`
echo $SUBJECTS_DIR
The first line above, <code>cd ~</code> moves you to your home directory. The second line moves you from your home directory to the ubfs network folder containing several sets of experiments. The third line of code moves you into the subdirectory containing the LDT data. The fourth line sets the SUBJECTS_DIR environment variable to whatever gets printed out when you execute the <code>pwd</code> command (the <code>pwd</code> command '''p'''rints the current '''w'''orking '''d'''irectory). As a result, the current working directory becomes the new SUBJECTS_DIR after you execute this command, as you can see when you execute the last line of code. Note that in the <code>SUBJECTS_DIR=`pwd`</code> line, those are back-quotes, which you might find on your keyboard sharing a key with the ~ character. <code>`</code> is not the same character as <code>'</code>. When you enclose a command in a pair of back-quotes, you are telling the operating something along the lines of "this is a command that I want you to execute first, before using its output to figure out the rest of this business."

----
=== Subject directory organization ===
Data for each subject should be kept in their own directory. Moreover, different types of data (i.e., anatomical/structural or bold/functional) are kept in separate subdirectories. The basic directory structure for each participant ('session' in Freesurfer terminology) looks like this (see also [[Freesurfer_BOLD_files| Freesurfer BOLD files]]):

*SUBJECTS_DIR
**Subject_001
***mri
***bold
****001
****002
****003
****004
****005
****006
Copy the data for the participant from the /raw subdirectory for the project in the ubfs folder. You will only need the /mri and the /bold directories. If you are processing data for multiple session for a single participant, you may need to rename some of the files as you copy them over, otherwise, you will end up overwriting files.

 Note that all the functional data (in the 'bold' subdirectory) are stored in sequentially numbered folders (3-digits), and all are given the same name ('f.nii' or 'f.nii.gz'). This seems to be a requirement. It may be possible to circumvent this requirement, but this is a relatively minor concern at this time. 

By the end, your data should look like this:

*SUBJECTS_DIR
**Subject_001
***mri
****orig.nii.gz (or MPRAGE.nii)
***bold
****001/f.nii.gz
****002/f.nii.gz
****etc.

Note that the .nii.gz file extension indicates that this is a gzipped NIFTI file. You can use <code>gunzip</code> to unzip the files, but this isn't really necessary unless you are going to manipulate these files in MATLAB. We have figured out ways to do everything for FreeSurfer in the BASH shell, so you may as well just leave them as-is unless you have a compelling reason (or compulsion) to unzip them.

== Structural Preprocessing ==
The structural mri file (orig.nii) is transformed over a series of computationally-intensive steps invoked by the recon-all Freesurfer program. Recon-all is designed to execute all the steps in series without intervention, however in practice it seems preferable to execute the process in a series of smaller groups of steps and check the output in between. This is because the process is automated using computational algorithms, but if one step doesn't execute correctly, everything that follows will be compromised. The steps take many hours to complete, so by inspecting the progress along the way can save many hours of processing time redoing steps that had been done incorrectly.

===Tip: Keeping Track===
If you are working on multiple subjects, or if you are sharing preprocessing duties with someone else, you can coordinate or track your progress by create a LOG_FS_xxxx.txt file. A template file can be found in ubfs in the LDT folder. After completing each step for processing (both structural and functional) mark an x next to the corresponding line. It can be really easy to forget to do this, but it will ensure that others accessing the folder on ubfs will know what's been done. This file should be a resource for you anyway since it contains a list of commands. More elaboration can be found on the wiki.

Since most of the folders on ubfs do not contain this file, it is hard to know what steps of functional analysis have been done. I am working on writing down what specific files/folders are created at each step to use as markers. I will fill this in as I process a new participant. For now, here is the template:

*slicer (a window-based graphical program) or mri_convert (a command-line program)
**MPRAGE.mgz
*autorecon1
**brainmask.mgz
*autorecon2
*autorecon3
*parfiles
*mkanalysis
*mkconstrast
*preproc
*selxavg3

Make sure to update ubfs! It's a bummer to run a participant through all the steps and then realize the files were just sitting completed
on someone's computer locally.

In order to help you through analysis, there is a file called commands in the LDT folder of ubfs. This has all the commands you need to go from raw data to time courses (no GLM though). This is a good skeleton for reference, but it will still be necessary to reference the wiki to recognize what's going on at each step and address any errors.

=== Image File Format ===
The first thing that you will need to do is convert the orig.nii file to .mgz format. This can be done using the graphic-based [[Slicer]] program, or in the terminal using <code>mri_convert</code>. Though Freesurfer is capable of reading .nii files, it natively uses .mgz files, and so this conversion step will ensure that the structural data file has all the information that Freesurfer expects (there's no reason to expect a problem if using .nii files, but we have run into problems with archival data that had funny data header information).

==== Using mri_convert ====
Slicer seemed to be useful for automatically fixing goofy .NII header info, however, if there's nothing wrong with your file header you might find the <code>mri_convert</code> utility to be the fastest means of converting your files. You will need to make sure that you are in the directory that holds the .nii file.
INFILE_BASE=MPRAGE
INFILE_EXT=nii.gz
mri_convert --in_type nii --out_type mgz -i ${INFILE_BASE}.${INFILE_EXT} -o ${INFILE_BASE}.mgz

=== Recon-All ===
The computationally-intensive surface mapping is carried out by a Freesurfer program called recon-all. This program is extensively spaghetti-documented on the Freesurfer wiki [https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all here]. Though the Freesurfer documentation goes into much detail, it is also a little hard to follow at times and sometimes does some odd things. Notably, it describes a generally problem-free case. This might work well for data that you already know is going to be problem-free, but we seldom have that guarantee. Instead, this guide will split the recon-all processing into sub-stages where you can do quality-control inspection at each step.
#[[Autorecon1]] (~2-2.5 hours, assuming no problems encountered)
#[[Autorecon2]] (~6-8 hours, assuming no problems encountered)
#[[Autorecon3]]

After running autorecon1, it is best to run autorecon2 immediately afterward. Usually autorecon1 does an alright job skull stripping. If it doesn't, the results will be evident after autorecon2 is completed if you use the <code>tksurfer SUBJECTID HEMI inflated</code>. Fill in the SUBJECTID, and fill in HEMI with lh or rh (but check both). If the brain appears overly lumpy or there are odd points sticking out, proceede to [[Autorecon2]] editing.

== Functional Analysis ==
The previous steps have been concerned only with processing the T1 anatomical data. Though this might suffice for a purely structural brain analysis (e.g., voxel-based brain morphometry, which might explore how cortical thickness relates to some cognitive ability), most of our studies will employ functional MRI, which measures how the hemodynamic response changes as a function of task, condition or group. In the Freesurfer pipeline, this is done using a program called FS-FAST.

=== FS-FAST Functional Analysis===
Each of these steps are detailed more extensively elsewhere, but generally speaking you will need to follow these steps before starting your functional analysis:
#Copy BOLD data to the Freesurfer subject folder (see page for [[Freesurfer BOLD files]])
#Create (or copy if experiment used a fixed schedule) your paradigm files for each fMRI run, and edit them using matlab (see "[[Par-Files]]").
#*When editing par files, be sure to check how many volumes to drop for each par file; it may be different every time! See above link for more details.
#Create a subjects text file in your $SUBJECTS_DIR called "subjectname" that contains a list of your subjects necessary for later (used for [[Configure preproc-sess|preproc-sess]])
#*A quick way to do this, assuming you want to preprocess everyone, is to pipe the results of the ls command with the -1 switch (1 per line) into grep and then redirect the output to a file:
#*<code>ls -1 | grep "^FS" > subjects</code>
#*This will list the contents of the current directory, 1 per line, then keep only lines starting with ''FS''
#Configure your analyses (using [[Configure mkanalysis-sess|mkanalysis-sess]])
#Configure your contrast (using [[Configure mkcontrast-sess|mkcontrast-sess]])
#Preprocess your data (smoothing, slice-time correction, intensity normalization and brain mask creation) (using [[Configure preproc-sess|preproc-sess]])
#Check the *.mcdat files in each of the ''subject_name/bold/xxx'' directories to inspect the amount of motion detected during the motion correction step. Data associated with periods of excessive movement (>1mm) should be dealt with carefully. Columns in the text document from left to right are: (1) time point number (2) roll rotation (in ) (3) pitch rotation (in ) (4) yaw rotation (in ) (5) between-slice motion or translation (in mm) (6) within slice up-down motion or translation (in mm) (7) within slice left-right motion or translation (in mm) (8) RMS error before correction (9) RMS error after correction (10) total vector motion or translation (in mm). We need to look at column 10. If any of these values are above 1, this might be indicative of excessive movement. Consult with someone further up the chain for advice (undergrads ask a grad student; grad students ask Chris or a Postdoc if he ever has the funding to get one).
#Run the GLM for Single Subjects([[selxavg3-sess]])
#*Typically, we will do a group-level GLM. I have come to realize that it should generally suffice to do all processing in '''fsaverage''' surface space (mri_glmfit requires all operations to be done in a common surface space).
#*This will be relevant to the parameters you use in steps 4,6 and 8
#Run the group-level GLM ([[mri_glmfit]])
Lab-specific documentation can be found on this wiki, but a more thorough (and accurate) description can be found on the [https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV5.1/FsFastFirstLevel Freesurfer Wiki]

== Trouble Shooting ==
=== Missing surfaces ===
Not sure how this came to pass, as I have never encountered this before, but probably was the result of one of the autorecon steps stopping early. I was running preproc-sess using the ''fsaverage'' surface (having already successfully run it on the ''self'' surface) and got an error message about being unable to find lh.sphere.reg. A quick google found a FreeSurfer mailing list archive email that was concerned with a different issue that had a similar solution. In Bruce the Almighty's words:

> >> you can use mris_register with the -1 switch to indicate that the target
> >> is a single surface not a statistical atlas. You will however still have to
> >> create the various surface representations and geometric measures we expect
> >> (e.g. ?h.inflated, ?h.sulc, etc....). If you can convert your
> >> surfaces to our binary format (e.g. using mris_convert) to create
> >> an lh.orig, it would be something like:
> >>
> >> mris_smooth lh.orig lh.smoothwm
> >> mris_inflate lh.smoothwm lh.inflated
> >> mris_sphere lh.inflated lh.sphere
> >> mris_register -1 lh.sphere $TARGET_SUBJECT_DIR/lh.sphere ./lh.sphere.reg
> >>
> >> I've probably left something out, but that basic approach should work.
> >>
> >> cheers
> >> Bruce

The subject that had given me a problem already had ?h.inflated files, but no ?h.sphere files. I tried running some of the above steps but there were missing dependencies. Right now running:
recon-all -s $SUBJECT -surfreg
This allegedly produces the surf.reg files as an output.

=== My script can't find my data ===
Some versions of the autorecon*.sh scripts have the SUBJECTS_DIR hard-coded. Or sometimes you will close your terminal window (e.g., at the end of the day), and then launch a new terminal window when you come back to the workstation (or resume working at a different computer). There's a good chance that your Freesurfer malfunction is the result of your SUBJECTS_DIR environment variable being set to the incorrect value. Troubleshooting step #1 should be the following:
echo $SUBJECTS_DIR
If the wrong directory name is printed to the screen, setting it to the correct value may well fix your problem.

At this point you might expect me to tell you how to set SUBJECTS_DIR to the correct value. But I'm not going to do that, and here's why:
#It's documented elsewhere on the wiki
#If you're confused about how to set SUBJECTS_DIR, you're also likely to just blindly type whatever example command I give without understanding what the command does. If this is the case, please become more proficient with the lab's procedures and software.

=== Is Freesurfer in your path? ===
This is an unlikely issue, but it is possible that your ~/.bashrc file doesn't add Freesurfer to your path. To check, launch a new terminal window. You should see something like the following:
-------- freesurfer-Linux-centos6_x86_64-stable-pub-v5.3.0 --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer
FSFAST_HOME /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR /usr/local/freesurfer/subjects
MNI_DIR /usr/local/freesurfer/mni
If you don't, then open up your .bashrc file with a text editor:
gedit ~/.bashrc
Then add the following lines to the bottom of the file:
#FREESURFER
export FREESURFER_HOME=/usr/local/freesurfer
source ${FREESURFER_HOME}/SetUpFreeSurfer.sh

#FSL
export FSLDIR=/usr/share/fsl/5.0
source ${FSLDIR}/etc/fslconf/fsl.sh
Save your changes, log out of Linux and log back in.

=== ERROR: Flag unrecognized. ===
Most Linux programs take parameters, or ''flags'' that modify or specify how they are run. For example, you can't just call the <code>recon-all</code> command; you have to tell the progam ''what'' data you want to work on, and so this information is provided using the <code>-i</code> flag. Other flags might tell the program how aggressive to be when deciding to remove potential skull voxels, for example.
There are no hard-and-fast rules, but to find the set of flags that you can use for a particular Linux program, there are a few options you can try:
#<code>man program_name</code>
#<code>program_name -help</code>
#<code>program_name -?</code>
Though often the <code>program_name -some_flag</code> option causes the usage information to be displayed if ''some_flag'' is not a valid flag.

When you see an error message concerning an unrecognized flag, it is most likely because there is a typo in your command. For example:
recon-all -autorecon1 watershed 15
Each of the flags is supposed to be prefixed with a '-' character, but in the example above, <code>-watershed</code> was instead typed as <code>watershed</code> ''without'' the '-' character. These little typos can be hard to spot.

'''If you are completely perplexed why something doesn't work out when you followed the directions to the letter, the first thing you should do is throw out your assumption that you typed in the command correctly.'''

[[Category:FreeSurfer]]

FreeSurfer

2018-02-14T21:42:38Z

Erica: /* Using mri_convert */

Freesurfer is a surface-based fMRI processing and analysis package written for the Unix environment (including Mac OS X, which is based on Unix). The neuroanatomical organization of the brain has the grey matter on the outside surface of the cortex. Aside from the ventral/medial subcortical structures, the interior volume of the brain is predominately white matter axonal tracts. Because neurons metabolize in the cell body, rather than along the axons, we can focus on the grey matter found in the cortical surface because any fMRI signal changes detected in the white matter should theoretically be noise. This is the motivation for surface-based analyses of fMRI.

Freesurfer has a rigid set of assumptions concerning how the input data is organized and labeled. The following instructions will help avoid any violations of these assumptions that might derail your Freesurfer fMRI processing pipeline.

These instructions assume that Freesurfer has already been installed and configured on your workstation.

== Organization ==
Freesurfer data for a collection of subjects is organized into a single project directory, called $SUBJECTS_DIR. Try this in the Linux terminal:
echo $SUBJECTS_DIR
It is likely that you will see something like the following, which is the sample 'bert' dataset that comes with a Freesurfer installation:
/usr/local/freesurfer/subjects

Let us assume that you have been collecting data for some lexical decision task experiment. All the data for all subjects should be stored in a single directory, which you will set as your $SUBJECTS_DIR variable. For example, if we keep all our data in ~/ubfs/cpmcnorg/openfmri/LDT, then we would type the following:
SUBJECTS_DIR=~/ubfs/cpmcnorg/openfmri/LDT
echo $SUBJECTS_DIR
Another trick we can do is to use the Unix <code>pwd</code> command to set the SUBJECTS_DIR to be whatever directory we happen to be in at the moment. The following series of commands will do the same as the previous example command:
cd ~
cd ubfs/cpmcnorg/openfmri
cd LDT
SUBJECTS_DIR=`pwd`
echo $SUBJECTS_DIR
The first line above, <code>cd ~</code> moves you to your home directory. The second line moves you from your home directory to the ubfs network folder containing several sets of experiments. The third line of code moves you into the subdirectory containing the LDT data. The fourth line sets the SUBJECTS_DIR environment variable to whatever gets printed out when you execute the <code>pwd</code> command (the <code>pwd</code> command '''p'''rints the current '''w'''orking '''d'''irectory). As a result, the current working directory becomes the new SUBJECTS_DIR after you execute this command, as you can see when you execute the last line of code. Note that in the <code>SUBJECTS_DIR=`pwd`</code> line, those are back-quotes, which you might find on your keyboard sharing a key with the ~ character. <code>`</code> is not the same character as <code>'</code>. When you enclose a command in a pair of back-quotes, you are telling the operating something along the lines of "this is a command that I want you to execute first, before using its output to figure out the rest of this business."

----
=== Subject directory organization ===
Data for each subject should be kept in their own directory. Moreover, different types of data (i.e., anatomical/structural or bold/functional) are kept in separate subdirectories. The basic directory structure for each participant ('session' in Freesurfer terminology) looks like this (see also [[Freesurfer_BOLD_files| Freesurfer BOLD files]]):

*SUBJECTS_DIR
**Subject_001
***mri
***bold
****001
****002
****003
****004
****005
****006
Copy the data for the participant from the /raw subdirectory for the project in the ubfs folder. You will only need the /mri and the /bold directories. If you are processing data for multiple session for a single participant, you may need to rename some of the files as you copy them over, otherwise, you will end up overwriting files.

 Note that all the functional data (in the 'bold' subdirectory) are stored in sequentially numbered folders (3-digits), and all are given the same name ('f.nii' or 'f.nii.gz'). This seems to be a requirement. It may be possible to circumvent this requirement, but this is a relatively minor concern at this time. 

By the end, your data should look like this:

*SUBJECTS_DIR
**Subject_001
***mri
****orig.nii.gz (or MPRAGE.nii)
***bold
****001/f.nii.gz
****002/f.nii.gz
****etc.

Note that the .nii.gz file extension indicates that this is a gzipped NIFTI file. You can use <code>gunzip</code> to unzip the files, but this isn't really necessary unless you are going to manipulate these files in MATLAB. We have figured out ways to do everything for FreeSurfer in the BASH shell, so you may as well just leave them as-is unless you have a compelling reason (or compulsion) to unzip them.

== Structural Preprocessing ==
The structural mri file (orig.nii) is transformed over a series of computationally-intensive steps invoked by the recon-all Freesurfer program. Recon-all is designed to execute all the steps in series without intervention, however in practice it seems preferable to execute the process in a series of smaller groups of steps and check the output in between. This is because the process is automated using computational algorithms, but if one step doesn't execute correctly, everything that follows will be compromised. The steps take many hours to complete, so by inspecting the progress along the way can save many hours of processing time redoing steps that had been done incorrectly.

===Tip: Keeping Track===
If you are working on multiple subjects, or if you are sharing preprocessing duties with someone else, you can coordinate or track your progress by create a LOG_FS_xxxx.txt file. A template file can be found in ubfs in the LDT folder. After completing each step for processing (both structural and functional) mark an x next to the corresponding line. It can be really easy to forget to do this, but it will ensure that others accessing the folder on ubfs will know what's been done. This file should be a resource for you anyway since it contains a list of commands. More elaboration can be found on the wiki.

Since most of the folders on ubfs do not contain this file, it is hard to know what steps of functional analysis have been done. I am working on writing down what specific files/folders are created at each step to use as markers. I will fill this in as I process a new participant. For now, here is the template:

*slicer (a window-based graphical program) or mri_convert (a command-line program)
**MPRAGE.mgz
*autorecon1
**brainmask.mgz
*autorecon2
*autorecon3
*parfiles
*mkanalysis
*mkconstrast
*preproc
*selxavg3

Make sure to update ubfs! It's a bummer to run a participant through all the steps and then realize the files were just sitting completed
on someone's computer locally.

In order to help you through analysis, there is a file called commands in the LDT folder of ubfs. This has all the commands you need to go from raw data to time courses (no GLM though). This is a good skeleton for reference, but it will still be necessary to reference the wiki to recognize what's going on at each step and address any errors.

=== Image File Format ===
The first thing that you will need to do is convert the orig.nii file to .mgz format. This can be done using the graphic-based [[Slicer]] program, or in the terminal using <code>mri_convert</code>. Though Freesurfer is capable of reading .nii files, it natively uses .mgz files, and so this conversion step will ensure that the structural data file has all the information that Freesurfer expects (there's no reason to expect a problem if using .nii files, but we have run into problems with archival data that had funny data header information).

==== Using mri_convert ====
Slicer seemed to be useful for automatically fixing goofy .NII header info, however, if there's nothing wrong with your file header you might find the <code>mri_convert</code> utility to be the fastest means of converting your files.
INFILE_BASE=MPRAGE
INFILE_EXT=nii.gz
mri_convert --in_type nii --out_type mgz -i ${INFILE_BASE}.${INFILE_EXT} -o ${INFILE_BASE}.mgz

=== Recon-All ===
The computationally-intensive surface mapping is carried out by a Freesurfer program called recon-all. This program is extensively spaghetti-documented on the Freesurfer wiki [https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all here]. Though the Freesurfer documentation goes into much detail, it is also a little hard to follow at times and sometimes does some odd things. Notably, it describes a generally problem-free case. This might work well for data that you already know is going to be problem-free, but we seldom have that guarantee. Instead, this guide will split the recon-all processing into sub-stages where you can do quality-control inspection at each step.
#[[Autorecon1]] (~2-2.5 hours, assuming no problems encountered)
#[[Autorecon2]] (~6-8 hours, assuming no problems encountered)
#[[Autorecon3]]

After running autorecon1, it is best to run autorecon2 immediately afterward. Usually autorecon1 does an alright job skull stripping. If it doesn't, the results will be evident after autorecon2 is completed if you use the <code>tksurfer SUBJECTID HEMI inflated</code>. Fill in the SUBJECTID, and fill in HEMI with lh or rh (but check both). If the brain appears overly lumpy or there are odd points sticking out, proceede to [[Autorecon2]] editing.

== Functional Analysis ==
The previous steps have been concerned only with processing the T1 anatomical data. Though this might suffice for a purely structural brain analysis (e.g., voxel-based brain morphometry, which might explore how cortical thickness relates to some cognitive ability), most of our studies will employ functional MRI, which measures how the hemodynamic response changes as a function of task, condition or group. In the Freesurfer pipeline, this is done using a program called FS-FAST.

=== FS-FAST Functional Analysis===
Each of these steps are detailed more extensively elsewhere, but generally speaking you will need to follow these steps before starting your functional analysis:
#Copy BOLD data to the Freesurfer subject folder (see page for [[Freesurfer BOLD files]])
#Create (or copy if experiment used a fixed schedule) your paradigm files for each fMRI run, and edit them using matlab (see "[[Par-Files]]").
#*When editing par files, be sure to check how many volumes to drop for each par file; it may be different every time! See above link for more details.
#Create a subjects text file in your $SUBJECTS_DIR called "subjectname" that contains a list of your subjects necessary for later (used for [[Configure preproc-sess|preproc-sess]])
#*A quick way to do this, assuming you want to preprocess everyone, is to pipe the results of the ls command with the -1 switch (1 per line) into grep and then redirect the output to a file:
#*<code>ls -1 | grep "^FS" > subjects</code>
#*This will list the contents of the current directory, 1 per line, then keep only lines starting with ''FS''
#Configure your analyses (using [[Configure mkanalysis-sess|mkanalysis-sess]])
#Configure your contrast (using [[Configure mkcontrast-sess|mkcontrast-sess]])
#Preprocess your data (smoothing, slice-time correction, intensity normalization and brain mask creation) (using [[Configure preproc-sess|preproc-sess]])
#Check the *.mcdat files in each of the ''subject_name/bold/xxx'' directories to inspect the amount of motion detected during the motion correction step. Data associated with periods of excessive movement (>1mm) should be dealt with carefully. Columns in the text document from left to right are: (1) time point number (2) roll rotation (in ) (3) pitch rotation (in ) (4) yaw rotation (in ) (5) between-slice motion or translation (in mm) (6) within slice up-down motion or translation (in mm) (7) within slice left-right motion or translation (in mm) (8) RMS error before correction (9) RMS error after correction (10) total vector motion or translation (in mm). We need to look at column 10. If any of these values are above 1, this might be indicative of excessive movement. Consult with someone further up the chain for advice (undergrads ask a grad student; grad students ask Chris or a Postdoc if he ever has the funding to get one).
#Run the GLM for Single Subjects([[selxavg3-sess]])
#*Typically, we will do a group-level GLM. I have come to realize that it should generally suffice to do all processing in '''fsaverage''' surface space (mri_glmfit requires all operations to be done in a common surface space).
#*This will be relevant to the parameters you use in steps 4,6 and 8
#Run the group-level GLM ([[mri_glmfit]])
Lab-specific documentation can be found on this wiki, but a more thorough (and accurate) description can be found on the [https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV5.1/FsFastFirstLevel Freesurfer Wiki]

== Trouble Shooting ==
=== Missing surfaces ===
Not sure how this came to pass, as I have never encountered this before, but probably was the result of one of the autorecon steps stopping early. I was running preproc-sess using the ''fsaverage'' surface (having already successfully run it on the ''self'' surface) and got an error message about being unable to find lh.sphere.reg. A quick google found a FreeSurfer mailing list archive email that was concerned with a different issue that had a similar solution. In Bruce the Almighty's words:

> >> you can use mris_register with the -1 switch to indicate that the target
> >> is a single surface not a statistical atlas. You will however still have to
> >> create the various surface representations and geometric measures we expect
> >> (e.g. ?h.inflated, ?h.sulc, etc....). If you can convert your
> >> surfaces to our binary format (e.g. using mris_convert) to create
> >> an lh.orig, it would be something like:
> >>
> >> mris_smooth lh.orig lh.smoothwm
> >> mris_inflate lh.smoothwm lh.inflated
> >> mris_sphere lh.inflated lh.sphere
> >> mris_register -1 lh.sphere $TARGET_SUBJECT_DIR/lh.sphere ./lh.sphere.reg
> >>
> >> I've probably left something out, but that basic approach should work.
> >>
> >> cheers
> >> Bruce

The subject that had given me a problem already had ?h.inflated files, but no ?h.sphere files. I tried running some of the above steps but there were missing dependencies. Right now running:
recon-all -s $SUBJECT -surfreg
This allegedly produces the surf.reg files as an output.

=== My script can't find my data ===
Some versions of the autorecon*.sh scripts have the SUBJECTS_DIR hard-coded. Or sometimes you will close your terminal window (e.g., at the end of the day), and then launch a new terminal window when you come back to the workstation (or resume working at a different computer). There's a good chance that your Freesurfer malfunction is the result of your SUBJECTS_DIR environment variable being set to the incorrect value. Troubleshooting step #1 should be the following:
echo $SUBJECTS_DIR
If the wrong directory name is printed to the screen, setting it to the correct value may well fix your problem.

At this point you might expect me to tell you how to set SUBJECTS_DIR to the correct value. But I'm not going to do that, and here's why:
#It's documented elsewhere on the wiki
#If you're confused about how to set SUBJECTS_DIR, you're also likely to just blindly type whatever example command I give without understanding what the command does. If this is the case, please become more proficient with the lab's procedures and software.

=== Is Freesurfer in your path? ===
This is an unlikely issue, but it is possible that your ~/.bashrc file doesn't add Freesurfer to your path. To check, launch a new terminal window. You should see something like the following:
-------- freesurfer-Linux-centos6_x86_64-stable-pub-v5.3.0 --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer
FSFAST_HOME /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR /usr/local/freesurfer/subjects
MNI_DIR /usr/local/freesurfer/mni
If you don't, then open up your .bashrc file with a text editor:
gedit ~/.bashrc
Then add the following lines to the bottom of the file:
#FREESURFER
export FREESURFER_HOME=/usr/local/freesurfer
source ${FREESURFER_HOME}/SetUpFreeSurfer.sh

#FSL
export FSLDIR=/usr/share/fsl/5.0
source ${FSLDIR}/etc/fslconf/fsl.sh
Save your changes, log out of Linux and log back in.

=== ERROR: Flag unrecognized. ===
Most Linux programs take parameters, or ''flags'' that modify or specify how they are run. For example, you can't just call the <code>recon-all</code> command; you have to tell the progam ''what'' data you want to work on, and so this information is provided using the <code>-i</code> flag. Other flags might tell the program how aggressive to be when deciding to remove potential skull voxels, for example.
There are no hard-and-fast rules, but to find the set of flags that you can use for a particular Linux program, there are a few options you can try:
#<code>man program_name</code>
#<code>program_name -help</code>
#<code>program_name -?</code>
Though often the <code>program_name -some_flag</code> option causes the usage information to be displayed if ''some_flag'' is not a valid flag.

When you see an error message concerning an unrecognized flag, it is most likely because there is a typo in your command. For example:
recon-all -autorecon1 watershed 15
Each of the flags is supposed to be prefixed with a '-' character, but in the example above, <code>-watershed</code> was instead typed as <code>watershed</code> ''without'' the '-' character. These little typos can be hard to spot.

'''If you are completely perplexed why something doesn't work out when you followed the directions to the letter, the first thing you should do is throw out your assumption that you typed in the command correctly.'''

[[Category:FreeSurfer]]

FreeSurfer

2018-02-14T21:42:13Z

Erica: /* Using mri_convert */

Freesurfer is a surface-based fMRI processing and analysis package written for the Unix environment (including Mac OS X, which is based on Unix). The neuroanatomical organization of the brain has the grey matter on the outside surface of the cortex. Aside from the ventral/medial subcortical structures, the interior volume of the brain is predominately white matter axonal tracts. Because neurons metabolize in the cell body, rather than along the axons, we can focus on the grey matter found in the cortical surface because any fMRI signal changes detected in the white matter should theoretically be noise. This is the motivation for surface-based analyses of fMRI.

Freesurfer has a rigid set of assumptions concerning how the input data is organized and labeled. The following instructions will help avoid any violations of these assumptions that might derail your Freesurfer fMRI processing pipeline.

These instructions assume that Freesurfer has already been installed and configured on your workstation.

== Organization ==
Freesurfer data for a collection of subjects is organized into a single project directory, called $SUBJECTS_DIR. Try this in the Linux terminal:
echo $SUBJECTS_DIR
It is likely that you will see something like the following, which is the sample 'bert' dataset that comes with a Freesurfer installation:
/usr/local/freesurfer/subjects

Let us assume that you have been collecting data for some lexical decision task experiment. All the data for all subjects should be stored in a single directory, which you will set as your $SUBJECTS_DIR variable. For example, if we keep all our data in ~/ubfs/cpmcnorg/openfmri/LDT, then we would type the following:
SUBJECTS_DIR=~/ubfs/cpmcnorg/openfmri/LDT
echo $SUBJECTS_DIR
Another trick we can do is to use the Unix <code>pwd</code> command to set the SUBJECTS_DIR to be whatever directory we happen to be in at the moment. The following series of commands will do the same as the previous example command:
cd ~
cd ubfs/cpmcnorg/openfmri
cd LDT
SUBJECTS_DIR=`pwd`
echo $SUBJECTS_DIR
The first line above, <code>cd ~</code> moves you to your home directory. The second line moves you from your home directory to the ubfs network folder containing several sets of experiments. The third line of code moves you into the subdirectory containing the LDT data. The fourth line sets the SUBJECTS_DIR environment variable to whatever gets printed out when you execute the <code>pwd</code> command (the <code>pwd</code> command '''p'''rints the current '''w'''orking '''d'''irectory). As a result, the current working directory becomes the new SUBJECTS_DIR after you execute this command, as you can see when you execute the last line of code. Note that in the <code>SUBJECTS_DIR=`pwd`</code> line, those are back-quotes, which you might find on your keyboard sharing a key with the ~ character. <code>`</code> is not the same character as <code>'</code>. When you enclose a command in a pair of back-quotes, you are telling the operating something along the lines of "this is a command that I want you to execute first, before using its output to figure out the rest of this business."

----
=== Subject directory organization ===
Data for each subject should be kept in their own directory. Moreover, different types of data (i.e., anatomical/structural or bold/functional) are kept in separate subdirectories. The basic directory structure for each participant ('session' in Freesurfer terminology) looks like this (see also [[Freesurfer_BOLD_files| Freesurfer BOLD files]]):

*SUBJECTS_DIR
**Subject_001
***mri
***bold
****001
****002
****003
****004
****005
****006
Copy the data for the participant from the /raw subdirectory for the project in the ubfs folder. You will only need the /mri and the /bold directories. If you are processing data for multiple session for a single participant, you may need to rename some of the files as you copy them over, otherwise, you will end up overwriting files.

 Note that all the functional data (in the 'bold' subdirectory) are stored in sequentially numbered folders (3-digits), and all are given the same name ('f.nii' or 'f.nii.gz'). This seems to be a requirement. It may be possible to circumvent this requirement, but this is a relatively minor concern at this time. 

By the end, your data should look like this:

*SUBJECTS_DIR
**Subject_001
***mri
****orig.nii.gz (or MPRAGE.nii)
***bold
****001/f.nii.gz
****002/f.nii.gz
****etc.

Note that the .nii.gz file extension indicates that this is a gzipped NIFTI file. You can use <code>gunzip</code> to unzip the files, but this isn't really necessary unless you are going to manipulate these files in MATLAB. We have figured out ways to do everything for FreeSurfer in the BASH shell, so you may as well just leave them as-is unless you have a compelling reason (or compulsion) to unzip them.

== Structural Preprocessing ==
The structural mri file (orig.nii) is transformed over a series of computationally-intensive steps invoked by the recon-all Freesurfer program. Recon-all is designed to execute all the steps in series without intervention, however in practice it seems preferable to execute the process in a series of smaller groups of steps and check the output in between. This is because the process is automated using computational algorithms, but if one step doesn't execute correctly, everything that follows will be compromised. The steps take many hours to complete, so by inspecting the progress along the way can save many hours of processing time redoing steps that had been done incorrectly.

===Tip: Keeping Track===
If you are working on multiple subjects, or if you are sharing preprocessing duties with someone else, you can coordinate or track your progress by create a LOG_FS_xxxx.txt file. A template file can be found in ubfs in the LDT folder. After completing each step for processing (both structural and functional) mark an x next to the corresponding line. It can be really easy to forget to do this, but it will ensure that others accessing the folder on ubfs will know what's been done. This file should be a resource for you anyway since it contains a list of commands. More elaboration can be found on the wiki.

Since most of the folders on ubfs do not contain this file, it is hard to know what steps of functional analysis have been done. I am working on writing down what specific files/folders are created at each step to use as markers. I will fill this in as I process a new participant. For now, here is the template:

*slicer (a window-based graphical program) or mri_convert (a command-line program)
**MPRAGE.mgz
*autorecon1
**brainmask.mgz
*autorecon2
*autorecon3
*parfiles
*mkanalysis
*mkconstrast
*preproc
*selxavg3

Make sure to update ubfs! It's a bummer to run a participant through all the steps and then realize the files were just sitting completed
on someone's computer locally.

In order to help you through analysis, there is a file called commands in the LDT folder of ubfs. This has all the commands you need to go from raw data to time courses (no GLM though). This is a good skeleton for reference, but it will still be necessary to reference the wiki to recognize what's going on at each step and address any errors.

=== Image File Format ===
The first thing that you will need to do is convert the orig.nii file to .mgz format. This can be done using the graphic-based [[Slicer]] program, or in the terminal using <code>mri_convert</code>. Though Freesurfer is capable of reading .nii files, it natively uses .mgz files, and so this conversion step will ensure that the structural data file has all the information that Freesurfer expects (there's no reason to expect a problem if using .nii files, but we have run into problems with archival data that had funny data header information).

==== Using mri_convert ====
Slicer seemed to be useful for automatically fixing goofy .NII header info, however, if there's nothing wrong with your file header you might find the <code>mri_convert</code> utility to be the fastest means of converting your files.
INFILE_BASE=orig
INFILE_EXT=nii.gz
mri_convert --in_type nii --out_type mgz -i ${INFILE_BASE}.${INFILE_EXT} -o ${INFILE_BASE}.mgz

=== Recon-All ===
The computationally-intensive surface mapping is carried out by a Freesurfer program called recon-all. This program is extensively spaghetti-documented on the Freesurfer wiki [https://surfer.nmr.mgh.harvard.edu/fswiki/recon-all here]. Though the Freesurfer documentation goes into much detail, it is also a little hard to follow at times and sometimes does some odd things. Notably, it describes a generally problem-free case. This might work well for data that you already know is going to be problem-free, but we seldom have that guarantee. Instead, this guide will split the recon-all processing into sub-stages where you can do quality-control inspection at each step.
#[[Autorecon1]] (~2-2.5 hours, assuming no problems encountered)
#[[Autorecon2]] (~6-8 hours, assuming no problems encountered)
#[[Autorecon3]]

After running autorecon1, it is best to run autorecon2 immediately afterward. Usually autorecon1 does an alright job skull stripping. If it doesn't, the results will be evident after autorecon2 is completed if you use the <code>tksurfer SUBJECTID HEMI inflated</code>. Fill in the SUBJECTID, and fill in HEMI with lh or rh (but check both). If the brain appears overly lumpy or there are odd points sticking out, proceede to [[Autorecon2]] editing.

== Functional Analysis ==
The previous steps have been concerned only with processing the T1 anatomical data. Though this might suffice for a purely structural brain analysis (e.g., voxel-based brain morphometry, which might explore how cortical thickness relates to some cognitive ability), most of our studies will employ functional MRI, which measures how the hemodynamic response changes as a function of task, condition or group. In the Freesurfer pipeline, this is done using a program called FS-FAST.

=== FS-FAST Functional Analysis===
Each of these steps are detailed more extensively elsewhere, but generally speaking you will need to follow these steps before starting your functional analysis:
#Copy BOLD data to the Freesurfer subject folder (see page for [[Freesurfer BOLD files]])
#Create (or copy if experiment used a fixed schedule) your paradigm files for each fMRI run, and edit them using matlab (see "[[Par-Files]]").
#*When editing par files, be sure to check how many volumes to drop for each par file; it may be different every time! See above link for more details.
#Create a subjects text file in your $SUBJECTS_DIR called "subjectname" that contains a list of your subjects necessary for later (used for [[Configure preproc-sess|preproc-sess]])
#*A quick way to do this, assuming you want to preprocess everyone, is to pipe the results of the ls command with the -1 switch (1 per line) into grep and then redirect the output to a file:
#*<code>ls -1 | grep "^FS" > subjects</code>
#*This will list the contents of the current directory, 1 per line, then keep only lines starting with ''FS''
#Configure your analyses (using [[Configure mkanalysis-sess|mkanalysis-sess]])
#Configure your contrast (using [[Configure mkcontrast-sess|mkcontrast-sess]])
#Preprocess your data (smoothing, slice-time correction, intensity normalization and brain mask creation) (using [[Configure preproc-sess|preproc-sess]])
#Check the *.mcdat files in each of the ''subject_name/bold/xxx'' directories to inspect the amount of motion detected during the motion correction step. Data associated with periods of excessive movement (>1mm) should be dealt with carefully. Columns in the text document from left to right are: (1) time point number (2) roll rotation (in ) (3) pitch rotation (in ) (4) yaw rotation (in ) (5) between-slice motion or translation (in mm) (6) within slice up-down motion or translation (in mm) (7) within slice left-right motion or translation (in mm) (8) RMS error before correction (9) RMS error after correction (10) total vector motion or translation (in mm). We need to look at column 10. If any of these values are above 1, this might be indicative of excessive movement. Consult with someone further up the chain for advice (undergrads ask a grad student; grad students ask Chris or a Postdoc if he ever has the funding to get one).
#Run the GLM for Single Subjects([[selxavg3-sess]])
#*Typically, we will do a group-level GLM. I have come to realize that it should generally suffice to do all processing in '''fsaverage''' surface space (mri_glmfit requires all operations to be done in a common surface space).
#*This will be relevant to the parameters you use in steps 4,6 and 8
#Run the group-level GLM ([[mri_glmfit]])
Lab-specific documentation can be found on this wiki, but a more thorough (and accurate) description can be found on the [https://surfer.nmr.mgh.harvard.edu/fswiki/FsFastTutorialV5.1/FsFastFirstLevel Freesurfer Wiki]

== Trouble Shooting ==
=== Missing surfaces ===
Not sure how this came to pass, as I have never encountered this before, but probably was the result of one of the autorecon steps stopping early. I was running preproc-sess using the ''fsaverage'' surface (having already successfully run it on the ''self'' surface) and got an error message about being unable to find lh.sphere.reg. A quick google found a FreeSurfer mailing list archive email that was concerned with a different issue that had a similar solution. In Bruce the Almighty's words:

> >> you can use mris_register with the -1 switch to indicate that the target
> >> is a single surface not a statistical atlas. You will however still have to
> >> create the various surface representations and geometric measures we expect
> >> (e.g. ?h.inflated, ?h.sulc, etc....). If you can convert your
> >> surfaces to our binary format (e.g. using mris_convert) to create
> >> an lh.orig, it would be something like:
> >>
> >> mris_smooth lh.orig lh.smoothwm
> >> mris_inflate lh.smoothwm lh.inflated
> >> mris_sphere lh.inflated lh.sphere
> >> mris_register -1 lh.sphere $TARGET_SUBJECT_DIR/lh.sphere ./lh.sphere.reg
> >>
> >> I've probably left something out, but that basic approach should work.
> >>
> >> cheers
> >> Bruce

The subject that had given me a problem already had ?h.inflated files, but no ?h.sphere files. I tried running some of the above steps but there were missing dependencies. Right now running:
recon-all -s $SUBJECT -surfreg
This allegedly produces the surf.reg files as an output.

=== My script can't find my data ===
Some versions of the autorecon*.sh scripts have the SUBJECTS_DIR hard-coded. Or sometimes you will close your terminal window (e.g., at the end of the day), and then launch a new terminal window when you come back to the workstation (or resume working at a different computer). There's a good chance that your Freesurfer malfunction is the result of your SUBJECTS_DIR environment variable being set to the incorrect value. Troubleshooting step #1 should be the following:
echo $SUBJECTS_DIR
If the wrong directory name is printed to the screen, setting it to the correct value may well fix your problem.

At this point you might expect me to tell you how to set SUBJECTS_DIR to the correct value. But I'm not going to do that, and here's why:
#It's documented elsewhere on the wiki
#If you're confused about how to set SUBJECTS_DIR, you're also likely to just blindly type whatever example command I give without understanding what the command does. If this is the case, please become more proficient with the lab's procedures and software.

=== Is Freesurfer in your path? ===
This is an unlikely issue, but it is possible that your ~/.bashrc file doesn't add Freesurfer to your path. To check, launch a new terminal window. You should see something like the following:
-------- freesurfer-Linux-centos6_x86_64-stable-pub-v5.3.0 --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
FREESURFER_HOME /usr/local/freesurfer
FSFAST_HOME /usr/local/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR /usr/local/freesurfer/subjects
MNI_DIR /usr/local/freesurfer/mni
If you don't, then open up your .bashrc file with a text editor:
gedit ~/.bashrc
Then add the following lines to the bottom of the file:
#FREESURFER
export FREESURFER_HOME=/usr/local/freesurfer
source ${FREESURFER_HOME}/SetUpFreeSurfer.sh

#FSL
export FSLDIR=/usr/share/fsl/5.0
source ${FSLDIR}/etc/fslconf/fsl.sh
Save your changes, log out of Linux and log back in.

=== ERROR: Flag unrecognized. ===
Most Linux programs take parameters, or ''flags'' that modify or specify how they are run. For example, you can't just call the <code>recon-all</code> command; you have to tell the progam ''what'' data you want to work on, and so this information is provided using the <code>-i</code> flag. Other flags might tell the program how aggressive to be when deciding to remove potential skull voxels, for example.
There are no hard-and-fast rules, but to find the set of flags that you can use for a particular Linux program, there are a few options you can try:
#<code>man program_name</code>
#<code>program_name -help</code>
#<code>program_name -?</code>
Though often the <code>program_name -some_flag</code> option causes the usage information to be displayed if ''some_flag'' is not a valid flag.

When you see an error message concerning an unrecognized flag, it is most likely because there is a typo in your command. For example:
recon-all -autorecon1 watershed 15
Each of the flags is supposed to be prefixed with a '-' character, but in the example above, <code>-watershed</code> was instead typed as <code>watershed</code> ''without'' the '-' character. These little typos can be hard to spot.

'''If you are completely perplexed why something doesn't work out when you followed the directions to the letter, the first thing you should do is throw out your assumption that you typed in the command correctly.'''

[[Category:FreeSurfer]]