This is an old revision of the document!
Table of Contents
EPI Correction with polarity images using TOPUP
Steps to setup and apply FSL Topup correction on EPI data collected here with the use of your polarity images
Create your acquisition parameters
There will be two series of single timepoint EPI images. You can grab relevant info to create the acq_params.txt files from your XML header.
You need to calculate readout time in seconds ( the physical time it takes to get the acquisition matrix of a single slice ) and get the polarity direction ( phase encode direction ).
the readout time for the parameter file will be:
readout = (echospacing * (acquisitionmatrix[0] * (percentsampling/100))) / 1e6 echospacing in BXH header is in microseconds
the polarity for the entry will have to be determined from the seriesdescription, which is typically “field map reverse polarity” or “field map regular”
reverse will be “-1” in the acq_params.txt and regular will be “1”
echo '0 1 0 readout' > acq_params.txt echo '0 -1 0 readout' >> acq_params.txt example output: 0 1 0 0.077312 0 -1 0 0.077312
Create your Blip Up/Down image
Merge the two polarity images together into a 4D file with fsl_merge. Put them in the order of your acq_params.txt file. In the example above, it would be regular, then reversed.
fslmerge -t bud ../bia6_00186_006.nii.gz ../bia6_00186_007.nii.gz tesla:00273 cmp12$ fslinfo bud.nii.gz data_type INT16 dim1 128 dim2 128 dim3 70 dim4 2
Run topup to calculate the field and coefficients images for correction
#run popup calculate the field/coef topup --verbose --imain=bud --datain=acq_params.txt --config=$FSLDIR/src/topup/flirtsch/b02b0.cnf --out=rs_topup --fout=topup_field
Now apply the correction to your functional runs
inindex references the “regular” image index from your acq_params.txt file, which is the same phase encode direction of your functional runs
#apply it applytopup --imain=../bia6_00186_008_01.nii.gz --inindex=1 --method=jac --datain=acq_params.txt --topup=rs_topup --out=run008 --verbose applytopup --imain=../bia6_00186_009_01.nii.gz --inindex=1 --method=jac --datain=acq_params.txt --topup=rs_topup --out=run009 --verbose applytopup --imain=../bia6_00186_010_01.nii.gz --inindex=1 --method=jac --datain=acq_params.txt --topup=rs_topup --out=run010 --verbose
The top two images are an example of the polarity images after correction, which is not necessary. The bottom two images are the mean functional image of a series uncorrected, then corrected by the topup results.
If you want to re-generate a valid BXH for the corrected data, you can generate a new BXH and merge in the original info
fslwrapbxh run008 mv run008.bxh tmp.bxh bxh_merge ../bia6_00186_008_01.bxh tmp.bxh run008.bxh rm tmp.bxh
DWI Correction with B0s using TOPUP
Correcting DWI images using B0s is almost the same as the above. Typically you'll have a couple B0s in your normal DWI acquisition, with a separate series of the same number of B0s collected with the phase encoding direction reversed.
Create your acq_params.txt file
the ETL for the parameter file will be:
ETL = ( echospacing * echotrainlength ) / 1000 #in secs
the regular B0s will get the “1” and the reverse phase B0s will get the “-1”
echo '0 1 0 [ETL]' > acq_params.txt echo '0 1 0 [ETL]' >> acq_params.txt echo '0 -1 0 [ETL]' >> acq_params.txt echo '0 -1 0 [ETL]' >> acq_params.txt example output: 0 1 0 0.740 0 1 0 0.740 0 -1 0 0.740 0 -1 0 0.740
Create your Blip Up/Down image
First, you'll need to extract your B0s from the regular DWI acquisition.
If you look at the gradient directions within the DWI acquisition the B0s will be “0 0 0”.
Within the BXH the first 2 directions are B0:
<datapoints label="diffusiondirection"> <value>0 0 0</value> <value>0 0 0</value> <value>0.707107 0 0</value> <-- not a B0
Extract them with bxhselect:
bxhselect --timeselect 0:1 bia6_00197_012.bxh bu
This will create bu.nii.gz with the first 2 gradient directions ( the B0s )
Now merge the extracted B0s from the regular acquisition with the images from the reversed acquisition. Merge these in the same order of the acq_params.txt file.
fslmerge -t bud bu.nii.gz bia6_00197_013.nii.gz tesla:HCP cmp12$ fslinfo bud.nii.gz data_type INT16 dim1 256 dim2 256 dim3 92 dim4 4
Run topup to calculate the field and coefficients images for correction
#run popup calculate the field/coef topup --verbose --imain=bud --datain=acq_params.txt --config=$FSLDIR/src/topup/flirtsch/b02b0.cnf --out=dwi_topup --fout=topup_field
Now apply the correction to your DWI
inindex references the “regular” dwi B0s index from your acq_para ms.txt file
#apply it applytopup --imain=bia6_00197_012.nii.gz --inindex=1 --method=jac --datain=acq_params.txt --topup=dwi_topup --out=dwi_corrected --verbose
If you want to re-generate a valid BXH for the corrected data, you can generate a new BXH and merge in the original info
fslwrapbxh dwi_corrected..nii.gz mv dwi_corrected.bxh tmp.bxh bxh_addgradients --fsl tmp.bxh bvecs bvals dwi_corrected.bxh rm tmp.bxh