AFNI program: obliquity_remover.py

Output of -help

Overview ~1~

This program is primarily for removing oblquity from an input
dataset's header, with the two important properties:

+ **not** regridding (= smoothing/interpolating) the data itself

+ preserving the coordinate origin, (x, y, z) = (0, 0, 0).

**Also** note this important bonus feature: the removed obliquity can
also be transferred to other datasets (called "child" datasets).
Doing this preserves the relative overlap of the main input and child
datasets, in the real terms of where they are in real/scanner space
when obliquity is taken into account.

This program makes a convenient step in preparing FMRI data
collections to be processed (e.g., before sswarper2, FreeSurfer,
afni_proc.py, etc.).  Users can provide the T1w anatomical reference
as the inset to have its obliquity removed, *while also* providing the
EPIs from the same session as child datasets.  In this way, the
relative overlap of the EPI and anatomical will be preserved during
processing.

auth = PA Taylor (SSCC, NIMH, NIH, USA)

------------------------------------------------------------------------

Usage ~1~

-inset INSET   :(req) name of the input dataset

-prefix PREFIX :(req) name of output dset

-child_dsets CD1 [CD2 CD3 ...] 
               :one or more datasets that can inherit the obliquity 
                that gets purged from the inset.

     ... and if using '-child_dsets', at least one of the following
         '-child_*' options must be included to specify their output
         naming:

-child_prefixes CP1 [CP2 CP3 ...] 
               :when using '-child_dsets ..', users can specify the
                output path+name for each child dset here. The number 
                of entries here must match number of child dsets.  
                This option canNOT be combined with '-child_outdir' 
                or '-child_suffix'

-child_outdir CO :when using '-child_dsets ..', users can specify a
                single output directory for all output childs.  If
                '-child_suffix ..' is not also provided, then the each
                output file will have the same name as its input (and
                in such a case, the CO should differ from each child 
                dset's original directory, unless '-overwrite' is used)

-child_suffix CS :when using '-child_dsets ..', users can specify a
                suffix to be inserted just before each output child's file
                extension.  Typically, uses will want to start the
                suffix with '_'.
                This option can be used along with '-child_outdir ..';
                otherwise, each child will be output in same directory as
                its original child dset

-do_qc DQ      :state whether to make QC images when using '-child_dsets ..',
                which means showing the overlap of each child dset with the
                main inset both before and after obliquity changes;
                allowed values are:  Yes, 1, No, 0
                (def: 'Yes')

-workdir WD    : working directory name, without path; the working dir
                will be subdirectory of the output location
                (def: name with random chars)

-do_clean DC   :state whether to clean up any intermediate files;
                allowed values are:  Yes, 1, No, 0
                (def: 'Yes')

-do_log        :add this opt to turn on making a text log of all the
                shell commands that are run when this program is
                executed.  Mainly for debugging purposes.

-help, -h      :display program help file

-hist          :display program history

-ver           :display program version number

-verb  VVV     :control verbosity (def: 1)

-show_valid_opts :show valid options for this program

------------------------------------------------------------------------

Notes ~1~

Obliquity in general ~2~

+ Some involve changing header information, without regridding (and
  therefore interpolating and smoothing) the data itself but
  effectively changing the coordinate locations of data.  

+ Others involve applying the obliquity to the data, thereby
  regridding/smoothing the data, but preserving the locations of the 
  data in the original scanner coordinates.  

Each can have its own use cases.

Why do we recommend removing anatomical dataset's obliquity like this? ~2~

It is generally convenient for the anatomical dataset to have its
obliquity removed in the way this program does it.

+ First, after removing obliquity like this, the anatomical should
  overlap better with any reference template dataset (since it will
  "sit more squarely" within the FOV).

+ Second, different software deal with obliquity differently (e.g.,
  ignoring or applying it), and so when integrating different tools
  (like FS, SUMA and AFNI), this can be minorly annoying.  

+ Third, *applying* obliquity leads to resampling and interpolation,
  and hence blurring of the anatomical dataset. So, *purging* it
  before processing can remove an unnecessary
  resampling/interpolation/blur procedure.

+ Fourth, transferring the anatomical's removed obliquity to the child
  datasets (like, EPI or other volumes acquired in the same session)
  will help preserve the relative angle of overlap.  While in many
  cases AFNI alignment programs can overcome a fair bit of relative
  rotation, some cases are more extreme (looking at you, slab EPI
  datasets!) and so really benefit from maintaining original
  overlap. Also, the stability of all alignment procedures (AFNI's or
  other tools') benefits from closer starting overlap of datasets, and
  who needs to add more uncertainty into data processing?


------------------------------------------------------------------------

Examples ~1~

 1) Remove obliquity from a dset:

    obliquity_remover.py                                                  \
        -inset            sub-017_T1w.nii.gz                              \
        -prefix           sub-017_T1w_DEOB.nii.gz

 2) Remove obliquity from a dset, and pass it along to its associated 
    EPI datasets:

    obliquity_remover.py                                                  \
        -inset            anat/sub-017_T1w.nii.gz                         \
        -prefix           anat/sub-017_T1w_DEOB.nii.gz                    \
        -child_dsets      func/sub-017_task-rest_run-01_bold.nii.gz       \
                          func/sub-017_task-rest_run-02_bold.nii.gz       \
                          func/sub-017_task-rest_run-03_bold.nii.gz       \
        -child_prefixes   func/sub-017_task-rest_run-01_bold_DEOB.nii.gz  \
                          func/sub-017_task-rest_run-02_bold_DEOB.nii.gz  \
                          func/sub-017_task-rest_run-03_bold_DEOB.nii.gz

 3) Same as #2, but with a succinct method of adding a suffix to each child:
           
    obliquity_remover.py                                                  \
        -inset            anat/sub-017_T1w.nii.gz                         \
        -prefix           anat/sub-017_T1w_DEOB.nii.gz                    \
        -child_dsets      func/sub-017_task-rest_run-01_bold.nii.gz       \
                          func/sub-017_task-rest_run-02_bold.nii.gz       \
                          func/sub-017_task-rest_run-03_bold.nii.gz       \
        -child_suffix      _DEOB

 4) Same as #3, but putting each output child into a new dir:

    obliquity_remover.py                                                  \
        -inset            anat/sub-017_T1w.nii.gz                         \
        -prefix           anat/sub-017_T1w_DEOB.nii.gz                    \
        -child_dsets      func/sub-017_task-rest_run-01_bold.nii.gz       \
                          func/sub-017_task-rest_run-02_bold.nii.gz       \
                          func/sub-017_task-rest_run-03_bold.nii.gz       \
        -child_suffix     _DEOB                                           \
        -child_outdir     func_deob

 5) Same as #4, but renaming in the outputs in a particular way: all
    output datasets have the same filenames but different paths. This
    might be quite useful when doing group processing in a way that
    each major step outputs the data in parallel directory trees:

    obliquity_remover.py                                                  \
        -inset            p1/anat/sub-017_T1w.nii.gz                      \
        -prefix           p2/anat/sub-017_T1w.nii.gz                      \
        -child_dsets      p1/func/sub-017_task-rest_run-*_bold.nii.gz     \
        -child_outdir     p2/func
This page auto-generated on Mon Dec 8 09:07:50 PM EST 2025