| Deletions are marked like this. | Additions are marked like this. |
| Line 33: | Line 33: |
| Presumably, you have copied the dicoms for this subject off the scanner to somewhere else. Running the {{{unpacksdcmdir}}} 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 it corresponds with. From there, you can identify the T1-weighted image you want to use as input to !FreeSurfer. | Presumably, you have copied the dicoms for this subject off the scanner to somewhere else. Running the {{{unpacksdcmdir}}} 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. |
Back to list of all tutorials Back to course page
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/buckner_data/tutorial_subjs 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/buckner_data/tutorial_subjs 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 unpacksdcmdir 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:
/path/to/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 unpacksdcmdir command to create the text file mentioned above:
unpacksdcmdir --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!!
>
>
>
>
>
>
>
>
>
unpacksdcmdir -src . -targ . -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.
-targ . indicates the target destination for the text file. Again, you could specify a path to a location instead of using the current 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 unpacksdcmdir command above creates the text file scan.log as well as unpack.log and dicomdir.sumfile. Feel free to use any text editor (gedit, emacs, pico, etc.) to view these files. To move on to the next step, the easiest is to check the scan.log:
gedit scan.log
You will see something like this (make your browser window as wide as possible):
19 rfMRI_REST_AP err -1 -1 1 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718302176932206486 43 dMRI_dir98_AP_Blue_Umbrella err -1 -1 1 1 MR.1.3.12.2.1107.5.2.43.67026.201707171911366471881282 1 Localizer ok 256 256 3 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718091278804745060 2 AAHScout ok 160 160 128 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718092818353645283 3 AAHScout ok 162 162 5 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718093274784146234 4 AAHScout ok 162 162 3 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718093274859646238 5 AAHScout ok 162 162 3 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718093274911846241 6 Localizer_aligned ok 256 256 9 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718095692940546264 7 T1w_setter ok 32 32 32 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718104448601646302 8 T1w_MPR_vNav_4e err 32 32 1 159 MR.1.3.12.2.1107.5.2.43.67026.2017071718164194148262553 9 T1w_MPR_vNav_4e ok 256 256 176 4 MR.1.3.12.2.1107.5.2.43.67026.2017071718183745719167585 10 T1w_MPR_vNav_4e ok 256 256 176 4 MR.1.3.12.2.1107.5.2.43.67026.2017071718183745107467584 11 T1w_MPR_vNav_4e ok 256 256 176 4 MR.1.3.12.2.1107.5.2.43.67026.2017071718183745086167583 12 T1w_MPR_vNav_4e ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718183762466867688 13 T1w_MPR_vNav_4e ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718183763082267690 14 gre_field_mapping_2mm ok 64 64 72 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718195795709374046 15 SpinEchoFieldMap_AP ok 104 104 72 3 MR.1.3.12.2.1107.5.2.43.67026.2017071718203235570174376 16 SpinEchoFieldMap_PA ok 104 104 72 3 MR.1.3.12.2.1107.5.2.43.67026.2017071718211177006975034 17 rfMRI_REST_AP err 104 104 72 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718224883392580574 18 rfMRI_REST_AP ok 104 104 72 600 MR.1.3.12.2.1107.5.2.43.67026.2017071718224933356480728 20 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718405780296306738 21 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718405779709906735 22 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718405784369006754 23 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718405783794306750 24 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718405795817006792 25 t1_mp2rage_sag_p3_iso_TI_0700-2500 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718405796544506795 26 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718494130160309420 27 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718494129486309412 28 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718494143744009445 29 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718494145168309452 30 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718494120123309369 31 t1_mp2rage_sag_p3_iso_TI_1300-2700 ok 256 240 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718494119530309368 32 t2_tse_ax-2mm ok 512 512 27 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718523615631111833 33 T2w_setter ok 32 32 32 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718524612703111932 34 T2w_SPC_vNav err 32 32 1 71 MR.1.3.12.2.1107.5.2.43.67026.2017071718531066825212797 35 T2w_SPC_vNav ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718564877227921505 36 T2w_SPC_vNav ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718564876615021504 37 gre3D_1iso_PAT2x2_12e ok 256 256 176 12 MR.1.3.12.2.1107.5.2.43.67026.2017071719054080732722265 38 gre3D_1iso_PAT2x2_12e ok 256 256 176 12 MR.1.3.12.2.1107.5.2.43.67026.2017071719054077330622237 39 gre3D_1iso_PAT2x2_12e ok 256 256 176 12 MR.1.3.12.2.1107.5.2.43.67026.2017071719054076460222227 40 gre3D_1iso_PAT2x2_12e ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071719054081692222280
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 with "vNav" indicating navigators were used for motion correction and "4e" indicating 4 echoes were collected.
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 dimensions (indicated by the 4 following the numbers 256 256 176) and for two scans there is only 1 dimension. The two scans with only 1 dimension are likely the RMS (root mean square) or "average" of the echoes. We'll use the RMS as input for FreeSurfer, therefore we will use this T1-weighted dicom series:
12 T1w_MPR_vNav_4e ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718183762466867688 13 T1w_MPR_vNav_4e ok 256 256 176 1 MR.1.3.12.2.1107.5.2.43.67026.2017071718183763082267690
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?
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!!
>
>
>
>
>
>
>
>
>
First, you always want to make sure the variable SUBJECTS_DIR is set to the location where the FreeSurfer output should go.
echo $SUBJECTS_DIR
For the purposes of this tutorial, SUBJECTS_DIR should be set to ???.
Once your SUBJECTS_DIR is set, you would run the recon-all command using this format:
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 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.
recon-all -all -i MR.1.3.12.2.1107.5.2.43.67026.2017071718183762466867688 -s Subj001
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".