PHILIPS B0 UNWARPING IN FSL FEAT ON SHARK (OR LOCALLY)

Transcription

1 PHILIPS B0 UNWARPING IN FSL FEAT ON SHARK (OR LOCALLY) LATEST VERSION: MARCH, 2017 ANNA VAN T VEER & ANNE HAFKEMEIJER HENK VAN STEENBERGEN & JANNA MARIE BAS-HOOGENDAM This le is updated every now and. Check whether you have the latest version: 1. GETTING STARTED This manual describes how you can use a B0-map scan from for instance the LIBC Philips Achieva scanner to correct for distortions due to B0 inhomogeneities. In other words, putting participants in the scanner messes up the uniform magnetic eld and in places where the signal is displaced it can be brought back to the correct position (if the signal is lost it cannot be recovered, but this fact is also taken into account, see below). FSL recommends using the B0 scan, as it can enhance your analyses at the group level considerably. The scan itself only takes about 1 minute and 5 seconds, so why not use it? This manual will help you construct the required eldmap images for B0 unwarping in FEAT. Once you have used the steps below to verify specic parameters that apply to you, you should be able to things more automated for multiple data sets (e.g., multiple participants), and throughout this manual we therefore include commands that can be run on the SHARK cluster. IMPORTANT NOTE: This manual can only be used on B0 scans that were acquired with parameters that were added to the example examcard on the LIBC scanner after March This means that if you have B0 scans from before that time (in other words, if you copied the B0 scan from the example examcard before that time) you cannot correct for inhomogeneities (for a more detailed explanation ask one of the authors). What you need? - the B0 PAR/REC les of B0 scans that are acquired after March If you have exported only the nii les from the scanner you will probably have partial B0 data and there is likely no way to x this. So always export the PAR/REC les for the B0 scan! - A terminal (and access to SHARK if you want to run this there). - Dcm2nii (already available on SHARK or wnload it here if you run locally: - Parameters from your scans, see under 6. B0 unwarping in FEAT Log in on to the SHARK cluster. Use your usual way of logging into shark, e.g. with mobaxterm (manual available soon here) or with the terminal on a Mac (see ssh cong in the SHARK on a mac manual for a nice way to set this up). Or, if you are in the LUMC, in the terminal, type: $ ssh XY username@ Enter your shark password. If you want to change your password (once in 3 months), use: $ passwd Enter rst your old password, followed by twice your new one. Dcm2nii (version June 1, 2015) is installed on the cluster under: $ /usr/local/bin/dcm2nii If you are working locally, make sure you have the path to where Dcm2nii is installed. 1

2 2. USE DCM2NII TO CONVERT PAR/REC FILES OF A FIRST PARTICIPANT For the following, we assume your B0 les are saved as PAR/REC les in separate subject directories in your project folder. Go to the project folder. In our case: $ cd /data/projecta Within this folder we will use dcm2nii to recode all *.PAR les that include the description B0. Check whether the B0 images are in the folders, for example in folder 004: $ ls 004/*B0*.PAR 004/ProjectA004^^^^_WIP_B0-map_5_1.PAR To convert this le to nii.gz we use the following command: $ /usr/local/bin/dcm2nii -v N -f Y -o./004./004/*b0*.par In the parameters we have dened (from left to right): dicom to nifti converter tool (dcm2nii), not (N) all les in the folder (-v), indicated to keep (Y) the original name in the le name of converted le (-f), the output directory (-o), and the input le. Don t forget using the./ indicating that the paths are relative to the current folder. Let's see what dcm2nii produced. $ ls 004/*B0*.nii.gz 004/ _092455ProjectA004^^^^_WIP_B0-map_5_1WIPB0-maps005a001x1.nii.gz 004/ _092455ProjectA004^^^^_WIP_B0-map_5_1WIPB0-maps005a001x2.nii.gz So, dcm2nii produced two les. 3. CONVERT ALL PAR/REC FILES USING FSL_SUB Let's now convert all B0 les in all subject directories. Don t this on the head node. Rather submit it as a job to the cluster. The easiest way is to call fsl_sub and submit it to any queue (*.q) because conversion is quick and a predened queue is not necessary. So simply add fsl_sub q *.q before copy-pasting the earlier command. $ fsl_sub -q *.q /usr/local/bin/dcm2nii -v N -f Y o./004./004/*b0*.par <fsl_sub gives back jobnumber> Because we would like to the conversion for each subject directory, we will use pipelining statements in combination with the beloved xargs to submit many conversion jobs to the cluster. In Appendix A we explain how you can also this using loops in a bash script. Let's rst get a list of subject directories. Remember: the number of question marks must represent the number of characters of the names of your subject directories! In our case: $ ls d??? We want to pass (pipe) the output of ls to the fsl_sub command mentioned before. For that reason we use xargs. For example: $ ls -d??? xargs -I TODO echo Hello this is directory TODO 2

3 This will call echo repeatedly and put the output of ls in the placeholder text TODO. This will create the following output: Hello this is directory 001 Hello this is directory 002 Hello this is directory 003 ( ) Hello this is directory 028 Hello this is directory 029 Hello this is directory 030 Try this yourself. Let's now apply this to the fsl_sub command. We rst use the echo statement so that it only shows the command and es not execute it. Use the TODO placeholder to replace 004 $ ls -d??? xargs -I TODO echo fsl_sub -q *.q /usr/local/bin/dcm2nii -v N -f Y -o./todo./todo/*b0*.par This should give you the following output: fsl_sub -q *.q /home/username/software/mricron/dcm2nii -f Y -v N -o./001./001/*b0*.par fsl_sub -q *.q /home/username/software/mricron/dcm2nii -f Y -v N -o./002./002/*b0*.par fsl_sub -q *.q /home/username/software/mricron/dcm2nii -f Y -v N -o./003./003/*b0*.par ( ) fsl_sub -q *.q /home/username/software/mricron/dcm2nii -f Y -v N -o./028./028/*b0*.par fsl_sub -q *.q /home/username/software/mricron/dcm2nii -f Y -v N -o./029./029/*b0*.par fsl_sub -q *.q /home/username/software/mricron/dcm2nii -f Y -v N -o./030./030/*b0*.par Check whether these are the commands you want to execute. As soon you are sure, just add bash at the end of the previous command to execute it. This will execute fsl_sub and submit all jobs to the cluster. $ ls -d??? xargs -I TODO echo fsl_sub -q *.q /usr/local/bin/dcm2nii -v N -f Y -o./todo./todo/*b0*.par bash Use qstat to check when the conversions are. Check the output log les (e.g. use cat *.o*) and error log les (e.g. use cat *.e*) les in the folder where you submitted the jobs. Remove the output les and error les if you have checked them (e.g ls *.e*; ls *.o*; replace ls with rm if you are sure that you want to remove the les). When all jobs are nished, check whether the converted les have been created. $ ls???/*b0*.nii.gz should give: 001/ _204859ProjectA030^^^^_WIP_B0-map_5_1WIPB0-maps005a001x1.nii.gz 001/ _204859ProjectA030^^^^_WIP_B0-map_5_1WIPB0-maps005a001x2.nii.gz ( ) 030/ _145035ProjectA016^^^^_WIP_B0-map_5_1WIPB0-maps005a001x1.nii.gz 030/ _145035ProjectA016^^^^_WIP_B0-map_5_1WIPB0-maps005a001x2.nii.gz 3

4 4. CHECK CONVERTED FILES Check what the data looks like (see Open the les in fslview 1. In this case the 001x1 le is the magnitude image whereas the 001x2 le is the real eldmap image. For the eldmap image, you may want to play around with the min and max brightness/contrast tools. Rename the les to reflect what type the les are. Only use the command line statements below if you are absolutely sure what you are ing. Otherwise, just the renaming manually. Step 1: rename the 001x1.nii.gz les to B0_magnitude.nii.gz. $ ls -d??? xargs -I TODO echo mv./todo/*b0*001x1.nii.gz./todo/b0_magnitude.nii.gz Check the result. Are you sure you want to this? Add bash at the end of the command to execute it. Step 2. We the same for 001x2 (rename 001x2.nii.gz to B0_realeldmap.nii.gz): $ ls -d??? xargs -I TODO echo mv./todo/*b0*001x2.nii.gz./todo/b0_realeldmap.nii.gz Add bash if you are ready. Check whether the correct les are in the subject folders: $ ls???/b0* should give: 001/B0_magnitude.nii.gz 001/B0_realeldmap.nii.gz ( ) 030/B0_magnitude.nii.gz 030/B0_realeldmap.nii.gz Open the les in fslview (or fsleyes in the future) and check whether they indeed show magnitude and eldmap information respectively (see example below). The eldmap image likely shows negative and positive values (adapt the scale if necessary) and shows inhomogeneities mainly in the inferior regions of the brain. The magnitude images looks more like a structural image and likely only includes positive values. Magnitude image Real eldmap image 1 If this esn t work using the command line, try opening fslview and choosing le, open. 4

5 5. PREPROCESS IMAGES PREPROCESS REAL FIELDMAP IMAGE Following the instructions on we will now process the eldmap to get it in rad/s (Hz) by multiplying the map with 2 * pi: $ fslmaths B0_realeldmap -mul 6.28 B0_eldmap_rads Or to this for all subjects on the cluster: $ ls -d??? xargs -I TODO echo fsl_sub -q *.q fslmaths./todo/b0_realeldmap -mul 6.28./TODO/B0_eldmap_rads Check the result. Are you sure you want to this? Add bash at the end of the command to execute it. Because the eldmap is noisy, we will need some regularization (many options available, see FSL cumentation). We have used median ltering here: $ fugue --loadfmap=b0_eldmap_rads -m --savefmap=b0_eldmap_rads_reg Do this for all subjects in your folder using (this can take a little time): $ ls -d??? xargs -I TODO echo fsl_sub -q *.q fugue -- loadfmap=./todo/b0_eldmap_rads -m --savefmap=./todo/b0_eldmap_rads_reg Add bash if you are ready. PREPROCESS MAGNITUDE IMAGE In order to use the magnitude image in FEAT we need to extract the brain from it: $ bet B0_magnitude B0_magnitude_brain Check whether this worked: $ fslview B0_magnitude B0_magnitude_brain -l Green & Do this for all subjects: $ ls -d??? xargs -I TODO echo fsl_sub -q *.q bet./todo/b0_magnitude./todo/b0_magnitude_brain Check the result. Are you sure you want to this? Add bash at the end of the command to execute it. Check bet for all subjects using fslview: $ ls -d??? xargs -I TODO echo fslview./todo/b0_magnitude./todo/b0_magnitude_brain -l Green Add bash if you are ready. The rst participant will be shown in fslview. Closing the winw will open the next participant, so you can check all betting. If this command esn t work, try opening B0_magnitude via File/Open in fslview and adding B0_magnitude_brain via File/Add. 5

6 Next to betting this magnitude image, we will also erode it (removing one voxel from all edges) as eldmap images contain a noisy rim around the brain. It is advised by the FMRIB experts to stick with the erosion as the safe, albeit conservative, option. $ fslmaths 001/B0_magnitude_brain ero 001/B0_magnitude_brain_ero These are the parameters we have dened (from left to right): the fslmaths tool (fslmaths), the input le (B0_magnitude_brain), the operation (-ero), and the output le (B0_magnitude_brain_ero). This fslmaths function removes noisy voxels at the edge. Check whether this worked: $ fslview 001/B0_magnitude_brain 001/B0_magnitude_brain_ero l Red-Yellow & Do this for all subjects: $ ls -d??? xargs -I TODO echo fsl_sub -q *.q fslmaths./todo/b0_magnitude_brain - ero./todo/b0_magnitude_brain_ero Check the result. Are you sure you want to this? Add bash at the end of the command to execute it. Check what this looks like for all subjects using fslview: $ ls -d??? xargs -I TODO echo fslview./todo/b0_magnitude_brain./todo/b0_magnitude_brain_ero -l Red-Yellow Add bash if you are ready. REMOVE OLD FILES AND RENAME THE _ERO FILE We only want to keep the following nii les: B0_eldmap_rads_reg.nii.gz (needed in FEAT) B0_magnitude.nii.gz (needed in the same folder as the B0_magnitude_brain.nii.gz for FEAT) B0_magnitude_brain_ero.nii.gz rename (see below) to B0_magnitude_brain.nii.gz (needed FEAT) So list the other nii les: $ ls???/b0_realeldmap.nii.gz $ ls???/b0_eldmap_rads.nii.gz $ ls???/b0_magnitude_brain.nii.gz replace ls with rm to remove them! Always keep the PAR/REC les. Rename B0_magnitude_brain_ero.nii.gz to B0_magnitude_brain.nii.gz (needed FEAT) $ mv???/b0_magnitude_brain_ero.nii.gz???/b0_magnitude_brain.nii.gz 6

7 6. B0 UNWARPING IN FEAT We are going to run Feat for each subject using B0 unwarping. Open Feat gui and use your favorite settings. Check whether they are up to date. For example, we have learned that in FSL you should not use an expanded structural image (a high resolution functional scan, often called hires ) in the registration steps if you use whole brain fmri scans. 2 For B0 unwarping, go to tab 'prestat' and check B0 unwarping. Fieldmap = B0_eldmap_rads_reg.nii.gz Fieldmap mag = B0_magnitude_brain.nii.gz Make sure that the B0_magnitude.nii.gz le (so without _brain) is in the same folder (fsl uses this too). We have used the default 10% signal loss threshold. From the FSL website: This determines where the signal loss in the EPI is too great for registration to get a good match between the EPI data and other images. Areas where the % signal loss in the EPI exceeds this threshold will get masked out of the registration process between the EPI and the eldmap and structural images. SET EFFECTIVE ECHO SPACING, EPI TE AND UNWARP DIRECTION. Effective echo spacing. You will need to calculate this value using a formula (please note that the formula we provide here is for 3 Tesla scanners): ( retrieved 28 July 2014): "For Philips Achieva, the best equation for calculating "effective" echo spacing (corrected for accelerated imaging) in milliseconds would seem to be: effective echo spacing = (((1000 * wfs)/( * (etl+1))/acceleration) where wfs is the value of water fat shift in pixels, etl is the echo train length (Philips calls this the epi factor) and acceleration represents the degree of parallel imaging acceleration (SENSE in Philips terminology). Please check these settings at the scanner in the geometry tab of your fmri (see example screenshot below). Remember that these numbers are settings related to your fmri scans (not the B0)! 2 see for a forum question about this. 7

8 You will need: Water fat shift (wfs) EPI factor (echo train length, etl) SENSE p reduction (AP, degree of parallel imaging acceleration, acceleration) EPI TE The water fat shift and EPI factor (echo train length) can also be read from the.par le using geany. $ geany fmri.par & SENSE p reduction can also be found in a text le saved from the scanner exam card. For our particular dataset we got the following values: (Check this data for your own exam card!) Act. WFS (pix) / BW (Hz) = " / 33.4"; EPI factor = 35; SENSE = "yes"; P reduction (AP) = 2.5; Based on these values, we can calculate effective echo spacing (using the Spinoza centre formula): effective echo spacing = (((1000 * wfs)/( * (etl+1))/acceleration) effective echo spacing = (((1000 * )/( * (35+1))/2.5) effective echo spacing = So in the FEAT winws we use effective echo spacing =

9 EPI-TE In addition, based on the exam card info: TE = "user dened"; (ms) = 30; EPI TE (ms) in FEAT was set to 30. Unwarp direction Test both +y and y. The right choice should be identiable in the post-stats section of resulting FEAT report or even better by checking the raw example_func and example_func_orig_distorted images in fslview (instructions below). The example_func should be horizontally squeezed rather than stretched. See the examples on next pages! In our case we have set unwarp direction to +y. In the results with the +y direction, the visible structures are generally well aligned (e.g. ventricles, cerebellum, frontal lobes) except in some areas near air, but this is due to signal loss in the functional images that cannot be corrected for by unwarping. So you cannot evaluate the accuracy of the registrations by looking in these regions, as the signal loss means that the borders are not anatomical borders but articial ones created by signal loss. We recommend that you have a closer look at this result, taking into account the issue with the signal loss, and see if it looks accurate in the areas away from the signal loss (which will be in the inferior frontal and temporal lobes). Run your own registration with unwarping (remember to leave out the hires scan in the registration tab!) and the following to check your results: - In fslview, open (from the reg folder) the highres.nii.gz scan (this is your structural image) and add example_func2highres.nii.gz - Add the example_func2highres_fast_wmedge.nii.gz, and click the i (information icon in lower part of fslview) while this image is selected in order to change the color from greyscale to red (select the color under Lookup table options in the winw that opens after clicking the information icon). Carefully check whether the red lines are corresponding to the anatomical borders. - Select the example_func2highres image and use the transparency slider (located below the eld where you select the images) to slowly see the highres image (remember you opened that one rst, so it was hiding below the other images). This should enable you to see whether the scans are aligned (the red lines are derived from the highres scan, so this should give you similar conclusions). - Then add from the unwarp folder within the reg folder the image called example_func_distorted2highres, this shows you the uncorrected registration result. Play around with which image is on top: es the example_func2highres t better on the anatomical brain than the example_func_distorted2highres? If yes, using the B0 map was a good idea. If the frontal lobe and the occipital lobe of your functional data (example_func) get pushed inwards (this is likely to happen due to unwarping), make sure they not go more inwards than where you know the brain boundaries are by looking at the structural brain (use the transparency slider to see whether the uncorrected or the corrected ts better on the hires). - If you ran this registration twice, once with +y and once with y (well!), open the same les for the other y-direction in another fslview winw so you can compare the results. When comparing the images, remember to choose the same x,y,z values (although the images may still look a little different due to the correction off course) and to set the transparency the same (for all example_func2highres images so the structural scan will show equally). Below you can see an example of an uncorrected fmri scan and a corrected scan. Notice how in the corrected scan the red lines (the structural borders) align better with tissue changes, such as around the csf. 9

10 Uncorrected: Corrected (notice how the area s indicated by the arrows improve in this image): In your report, go to Registration, Unwarping. Have a look at the gif at the bottom of the page. You might get a grey image for the distorted (or for both scans). We have checked this with the fsl people and their answer was that this is just the gif that is incorrect; it is probably because the automatic intensity scaling has gone wrong in the image generation tool. This esn t affect your analyses, just this illustration for the webpage. From this gif you might already see that the B0 correction improved your scans, but it is always better to look at the images as described above (i.e., with fslview). 10

11 APPENDIX A. EXAMPLE OF PREPROCESSING B0 MAPS WITH LOOPS IN A BASH SCRIPT For a variety of reasons, you might want to use loops in your bash script when preprocessing the B0 maps, instead of the one-liners (using pipes and xargs) used in the cumentation above. One example might be that you want to rename all your les using a participant ID that is in a folder name (e.g., the folder is called ID001 and the scan inside it esn t have a unique ID but you want it to be named using the folder name). Another example is that using a loop may be a useful way of ing the preprocessing on new data that has come in, without re-ing the old data again. In other words, you could ask the loop to see if a certain le already exists (say, the preprocessed eldmap) and IF there is no such le for a certain participant THEN to go ahead and start preprocessing the raw les. Below we provide an example of scripts that all the B0 preprocessing steps in loops. Please be careful when using these as you should always make sure you know what you are ing (n t just mindlessly copy and paste!). In this example, we have the data for participant (PP) 001 in the following two session folders: Data/ProjectA/001/SESSION1 Data/ProjectA/001/SESSION2 Specify the interpreter you want to run the following commands with. $ #!/bin/bash Set the directory. $ DIR=/Users/Data/ProjectA For each participant (PP) in the participants list (i.e., all subfolders in ProjectA, *), and for both the sessions of these participants (i.e., the subfolders within the subfolders in ProjectA, which are named SESSION1 and SESSION2 in our example), the following: see if the *001x* le (one of the converted par les) is not there yet, and if the le is not there (! f), convert the *B0*.PAR le (convert the le that has B0 somewhere in the name and ends in.par). #if no converted les exist, convert the par if [! -f $DIR/$PP/$SESSION/*001x* ] /APPlications/mricron/dcm2nii -v N -f Y -o $DIR/$PP/$SESSION $DIR/$PP/$SESSION/*B0*.PAR Rename the new les. DIR=/Users/Data/ProjectA if [! -f $DIR/$PP/$SESSION/B0_magnitude ] mv $DIR/$PP/$SESSION/*B0*001x1.nii.gz $DIR/$PP/$SESSION/B0_magnitude.nii.gz if [! -f $DIR/$PP/$SESSION/B0_realeldmap ] mv $DIR/$PP/$SESSION/*B0*001x2.nii.gz $DIR/$PP/$SESSION/B0_realeldmap.nii.gz 11

12 Make the eldmap in rad/s. DIR=/Users/Data/ProjectA if [! -f $DIR/$PP/$SESSION/B0_eldmap_rads ] mv fslmaths $DIR/$PP/$SESSION/B0_realeldmap -mul 6.28 $DIR/$PP/$SESSION/B0_eldmap_rads Regularize the eldmap. DIR=/Users/Data/ProjectA if [! -f $DIR/$PP/$SESSION/B0_eldmap_rads_reg ] fugue --loadfmap=$dir/$pp/$session/b0_eldmap_rads -m -- savefmap=$dir/$pp/$session/b0_eldmap_rads_reg Erode the magnitude image. DIR=/Users/Data/ProjectA if [! -f $DIR/$PP/$SESSION/B0_magnitude_brain_ero ] fslmaths $DIR/$PP/$SESSION/B0_magnitude_brain -ero $DIR/$PP/$SESSION/B0_magnitude_brain_ero Remove unneeded les; rst list the les for removal (should be B0_realeldmap.nii.gz, B0_eldmap_rads.nii.gz, B0_magnitude_brain.nii.gz) and delete if you are sure. DIR=/Users/Data/ProjectA if [ -f $DIR/$PP/$SESSION/B0_magnitude_brain_ero ] ls $DIR/$PP/$SESSION/B0_realeldmap.nii.gz ls $DIR/$PP/$SESSION/B0_eldmap_rads.nii.gz ls $DIR/$PP/$SESSION/B0_magnitude_brain 12

13 Sure? DIR=/Users/Data/ProjectA if [ -f $DIR/$PP/$SESSION/B0_magnitude_brain_ero ] rm $DIR/$PP/$SESSION/B0_realeldmap.nii.gz rm $DIR/$PP/$SESSION/B0_eldmap_rads.nii.gz rm $DIR/$PP/$SESSION/B0_magnitude_brain Rename the B0_magnitude_brain_ero le to B0_magnitude_brain. DIR=/Users/Data/ProjectA if [ -f $DIR/$PP/$SESSION/B0_magnitude_brain_ero ] mv $DIR/$PP/$SESSION/B0_magnitude_brain_ero.nii.gz $DIR/$PP/$SESSION/B0_magnitude_brain.nii.gz If you are happy with the above loops, you can submit them on SHARK by putting your loops in a.sh le and submitting that using qsub: $ qsub B0loople.sh This is an example of what is in your B0loople.sh (replace the blue text with your chosen script name / address): #!/bin/bash #$ -S /bin/bash #$ -q all.q #$ -N script_par_convert #$ -cwd #$ -j Y #$ -V #$ -m be #$ -M username@fsw.leidenuniv.nl DIR=/exports/fsw/ProjectA #if no converted les exist, convert the par if [! -f $DIR/$PP/$SESSION/*001x* ] /Applications/mricron/dcm2nii -v N -f Y -o $DIR/$PP/$SESSION $DIR/$PP/$SESSION/*B0*.PAR Check your to see if the job is, or use qstat if you are impatient and want to see if it s running already. Then use cat script*.e* to see if running the script had any errors. 13

14 APPENDIX B. ADDITIONAL EXAMCARD INFORMATION: CONFIGURING THE B0 SCAN If you are setting up your examcard and want to add the B0 map, there is an example scan in the example les that the LIBC uses. If you want to check your own scan, pay attention to the following settings: 1) Set the shimming to auto (see picture below): the same shimming is used as in the fmri scans (e.g., your task data). 2) Set the scan to fmri (see picture below); this will ensure the eld of view is the same as in your fmri scans, which is the same fov that you want to the correction in, so this is preferable (although bigger fov boxes cannot hurt). 3) You can best perform the B0 scan after the functional scans that you want to correct (this way you are sure that settings are the same). If you have different goals, such as ing a B0 map scan on a 7 tesla for testing purposes instead of correction purposes, you might want to the exact opposite: a B0 map rst and set the shim to default (consult your technician if you are not sure what your best options are). 14