fieldmap_correction

Corrects EPI images using the field map compute by make_fmap.

Usage:
fieldmap_correction [-m mask_file --output_format=<output_format> --tag=<tag>] <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.
  • --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.
  • --tag= <tag>: Tag appended to the output filename. Default value is "_fm".
  • --beautify: Process edges of fieldmap to remove incorrect values at the edge of the image.
  • <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.

Modification for use with DTI Data, 8/31/09

Fieldmap correction can leave erroneous values outside the brain, either in regions that have invalid fieldmap data (e.g. in CSF) or because pixels resampled to the inside of the brain are left outside the brain. These problems are not important for fMRI, but are an in issue for DTI. Three changes were made to address this.

  1. Implemented a "smart mask", which is based on the fact that any voxel that has been used in the resampling but is outside of the fieldmap map should be zero (if the correction moved that pixel inside the brain, the pixel it originally resided at should be set to zero.) Moreover, any pixel farther from the brain should be set to zero. That turns out to be a robust way to get rid of some of the crap outside the brain.
  2. Changed the interpolation method to cubic spline.
  3. Added a processing step to detect erroneous fieldmap values and set them to more reasonable algorithms. Here's the algorithm:
    • Erode the fieldmap by 7 pixels to form a fieldmap consisting only of inside-the-brain voxels.
    • Create a mask defined by the fieldmap, then erode this mask by three voxels, then take the difference of the this mask and a fieldmap mask to define a "band" three-pixels thick around the edge of the brain.
    • For each slice, do the following:
      • compute the center of mass
      • For each pixel in the "band":
        • compute a vector pointing towards the center of mass.
        • sample 32 values along this line from the fieldmap eroded by 7 pixels.
        • If the pixel being tested has a value larger than the maximum (or less than the minimum) of these values, set the pixel value to the value of the nearest pixel on the line (nearest in terms of the Euclidean norm). Otherwise retain the original value.
This method can potentially replace valid value with incorrect values, but it should be pretty robust.

Results

Here is the result of applying the modifications to DTI data.

Here is the result of applying the modifications to EPI data.

Last modified February 24, 2011