<< prev file | next file >>    view single page | view frames    summary: fields | routine    details: routine

ToBeReviewed/PLOTS/DESSINE/

bar_plot.pro

Create a bar graph, or overplot on an existing one.

topbar_plot Graphics

bar_plot, values, baselines=baselines, colors=colors, barnames=barnames, title=title, xtitle=xtitle, ytitle=ytitle, baserange=baserange, barwidth=barwidth, barspace=barspace, baroffset=baroffset, outline=outline, overplot=overplot, background=background, rotate=rotate, _EXTRA=_EXTRA

Parameters

values        in required

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       

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       

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 indices as widely as possible within the available colors (specified by D.N_COLORS).

barnames       

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       

A string containing the main title to for the bar plot.

xtitle       

A string containing the title for the X axis.

ytitle       

A string containing the title for the Y axis.

baserange       

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       

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       

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       

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. If not specified, the default offset is equal to BARSPACE.

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       

A scalar that specifies the color index to be used for the background color. By default, the normal IDL background color is used.

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

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. $Id: bar_plot.pro 142 2006-07-21 12:47:49Z navarro $
Produced by IDLdoc 2.0.