AFNI program: colorbar_tool.py

Output of -help


Overview ~1~

This program is for working with AFNI-style colorbar (cbar) and
palette bar (pbar) files. It might also be fairly general-purpose for
PNG, JPG and other rasterized colorbar files, as long as they have a
pretty straightforward formatting.  Particularly, this program is
meant for putting in threshold information, both opaque (=strict)
thresholds and transparent (=alpha fading, AKA subthreshold fading)
ones.

In AFNI, the colorbar goes with the overlay dataset, which may or may
not be the same as the threshold dataset. 

+ In cases where they *are* the same, this program can be used to:

  - add in (striped) threshold boundary lines

  - replace subthreshold regions with a dull/null gray color

  - put in alpha-based fading (either Linear or Quadratic)

  - use values from a JSON file output by @chauffeur_afni to efficiently
    gain useful knowledge about relevant cbar info, like min/max, threshold
    values, ON/OFFness of alpha fading, etc.

+ In cases where they differ, this program might be useful for:

  - representing alpha-fading as an orthogonal (=perpendicular to the
    the color gradient) melding of the colorbar with a null/dull gray

+ In all cases, this program can:

  - add a boundary of chosen thickness and color.

More functionality will likely be added over time.

**Notation note:** For simplicity, we mostly just refer to the
colorbar or palette as a 'cbar', which should be synonymous here with
'pbar'.  Some programs also refer to these as 'colorscales' or
'colormaps'.

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

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

Usage ~1~

-in_cbar CBAR  :(req) name of the cbar file, which can be in one of the
                following formats: JPG, PNG, TIF

-prefix PREFIX :(req) name of output file, including file extension

-in_cbar_name NAME  
               :alternative way to provide input colorbar, by specifying
                the name of a known colorbar (i.e., one that would show
                up in the AFNI GUI menu).  NB: if you mistype the name or
                enter one that doesn't exist, then some default colorbar
                will be used.

-in_json  JSON :name of a JSON file with known keys that describe relevant
                cbar values; in particular, JSONs output by @chauffeur_afni
                are good to use here. An efficient way to provide cbar_min,
                cbar_max, alpha, thr_val (and perhaps more over time)

-cbar_min MIN  :lower/minimum/bottom value of cbar

-cbar_max MAX  :upper/maximum/top value of cbar

-alpha  ALPHA  :keyword setting for specifying alpha transparency for
                thresholding.  Must be one of the following values:
                  No, Yes, Quadratic, Linear

-thr_val TVAL  :threshold value, applied as an absolute value

-thr_width TWID :when displaying the threshold line in the output cbar,
                this controls the width, as an integer number of pixels
                (def: 4)

-thr_num_osc TNO :by default, the threshold line oscillates between two
                colors for increased visibility. This integer specifies  
                the number of oscillations (def: 4)

-thr_colors TCOL1 [TCOL2]
               :by default, the threshold line oscillates between two
                colors for increased visibility. Users can put 1 color
                name here, for a solid line, or two of their own color
                choices (def: 'black' 'white')

-thr_off       :turn off displaying the threshold line, even if
                thresholding is being applied

-tick_num_int TNI :add tick lines, where TNI is the integer number of 
                intervals to use; specifying 0 turns of tick display
                (def: 10)

-tick_frac TF  :when tick lines are used, how far should they extend, as 
                a fraction of the cbar width (def: 0.07)

-tick_color TCOL :specify the color of the tick lines (def: 'black')

-orth_on       :by default, the alpha fading is applied _along_ the 
                cbar gradient. Using this flag means it will be applied
                orthogonally/perpendicularly to that gradient. This is 
                most useful in cases when the overlay and threshold 
                data differ

-orth_frac OF  :specify at what fraction of the cbar width the fading
                should start (def: 0.8)

-outline_width OUTWID
               :add an outline to the output cbar, whose width is
                an integer OUTWID number of pixels at each edge
                (def: 0)

-outline_color OUTCOL
               :choose the color of any added outline (def: 'black')

-bkgd_color BC :background color that appears when thresholding is
                applied (def: '#c8c8c8')

-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~

These are some notes about using this program.

Cbar Orientation
Input colorbars can be either vertically oriented (assumes cbar_max is
at the top) or horizontally oriented (assumes cbar_max is to the
right).

File formats
Input formats that are known to be valid include *.jpg, *.tiff and
*.png.  Valid output formats include those, as well as *.svg and
likely any other that Python's Matplotlib module can write.

JSONs
This program is meant to work smoothly with *.json files exported via
'@chauffeur_afni -pbar_saveim ..'.  That is, this program only looks
for certain keys there (pbar_bot, pbar_top, thr_val and olay_alpha).
JSON files from other sources can work, but these would have to use
those same key names.  Again, cbar and pbar are effectively synonyms.

Precedence
When both JSON files and command line options are used, the latter
will take precedence if there is any overlap/conflict. This makes it
easier to tweak values. NB: they JSON keys and command line options
are often not the exact same name, but something similar (see previous
note on JSONs).

Colors
As with many AFNI programs, the color values that are recognized can
be any of those in the GUI menu (yellow, yell-oran, oran-yell,
rbgyr20_01, etc.), or hex-defined colors (likely putting these in some
quotes), or Matplotlib-recognized colors (e.g., see:
https://matplotlib.org/stable/gallery/color/named_colors.html).

Importance
The alpha fading is appropriate when transparent thresholding has been 
used in the related data.  To see more about why this is relevant and
*very* important in results reporting, please see:

  + Taylor PA, Reynolds RC, Calhoun V, Gonzalez-Castillo J, Handwerker
    DA, Bandettini PA, Mejia AF, Chen G (2023). 
    Highlight Results, Don’t Hide Them: Enhance interpretation, reduce
    biases and improve reproducibility. Neuroimage 274:120138.
    https://pubmed.ncbi.nlm.nih.gov/37116766/

  + Chen G, Taylor PA, Stoddard J, Cox RW, Bandettini PA, Pessoa L (2022). 
    Sources of information waste in neuroimaging: mishandling
    structures, thinking dichotomously, and over-reducing
    data. Aperture Neuro. 2.
    https://doi.org/10.52294/ApertureNeuro.2022.2.ZRJI8542

  + Allen EA, Erhardt EB, Calhoun VD (2012). 
    Data Visualization in the Neurosciences: overcoming the Curse of
    Dimensionality. Neuron 74:603-608.
    https://pubmed.ncbi.nlm.nih.gov/22632718/

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

Examples ~1~

The following examples make reference to the AFNI Bootcamp data, and
can be run directly with copy+paste in the following directory:
    ~/AFNI_data6/FT_analysis/FT.results/QC_FT/media

The following two palettes/colorbars star in the examples:
  + qc_06_vstat_Full_Fstat.pbar.jpg, which is 'unidirectional', likely
    going from cbar_min = 0 to some positive cbar_max
  + qc_07_vstat_vis_0_Coef.pbar.jpg, which is 'bidirectional', likely
    going from some cbar_min = -VAL to cbar_max = VAL
Each *.jpg has an associated *.json file, which was created by
@chauffeur_afni and contains useful parameters associated with the
cbar (see 'JSONs' in the Notes above).

    1) Use the JSON information to place threshold and set fading:

    colorbar_tool.py                                             \
        -in_cbar  qc_06_vstat_Full_Fstat.pbar.jpg                \
        -in_json  qc_06_vstat_Full_Fstat.pbar.json               \
        -prefix   qc_06_vstat_Full_Fstat.pbar_FADE1.jpg            

    colorbar_tool.py                                             \
        -in_cbar  qc_07_vstat_vis_0_Coef.pbar.jpg                \
        -in_json  qc_07_vstat_vis_0_Coef.pbar.json               \
        -prefix   qc_07_vstat_vis_0_Coef.pbar_FADE1.jpg            

    2) Use orthogonal fading (no min/max/etc. info needed):

    colorbar_tool.py                                             \
        -in_cbar  qc_06_vstat_Full_Fstat.pbar.jpg                \
        -prefix   qc_06_vstat_Full_Fstat.pbar_FADE2.jpg          \
        -alpha    Yes                                            \
        -orth_on                                                   

    colorbar_tool.py                                             \
        -in_cbar  qc_07_vstat_vis_0_Coef.pbar.jpg                \
        -prefix   qc_07_vstat_vis_0_Coef.pbar_FADE2.jpg          \
        -alpha    Yes                                            \
        -orth_on                                                   

    3) Implement fading, and add an outline

    colorbar_tool.py                                             \
        -in_cbar        qc_06_vstat_Full_Fstat.pbar.jpg          \
        -in_json        qc_06_vstat_Full_Fstat.pbar.json         \
        -prefix         qc_06_vstat_Full_Fstat.pbar_FADE3.jpg    \
        -outline_color  green                                    \
        -outline_width  4                                          

    colorbar_tool.py                                             \
        -in_cbar        qc_07_vstat_vis_0_Coef.pbar.jpg          \
        -in_json        qc_07_vstat_vis_0_Coef.pbar.json         \
        -prefix         qc_07_vstat_vis_0_Coef.pbar_FADE3.jpg    \
        -outline_color  darkmagenta                              \
        -outline_width  6                                          

    4) Implement fading, and adjust the threshold line properties, 
       tick properties and min/max; NB: options directly entered on
       the command line have precedence over JSON values:

    colorbar_tool.py                                             \
        -in_cbar      qc_06_vstat_Full_Fstat.pbar.jpg            \
        -in_json      qc_06_vstat_Full_Fstat.pbar.json           \
        -prefix       qc_06_vstat_Full_Fstat.pbar_FADE4.jpg      \
        -thr_colors   '#f5b041' 'tab:brown'                      \
        -thr_num_osc  2                                          \
        -thr_width    8                                            

    colorbar_tool.py                                             \
        -in_cbar       qc_07_vstat_vis_0_Coef.pbar.jpg           \
        -in_json       qc_07_vstat_vis_0_Coef.pbar.json          \
        -prefix        qc_07_vstat_vis_0_Coef.pbar_FADE4.jpg     \
        -cbar_max      10                                        \
        -cbar_min      -10                                       \
        -tick_num_int  4                                         \
        -tick_color    antiquewhite

    5) Implement linear fading, for various min/max/thr values:

    colorbar_tool.py                                             \
        -in_cbar   qc_06_vstat_Full_Fstat.pbar.jpg               \
        -prefix    qc_06_vstat_Full_Fstat.pbar_FADE5.jpg         \
        -cbar_min  0                                             \
        -cbar_max  10                                            \
        -thr_val   7                                             \
        -alpha     Linear                                             

    colorbar_tool.py                                             \
        -in_cbar   qc_07_vstat_vis_0_Coef.pbar.jpg               \
        -prefix    qc_07_vstat_vis_0_Coef.pbar_FADE5.jpg         \
        -cbar_min  -5                                            \
        -cbar_max  5                                             \
        -thr_val   3                                             \
        -alpha     Linear                                          

    6) Same examples as #5 above, but with simple thresholding (i.e.,
       fading turned off)

    colorbar_tool.py                                             \
        -in_cbar   qc_06_vstat_Full_Fstat.pbar.jpg               \
        -prefix    qc_06_vstat_Full_Fstat.pbar_FADE6.jpg         \
        -cbar_min  0                                             \
        -cbar_max  10                                            \
        -thr_val   7                                             \
        -alpha     No                                             

    colorbar_tool.py                                             \
        -in_cbar   qc_07_vstat_vis_0_Coef.pbar.jpg               \
        -prefix    qc_07_vstat_vis_0_Coef.pbar_FADE6.jpg         \
        -cbar_min  -5                                            \
        -cbar_max  5                                             \
        -thr_val   3                                             \
        -alpha     No                                          

    7) Make a colorbar from the name within the known AFNI list.

    colorbar_tool.py                                             \
        -in_cbar_name  Viridis                                   \
        -prefix        CBAR_Viridis.jpg                          \
        -cbar_min      -5                                        \
        -cbar_max      5                                         \
        -thr_val       3                                         \
        -alpha         Linear                                          




This page auto-generated on Wed Mar 12 07:59:58 PM EDT 2025