ToBeReviewed/PLOTS/DESSINE/
bar_plot.pro
Create a bar graph, or overplot on an existing one.
bar_plot
Graphics
bar_plot, values, baselines=vector, colors=vector, barnames=string, title=string, xtitle=string, ytitle=string, baserange=float, barwidth=float, barspace=scalar, baroffset=scalar, outline=outline, overplot=overplot, background=scalar, rotate=rotate, _EXTRA=_EXTRA
Parameters
values
in
required
type: vector
A vector containing the values to be represented by the bars.
Each element in VALUES corresponds to a single bar in the
output.
Keywords
baselines
type: vector
A vector, the same size as VALUES, that contains the
base value associated with each bar. If not specified,
a base value of zero is used for all bars.
colors
type: vector
A vector, the same size as VALUES, containing the color index
to be used for each bar. If not specified, the colors are
selected based on spacing the color indexes as widely as
possible within the available colors (specified by D.N_COLORS).
barnames
type: string
A string array, containing one string label per bar.
If the bars are vertical, the labels are placed beneath
them. If horizontal (rotated) bars are specified, the labels
are placed to the left of the bars.
title
type: string
A string containing the main title to for the bar plot.
xtitle
type: string
A string containing the title for the X axis.
ytitle
type: string
A string containing the title for the Y axis.
baserange
type: float
A floating-point scalar in the range 0.0 to 1.0, that
determines the fraction of the total available plotting area
(in the direction perpendicular to the bars) to be used.
If not specified, the full available area is used.
barwidth
type: float
A floating-point value that specifies the width of the bars
in units of "nominal bar width". The nominal bar width is
computed so that all the bars (and the space between them,
set by default to 20% of the width of the bars) will fill the
available space (optionally controlled with the BASERANGE
keyword).
barspace
type: scalar
A scalar that specifies, in units of "nominal bar width",
the spacing between bars. For example, if BARSPACE is 1.0,
then all bars will have one bar-width of space between them.
If not specified, the bars are spaced apart by 20% of the bar
width.
baroffset
type: scalar
default: BARSPACE
A scalar that specifies the offset to be applied to the
first bar, in units of "nominal bar width". This keyword
allows, for example, different groups of bars to be overplotted
on the same graph.
outline
If set, this keyword specifies that an outline should be
drawn around each bar.
overplot
If set, this keyword specifies that the bar plot should be
overplotted on an existing graph.
background
type: scalar
default: The normal IDL background color is used
A scalar that specifies the color index to be used for
the background color.
rotate
If set, this keyword indicates that horizontal rather than
vertical bars should be drawn. The bases of horizontal bars
are on the left, "Y" axis and the bars extend to the right.
_EXTRA
Examples
By using the overplotting capability, it is relatively easy to create
stacked bar charts, or different groups of bars on the same graph.
For example, if ARRAY is a two-dimensional array of 5 columns and 8
rows, it is natural to make a plot with 5 bars, each of which is a
"stacked" composite of 8 sections. First, create a 2D COLORS array,
equal in size to ARRAY, that has identical color index values across
each row to ensure that the same item is represented by the same color
in all bars.
With ARRAYS and COLORS defined, the following code fragment
illustrates the creation of stacked bars (note that the number of rows
and columns is arbitrary):
!Y.RANGE = [0,ymax] ; Scale range to accommodate the total bar lengths.
BASE = INTARR(NROWS)
FOR I = 0, NROWS-1 DO BEGIN
BAR_PLOT, ARRAY(*,I), COLORS=COLORS(*,I), BASELINES=BASE, $
BARWIDTH=0.75, BARSPACE=0.25, OVER=(I GT 0)
BASE = BASE + ARRAY(*,I)
ENDFOR
To plot each row of ARRAY as a clustered group of bars within the same
graph, use the BASERANGE keyword to restrict the available plotting
region for each set of bars. The sample code fragment below
illustrates this method:
FOR I = 0, NROWS-1 DO $
BAR_PLOT, ARRAY(*,I), COLORS=COLORVECT, BARWIDTH=0.8,BARSPACE=0.2, $
BAROFFSET=I*((1.0+BARSPACE)*NCOLS), OVER=(I GT 0), BASERANGE=0.19
where NCOLS is the number of columns in ARRAY, and COLORVECT is a
vector containing the color indices to be used for each group of
bars. (In this example, each group uses the same set of colors, but
this could easily be changed.)
Version history
Version
$Id: bar_plot.pro 240 2007-03-28 12:17:24Z pinsard $
History
August 1990, T.J. Armitage, RSI, initial programming. Replacement
for PLOTBAR and OPLOTBAR routines written by William Thompson.
September 1990, Steve Richards, RSI, changed defaults to improve the
appearance of the bar plots in the default mode. Included
spacing the bars slightly.
Produced by IDLdoc 2.0.