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
Sun Apr 13 08:27:12 PM EDT 2025