:orphan: .. _ahelp_chauffeur_map_rois: ****************** chauffeur_map_rois ****************** .. contents:: :local: | Overview ======== .. code-block:: none 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 ======= .. code-block:: none -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 ===== Provide your own options for @chauffeur_afni ++++++++++++++++++++++++++++++++++++++++++++ .. code-block:: none 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 ======== .. code-block:: none 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