>  Docs Center  >  Libraries  >  Coyote  >  CGHISTOGRAM

CGHISTOGRAM

CGHISTOGRAM
  This program is used as a wrapper to the Histogram command in IDL. It works around a bug
  in the Histogram command when byte data is binned in versions prior to IDL 8.2, and it takes
  care to match the data type of the `BinSize` keyword to the data type of the data being binned.
  If this matching is not done, Histogram silently returns incorrect results. I have added the ability to
  smooth the data (with the `Smooth` keyword) and to return the relative frequency of the histogram,
  rather than the histogram counts (with the `Frequency` keyword). The relative frequency is a
  number between 0 and 1. I have also added the ability to specify "missing" data that should not be
  binned.

Categories


    General
   

Params


    data: in, required,
      The data from which the histogram is created.
     

Keywords


    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, but the
      worst is that HISTOGRAM silently returns incorrect results. I try hard to avoid this
      result in this program.
    frequency: in, optional, type=boolean, default=0
      If this keyword is set, the relative frequency is returned, rather than the
      histogram counts. Relative frequency is a number between 0 and 1. The total of
      all the relative frequencies should equal 1.0.
    input: in, optional
      Set this keyword to a named variable that contains an array to be added to the
      output of cgHistogram. The density function of `data` is added to the existing
      contents of `Input` and returned as the result. The array is converted to
      longword type if necessary and must have at least as many elements as are
      required to form the histogram. Multiple histograms can be efficiently
      accumulated by specifying partial sums via this keyword.
    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. Set by default if 64-bit integers are passed in.
    locations: out, optional
      Starting locations of each bin. `Locations` has the same number of elements as the result,
      and has the same data type as the input data array.
    max: in, optional
      The maximum value to use in calculating input histogram.
    min: in, optional
      The minimum value to use in calculating input histogram.
    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. Set by default if the
      `Missing` keyword is used.
    nbins: in, optional, type=integer
      The number of output bins in the histogram. The meaning is slightly different from
      the meaning in the HISTOGRAM command. Used only to calculate BINSIZE when BINSIZE is
      not specified. In this case, binsize = rangeofData/(nbins-1). When the number of bins
      is low, the results can be non-intuitive. For this reason, I would discourage the use
      of `NBins` in favor of the `BinSize` keyword.
    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.)
    reverse_indices: out, optional
      The list of reverse indices returned from the HISTOGRAM command. (See HISTOGRAM documentation.)
    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. This keyword is ignored if the `Frequency` keyword is set.
         

Examples


    Create a normal distribution of random numbers and take the histogram::
   
      numbers = RandomU(-3L, 1000, /Normal)
      histResults = cgHistogram(numbers, Binsize=0.25)
      cgPlot, histResults
     
    Additional examples of histogram plots can be found here::
   
        http://www.idlcoyote.com/gallery/index.html
       

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, 7 March 2013.
       

Copyright


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



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us