# coyote: CGCONLEVELS

- coyote/Graphics
- coyote/Utilities
- [Source code]

Description

      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.
      The program requires the `Coyote Library <http://www.idlcoyote.com/documents/programs.php>`
      to be installed on your machine.

Categories

      Graphics, Utilities

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 = cgScaleVector(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 = cgScaleVector(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 = cgScaleVector(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 = cgScaleVector(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

Copyright

      Copyright (c) 2011, Fanning Software Consulting, Inc.