coyote: CGBARPLOT

Description
Provides a device-independent and color-model-independent way to create a bar
plot or to overplot on an existing bar plot.
The program requires the `Coyote Library `
to be installed on your machine.
Categories
Graphics
Params
values: in, required
    A vector containing the values to be represented by bars. Each element in
    the vector will be represented by a bar. 
Keywords
addcmd: in, optional, type=boolean, default=0
   Set this keyword to add the command to a cgWindow resizeable graphics window.
axiscolor: in, optional, type=string/integer, default='black'
   If this keyword is a string, the name of the axis color. By default, 'black'.
   Otherwise, the keyword is assumed to be a color index into the current color table.
background: in, optional, type=string/integer, default='white'
   If this keyword is a string, the name of the background color. By default, 'white'.
   Otherwise, the keyword is assumed to be a color index into the current color table.
barcoords: out, optional, type=float
   A vector of values for the center point of the bars.
barnames: in, optional, type=string, default=""
   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.
baroffset: in, optional, type=float, default=barspace/barwidth*1.5
   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.  
barspace: in, optional, type=float, default=barwidth*0.20
   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.
barthick: in, optional, type=float, default=1.0
   A scalar that specifies the thickness of the bar outlines. 
barwidth: in, optional, 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 will fill the available space (optionally controlled with the BASERANGE 
    keyword).
baselines: in, optional, type=float, default=0.0
    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.
baserange: in, optional, type=float, default=1.0
    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.
colors: in, optional, type=varies
    A vector of color values, the same size as VALUES, containing either the color
    names, 24-bit color values, or color index numbers (byte values) of the colors to
    be used for the bars. If not specified, the colors are selected based on the 
    available colors in the current color table.
labelskip: in, optional, type=integer, default=1
    Normally, every bar is labelled. IDL has a maximum number of 60 labels. This keyword
    allows you to control how bars are labelled and to work around the 60 label limit.
    Set this keyword the number of labels to skip. For example, if you had 90 bars, you
    could set Labelskip=3 and have 30 labels. If undefined, Labelskip will always be set 
    so there are less than 60 labels on the plot.
layout: in, optional, type=intarr(3)
    This keyword specifies a grid with a graphics window and determines where the
    graphic should appear. The syntax of LAYOUT is three numbers: [ncolumns, nrows, location].
    The grid is determined by the number of columns (ncolumns) by the number of 
    rows (nrows). The location of the graphic is determined by the third number. The
    grid numbering starts in the upper left (1) and goes sequentually by column and then
    by row.
noerase: in, optional, type=boolean, default=0
    Set this keyword to draw the plot without erasing the display first.
outfilename: in, optional, type=string
   If the `Output` keyword is set, the user will be asked to supply an output
   filename, unless this keyword is set to a non-null string. In that case, the
   value of this keyword will be used as the filename and there will be no dialog
   presented to the user.
outline: in, optional, type=boolean, default=0
    Set this keyword to draw an outline around each bar in the OPLOTCOLORS.
output: in, optional, type=string, default=""
   Set this keyword to the type of output desired. Possible values are these::
       'PS'   - PostScript file
       'EPS'  - Encapsulated PostScript file
       'PDF'  - PDF file
       'BMP'  - BMP raster file
       'GIF'  - GIF raster file
       'JPEG' - JPEG raster file
       'PNG'  - PNG raster file
       'TIFF' - TIFF raster file
   Or, you can simply set this keyword to the name of the output file, and the type of
   file desired will be determined by the file extension. If you use this option, the
   user will not be prompted to supply the name of the output file.
   All raster file output is created through PostScript intermediate files (the
   PostScript files will be deleted), so ImageMagick and Ghostview MUST be installed 
   to produce anything other than PostScript output. (See cgPS2PDF and cgPS_Close for 
   details.) And also note that you should NOT use this keyword when doing multiple 
   plots. The keyword is to be used as a convenient way to get PostScript or raster 
   output for a single graphics command. Output parameters can be set with cgWindow_SetDefs.
oplotcolors: in, optional, type=varies, default='charcoal'
    A vector of color values, similar to colors for overplot outlines on the bars.
    If a scalar value (e.g., "charcoal") the same value is used for all outlines.
overplot: in, optional, type=boolean, default=0
    Set this keyword if you wish to overplot data on an already exisiting set of
    axes. It is like calling the IDL OPLOT command.
position: in, optional, type=fltarr(4)
    The usual four-element normalized position vector for the Plot comamnd. 
rotate: in, optional, type=boolean, default=0
    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.
title: in, optional, type=string, default=""
    The title of the plot, if supplied.
window: in, optional, type=boolean, default=0
    Set this keyword if you want to display the plot in a resizable graphics window.
xstyle: in, optional, type=boolean, default=1
    The normal XSTYLE keyword. See "Graphics Keywords" in on-line help.
xtitle: in, optional, type=string, default=""
    The X title of the plot, if supplied.
ystyle: in, optional, type=boolean, default=1
    The normal YSTYLE keyword. See "Graphics Keywords" in on-line help.
ytitle: in, optional, type=string, default=""
    The Y title of the plot, if supplied.
_ref_extra: in, optional, type=any
   Any keyword appropriate for the IDL Plot command is allowed in the program.
Examples
To create bar plots of four different bar classes. Example uses AL_Legend from
the NASA Astronomy Library. Comment out if not available.::
Create data::
   seed = -5L
   data1 = RandomU(seed, 5) * 10.0
   data2 = RandomU(seed, 5) * 7.5
   data3 = RandomU(seed, 5) * 7.5
   data4 = RandomU(seed, 5) * 10.0
Display as four different plots::
   !P.Multi=[0,2,2]
   cgDisplay, WID=0
   cgBarPlot, data1, /OUTLINE, OPLOTCOLOR='charcoal', YRANGE=[0, 12], COLORS='red', XTITLE='Class 1'
   cgBarPlot, data2, /OUTLINE, OPLOTCOLOR='charcoal', YRANGE=[0, 12], COLORS='blue', XTITLE='Class 2'
   cgBarPlot, data3, /OUTLINE, OPLOTCOLOR='charcoal', YRANGE=[0, 12], COLORS='gold', XTITLE='Class 3'
   cgBarPlot, data4, /OUTLINE, OPLOTCOLOR='charcoal', YRANGE=[0, 12], COLORS='dark green', XTITLE='Class 4'
   !P.Multi=0
Display as accumulated bar plots::
   cgDisplay, WID=1
   barnames = ['Exp 1', 'Exp 2', 'Exp 3', 'Exp 4', 'Exp 5']
   cgBarPlot, data1, YRANGE=[0, 35], COLORS='red', BARNAMES=barnames
   cgBarplot, data2, /OVERPLOT, BASELINE=data1, COLORS='blue'
   cgBarplot, data3, /OVERPLOT, BASELINE=data1+data2, COLORS='gold'
   cgBarplot, data4, /OVERPLOT, BASELINE=data1+data2+data3, COLORS='dark green'
   colors = ['red', 'blue', 'gold', 'dark green']
   items = ['Class 1', 'Class 2', 'Class 3', 'Class 4']
   Al_Legend, items, /FILL, PSYM=Replicate(15,4), COLORS=colors, SYMSIZE=Replicate(1.75,4), $
       POSITION=[0.20, 0.92], /NORMAL, CHARSIZE=cgDefCharSize()
Display all on same plot::
   cgDisplay, WID=2
   cgBarPlot, data1, YRANGE=[0, 12], BAROFFSET=2.5, BASERANGE=0.20, COLORS='red'
   cgBarplot, data2, /OVERPLOT, BAROFFSET=9.5, BASERANGE=0.20, COLORS='blue'
   cgBarplot, data3, /OVERPLOT, BAROFFSET=17.0, BASERANGE=0.20, COLORS='gold'
   cgBarplot, data4, /OVERPLOT, BAROFFSET=24.5, BASERANGE=0.20, COLORS='dark green'
   colors = ['red', 'blue', 'gold', 'dark green']
   items = ['Class 1', 'Class 2', 'Class 3', 'Class 4']
   Al_Legend, items, /FILL, PSYM=Replicate(15,4), COLORS=colors, SYMSIZE=Replicate(1.75,4), $
       POSITION=[0.45, 0.92], /NORMAL, CHARSIZE=cgDefCharSize()
image:: cgbarplot.png
Author
FANNING SOFTWARE CONSULTING::
    David W. Fanning 
    1645 Sheely Drive
    Fort Collins, CO 80526 USA
    Phone: 970-221-0438
    E-mail: david@idlcoyote.com
    Coyote's Guide to IDL Programming: http://www.idlcoyote.com
History
Change History::
   Written, 3 October 2011. DWF. Written as a straight-forward translation of
       the IDL Bar_Plot program. In retrospect, maybe not the best idea, as I 
       don't think the Bar_Plot program actually works and the interface is clunky.
       But, this is a start. The interface may change to something more elegant over
       time.
    Updated the BACKGROUND color selection from lessons learned in 27 Oct 2011 cgContour 
        corrections. 27 Oct 2011. DWF.
    Added the ability to send the output directly to a file via the OUTPUT keyword. 9 Dec 2011, DWF.
    PostScript, PDF, and Imagemagick parameters can now be tailored with cgWindow_SetDefs. 14 Dec 2001. DWF.
    Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
    Fixed a problem with keyword inheritance. Added XStyle and YStyle keywords. 25 Jan 2012. DWF.
    Added BARCOORDS keyword to return bar plot locations. 25 Jan 2012.
    Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF.
    Small problem with setting range keywords and with extraneous marks on the bar plot axis fixed. 6 Feb 2012. DWF.
    Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
    Fixed a typo that was interfering with the YTITLE keyword. 3 Oct 2012. DWF.
    Fixed a bug in the interaction of the NOERASE and OVERPLOT keywords. 14 Jan 2013. DWF.
    Added a BARTHICK keyword to change the thickness of the bar outlines. 28 Feb 2013. DWF.
    Further work checking for NANs in the display of the data. NAN data set to length of 0. 3 Sept 2013. DWF.
    Added LABELSKIP keyword and make sure number of labels doesn't exceed 60. 8 Feb 2014. DWF.
    Somehow the BARCOORDS coordinates have gone on walk-about. Restored. 15 April 2014. DWF.
Copyright
Copyright (c) 2011-2014, Fanning Software Consulting, Inc.