Positive-zero-negative colorbar

Version 1.8.0 (8.39 KB) by Xiaowei He
Create positive-zero-negative colormap and colorbar. Customized colormap/colorbar options are available.
416 Downloads
Updated 16 Jun 2023

View License

COLORBARPZN creates positive-zero-negative colormap and colorbar.
Zero is in white if while color location is not specified.
Customized colormap/colorbar options are available for:
- automatic/manual positive, zero, and negative color.
- predefined colors for different combinations of colormap spectrum.
- automatic/manual positive, negative, or positive-negative colormap.
- automatic/manual white position (at zero or specified).
- secondary positive and negative colors assigned to specific values.
- reversed default positive and negative colors.
- reversed colorbar direction by switching the order of input limits.
- number of colormap levels.
- LaTeX colorbar label.
- log scale colormap with adjustable loginess.
- extended white region to display small values in a uniform color.
- returning colorbar handle and/or colormap array.
-------------------------------------------------------------------------
Syntax:
colorbarpzn(caxis1, caxis2)
colorbarpzn(caxis1, caxis2, 'options')
colorbarpzn(target, __)
colorbarpzn(__, 'off')
h = colorbarpzn(__)
[h, cmap] = colorbarpzn(__)
cmap = colorbarpzn(__, 'off')
-------------------------------------------------------------------------
Description:
colorbarpzn(caxis1, caxis2): creates automatic colormap and colorbar
based on caxis([cmin, cmax]), where
cmin = min([caxis1, caxis2]) and
cmax = max([caxis1, caxis2]). The colormap
has a default style in which zero is in
white, positive is in red, and negative is
in blue. When caxis1 < caxis2, the colorbar
is displayed in 'normal' direction; when
caxis1 > caxis2, the colorbar is displayed
in 'reversed' direction (see e.g.[3]).
'options':
(one input/output option can be used independently or with other options)
colorbarpzn(__, 'rev'): creates reversed default colormap, where positive
is in blue and negative is in red. 'rev' will be
overwritten if 'colorP' or 'colorN' is manually
specified. See e.g.[6]
colorbarpzn(__, 'dft', 'colors'): change defaul colors in the order of
positive, zero, negative with
predefined colors. 'colors' is an 1 X 3
char variable which is a combination of
any 3 characters from 'r' (red), 'b'
(blue), 'g' (green), 'p' (purple), 'y'
(yellow), 'w' (white), and 'k' (black).
E.g., 'rgb', 'ywg', 'bwp', etc. 'dft'
will be overwritten if 'colorP',
'colorN', or 'colorZ' is manually
specified. See e.g.[5].
colorbarpzn(__, 'colorP', [R G B]/'color'): customizes positive color
with RGB or one of the color
code (see 'colors' in the
'dft' option). See e.g.[1].
colorbarpzn(__, 'colorN', [R G B]/'color'): customizes negative color
with RGB or one of the color
code (see 'colors' in the
'dft' option). See e.g.[5].
colorbarpzn(__, 'colorZ', [R G B]/'color'): customizes white/zero color
with RGB or one of the color
code (see 'colors' in the
'dft' option). See e.g.[5].
colorbarpzn(__, 'colorP2', [R G B]/'color', P2value):
adds a secondary color to the positive
color spectrum with RGB or one of the
predefined color code. The parameter
P2value specifies the position of
colorP2 on the colorbar where
cmin (or Wvalue) < P2value < cmax.
P2value is at the middle of
[cmin/Wvalue, cmax] if not specified.
See e.g.[8].
colorbarpzn(__, 'colorN2', [R G B]/'color', N2value):
adds a secondary color to the negative
color spectrum with RGB or one of the
predefined color code. The parameter
N2value specifies the position of
colorN2 on the colorbar where
cmin < N2value < cmax (or Wvalue).
N2value is at the middle of
[cmin, cmax/Wvalue] if not specified.
See e.g.[8]
colorbarpzn(__, 'full'): enforces full positive-negative color map with
white is at the middle of [cmin, cmax].
See e.g.[5].
colorbarpzn(__, 'full', Wvalue): enforces full positive-negative colormap
and specifies white position by Wvalue.
See e.g.[4].
colorbarpzn(__, 'level', Nlevel): customizes the number of colormap
levels (see e.g.[1, 5]). An odd integer
is preferred. The default Nlevel is 127
if 'level' option is not used.
colorbarpzn(__, 'label', 'LaTeXString'): creates a LaTeX colorbar label.
See e.g.[3].
colorbarpzn(__, 'log'): creates log scale colormap for coarser
increment near white (smaller white region) with
defualt loginess = 1. (citation [1]).
colorbarpzn(__, 'log', loginess): creates log scale colormap and
specifies the loginess value to make
smaller white region (loginess > 0, see
e.g.[3]) or larger white region
(loginess < 0, see e.g.[6]).
colorbarpzn(__, 'wrs', WhiteRegionSize): define the white color region
size as a ratio to the total
size of the colorbar/map, so
small values are displayed in a
uniform color. See e.g.[7].
0 < WhiteRegionSize < 1.
colorbarpzn(__, 'off'): set the colormap without creating a colorbar.
colorbarpzn(target, __): sets the colormap for the figure, axes, or chart
specified by target, instead of for the current
figure and adds a colorbar to the axes or chart
specified by target. Specify the target axes or
chart as the first argument in any of the
previous syntaxes. Similar to the combined use
of colormap(target, map) and colorbar(target).
See e.g.[3, 4].
h = colorbarpzn(__): h returns a colorbar handle. See e.g.[4].
[h, cmap] = colorbarpzn(__): h returns a colorbar handle and cmap returns
the colormap array. See e.g.[5].
cmap = colorbarpzn(__): cmap returns the colormap array only. See e.g.[6].
-------------------------------------------------------------------------
Examples:
[1] colorbarpzn(-1, 2, 'level', 21, 'colorP', [0.6 0.4 0.3]):
creates a colormap and a colorbar from -1 to 2 where 0 is in white
color with 21 levels on one side and with customized positive color
[0.6 0.4 0.3].
[2] colorbarpzn(-1, 2, 'dft', 'ywg'):
creates a colormap and a colorbar from -1 to 2 where the default
positive color is changed to predefined yellow 'y', the default
zero color remains white 'w', and the default negative color is
changed to predefined green 'g'.
[3] colorbarpzn(ax1, 2, 1, 'log', 1.2, 'label', '$\alpha$'):
on axis ax1, creates a colormap and a colorbar from 1 to 2 with
only positive color where the white color region is shortened by a
loginess of 1.2; the colorbar is displayed in reversed direction
as 2 > 1; the colorbar label desplays $\alpha$ with LaTeX
interpreter.
[4] h = colorbarpzn(ax2, 1, 3, 'full', 1.5):
on axis ax2, creates a colormap and a colorbar from 1 to 3 with
full default positive-negative color spectrum where white color is
aligned with the specified Wvalue 1.5 following the 'full' option;
h returns the colorbar handle.
[5] [h, cmap] = colorbarpzn(-4, -2, 'full', 'colorZ', [0.8 0.8 0.8], ...
'colorN', 'p', 'level', 31):
creates a colormap and a colorbar from -4 to -2 with full
positive-negative color spectrum with 31 levels on each side where
white color is customized with [0.8 0.8 0.8] and the negative end
of the spectrum is in predefined purple color 'p'; the white color
is aligned with the mean of caxis1 and caxis2 -3 on the colorbar as
no Wvalue is specifice after 'full' option; h returns the colorbar
handle and cmap returns the 31 X 3 colormap array generated.
[6] cmap = colorbarpzn(-2, 2, 'log', -1, 'rev', 'off'):
returns a 127 X 3 colormap array to cmap whlie disables displaying
the colorbar; the colormap is with a reversed defualt color
spectrum and the white color region is enlarged by a loginess of -1.
[7] colorbarpzn(-1, 2, 'wrs', 0.4):
creates a colormap and a colorbar from -1 to 2 with the default
positive-negative color spectrum where the values between -0.4 and
0.8 are displayed in White; the red and blue linear color gradients
tarts at 0.8 and -0.4 respectively, with a white regein in the
middle.
[8] colorbarpzn(-1, 2, 'colorP2', 'g', 1.5, 'colorN2', [0.3 0.4 0.2]):
creates a colormap and a colorbar from -1 to 2 with the default
positive-negative color spectrum and adds a secondary positive
color with predefined green 'g' aligned with the value 1.5 and a
secondary negative color with RGB [0.3 0.4 0.2] at the middle of
[-1 0] as the N2value parameter is not specified.
=========================================================================
version 1.8.0
- Function name changed to >>colorbarpzn denoting
positive-zero-negative. 'colorW' option name changed to 'colorZ'
accordingly.
- Fix a bug when using the 'full' option without specifying 'Wvalue'
gives a false error.
Xiaowei He
06/16/2023
-------------------------------------------------------------------------
version 1.7.2
- Fixed a bug where the number of levels is incorrect when using the
'log' option.
- Fixed a bug where the 'zero' color is missing when generating a
one-sided colorbar/colormap.
Xiaowei He
05/22/2023
-------------------------------------------------------------------------
version 1.7.1
- Fixed a bug in v1.7.0 where using [R G B] and P2value/N2value
together in 'colorP2' or 'colorN2' can cause a fault error.
Xiaowei He
04/25/2023
-------------------------------------------------------------------------
version 1.7.0
- Added options 'colorP2' and 'colorN2' for secondary colors in the
positive and negative color spectra, respectively.
- Predefined colors can now be used for 'colorP', 'colorN', 'colorZ',
as well as the new 'colorP2' and 'colorN2' options.
- Removed the warning messages when overwritting 'dft' colors with
'colorP', 'colorN', and 'colorZ'.
Xiaowei He
04/25/2023
-------------------------------------------------------------------------
version 1.6.1
- Fixed a bug in v1.6.0 where the white color is not at zero when using
default cmin and cmax settings.
Xiaowei He
09/01/2022
-------------------------------------------------------------------------
version 1.6.0
- Added an option 'wrs' for extending the White color region so small
values are displayed in the White color and the color gradient does
not start until a threshold. See description of
colormap(__, 'wrs', WhiteRegionSize).
- Adjusted the default red and blue color.
- Fixed a bug where an even number level cannot be generated, although
an odd Nlevel value is preferred for acurate Zero value positioning.
- 'off' potion can now be used without an output argument.
Xiaowei He
08/25/2022
-------------------------------------------------------------------------
version 1.5.0
- Added several predefined low-saturation colors and an input argument
'dft' which allows for changing the default red-white-blue colormap
with combinations of these predefined colors. See description of
colormap(__, 'dft', 'colors') for details.
- Fixed a bug that causes errors when the colorbar label string is the
same as one of the input arguments.
Xiaowei He
05/28/2022
-------------------------------------------------------------------------
version 1.4.0
- Added support for reversed colorbar direction by switching cmin and
cmax order, so the input limits became colorbarpzn(caxis1, caxis2).
E.g., colorbarpzn(2, -1) displays a -1 to 2 colorbar in reversed
direction, which is equivalent to cb.Direction = 'rev'.
- Removal of the caxis1 < caxis2 rule accordingly.
- Fixed a bug that causes an error when using 0 or 1 as the first caxis
limit, i.e., colorbarpzn(0, caxis2) or colorbarpzn(1, caixs2).
- Updates in headline description and examples.
Xiaowei He
05/23/2022
-------------------------------------------------------------------------
version 1.3.0
- Added support for setting colormap and displaying colorbar on
specific target, e.g., colorbarpzn(ax, cmin, cmax).
- Updates and corrections in headline description and examples.
Xiaowei He
05/07/2022
-------------------------------------------------------------------------
version 1.2.0
- Changed the function name from >>colorbarPWN to >>colorbarpwn for
friendlier user experience.
- Added an option 'off' which disables creatting the colorbar and only
returns the colormap array.
- Updates in headline description including a few examples.
Xiaowei He
04/27/2022
-------------------------------------------------------------------------
version 1.1.1
- Minor code improvement.
- Updates in headline descriptions.
Xiaowei He
04/21/2022
-------------------------------------------------------------------------
version 1.1.0
- Added an output argument for the colormap array.
- Added an input argument 'rev' for reversed default Positive and
Negative colors, where Positive is in blue and Negative is in red.
- Improved some logical structures.
- Updated some descriptions in the headlines.
Xiaowei He
04/15/2022
-------------------------------------------------------------------------
version 1.0.1
- Fixed a bug when output coloarbar handle.
Xiaowei He
04/07/2022
-------------------------------------------------------------------------
version 1.0.0
Xiaowei He
03/30/2022
=========================================================================
citation [1]
Connor Ott (2017). Non-linearly Spaced Vector Generator
https://www.mathworks.com/matlabcentral/fileexchange/64831-non-linearly-spaced-vector-generator,
MATLAB Central File Exchange.
function nonLinVec = nonLinspace(mn, mx, num)
loginess = 1.5; Increasing loginess will decreasing the spacing towards
the end of the vector and increase it towards the beginning.
nonLinVec = (mx - mn)/loginess*log10((linspace(0, 10^(loginess) - 1, num)+ 1)) + mn;
end
=========================================================================

Cite As

Xiaowei He (2024). Positive-zero-negative colorbar (https://www.mathworks.com/matlabcentral/fileexchange/110190-positive-zero-negative-colorbar), MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2022a
Compatible with R2006a and later releases
Platform Compatibility
Windows macOS Linux
Tags Add Tags

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
Version Published Release Notes
1.8.0

- Function name changed to >>colorbarpzn denoting positive-zero-negative. 'colorW' option name changed to 'colorZ' accordingly.
- Fix a bug when using the 'full' option without specifying 'Wvalue' gives a false error.

1.7.2

- Fixed a bug where the number of levels is incorrect when using the 'log' option.
- Fixed a bug where the 'White' color is missing when generating a one-sided colorbar/colormap.

1.7.1

- Fixed a bug in v1.7.0 where using [R G B] and P2value/N2value together in 'colorP2' or 'colorN2' can cause a fault error.

1.7.0

- Added options 'colorP2' and 'colorN2' for secondary colors in the positive and negative color spectra, respectively.
- Predefined colors can now be used for 'colorP', 'colorN', 'colorW', as well as the new 'colorP2' and 'colorN2' options.

1.6.1

- Fixed a bug in v1.6.0 where the white color is not at zero when using default cmin and cmax settings.

1.6.0

- Added an option 'wrs' for extending the white color region so small values are displayed in a uniform color.
- Adjusted the default color.
- Fixed a bug where an even number level cannot be generated.
- 'off' potion can be used without an output.

1.5.0

- Added predefined low-saturation colors which allows for changing the default colormap with combinations of these predefined colors.
- Fixed a bug that causes errors when the colorbar label string is the same as one of the input arguments.

1.4.0

- Added support for reversed colorbar direction by switching cmin and cmax order.
- Removal of the caxix1 < caxis2 rule accordingly.
- Fixed a bug that causes an error when using 0 or 1 as the first caxis limit.
- Updates in description and examples.

1.3.0

- Added support for setting colormap and displaying colorbar on specific target, e.g., colorbarpwn(ax, cmin, cmax).
- Updates and corrections in headline description and examples.

1.2.0

- Changed the function name from >>colorbarPWN to >>colorbarpwn for friendlier user experience.
- Added an option 'off' which disables creating the colorbar and only returns the colormap array.
- Updates in the headlines including a few examples.

1.1.1

- Minor code improvement.
- Updates in headline descriptions.

1.1.0