fat_proc_filter_dwis


# -----------------------------------------------------------------------

    The purpose of this function is to help filter out user-found and
    user-defined bad volumes from DWI data sets.

    If a bad volume is found, then it should be removed from the 4D
    dset, and it also has to be removed from the gradient list and
    the bvalue list.  In addition, if the user is processing DWI data
    that was acquired with two sets of phase encodings for EPI
    distortion correction, then one wants to remove the same volume
    *from both sets*.  This script is designed to help facilitate this
    process in a scriptable manner (the script still has to be run twice,
    but hopefully with easy enough syntax to avoid confusion/bugs).

    The user has to input

        1) a 4D volumetric data sets of N DWIs (NAME.nii.gz),

        2) and accompanying bvalue/bmatrix/bvector values that they
           want to be parsed; this could be a unit-magn bvec file + a
           file of bvalues, or it could be a single file of scaled
           vector|matrix values.

    The output will be in similar format to what was input (i.e., the
    type of bvector|bmatrix files matching what was input), but with a
    different prefix name and/or directory, and everything filtered in
    a consistent manner *hopefully*.

    Check out the function "fat_proc_select_vols" for a nice, GUI way
    to select the bad DWIs you want to get rid of and to build a
    selector nicely (courtesy of J. Rajendra).

    REQUIRES: AFNI.

    Ver. 3.8 (PA Taylor, Feb 12, 2019)

# -----------------------------------------------------------------------

  RUNNING:

    fat_proc_filter_dwis  \
        -in_dwi    DDD                     \
        -select   'SSS'                    \
        {-select_file SF}                  \
        -prefix   PPP                      \
        {-in_col_matA|-in_col_matT|        \
         -in_col_vec|-in_row_vec} FFF      \
        {-in_bvals BBB}                    \
        {-unit_mag_out}                    \
        {-qc_prefix  QCPREF}               \
        {-no_cmd_out}                      \
        {-no_qc_view}                      \
        {-do_movie AGIF|MPEG}

  where:
  -in_dwi  DDD      :name of a 4D file of DWIs (required).

  -in_col_matA |
  -in_col_matT |
  -in_col_vec  |
  -in_row_vec  FFF  :one of these options must be used to input
                     a bvec/bmat file from the gradients. Required.
                     Same type of output file is returned.

  -in_bvals BBB     :if the bvec/bmat is a file of unit-magnitude values,
                     then the bvalues can be input, as well (optional).

  -select 'SSS'     :a string of indices and index ranges for
                     selecting which volumes/grads/bvals to *keep*.
                     This is done in a generic form of the typical
                     AFNI format, and index counting starts at 0 and
                     the 'last' brick could be specified as '$'.  An
                     example for skipping the index-4 and index-6
                     volumes in a data set:
                        '0..3,5,7..$'
                     This string gets applied to the volume, bval|bvec|bmat
                     files for an input set. Either this or '-select_file ..',
                     below, is required.
                     NB: there are neither square nor curly brackets used
                     here!
                     NB2: Always use single or double quotes around the
                     selector expression.
                     NB3: User can enter a list of strings here, such as:
                       '0..3,5,7..$' '1..3,6..$'
                     which then get joined by intersection.
       or
  -select_file SF   :where SF is a file name whose only contents are a nice
                     string of indices and index ranges for selecting which
                     volumes/grads/bvals to *keep*.  Like, literally just
                        0..3,5,7..$
                     sitting alone in a file-- no apostrophes needed/wanted.
                     User can enter more than one file here, to be joined
                     by intersection.

  -prefix    PPP    :output prefix for all the volumes and text files.
                     Required.

  -unit_mag_out     :if one wants to prevent an input bvalue file being
                     applied to unit-magnitude gradients|vecs|matrices,
                     or if one just wants to ensure that the output grad
                     information is unit magnitude, use this option.  If
                     this is used with just a vec/matrix file input, then
                     a b-value file will also be output (so b-value info
                     wouldn't be lost at this moment).  Optional.

  -qc_prefix QCPREF :can set the prefix of the QC image files separately
                     (default is '').
   -no_qc_view      :can turn off generating QC image files (why?)
   -no_cmd_out      :don't save the command line call of this program
                     and the location where it was run (otherwise, it is
                     saved by default in the ODIR/).

    -do_movie AGIF | MPEG
                    :one can use this option with either of the given
                     arguments to output a movie of the newly created
                     dset.  Only those arguments can be used at
                     present.

# -----------------------------------------------------------------------

  EXAMPLES:

    1) ... with selector via the command line (again, note the single
       apostrophes around the selector!):

        fat_proc_filter_dwis  \
            -in_dwi       UNFILT_AP/AP.nii.gz       \
            -in_col_matT  UNFILT_AP/AP_bmatT.dat    \
            -select       '0..5,8,20..$'           \
            -prefix       FILT_AP/AP


    2) ... with selector via file contents (where there would *not* be
       apostrophes in the string sitting in the file):

        fat_proc_filter_dwis  \
            -in_dwi       UNFILT_AP/AP.nii.gz           \
            -in_col_matT  UNFILT_AP/AP_bmatT.dat        \
            -select_file  UNFILT_AP/dwi_sel_goods.txt   \
            -prefix       FILT_AP/AP

# -----------------------------------------------------------------------