CGCONLEVELS

CGCONLEVELS
This program is designed to create "nicely formatted" contour levels for use in
contour plots. The idea is to be able to produce evenly spaced contour intervals
with the contour levels rounded off to the preferred degree of accuracy. The program
will make a "guess" as to how to do this, but users can also take control of the
process if the results are not pleasing enough.

There is no claim that this program always produces the best results. It is more
of a tool that can produce decent result in many situations.

Returns

A vector of contour levels of the requested number. Each level is
rounded to a predefined or specified degree of accuracy.

Params

data: in, required
The data for which contour levels are desired.

Keywords

factor: in, optional, type=float
The program makes a "guess" at how to best round the levels in the data
presented to it. This guess is not always what the user wants. This keyword
allows the user to "fine tune" the guess, so that it behaves better. See the
examples for details on how this keyword can be used. There is some danger,
when using the factor keyword that the results will be terrible. Don't dismay!
Just try something else.
maxvalue: in, optional
Normally, the levels are calculated using the minimum and maximum values
of the input data. The maximum value used in the calculation can be replaced
with this value, if you wish. If both the `MinValue` and MaxValue keywords
are used, you do not need to pass the data parameter.
minmax: out, optional
The actual minimum and maximum values used to calculate the levels.
minvalue: in, optional
Normally, the levels are calculated using the minimum and maximum values
of the input data. The minimum value used in the calculation can be replaced
with this value, if you wish.
nlevels: in, optional, type=integer, default=10
The number of contour levels desired.
silent: in, optional, type=boolean, default=0
Set this keyword if you want the program to remain "silent" in the face of
errors. If this keyword is set, the user should rely on the `Success` keyword
to determine whether the program completed its work.
step: out, optional
The step size actually used in the program to calculate the levels.
success: out, optional, type=boolen
Upon return, will contain a 1 if the program executed succesfully and
a 0 otherwise.

Examples

Here is the normal way a contour plot might be created::
cgDisplay, WID=0
data = Scale_Vector(cgDemoData(2), 0.1, 4534.5)
cgLoadCT, 33, NColors=10, Bottom=1
cgContour, data, NLevels=10, /Fill, /Outline, $
Position=[0.1, 0.1, 0.9, 0.75], C_Colors=Indgen(10)+1
cgColorbar, NColors=9, Bottom=1, /Discrete, /Fit, $
Range=[Min(data), Max(data)], OOB_High=10, OOB_Low='white'

Here is how the same plot might be created with cgConLevels
to produce contour levels at 500 step intervals::

cgDisplay, WID=1
data = Scale_Vector(cgDemoData(2), 0.1, 4534.5)
cgLoadCT, 33, NColors=10, Bottom=1
levels = cgConLevels(data, Factor=100, MINVALUE=0)
cgContour, data, Levels=levels, /Fill, /Outline, $
Position=[0.1, 0.1, 0.9, 0.75], C_Colors=Indgen(10)+1
cgColorbar, NColors=9, Bottom=1, /Discrete, /Fit, $
Range=[Min(levels), Max(levels)], OOB_High=10, OOB_Low='white'

In this example, the data is scaled so that it is a bit more perverse.
The levels have been chosen so they round in the third decimal place::

cgDisplay, WID=2
data = Scale_Vector(cgDemoData(2), 0.153, 0.986)
cgLoadCT, 33, NColors=10, Bottom=1
levels = cgConLevels(data)
cgContour, data, Levels=levels, /Fill, /Outline, $
Position=[0.1, 0.1, 0.9, 0.75], C_Colors=Indgen(10)+1
cgColorbar, NColors=9, Bottom=1, /Discrete, /Fit, $
Range=[Min(levels), Max(levels)], OOB_High=10, OOB_Low='white'

It might be better to have the data rounded in the second data place, to
the nearest 0.05 value. This can be done with the `Factor` keyword::

cgDisplay, WID=3
data = Scale_Vector(cgDemoData(2), 0.153, 0.986)
cgLoadCT, 33, NColors=10, Bottom=1
levels = cgConLevels(data, Factor=0.05)
cgContour, data, Levels=levels, /Fill, /Outline, $
Position=[0.1, 0.1, 0.9, 0.75], C_Colors=Indgen(10)+1
cgColorbar, NColors=9, Bottom=1, /Discrete, /Fit, $
Range=[Min(levels), Max(levels)], OOB_High=10, OOB_Low='white'

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, 8 December 2011. David W. Fanning