AFNI program: chauffeur_map_rois

Output of -help

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

Overview ~1~

This program facilitates making ROI-based images with transparent
thresholding and outlining, using @chauffeur_afni.

Many ROI-based calculations are output as text files (like, columns of
numbers). This program helps with combining output that has simple
structure (a text file of effect estimates and a text file of stats
values) with an ROI map, to make images of the stats in the ROIs. In
particular, users are encouraged to make use of transparent
thresholding here.

written by: PA Taylor (SSCC, NIMH, NIH, USA)

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

Options ~1~

-in_dset_rois DR   :(req) dataset to be the overlay in the images; can 
                    include subbrick selector

-in_dset_ulay DU   :(req) dataset to be the underlay in the images; can 
                    include subbrick selector

-in_map_olay  MO   :(req) text file mapping ROI values to overlay-dset
                    values.  This file has 2 columns:
                      1st col: ROI integer values
                      2nd col: overlay data value the ROI should have
                               (e.g., effect estimate value)

-in_map_thr   MT   :(req) text file mapping ROI values to threshold-dset
                    values.  This file has 2 columns:
                      1st col: ROI integer values
                      2nd col: threshold data value the ROI should have
                               (e.g., statistic value)

-thr_val THR       :(req) threshold value to apply

-prefix PREFIX     :(req) output prefix for generated images. This can 
                    include path, but should not include an extension
                    because the given alpha value will be appended

-list_alphas A1 [A2 A3 ...]
                   :list of alpha values to cycle through when making a 
                    set of images. Must be one of the following allowed
                    names:
                       Yes Linear Quadratic No
                    (def: Yes)

-chauffeur_opts_start [list of options for @chauffeur_afni ...]
-chauffeur_opts_end 
                   :a *pair* of options that work together to specify 
                    options for the @chauffeur_afni command that actually
                    makes the images.  If adding chauffeur options, *both*
                    of these options *must* be used to delimit the list.
                    See the Notes below for more details.                    

-do_output_dset    :output the created overlay+threshold dataset to the 
                    same location as the images.  This will create a new
                    dset called PREFIX.nii.gz.

-overwrite         :when '-do_output_dset' is used, add the '-overwrite' opt
                    to the 3dcopy command that puts the dset in its place

-workdir WDIR      :working dir name. If not chosen, one will be created
                    that includes a random string

-no_clean          :do not remove the working dir when done (by default,
                    it will be cleaned)

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

Notes ~1~

Provide your own options for @chauffeur_afni ~2~

This program creates images of ROI-based data, primarily by combining
data and driving @chauffeur_afni.  It is meant to facilitate applying
transparent thresholding to region-based results.

First, the program takes text files of values and an atlas dataset and
combines these into an appropriate overlay+threshold dataset. This is
called 'dset_02_mapped_combo.nii.gz'.

Another direct input to this program is a volume to be the underlay,
which gets called 'dset_00_ulay.nii.gz'.

Then, with a couple other parameter like a threshold value and alpha
thresholding mode, it builds an @chauffeur_afni command to drive the
image making.  The constructed command has some basic settings
generated from the user inputs, which are:

|    @chauffeur_afni                                             \
|        -ulay           dset_00_ulay.nii.gz                     \
|        -olay           dset_02_mapped_combo.nii.gz             \
|        -set_subbricks  0 0 1                                   \
|        -thr_olay       ${thr_val}                              \
|        -olay_alpha     ${alpha}                                \
|        -prefix         ${img_pref}                             \
|        -pbar_saveim    ${img_pref}.pbar.jpg  

The values with the ${...} syntax are determined within the program,
from user inputs. Then, it applies some default options, which are:

|        -olay_boxed        ${boxed}                             \
|        -box_focus_slices  dset_02_mapped_combo.nii.gz          \
|        -opacity           9                                    \
|        -ulay_range        0% 98%                               \
|        -cbar              Reds_and_Blues_Inv                   \
|        -func_range_perc   100                                  \
|        -set_xhairs        OFF                                  \
|        -montx             6                                    \
|        -monty             1                                    \
|        -label_mode        1                                    \
|        -label_size        4 

The first set of basic options ('-ulay ..', '-olay ..', etc.) are
*not* changeable.  However, the second set are completely
configurable/replaceable/overwriteable.  We note that the above
options were not necessarily chosen because they are the absolute
best, but we did have to choose _something_ and those are a reasonable
starting point. The user can provide a *replacement* set for the
second batch, by using this program's '-chauffeur_opts_start
.... -chauffeur_opts_end' pair of options.

For example, the user could provide the following set of options, with
the important fact that *all* options besides the initial basic set
have to be provided---so you might have to re-state the same colorbar
as you see in the optional default part:

|    -chauffeur_opts_start                                      \
|         -olay_boxed      Yes                                  \
|         -set_dicom_xyz   -5 -5 15                             \
|         -delta_slices    10 10 15                             \
|         -opacity         9                                    \
|         -ulay_range      0% 98%                               \
|         -cbar            Reds_and_Blues_Inv                   \
|         -func_range      0.002                                \
|         -set_xhairs      OFF                                  \
|         -montx           5                                    \
|         -monty           1                                    \
|         -zerocolor       white                                \
|         -label_mode      1                                    \
|         -label_size      4                                    \
|         -label_color     black                                \
|    -chauffeur_opts_end

In this way, the user should have the same full flexibility for making
images for these ROI-based datasets that @chauffeur_afni allows.

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

Examples ~1~

1) Basic usage, usage default @chauffeur_afni opts

   chauffeur_map_rois                                       \
    -in_dset_rois          MNI_Glasser_HCP_v1.0.nii.gz      \
    -in_dset_ulay          MNI152_2009_template.nii.gz      \
    -in_map_olay           dset_glass_effect_size.dat       \
    -in_map_thr            dset_glass_ttest_stats.dat       \
    -thr_val               3.0                              \
    -prefix                image_rois_ttest

2) Basic usage, for example with RBA output

   chauffeur_map_rois                                       \
    -in_dset_rois          MNI_Glasser_HCP_v1.0.nii.gz      \
    -in_dset_ulay          MNI152_2009_template.nii.gz      \
    -in_map_olay           dset_glass_rba_eff_med.dat       \
    -in_map_thr            dset_glass_rba_pplus_sh.dat      \
    -thr_val               0.95                             \
    -prefix                image_rois_rba

3) Take example 2, and implement advanced control of @chauffeur_afni
   options:

|   chauffeur_map_rois                                        \
|    -in_dset_rois          MNI_Glasser_HCP_v1.0.nii.gz       \
|    -in_dset_ulay          MNI152_2009_template.nii.gz       \
|    -in_map_olay           dset_glass_rba_eff_med.dat        \
|    -in_map_thr            dset_glass_rba_pplus_sh.dat       \
|    -thr_val               0.95                              \
|    -prefix                image_narps_hyp2_rba              \
|    -chauffeur_opts_start  -olay_boxed Yes                   \
|                           -set_dicom_xyz -5 -5 15           \
|                           -delta_slices 10 10 15            \
|                           -opacity 9                        \
|                           -ulay_range 0% 98%                \
|                           -cbar Reds_and_Blues_Inv          \
|                           -func_range 0.002                 \
|                           -set_xhairs OFF                   \
|                           -montx 5                          \
|                           -monty 1                          \
|                           -zerocolor white                  \
|                           -label_mode 1                     \
|                           -label_size 4                     \
|                           -label_color black                \
|    -chauffeur_opts_end
 
This page auto-generated on Wed Apr 23 11:20:24 PM EDT 2025