[Go to first, previous, next page;   contents;   index]

Chapter 9

Histograms

This chapter describes the functions for creating and using histograms provided by the PLT Scheme Science Collection. Histograms provide a convenient way of summarizing the distribution of a set of data. A histogram contains a vector of bins that count the number of events falling into a given range. The bins of a histogram can be used to record both integer and non-integer distributions.

The ranges of the bins can be either continuous or discrete over a range. For continuous ranges, the width of these ranges can be either fixed or arbitrary. Also, for continuous ranges, both one and two dimensional histograms are supported.

9.1  1D Histograms

The 1D histogram functions described in this section are defined in the histogram.ss file in the science collection and are made available using the following form: 

(require (planet "histogram.ss" ("williams" "science.plt")))

histogram?

Function: 
(histogram? x)

Contract: 

(-> any? boolean?)

This function returns true, #t, if x is a histogram and false, #f otherwise.

9.1.1  Creating 1D Histograms

make-histogram

Function: 
(make-histogram n)

Contract: 

(-> (integer-in 1 +inf.0) histogram?)

This function returns a new, empty histogram with n bins and n + 1 range entries. The range entries must be set with a subsequent call to set-histogram-ranges! or set-histogram-ranges-uniform!.

make-histogram-with-ranges-uniform

Function: 
(make-histogram-with-ranges-uniform n x-min x-max)

Contract: 

(->r ((n (integer-in 1 +inf.0)
      (x-min real?)
      (x-max (>/c x-min)))
     histogram?)

This function returns a new, empty histogram with n bins. The n + 1 range entries are initialized to provide n uniform width bins from x-min to x-max.

9.1.2  Updating and Accessing 1D Histogram Elements

histogram-n

Function: 
(histogram-n h)

Contract: 

(-> histogram? (integer-in 1 +inf.0))

This function returns the number of bins in the histogram h.

histogram-ranges

Function: 
(histogram-ranges h)

Contract: 

(-> histogram? (vectorof real?))

This function returns the vector of ranges for the histogram h. The length of the vector is equal to the number of bins in h plus one.

set-histogram-ranges!

Function: 
(set-histogram-ranges! h ranges)

Contract: 

(-> histogram? (vectorof real?) void?)

This function sets the ranges for the histogram h according to the given ranges. The length of the ranges vector must be equal to the number of bins in h plus one. The bins in h are also reset.

set-histogram-ranges-uniform!

Function: 
(set-histogram-ranges-uniform! h x-min x-max)

Contract: 

(->r ((h histogram?)
      (x-min real?)
      (x-max (>/c x-min)))
     void?)

This function sets the ranges for the histogram h uniformly from x-min to x-max. The bins in h are also reset.

histogram-bins

Function: 
(histogram-bins h)

Contract: 

(-> histogram? (vectorof real?))

This functions returns the vector of bins for the histogram h.

histogram-increment!

Function: 
(histogram-increment! h x)

Contract: 

(-> histogram? real? void?)

This function increments the bin in the histogram h containing x. The bin value is incremented by one.

histogram-accumulate!

Function: 
(histogram-accumulate! h x weight)

Contract: 

(-> histogram? real (>-/c 0.0) void?)

This function increments the bin in the histogram h containing x by the specified weight.

histogram-get

Function: 
(histogram-get h i)

Contract: 

(-> histogram? natural-number? (>=/c 0.0))

This functions returns the contents of the ith bin of the histogram h.

histogram-get-range

Function: 
(histogram-get-range h i)

Contract: 

(-> histogram? natural-number? (values real? real?))

This function returns the upper and lower range limits for the ith bin of the histogram h. The upper and lower range limits are returned as multiple values.

9.1.3  1D Histogram Statistics

histogram-max

Function: 
(histogram-max h)

Contract: 

(-> histogram? (>=/c 0.0))

This function returns the maximum bin value in the histogram h. Since in this implementation bin values are non-negative, the maximum value is also non-negative.

histogram-min

Function: 
(histogram-min h)

Contract: 

(-> histogram? (>=/c 0.0))

This function returns the minimum bin value in the histogram h. Since in this implementation bin values are non-negative, the minimum value is also non-negative.

histogram-mean

Function: 
(histogram-mean h)

Contract: 

(-> histogram? (>=/c 0.0))

This function returns the mean of the data in the histogram h.

histogram-sigma

Function: 
(histogram-sigma h)

Contract: 

(-> histogram? (>=/c 0.0))

This function returns the standard deviation of the data in the histogram h.

histogram-sum

Function: 
(histogram-sum h)

Contract: 

(-> histogram? (>=/c 0.0))

This function returns the sum of the data in the histogram h.

9.1.4  1D Histogram Graphics

The histogram graphics functions are defined in the file histogram-graphics.ss in the science collection and are made available using the following form: 

(require (planet "histogram-graphics.ss" ("williams" "science.plt")))

histogram-plot

Function: 
(histogram-plot h title)
(histogram-plot h)

Contract: 

(case->
   (-> histogram? string? any)
   (-> histogram? any))

This function returns a plot of the histogram h with the specified title. If title is not specified, "Histogram" is used. The plot is scaled to the maximum bin value. The plot is produced by the histogram plotting extension to the plot collection provided with PLT Scheme (PLoT Scheme).

histogram-plot-scaled

Function: 
(histogram-plot-scaled h title)
(histogram-plot-scaled h)

Contract: 

(case->
   (-> histogram? string? any)
   (-> histogram? any))

This function returns a plot of the histogram h with the specified title. If title is not specified, "Histogram" is used. The plot is scaled to the sum of the bin values. It is most useful for a small number of bin - generally, ten or less. The plot is produced by the histogram plotting extension to the plot collection provided with PLT Scheme (PLoT Scheme).

9.1.5  Examples

Example: Plot of histogram of random variates from the unit Gaussian (normal) distribution. 

(require (planet "gaussian.ss" ("williams" "science.plt")
                 "random-distributions"))
(require (planet "histogram-with-graphics.ss"
                 ("williams" "science.plt")))

(let ((h (make-histogram-with-ranges-uniform 40 -3.0 3.0)))
  (do ((i 0 (+ i 1)))
      ((= i 10000) (void))
    (histogram-increment! h (random-unit-gaussian)))
  (histogram-plot h "Histogram of Unit Gaussian Distribution"))

Figure 62 shows the resulting histogram.

[histograms-Z-G-1.gif]
Figure 62:  Histogram of Random Variates from Unit Gaussian (Normal)

Example: Scaled plot of histogram of random variates from the exponential distribution with mean 1.0. 

(require (planet "exponential.ss" ("williams" "science.plt")
                 "random-distributions"))
(require (planet "histogram-with-graphics.ss"
                 ("williams" "science.plt")))

(let ((h (make-histogram-with-ranges-uniform 10 0.0 8.0)))
  (do ((i 0 (+ i 1)))
      ((= i 10000) (void))
    (histogram-increment! h (random-exponential 1.0)))
  (histogram-plot-scaled
    h "Scaled Histogram of Exponential Distribution"))

Figure 63 shows the resulting histogram.

[histograms-Z-G-2.gif]
Figure 63:  Scaled Histogram of Random Variates from Exponential (1.0))

9.2  2D Histograms

The 2D histogram functions described in this chapter are defined in the histogram-2d .ss file in the science collection and are made available using the following form: 

(require (planet "histogram-2d.ss" ("williams" "science.plt")))

histogram-2d?

Function: 
(histogram-2d? x)

Contract: 

(-> any? boolean?)

This function returns true, #t, if x is a 2D histogram and false, #f otherwise.

9.2.1  Creating 2D Histograms

make-histogram-2d

Function: 
(make-histogram-2d nx ny)

Contract: 

(-> (integer-in 1 +inf.0) (integer-in 1 +inf.0) histogram-2d?)

This function returns a new, empty 2D histogram with nx bins in the x direction and ny bins in the y direction and nx + 1 range entries in the x direction and ny + 1 range entries in the y direction. The range entries must be set with a subsequent call to set-histogram-2d-ranges! or set-histogram-2d-ranges-uniform!.

make-histogram-2d-with-ranges-uniform

Function: 
(make-histogram-2d-with-ranges-uniform
   nx ny x-min x-max y-min y-max)

Contract: 

(->r ((nx (integer-in 1 +inf.0))
      (ny (integer-in 1 +inf.0))
      (x-min real?)
      (x-max (>/c x-min))
      (y-min real?)
      (y-max (>/c y-min)))
     histogram-2d?)

This function returns a new, empty 2D histogram with nx bins in the x direction and ny bins in the y direction. The nx + 1 range entries in the x direction are initialized to provide nx uniform width bins from x-min to x-max. The ny + 1 range entries in the y direction are initialized to provide ny uniform width bins from y-min to y-max.

9.2.2  Updating and Accessing 2D Histogram Elements

histogram-2d-nx

Function: 
(histogram-2d-nx h)

Contract: 

(-> histogram-2d? (integer-in 1 +inf.0))

This function returns the number of bins in the x direction in the 2D histogram h.

histogram-2d-ny

Function: 
(histogram-2d-ny h)

Contract: 

(-> histogram-2d? (integer-in 1 +inf.0))

This function returns the number of bins in the y direction in the 2D histogram h.

histogram-2d-x-ranges

Function: 
(histogram-2d-x-ranges h)

Contract: 

(-> histogram-2d? (vectorof real?))

This function returns the vector of ranges in the x direction for the 2D histogram h. The length of the vector is equal to the number of bins in the x direction in h plus one.

histogram-2d-y-ranges

Function: 
(histogram-2d-y-ranges h)

Contract: 

(-> histogram-2d? (vectorof real?))

This function returns the vector of ranges in the y direction for the 2D histogram h. The length of the vector is equal to the number of bins in the y direction in h plus one.

set-histogram-2d-ranges!

Function: 
(set-histogram-2d-ranges! h x-ranges y-ranges)

Contract: 

(-> histogram-2d? (vectorof real?) (vectorof real?) void?)

This function sets the ranges for the 2D histogram h according to the given x-ranges and y-ranges. The length of the x-ranges vector must be equal to the number of bins in the x direction in h plus one. The length of the y-ranges vector must be equal to the number of bins in the y direction in h plus one. The bins in h are also reset.

set-histogram-2d-ranges-uniform!

Function: 
(set-histogram-2d-ranges-uniform! h x-min x-max y-min y-max)

Contract: 

(->r ((h histogram-2d?)
      (x-min real?)
      (x-max (>/c x-min))
      (y-min real?)
      (y-max (>/c y-max)))
     void?)

This function sets the ranges for the 2D histogram h uniformly from x-min to x-max in the x direction and uniformly from y-min to y-max in the y direction. The bins in h are also reset.

histogram-2d-bins

Function: 
(histogram-bins h)

Contract: 

(-> histogram-2d? (vectorof real?))

This functions returns the vector of bins for the 2D histogram h. The length of the vector is nx * ny. The (i, j)th index is computed as (i * ny) + j.

histogram-2d-increment!

Function: 
(histogram-increment! h x y)

Contract: 

(-> histogram-2d? real? real? void?)

This function increments the bin in the 2D histogram h containing (x, y). The bin value is incremented by one.

histogram-2d-accumulate!

Function: 
(histogram-2daccumulate! h x y weight)

Contract: 

(-> histogram-2d? real? real? (>-/c 0.0) void?)

This function increments the bin in the 2D histogram h containing (x, y) by the specified weight.

histogram-2d-get

Function: 
(histogram-2d-get h i j)

Contract: 

(-> histogram-2d? natural-number? natural-number? (>=/c 0.0))

This functions returns the contents of the (i, j)th bin of the 2D histogram h.

histogram-2d-get-x-range

Function: 
(histogram-2d-get-x-range h i j)

Contract: 

(-> histogram-2d? natural-number? natural-number?
    (values real? real?))

This function returns the upper and lower range limits in the x direction for the (i, j)th bin of the 2D histogram h. The upper and lower range limits are returned as multiple values.

histogram-2d-get-y-range

Function: 
(histogram-2d-get-y-range h i j)

Contract: 

(-> histogram-2d? natural-number? natural-number?
    (values real? real?))

This function returns the upper and lower range limits in the y direction for the (i, j)th bin of the 2D histogram h. The upper and lower range limits are returned as multiple values.

9.2.3  2D Histogram Statistics

histogram-2d-max

Function: 
(histogram-2d-max h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the maximum bin value in the 2D histogram h. Since in this implementation bin values are non-negative, the maximum value is also non-negative.

histogram-2d-min

Function: 
(histogram-2d-min h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the minimum bin value in the 2D histogram h. Since in this implementation bin values are non-negative, the minimum value is also non-negative.

histogram-2d-sum

Function: 
(histogram-2d-sum h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the sum of the data in the 2D histogram h.

histogram-2d-x-mean

Function: 
(histogram-2d-x-mean h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the mean in the x direction of the data in the 2D histogram h.

histogram-2d-y-mean

Function: 
(histogram-2d-y-mean h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the mean in the y direction of the data in the 2D histogram h.

histogram-2d-x-sigma

Function: 
(histogram-2d-x-sigma h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the standard deviation in the x direction of the data in the 2D histogram h.

histogram-2d-y-sigma

Function: 
(histogram-2d-y-sigma h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the standard deviation in the y direction of the data in the 2D histogram h.

histogram-2d-covariance

Function: 
(histogram-2d-covariance h)

Contract: 

(-> histogram-2d? (>=/c 0.0))

This function returns the covariance of the data in the 2D histogram h.

9.2.4  2D Histogram Graphics

The 2D histogram graphics functions are defined in the file histogram-2d-graphics.ss in the science collection and are made available using the following form: 

(require (planet "histogram-2d-graphics.ss"
                 ("williams" "science.plt" 2 0)))

histogram-2d-plot

Function: 
(histogram-2d-plot h title)
(histogram-2d-plot h)

Contract: 

(case->
   (-> histogram-2d? string? any)
   (-> histogram-2d? any))

This function returns a plot of the 2D histogram h with the specified title. If title is not specified, "Histogram" is used. The plot is scaled to the maximum bin value. The plot is produced by the 2D histogram plotting extension to the plot collection provided with PLT Scheme (PLoT Scheme).

9.2.5  Example

Example: Plot of 2D histogram of random variates from the bivariate Gaussian distribution standard deviations 1.0 and 1.0 in the x and y directions and correlation coefficient 0.0. 

(require (planet "bivariate-gaussian.ss" ("williams" "science.plt")
                 "random-distributions"))
(require (planet "histogram-2d-with-graphics.ss"
                 ("williams" "science.plt")))

(let ((h (make-histogram-2d-with-ranges-uniform
          20 20 -3.0 3.0 -3.0 3.0)))
  (do ((i 0 (+ i 1)))
      ((= i 10000) (void))
    (let-values (((x y) (random-bivariate-gaussian 1.0 1.0 0.0)))
      (histogram-2d-increment! h x y)))
  (histogram-2d-plot h "Histogram of Bivariate Gaussian Distribution"))

Figure 64 shows the resulting 2D histogram.

[histograms-Z-G-3.gif]
Figure 64:  Histogram of Random Variates from Bivariate Gaussian (1.0, 1.0, 0.0)

9.3  Discrete Histograms

The discrete histogram functions described in this section are defined in the discrete-histogram.ss file in the science collection and are made available using the following form: 

(require (planet "discrete-histogram.ss" ("williams" "science.plt")))

discrete-histogram?

Function: 
(discrete-histogram? x)

Contract: 

(-> any? boolean?)

This function returns true, #t, if x is a discrete histogram and false, #f otherwise.

9.3.1  Creating Discrete Histograms

make-discrete-histogram

Function: 
(make-discrete-histogram n1 n2 dynamic?)
(make-discrete-histogram n1 n2)
(make-discrete-histogram)

Contract: 

(case-> (->r ((n1 integer?)
              (n2 (and/c integer? (>=/c n1)))
              (dynamic? boolean?))
             discrete-histogram?)
        (->r ((n1 integer?)
              (n2 (and/c integer? (>=/c n1))))
             discrete-histogram?)
        (->r discrete-histogram?)))

This function returns a new, empty discrete histogram with range n1 to n2. If dymanic? is #t or make-discrete-histogram is called with no arguments, the resulting discrete histogram will grow dynamically to accomodate subsequent data points.

9.3.2  Updating and Accessing Discrete Histogram Elements

discrete-histogram-n1

Function: 
(discrete-histogram-n1 h)

Contract: 

(-> discrete-histogram? integer?)

This function returns the lower range of the discrete histogram h.

discrete-histogram-n2

Function: 
(discrete-histogram-n2 h)

Contract: 

(-> discrete-histogram? integer?)

This function returns the upper range of the discrete histogram h.

discrete-histogram-dynamic?

Function: 
(discrete-histogram-dynamic? h)

Contract: 

(-> discrete-histogram? boolean?)

This function returns #t if the discrete histogram h is dynamic and #f otherwise.

discrete-histogram-bins

Function: 
(discrete-histogram-bins h)

Contract: 

(-> discrete-histogram? (vectorof real?))

This functions returns the vector of bins for the discrete histogram h.

discrete-histogram-increment!

Function: 
(discrete-histogram-increment! h i)

Contract: 

(-> discrete-histogram? integer? void?)

This function increments the bin in the discrete histogram h containing i. The bin value is incremented by one.

discrete-histogram-accumulate!

Function: 
(discrete-histogram-accumulate! h i weight)

Contract: 

(-> discrete-histogram? integer? (>-/c 0.0) void?)

This function increments the bin in the discrete histogram h containing i by the specified weight.

discrete-histogram-get

Function: 
(discrete-histogram-get h i)

Contract: 

(-> discrete-histogram? integer? (>=/c 0.0))

This functions returns the contents of the bin of the discrete histogram h containing i.

9.3.3  Discrete Histogram Statistics

discrete-histogram-max

Function: 
(discrete-histogram-max h)

Contract: 

(-> discrete-histogram? (>=/c 0.0))

This function returns the maximum bin value in the discrete histogram h. Since in this implementation bin values are non-negative, the maximum value is also non-negative.

discrete-histogram-min

Function: 
(discrete-histogram-min h)

Contract: 

(-> discrete-histogram? (>=/c 0.0))

This function returns the minimum bin value in the discrete histogram h. Since in this implementation bin values are non-negative, the minimum value is also non-negative.

discrete-histogram-sum

Function: 
(discrete-histogram-sum h)

Contract: 

(-> discrete-histogram? (>=/c 0.0))

This function returns the sum of the data in the discrete histogram h.

9.3.4  Discrete Histogram Graphics

The discrete histogram graphics functions are defined in the file discrete-histogram-graphics.ss in the science collection and are made available using the following form: 

(require (planet "discrete-histogram-graphics.ss"
                 ("williams" "science.plt" 2 0)))

discrete-histogram-plot

Function: 
(discrete-histogram-plot h title)
(discrete-histogram-plot h)

Contract: 

(case->
   (-> discrete-histogram? string? any)
   (-> discrete-histogram? any))

This function returns a plot of the discrete histogram h with the specified title. If title is not specified, "Histogram" is used. The plot is scaled to the maximum bin value. The plot is produced by the discrete histogram plotting extension to the plot collection provided with PLT Scheme (PLoT Scheme).

discrete-histogram-plot-scaled

Function: 
(discrete-histogram-plot-scaled h title)
(discrete-histogram-plot-scaled h)

Contract: 

(case->
   (-> discrete-histogram? string? any)
   (-> discrete-histogram? any))

This function returns a plot of the discrete histogram h with the specified title. If title is not specified, "Histogram" is used. The plot is scaled to the sum of the bin values. It is most useful for a small number of bin - generally, ten or less. The plot is produced by the discrete histogram plotting extension to the plot collection provided with PLT Scheme (PLoT Scheme).

9.3.5  Examples

Example: Plot of discrete histogram of random variates from the Poisson distribution with mean 10.0. 

(require (planet "poisson.ss" ("williams" "science.plt")
                 "random-distributions"))
(require (planet "discrete-histogram-with-graphics.ss"
                 ("williams" "science.plt")))

(let ((h (make-discrete-histogram)))
  (do ((i 0 (+ i 1)))
      ((= i 10000) (void))
    (discrete-histogram-increment! h (random-poisson 10.0)))
  (discrete-histogram-plot h "Histogram of Poisson Distribution"))

Figure 65 shows the resulting histogram.

[histograms-Z-G-4.gif]
Figure 65:  Histogram of Random Variates from Poisson (10.0)

Example: Scaled plot of discrete histogram of random variates from the logarithmic distribution with probability 0.5. 

(require (planet "logarithmic.ss" ("williams" "science.plt")
                 "random-distributions"))
(require (planet "discrete-histogram-with-graphics.ss"
                 ("williams" "science.plt")))

(let ((h (make-discrete-histogram)))
  (do ((i 0 (+ i 1)))
      ((= i 10000) (void))
    (discrete-histogram-increment! h (random-logarithmic 0.5)))
  (discrete-histogram-plot-scaled
    h "Histogram of Logarithmic Distribution"))

Figure 66 shows the resulting histogram.

[histograms-Z-G-5.gif]
Figure 66:  Histogram of Random Variates from Logarithmic (0.5)

[Go to first, previous, next page;   contents;   index]