Brain Imaging

fieldmap_correction

Corrects EPI images using the field map compute by make_fmap.

Usage:

fieldmap_correction [-m mask_file -t output_format -s tag -fs] <field_map_filename> <dwell_time> <output_path> <input_files>

• -m, --mask: Apply a loose mask to the output images. The mask is computed by first setting it equal to the nonzero areas of the fieldmap, dilating it by 2 pixels, and then smoothing with a Gaussian filter with a 2 pixel FWHM. The fieldmap correction resamples the phase-encode axis such that, for a posterior-to-anterior phase encode direction, the image is "pulled back" inside the skull. If masking is not performed, the area outside the skull will still contain "brain". The mask is intended to roll off the image to zero outside the skull.
• -t <output_format>, --output_format=<output_format>: Specify the output format. Valid values are "brik", "ni1", "n+1", "tes" and "analyze". Analyze format should not be used, rather, use the nifti ni1 format. The nifti n+1 (one-file) format should be used for data acquired at oblique angles since this format handles the orientation information well.
• -s <tag>, --tag= <tag>: Tag appended to the output filename. Default value is "_fm".
• <field_map_file>: File containing field map computed by make_fmap. The fieldmap can be in any orientation. It should ideally be in the same orientation as the data. If not, fieldmaps in the sagittal plane are preferred.
• <dwell_time>: Time between echoes in the acquisition. in ms (.688 ms for sagittal epibolds). This can be read from the raw data (P-file, I-file or dicom) using the "dump_header" utility and looking for the "EffEchoSpacing" parameter. Note that this parameter is different for coronal views and DTI images. If the images were reconstructed with epirecon_ex or if they were converted with "convert_file" the echo-spacing and phase-encode axis will be stored in the header. For BRIK format, they will be stored in the "HISTORY" field. The "aux_file" field is used for nifti format.
  
• <output_path>: Directory where the corrected file(s) go. The output file name is formed from the input file name by adding the suffix "_fm."
  
• <input_files>: One or more EPI image files.
  

Example:

export DATA=/study/study_name/data/subject_001/anatomicals
export PROC=/study/study_name/proc/subject_001
fieldmap_correction --tag=f ${PROC}/fieldmap/fmap_axial.nii 0.688 ${PROC}/epis/s8_epi ${PROC}/epis/s8_epi/s8_epi_run1_m+orig
where
- fieldmap/fmap_axial.nii is the fieldmap file name.
- .688 is the effective echo spacing, i.e., the required to read one line of k-space (including the ramps)
- ${PROC}/epis/s8_epi is the output directory
- ${PROC}/epis/s8_epi/s8_epi_run1_m+orig is the epi image to be corrected. Multiple images files can be specified on a single line.


Method

The fieldmap created by make_fmap is read from a NIFTI n+1 file. If the EPI image was originally reconstructed with epirecon, the phase encoding axis, phase encoding direction are retrieved from the HISTORY_NOTE field in the HEAD file. For NIFTI format, they are stored in the "aux_file" field. The same is done if the EPI images were in dicom format and converted to AFNI or NIFTI format using convert_file (phase direction is not available from dicom images). If this information is not available, the dwell time is retrieved from the command line and default values for phase axis and direction based on the acquisition plane are used. The fieldmap images are then resampled so they are in register with the EPIs, and the phase encode axis is resampled using linear interpolation.

Notes

• The field maps are acquired with the 2dfast pulse sequence on the scanner and are currently stored in dicom format. Our naming convention is to append the pulse sequence name to the series number, so, for example, if the field map is the sixth acquisition it will be stored in the directory S6_2DFAST. If both sagittal and axial field maps were collected you can find out which is which by dumping the header of one of the images (e.g. dump_header S6_2DFAST/*.0001).
• The fieldmaps are resliced to the same orientation and position as the EPIs before the correction is done. This requires correct orientation information in the header. This is usually lost if the data has been in Analyze format at some earlier point in the processing. This can be fixed by using convert_file with the -M option.