bar4viacolor

4-D bar graph : hack on bar3 with another dimension via color (2 poss. schemes)

bar4viacolor - 4-D bar graph : bar3 with another dimension via bar color.
Two color schemes are available: The jet colormap and another that, like
bar3, is a column group scheme whose groups colors vary mainly by saturation

[hh,ScalingDataColorImg,ScaleColorDataClim,colorbarh] = bar4viacolor(varargin)

This function is a add-on hack on bar3 and so I've left the bar3
documentation below. W/r to the bar3 documentation below, bar4 uses a
Z sized matrix to specifiy the 4D color dimension. I extended the bar3 Z argument to be a struture s.t.
one of the fields is Z and the rest the new 4D parameters. This "Z"
structure goes in the first or second argument, just like Bar3, and all
other Bar3 args stay the same.

Because color is used as another dimension, an obligatory colorbar is
automatically be displayed showing the range of colors.

The Z structure consists of these fields:
{.Z, .ColorScaleData, .ScalingOption, .BarColorType}
(Note that ScalingOption and BarColorType have defaults and those fields
do not have to be in the structure for their defaults to take
effect)

Z - 3D data just like bar3 where each element yields a bar.

ColorScaleData - Same size as Z. Defines the 4D data.
Note, negative values will yield bars with red edges. New if this
argument is left out or empty than it will default to the Z data which
then causes the bars to be Z colored.

ScalingOption - {'a'} | 's' | 'c' | Clim - This controls how the
Scaling Data is mapped to the colors:
'a' - autoscaling - if all ScalingData is between 0 and 1 nothing is
done but otherwise the data is mapped to the entire color range.
's' - scaled - The ScalingData is mapped to the entire color range
(like imagesc)
'c' - clipped - ScalingData between 0 and 1 is scaled to the entire
color range. Data outside that is mapped to the first and last
colors respectively (i.e. as if ScalingData was clipped to 0,1)
Clim - [minvalue, maxvalue] - ScalingData in the range of minvalue
to maxvalue is mapped to the first and last colors respectively
(i.e. as if ScalingData was clipped to Clim like imagesc w/
clim)

BarColorType - 'c' | {'s'} - controls the color scheme used to color
the bars.
The default 's' option colors each bar by indexing into the jet
colormap just like, say, an indexed image using imagesc
The 'c' option is, like bar3, is a column group color scheme.
Specifically, all the bars of a column are the same hue but vary by
saturation, and to a lesser degree intensity, of each bar is varied to
reflect the ColorScaleData.
WARNING: *** concerning the use of 'c' options with figures containing
multiple subplots/colorbars see *** below

Additional output args: ScalingDataColorImg,ScaleColorDataClim,colorbarh.
Only appropriate for the BarColorType=='c' option.
ScalingDataColorImg - shows the range of colors available to this
histogram. A RGB image with row being the hue used for the
respective column of the histogram and the columns being
the breakdown thereof.
ScaleColorDataClim - is the ScalingDataClim implied or specified (and
so is the appropriate item to specify the range of X labels for
ScalingDataColorImg as per the image function)
image(ScaleColorDataClim,1:size(ScalingDataColorImg,1),ScalingDataColorImg);
colorbarh - handle to colorbar. For the 'c' option resizing this might
be desirable but the colorbar won't auto resize or move nicely if you do

Example:

figure;
Z = reshape(1:6*7,6,7); % 3D values, i.e. bar heights, increase in column order
ScalingData= reshape(-20:21,7,6)'; % 4D values, i.e. bar colors, increase in row order
bar4viacolor(struct('Z',Z,'ColorScaleData',ScalingData, ...
'ScalingOption',[-17,17],'BarColorType','c'));

Here the Z data is just 1:42 reshaped to a 6,7 array and the
ScalingData is a likewise sized array from -20:21 but whos sequence is
in row major order.
The construction of Z is such that each column will have bar
heights greater than the previous column and the construction of
ScalingData, along with the specification of BarColorType == 'c', will
independly produce increasing saturation within each row. The negative
ScalingData values (the first 20 boxes in row major order) yield red
edged light bars. The Clim clipping value means that the ScalingData
outside of -17,17 is as if it were -17,17.

Here's the 's' color scheme w/ the same data
figure;
bar4viacolor(struct('Z',Z,'ColorScaleData',ScalingData, ...
'ScalingOption',[-17,17],'BarColorType','s'));
Now the bar color are completely independent and correspond to the jet
colormap

Here's a 3d color version.
bar4viacolor(struct('Z',Z,'ScalingOption','s'))