Practice Working with Data
In this exercise, you will take what you've learned from the course & tutorials so far and apply it to a new dataset.
Preparations
If You're at an Organized Course
If you are taking one of the formally organized courses, everything has been set up for you on the provided laptop. The only thing you will need to do is run the following commands in every new terminal window (aka shell) you open throughout this tutorial. Copy and paste the commands below to get started:
export SUBJECTS_DIR=$TUTORIAL_DATA/practice_with_data cd $SUBJECTS_DIR
To copy: Highlight the command in the box above, right click and select copy (or use keyboard shortcut Ctrl+c), then use the middle button of your mouse to click inside the terminal window (this will paste the command). Press enter to run the command. These two commands set the SUBJECTS_DIR variable to the directory where the data is stored and then navigates into this directory. You can now skip ahead to the tutorial (below the gray line).
If You're not at an Organized Course
If you are NOT taking one of the formally organized courses, then to follow this exercise exactly be sure you've downloaded the tutorial data set before you begin. If you choose not to download the data set you can follow these instructions on your own data, but you will have to substitute your own data paths and subject names. These are the commands that you need to run before getting started:
<source_freesurfer> export TUTORIAL_DATA=<path_to_your_tutorial_data> export SUBJECTS_DIR=$TUTORIAL_DATA/practice_with_data cd $SUBJECTS_DIR
Finding the correct input for the FreeSurfer pipeline
Let's pretend that you just finished scanning a research subject. You collected several different kinds of scans. You would like to get reconstructed surfaces off of this data. What do you do first?
Presumably, you have copied the dicoms for this subject off the scanner to somewhere else. Running the dcmunpack command on the directory in which the dicoms are located creates a text file showing the name of the scan (as you named it on the scanner) and the dicom series each scan corresponds with. From there, you can identify the T1-weighted image you want to use as input to FreeSurfer.
For the purposes of this tutorial, we have a directory of dicoms for you to work with here:
$TUTORIAL_DATA/practice_with_data/dicoms
Open a terminal window. It will be easiest to 'cd' into the directory above to work with the dataset.
Now, run the help flag to learn how to set up the dcmunpack command to create the text file mentioned above:
dcmunpack -help
Type your best guess at the correct command and corresponding flags into the terminal window and see if it works. If it's not working and you give up, scroll down past the arrows to see the correct command setup.
>
>
>
>
>
>
>
DON'T SCROLL BEYOND THESE ARROWS UNLESS YOU WANT THE ANSWER!!
>
>
>
>
>
>
>
>
>
dcmunpack -src . -scanonly scan.log
Some explanation on the command:
-src . indicates which directory to source (you want it to be the one where the dicoms are located). The period indicates to use the directory you are currently located in. Instead of using the period, you could specify the full path to the dicom directory.
-scanonly scan.log says to only scan the directory and create a text file with a list of scans. We decided to call this scan.log but you can name it anything you want.
Depending on how many dicoms are in the directory, this command can take a few minutes to a half hour to run. If it is taking too long, feel free to hit Ctrl+c to cancel it and look at the files that were created when we ran this command previously (details below).
Running the dcmunpack command above creates the text file scan.log. Feel free to use more or any text editor (gedit, emacs, pico, etc.) to view these files. Typically, it is only necessary to check the scan.log:
more scan.log
For the purposes of this tutorial, we have only put a few dicoms in this practice directory. When you look at your scan.log, you'll see:
13 T1w_MPR_vNav_4eRMS 1.69 2530 7 unknown ROW 650 ./I50 18 rfMRI_REST_AP 37 800 52 unknown COL 2290 ./I773
A typical scan.log may look something like this (make your browser window as wide as possible). Note this is only an example file and does not have the same scans or values as your dicoms:
1 Localizer ok 256 256 3 1 mri00003.dcm 2 AAHScout ok 160 160 128 1 mri00004.dcm 3 AAHScout ok 162 162 5 1 mri00133.dcm 4 AAHScout ok 162 162 3 1 mri00139.dcm 5 AAHScout ok 162 162 3 1 mri00141.dcm 6 Localizer_aligned ok 256 256 9 1 mri00151.dcm 7 T1w_setter ok 32 32 32 1 mri00152.dcm 8 T1w_MPR_vNav_4e err 192 192 23 1 mri00305.dcm 9 T1w_MPR_vNav_4e ok 256 256 176 4 mri00345.dcm 10 T1w_MPR_vNav_4e ok 256 256 176 4 mri00344.dcm 11 T1w_MPR_vNav_4e ok 256 256 176 4 mri00343.dcm 12 T1w_MPR_vNav_4e ok 256 256 176 1 mri00391.dcm 13 T1w_MPR_vNav_4e ok 256 256 176 1 mri00392.dcm 14 gre_field_mapping_2mm ok 64 64 72 1 mri02842.dcm 15 SpinEchoFieldMap_AP ok 936 936 1 3 mri02879.dcm 16 SpinEchoFieldMap_PA ok 936 936 1 3 mri02882.dcm 17 rfMRI_REST_AP ok 936 936 1 1 mri02885.dcm 18 rfMRI_REST_AP ok 936 936 1 600 mri02886.dcm 19 rfMRI_REST_AP ok 0 0 1 1 mri03485.dcm 20 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 mri03489.dcm 21 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 mri03487.dcm 22 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 mri03498.dcm 23 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 mri03495.dcm 24 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 mri03519.dcm 25 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 mri03520.dcm 26 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 mri04572.dcm 27 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 mri04567.dcm 28 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 mri04586.dcm 29 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 mri04588.dcm 30 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 mri04544.dcm 31 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 mri04543.dcm 32 t2_tse_ax-2mm ok 512 512 27 1 mri05614.dcm 33 T2w_setter ok 32 32 32 1 mri05626.dcm 34 T2w_SPC_vNav err 192 192 17 1 mri05663.dcm 35 T2w_SPC_vNav ok 256 256 176 1 mri05758.dcm 36 T2w_SPC_vNav ok 256 256 176 1 mri05757.dcm 37 gre3D_1iso_PAT2x2_12e ok 256 256 176 12 mri06089.dcm 38 gre3D_1iso_PAT2x2_12e ok 256 256 176 12 mri06083.dcm 39 gre3D_1iso_PAT2x2_12e ok 256 256 176 12 mri06081.dcm 40 gre3D_1iso_PAT2x2_12e ok 256 256 176 1 mri06099.dcm 41 dMRI_dir98_AP_Blue_Umbrella ok 1400 1400 1 1 mri12593.dcm 42 dMRI_dir98_AP_Blue_Umbrella ok 1400 1400 1 99 mri12594.dcm 43 dMRI_dir98_AP_Blue_Umbrella ok 0 0 1 1 mri12693.dcm 44 t1_mp2rage_sag_p3_iso_TI_1900-3210 ok 256 240 176 1 mri12713.dcm 45 t1_mp2rage_sag_p3_iso_TI_1900-3210 ok 256 240 176 1 mri12712.dcm 46 t1_mp2rage_sag_p3_iso_TI_1900-3210 ok 256 240 176 1 mri12717.dcm 47 t1_mp2rage_sag_p3_iso_TI_1900-3210 ok 256 240 176 1 mri12716.dcm 48 t1_mp2rage_sag_p3_iso_TI_1900-3210 ok 256 240 176 1 mri12731.dcm 49 t1_mp2rage_sag_p3_iso_TI_1900-3210 ok 256 240 176 1 mri12737.dcm 50 BIAS_BC ok 128 128 88 1 mri13750.dcm 51 BIAS_32ch ok 128 128 88 1 mri13902.dcm 52 BIAS_32ch ok 128 128 88 1 mri13840.dcm 53 T1w_MPR_ABCD_800um ok 320 300 208 1 mri14015.dcm 54 tfl_DBS ok 320 260 160 1 mri14379.dcm 55 t2_tse_ax-2mm ok 512 512 27 1 mri14395.dcm 56 T2w_SPC_HCP_700um ok 320 320 256 1 mri14409.dcm 57 T2w_SPC_HCP_700um ok 320 320 256 1 mri14468.dcm 58 t2_tse_ax-2mm ok 512 512 27 1 mri14934.dcm
If you were there at the scan, you probably know which scan above was intended to be the T1-weighted input to FreeSurfer. If you don't, you're typically looking for something called MPRAGE, MEMPRAGE, or SPGR with dimensions 256 x 256 x 176. In the above example, the scan we're interested in is called T1w_MPR_vNav_4e ("vNav" indicates navigators were used for motion correction and "4e" indicates 4 echoes were collected).
Some additional information about the above scan.log: Although T1w_MPR_vNav_4e is listed 6 times, this does not mean 6 of these scans were collected. Notice "err" for error after the first instance of T1w_MPR_vNav_4e as well as the incorrect dimensions. Notice that for some of the scans, there are 4 images in the series (indicated by the 4 following the numbers 256 256 176) and for some there is only 1 image in the series. The difference here is that dicom series with 4 images will provide the 4 echoes uncombined (as separate image files) while the other has combined the echoes by taking the RMS (root mean square) or "average" of the echoes.
We plan to use the RMS as input for FreeSurfer, therefore we will use this T1-weighted dicom series, as seen in the scan.log you produced:
13 T1w_MPR_vNav_4eRMS 1.69 2530 7 unknown ROW 650 ./I50
Now that you've identified the scan you want to use as input to FreeSurfer, what command do you need to use to create surfaces on it?
>
>
>
>
>
>
>
DON'T SCROLL BEYOND THESE ARROWS UNLESS YOU WANT THE ANSWER!!
>
>
>
>
>
>
>
>
>
The correct answer is recon-all. But wait! Before we run that command, there are a few other matters to take care of...
First, before processing a subject with FreeSurfer, you always want to make sure you have:
Sourced FreeSurfer (already done for you if you're at an organized course).
Set the SUBJECTS_DIR variable to the location where the FreeSurfer output should go (make sure there is enough space [around ~300MB])!
For this exercise, let's put the FreeSurfer output directory for this subject just above the dicoms directory you have been working in. You can check where the SUBJECTS_DIR variable is currently set to by doing:
echo $SUBJECTS_DIR
If the output you get from the above command is not the directory above the dicoms directory, how would you change it to set it correctly?
>
>
>
>
>
>
>
DON'T SCROLL BEYOND THESE ARROWS UNLESS YOU WANT THE ANSWER!!
>
>
>
>
>
>
>
>
>
export SUBJECTS_DIR=$TUTORIAL_DATA/practice_with_data
Or, if you're not at an organized course and you're using a tcsh shell instead of bash, you would use setenv instead of export. (More info on this command and the different shells is here.)
Once your SUBJECTS_DIR is set, you can type up the recon-all command needed to process a subject using dicoms as the input. Try it out before looking at the answer. If things go horribly wrong, you can always do Ctrl+c to stop it :).
>
>
>
>
>
>
>
DON'T SCROLL BEYOND THESE ARROWS UNLESS YOU WANT THE ANSWER!!
>
>
>
>
>
>
>
>
>
Hint:
recon-all \ -all \ -i <one slice in the anatomical dicom series> \ -s <subject id that you make up> \
Some explanation on the command:
-all will run all the steps in the FreeSurfer processing stream. Alternatively, you can run different parts of the stream.
-i stands for input. Here, you would specify one dicom file/slice in the T1-weighted scan series you collected (FreeSurfer will find the rest of the files in the DICOM series/ the rest of the slices automatically). Make sure you specify the full path to the file if it is not in the directory you are currently in. You could also specify nifti files as input. If you have more than one T1-weighted scan for a given subject, use additional -i flags for each one.
-s specifies the name or ID of the subject you would like to use. A directory with that name will be created for all the subject's FreeSurfer output.
>
>
>
>
>
>
>
>
>
The answer (assumes you are still inside the dicoms directory):
recon-all -all -i I50 -s Subj001
Feel free to run the command. You can let it run overnight or stop it at any point using Ctrl+c.
The command will create a new directory, called Subj001, in the directory above the dicoms directory. You can cd to that directory to see what has been created so far but you will have to open a new terminal window to do this if recon-all is still running.
The process is complete when the last line printed to the screen (and in the recon-all.log found in the subject's scripts directory) says "recon-all exited without errors". If you do let recon-all complete, you can use the freeview commands you learned in the other tutorials to open and inspect the data.
Batch Processing
Say you have DICOM files for hundreds of subjects and you want to process them using FreeSurfer. You can submit them to recon-all with just a couple of commands. For a sample script, look here. This information is linked to the course homepage at the bottom under "Additional Useful Information."
Summary
By the end of this exercise, you should know how to:
- unpack a set of scan dicoms
- find the correct input dicom file for a T1 weighted scan
pass this input dicom file to FreeSurfer's recon-all stream.
(Note: the following exercise requires data which has yet to be added to the tutorial data set, the data will be available by the September course)
Exercise 1
Difficulty: Beginner
Goal: Prepare a dicom series for the recon-all stream
Your goal is to set up your environment variables and assemble the correct recon-all command to process a dicom series.
To begin navigate to the following directory in your terminal: $TUTORIAL_DATA/practice_with_dicoms
Take a look at the directories found there. The dicoms directory contains a dicom series, and the subjects directory is where your recon-all subject output should go. You will want to use dcmunpack to find the first image of the first T1w_MPR_vNav_4eRMS series, set your SUBJECT_DIR environment variable, then then type out and run your recon-all command (use practice_subject as the subject name). Make sure the command starts without any errors - and if it does cancel the process by pressing ctrl and c on the keyboard (a recon-all can take many hours!).
Check in the work directory to ensure a directory with your subject's name was created (practice_subject), if you see the folder you have completed the challenge!
Hints:
- Follow the tutorial example for guidance
- It might be tricky to find the path to the subjects directory if you are new to Unix, you can use this: $TUTORIAL_DATA/practice_with_dicoms/subjects
You will find two T1 weighted volumes - you will select the first one. In a real experimental scenario you or the experiment designer would know which scan was intended for a structural processing through FreeSurfer.
Want to see the answer? Highlight the lines below
cd $TUTORIAL_DATA/dicom_challenge \ |
cd dicoms \ |
dcmunpack -src . -scanonly scan.log |
export SUBJECTS_DIR = $TUTORIAL_DATA/practice_with_dicoms |
recon-all -all -i I50 -s practice_subject |
Quiz
You can test your knowledge of this tutorial by clicking here for a quiz!