CGHISTOPLOT
This program is used to draw a histogram plot in an IDL direct graphics window..
Categories
Graphics
Params
data: in, required,
The data from which the histogram is created.
Keywords
addcmd: in, optional, type=boolean, default=0
Set this keyword to add the command to the resizeable graphics window cgWindow.
axiscolorname: in, optional, type=string, default='opposite'
The name of the axis color. All color names are derived from cgColor.
backcolorname: in, optional, type=string, default='background'
The name of the background color. All color names are derived from cgColor.
binsize: in, optional
The binsize of the histogram. By default, Scott's Choice of bin size for histograms is used::
binsize = (3.5 * StdDev(data)) / N_Elements(data)^(0.3333)
If BINSIZE in not defined, and NBINS is defined, the BINSIZE is calcuated as::
binsize = (Max(dataToHistogram) - Min(dataToHistogram)) / (NBINS -1)
While it is pointed out in the HISTOGRAM documentation, it is extremely
important that the BINSIZE be of the same data type as the data you are going to
calculate the histogram of. If it is not VERY strange things can happen. I've
tried to protect you from most of the bad things, but I don't have a high confidence
level that I have done it for every situation. If you see something that "just don't
look right", I would check first to see if your data types match. That might solve
all your problems.
charsize: in, optional, type=float
The character size of the annotations. Default set by calling cgDefCharSize().
datacolorname: in, optional, type=string, default="indian red"
The name of the data color for drawing the histogram outlines.
filename: in, optional, type=string
The name of a color name file to use with cgCOLOR.
fillpolygon: in, optional, type=boolean, default=0
Set this keyword to fill the histogram polygons with the `POLYCOLOR`.
frequency: in, optional, type=boolean, default=0
If this keyword is set, the relative frequency is plotted on the Y axis,
rather than the histogram density.
histdata: out, optional
The output value of the internal HISTOGRAM command.
l64: in, optional, type=boolean, default=0
If set, the return value of HISTOGRAM are 64-bit integers, rather than
the default 32-bit integers.
log: in, optional, type=boolean, default=0
Set this keyword if you wish the histogram count to be represented on a logarithmic scale.
layout: in, optional, type=integer
This keyword specifies a grid with a graphics window and determines
where the graphic should appear. The syntax of LAYOUT is a 3-element
array: [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.
line_fill: in, optional, type=boolean, default=0
If set, the polygons are filled with lines instead of solid color. If
this keyword is set, the following keywords can also be used: `ORIENTATION`,
`PATTERN`, `POLYCOLOR`, and `SPACING`.
locations: out, optional
Starting locations of each bin. (See the HISTOGRAM documentation for details.)
maxinput: in, optional
The maximum value to use in calculating input histogram. Equivalent to the MAX keyword
in the HISTOGRAM documentation.
max_value: in, optional
The maximum Y data value to represent on graphics plot. Default: Max(data) * 1.05.
mininput: in, optional
The minimum value to use in calculating input histogram. Equivalent to the MIN keyword
in the HISTOGRAM documentation.
min_value: in, optional
The minimum Y data value to represent on graphics plot. Default: 0.
missing: in, optional
The value that should be represented as "missing" and not used in the histogram.
Be aware that if the input data is not of type "float" or "double" that the input
data will be converted to floating point prior to calculating the histogram.
nan: in, optional, type=boolean, default=0
If set, ignore NAN values in calculating and plotting histogram.
nbins: in, optional, type=integer
The number of output bins in the histogram. Meaning is slightly different from
meaning in the HISTOGRAM command. Used only to calculate BINSIZE when BINSIZE is
not specified. In this case, binsize = rangeofData/(nbins-1).
omax: out, optional
The maximum output value used to construct the histogram. (See HISTOGRAM documentation.)
omin: out, optional
The minimum output value used to construct the histogram. (See HISTOGRAM documentation.)
oprobability: in, optional, type=boolean, default=0
Set this keyword if you want to overplot the cumulative probability on the plot.
oplot: in, optional, type=boolean, default=0
Set this keyword if you want to overplot the histogram on already established axes.
orientation: in, optional, type=float, default=0.0
The orientation (rotations) of the lines used to fill the polygons if `LINE_FILL` is set.
(See POLYFILL documentation.)
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 if you wish to draw only the outline of the histogram plot,
in a manner similar to setting PSYM=10 on a PLOT command.
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 PS_END 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.
pattern: in, optional
The fill pattern for the polygons if the `FILLPOLYGON` keyword is set. (See POLYFILL documentation.)
polycolor: in, optional, type=string, default="rose"
The name of the polygon fill color if the `FILLPOLYGON` keyword is set.
position: in, optional, type=fltarr
The position of the plot axes in normalized data coordinates, [x0,y0,x1,y1].
probability_function: out, optional, type=float
The total cummulative probability of the histogram plot, scaled from 0 to 1.
probcolorname: in, optional, type=string, default="blue"
The name of the probability color for overplotting the cumulative probability
on the plot.
probthick: in, optional, type=float, default=1.0
The thickness of the probability line drawn on the plot.
reverse_indices: out, optional
The list of reverse indices returned from the HISTOGRAM command. (See HISTOGRAM documentation.)
rotate: in, optional, type=boolean, default=0
Set this keyword to cause the histogram bins to be drawn from left to right, rather
than from bottom to top.
smooth: in, optional, type=integer, default=0
Set this keyword to an odd positive integer to smooth the histogram output before plotting.
The integer will set the width of a smoothing box to be applied to the histogram data with
the Smooth function.
spacing: in, optional
The spacing of fill line if the 'LINE_FILL` keyword is set. (See POLYFILL documentation.)
thick: in, optional, type=integer, default=1
Set this keyword to a value greater than 1 to draw thicker axes and lines.
title: in, optional, type=string
Set this keyword to the plot title.
window: in, optional, type=boolean, default=0
Set this keyword to replace all the commands in the current cgWindow or to
create a new cgWindow, if one doesn't currenly exist, for displaying this command.
To create a new cgWindow if one currenly exists, use the `cgWindow` command
xtitle: in, optional, type=string, default="Relative Frequency"
The X title of the histogram plot.
ytitle: in, optional, type=string, default="Histogram Density"
The Y title of the histogram plot.
_ref_extra: in, optional
Any additional PLOT commands are passed via keyword inheritance.
Examples
Some of the ways cgHistogram can be used::
cgHistoplot, Dist(256), BINSIZE=5.0
cgHistoplot, Fix(RandomU(seed, 200)*20), POLYCOLOR=['charcoal', 'steel blue'], /FILLPOLYGON
cgHistoplot, Fix(RandomU(seed, 200)*20), POLYCOLOR=['navy', 'forest green'], /LINE_FILL, ORIENTATION=[45,-45]
Additional examples can be found here::
http://www.idlcoyote.com/graphics_tips/histoplot.php
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 by: David W. Fanning, 14 November 2007.
Modified to work with !P.MULTI. 20 Nov 2007. DWF.
Slight problem with extra space at the right end of the plot resolved. 20 Nov 2007. DWF.
Added FILE and NOLINES keywords. 24 Nov 2007. DWF.
Added additional HISTOGRAM access via keywords. 24 Nov 2007. DWF.
Fixed a small problem with FILLPOLY keyword. 26 Nov 2007. DWF.
Fixed a small problem with the OVERPLOTTED histogram being slightly offset. 12 Jan 2009. DWF
Major reconstructive surgery on the actual drawing part of the program. As far as I can
tell, all functionality is the same, but without drawing problems evidenced before. 14 March 2009. DWF.
A small problem with the way I was specifying ranges caused the bars to be slightly offset. 23 March 2009. DWF.
I fixed a small problem with BINSIZE and HISTOGRAM data type matching (see the Note), and I also
fixed a small problem with the range calculations when byte data is passed in. 1 April 2009. DWF.
I removed a NOLINES keyword, which was no longer being used. 1 April 2009. DWF.
MIN_VALUE and MAX_VALUE keywords now work again, thanks to Josiah Schwab. 22 April 2009. DWF.
Changed default POLYFILL color to "ROSE". 22 April 2009. DWF.
Having problems with binsize selection when data to histogram is an integer type. Fixed. 8 June 2009. DWF.
When the input array has a considerable number of NANs, the Histogram command complains with an error
"Array has too many elements." This happens even when the NAN keyword is set for the Histogram
command. So, I now screen for NANs before I process the histogram. 8 June 2009. DWF.
Added MISSING keyword to represent missing data. 18 July 2009. DWF.
Adding the MISSING keyword exposed a problem I had in restoring the original input data
to its original values when there were NANs and MISSING values. Fixed now by making
a copy of the data to work on internally. Everything else is too complex. 20 July 2009. DWF.
Yikes! Bad error in calculating start and end of histogram plot when overplotting fixed. 4 Sept 2009. DWF.
Added needed XSTYLE=1 to AXIS command to match Plot axis labelling. 19 Oct 2009. DWF.
Added a THICK keyword. 9 November 2009. DWF.
Added an OUTLINE keyword so only the outline of the histogram is plotted. 3 December 2009. DWF.
I was trying to be a good citizen by reloading the input color table when I exited
the program. But, of course, that makes it impossible to use the program in
the Z-buffer. Fixed by being less of a good citizen. 23 July 2010. DWF.
Because of the way I was dealing with NANs and MISSING data, the reverse indices were
inaccurate when they were returned, if there was NANs or MISSING data in the
input array. The data is now being handled correctly in all cases. This requires
that missing data must be set to !VALUES.F_NAN prior to calculating the histogram.
This means the data MUST be converted to floats for this operation. Since I am
always working on a *copy* of the data when this occurs, it should not affect
user input data. Also, I scan all input floating point and double data for NANs,
and if found, and the NAN keyword is not set, I issue a warning and set the NAN
keyword. This is a change in behavior. 1 October 2010. DWF.
Fixed a problem when specifying more than one POLYCOLOR. I made a change to the program
and forgot to propogate it everywhere. 4 October 2010. DWF.
Default axis color name changed from "Navy" to "Black". 28 October 2010. DWF.
Fixed a problem with restoring color tables in PostScript. 24 Nov 2010. DWF.
Added OPROBABILITY, PROBCOLOR, and PROBABILITY keywords. 24 Nov 2010. DWF.
Changed the way I find a default axis color. 3 Dec 2010. DWF.
Expanded search for "integers" from in BINSIZE calculation from DataType LE 3
to include DataType GE 12, too. 8 Dec 2010. DWF.
Added WINDOW keyword. 24 Jan 2011. DWF.
Added ADDCMD keyword. 26 Jan 2011. DWF.
Added LAYOUT keyword. 28 Jan 2011. DWF.
Added CHARSIZE keyword. 2 Feb 2011. DWF.
Added YTITLE keyword. 9 May 2011. DWF.
Worked around a PLOT problem when setting the X axis range that caused the Y axis
range to be corrupted. 19 May 2011. DWF.
Added the ROTATE keyword. 18 Aug 2011. DWF.
I was calculating and displaying the cumulative probability distribution function
incorrectly. Now changed to what I think is the correct result. 8 Nov 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.
I had a problem with OVERPLOTs being slightly offset because I was calculating the xrange
and yrange, rather than taking them from !X.CRange and !Y.CRange. 17 Dec 2011. DWF.
Modified to use cgDefaultColor for default color selection. 24 Dec 2011. DWF.
Incomplete implementation of new color selection scheme, fixed. 30 Dec 2011. DWF.
The change of 17 Dec 2011 was incorrect, as I misunderstood the problem. Restored original. 30 Dec 2011. DWF.
Changes to allow better default colors, based on changes to cgColor and cgDefaultColor. 1 Feb 2012. DWF.
Added a SMOOTH keyword. 26 April 2012. DWF.
Small fix (CR missing!) to allow overplotting in cgWindow. 26 April 2012. DWF.
The Outline keyword was incorrectly drawing the last histogram bin outline. Fixed. 26 April 2012. DWF.
Added POSITION and PROBTHICK keywords to set the plot position and the thickness of the cumulative
probability line, respectively. 25 May 2012. DWF.
If the cumulative probability option (keyword OPROBABILITY) is set, a second axis is drawn indicating
the cumulative probablity from 0 to 1. 25 May 2012. DWF.
Whoops! Don't want to set default position unless Total(!P.MULTI) equals zero. 25 May 2012. DWF.
More work on getting the cumulative probability to be correctly plotted. 30 May 2012. DWF.
More whoops! Setting POSITION now interfering with LAYOUT keyword. More fixes to restore LAYOUT. 26 July 2012. DWF.
Aaauuughhh! Typo introduced in yesterday's fix before I saved final version. 27 July 2012. DWF.
Added the ability to use escape characters in plot titles to specify cgSymbol symbols. 27 July 2012. DWF.
Mis-spelled "probability" in one section of the code. Fixed. 31 July 2012. DWF.
Copyright
Copyright (c) 2007-2012, Fanning Software Consulting, Inc.