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
-in_map_thr MT :(req) text file mapping ROI values to threshold-dset
values
-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
Sat Mar 29 10:54:10 PM EDT 2025