:orphan: .. _ahelp_obliquity_remover.py: ******************** obliquity_remover.py ******************** .. contents:: :local: | Overview ======== .. code-block:: none 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 ===== .. code-block:: none -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 ===== Obliquity in general ++++++++++++++++++++ .. code-block:: none + 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? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. code-block:: none 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 ======== .. code-block:: none 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