preprocessMprage (Hallquist pipeline)

preprocessMprage is a prerequisite for Preprocess Functional (Hallquist pipeline). Code is https://github.com/LabNeuroCogDevel/fmri_processing_scripts/ and on rhea in /opt/ni_tools/fmri_processing_scripts.

It is analogous to smriprep: skullstrips and MNI-aligns the anatomical/structural T1w image.

Important files include:

• mprage.nii.gz – input structural image
• mprage_brain.nii.gz – skull stripped
• mprage_warpcoef.nii.gz – voxelwise nonlinear warp file for/using fsl's fnirt

The mp2rage from 7T projects (Brain Mechanisms R01 (7T) and Synaptic Pruning Adolescence (SPA)) have inhomogeneities/bias field that complicate skullstripping. See 7T Anatomical Acquisitions Workarounds

• skullstrip the INV component instead of the combined UNIDEN or use freesurfer's output. In either case, use -ss_method freesurfer=/path/toskullstrip or invert the mask and use -post_bet_skullmask
• SPM correction via VS's Correct UNI for B1+ transmit field biases
• try -strong_bias -unifize -ss_method ROBEX

The pipeline provides qa_images for quality checking. And can be further inspected using a full nifti viewer like afni.

The most likely failure is during skullstripping.

Inspecting further with afni, using $ keypress to toggle the overlay/underlay slider

----------------------------------------------
preprocessMprage is a shell script that computes the nonlinear warp of a
  participant's structural scan to a standard stereotaxic template (e.g., MNI).

It is intended to be run within an mprage directory containing raw data (or a
  nifti of the raw data if you use the -n option).

The basic pipeline is:
  1) Convert dicom files to NIFTI
  2) Optional bias field correction to reduce spatial variation in intensity
       due to coil sensitivity. Particularly important for 32-channel T1 images.
  3) Brain extract the structural image
  4) Warp structural to standard stereotactic space using affine (linear)
      transformation: flirt. (Used only for warp coefficients)
  5) Warp structural image to stereotactic space using nonlinear transformation
       with fnirt. Affine coefficients from the linear warping are used as
       starting values (helps optimization). In the case of MNI, uses FSL's
       config file with optimal parameters for fnirt. In the case of Talairach,
       use a custom settings file adapted from FSL's MNI configuration.

Command line options:
  -b -bet_opts: bet options. Passes value to fsl bet (brain extraction).
        Must be quoted (e.g., -b "-f 0.7"). Defaults to "-R -f 0.5 -v"
  -bright_skull: apply a correction to reduce the intensity of bright voxels in the skull prior to FNIRT.
        Skull voxels that are bright (esp. near top of brain) can lead to artifactual stretching in FNIRT.
        This correction is recommended if the skull is noticeably brighter (2-3x) than brain voxels.
  -check_dependencies: what tools are avaible on this system. Exit w/ status 0 if everything needed is found
  -cleanup: cleanup intermediate files not needed for further processing.
  -cleanup_only: run cleanup of intermediate files, then exit. (after checking files)
  -custom_brainmask: a NIfTI image containing a custom brain mask to be used instead of running a skull strip internally.
        Must be the same dimensions as the structural scan. Technically, this can even be a skull-stripped volume such that
        non-zero values are used to mask the structural image.
  -cut_zindex Z:  keep index Z to end. use Z1-Z2 to specify range. (e.g. '0-100' to keep up until 100 instead of 100 and up)
        useful when brain is only part of image.
  -d -delete_dicom: delete or archive DICOM files. Options are -d n ("no": leaves DICOM
        untouched), -d y ("yes": deletes DICOM files), -d a ("archive":
        compresses files into archive file: mprage_dicom.tar.gz. If not
        passed, user will be prompted for action. Can also use "yes", "no", and "archive."
  -deface: use pydeface to remove face and maybe also hands and arms near the face (esp. babies)
  -deneck: remove from the neck down with local remove_neck.py (implemented for baby data)
  -fnirt_mask: controls how dilated the --refmask is for fnirt. Changing this may help with undesirable stretching at edge. Options:
  	vtight: no dilation of template brain mask
	tight: 1x dilation (-dilF) of mask
	normal: 2x dilation (-dilF -dilF) of mask (default)
	loose: 3x dilation (-dilF -dilF -dilF) of mask
  -grad_unwarp: a file containing gradient nonlinearity coefficients for a SIEMENS scanner (e.g., trio.coeff.grad).
        Structural image will be corrected for gradient distortion prior to transformation to template.
  -h -help: print command help
  -log: Name for log file that documents each command that is run. Default: preprocessMprage.log
  -n -nifti: skip DICOM conversion and start with specified NIFTI file. 
        Example: -n mprage.nii.gz (will complete bet, flirt, and
        fnirt, but skip DICOM -> NIFTI conversion).
  -no_bias: skip bias field correction.
  -no_robustfov: skip robustfov neck cleanup
  -o -output: output file name. The filename for the final warped mprage image.
        Defaults to mprage_nonlinear_warp_<referenceName>.nii.gz
  -p -dicom: file pattern for dicom MR files. Defaults to "MR*". Please enclose the pattern in quotes or it may not function properly
  -post_bet_skullmask: provide a mask to remove extra skull even after skull stripping. likely created by hand using afni's draw plugin
        See https://labneurocogdevel.github.io/tuts/afni_draw
  -r -template_brain: reference brain. Currently supports "MNI_2mm", "MNI_FSL_2mm", "SPM_2mm", "Tal_2mm", 1YO_2mm, neo_2mm.
        Default is "MNI_2mm".
  -startover: ignore .preprocessmprage_complete. useful if changing/adding arguments like "-ss_method bet -b '-f .6 -R'"
  -ss_method: skull-stripping method used to create final brain-extracted data. Default is fnirt-inv. Options:
        fnirt-inv: uses the template brain mask warped onto the subject's brain to define brain mask
        bet: uses the bet program (FSL) to skull strip (also respects -bet_opts).
        3dSkullStrip: uses the 3dSkullStrip program (can pass additional parameters using -bet_opts).
        noisy: use @NoisySkullStrip
        ROBEX: uses the ROBEX program (which doesn't accept any parameters).
        freesurfer=/path/to/subj/mri/brainmask.mgz
  -strong_bias: used for images with very strong bias fields
  -unifize:  run afni's 3dUnifize on input mprage
  -use_old_mni: support legacy preprocessing
  -w -warpres: resolution of warp basis (nonlinear neighborhood size) in mm. Default is 8 mm.
  -weak_bias: used for images with little and/or smooth bias fields (cf. fsl_anat). This is the default.

Example call: preprocessMprage -r MNI_2mm -b "-R -f 0.5 -g 0.2" -d a -o mprage_final.nii.gz -w 6
----------------------------------------------