9 Histograms

This chapter describes the functions for creating and using histograms provided by the 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 within a given range. The bins of a histogram can be used to record both integer and non-integer distributions.

The ranges 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 Histograms

The histogram functions described in this section are defined in the "histogram.rkt" file in the Science Collection and are made available using the form:

(require (planet williams/science/histogram))

procedure
(histogram? x) → boolean?
x : any/c

Returns true, #t, if x is a histogram and false, #f, otherwise.

9.1.1 Creating Histograms

procedure
(make-histogram n) → histogram?
n : exact-positive-integer?

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!.

procedure
(make-histogram-with-ranges-uniform n
x-min
x-max) → histogram?
  n : exact-positive-integer?
  x-min : real?
  x-max : (>/c x-min)

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 Histogram Elements

procedure
(histogram-n h) → exact-positive-integer?
h : histogram?

Returns the number of bins in the histogram h.

procedure
(histogram-ranges h) → (vectorof real?)
h : histogram?

Returns a vector of ranges for the histogram h. The length of the vector is equal to the number of bins in h plus one.

procedure
(set-histogram-ranges! h ranges) → void?
  h : histogram?
   ranges :
(and/c (vectorof real?)
       (lambda (x)
         (= (vector-length ranges)
            (+ (histogram-n h) 1))))

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

procedure
(set-histogram-ranges-uniform! h
x-min
x-max) → void?
  h : histogram?
  x-min : real?
  x-max : (>/c x-min)

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

procedure
(histogram-bins h) → (vectorof real?)
h : histogram?

Returns the vector of bins for the histogram h.

procedure
(histogram-increment! h x) → void?
  h : histogram?
  x : real?
(unchecked-histogram-increment! h x) → void?
  h : histogram?
  x : real?

Increments the bin in the histogram h containing x. The bin value is incremented by one.

procedure
(histogram-accumulate! h x weight) → void?
  h : histogram?
  x : real?
  weight : (>=/c 0.0)
(unchecked-histogram-accumulate! h x weight) → void?
  h : histogram?
  x : real?
  weight : (>=/c 0.0)

Increments the bin in the histogram h containing x by the specified weight. Since in this implementation bin values are non-megative, the weight must be non-negative.

procedure
(histogram-get h i) → (>=/c 0.0)
  h : histogram?
   i :
(and/c exact-nonnegative-integer?
       (</c (histogram-n h)))

Returns the contents of the ith bin of the histogram h.

procedure
(histogram-get-range h i) →
real? real?
  h : histogram?
   i :
(and/c exact-non-negative-integer?
       (</c (histogram-n h)))

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

9.1.3 Histogram Statistics

procedure
(histogram-max h) → (>=/c 0.0)
h : histogram?

Returns the maximum bin value for the histogram h. Since in this implementation bin values are non-negative, the maximum value is also non-negative.

procedure
(histogram-min h) → (>=/c 0.0)
h : histogram?

Returns the minimum bin value for the histogram h. Since in this implementation bin values are non-negative, the minimum value is also non-negative.

procedure
(histogram-sum h) → (>=/c 0.0)
h : histogram?

Returns the sum of the data in the histogram h. Since in this implementation bin values are non-negative, the sum is also non-negative.

procedure
(histogram-mean h) → (>=/c 0.0)
h : histogram?

Returns the mean of the data in the histogram h. Since in this implementation bin values are non-negative, the mean is also non-negative.

procedure
(histogram-sigma h) → (>=/c 0.0)
h : histogram?

Returns the standard deviation of the data in the histogram h.

9.1.4 Histogram Graphics

The histogram graphics functions are defined in the file "histogram-graphics.rkt" in the Science Collection and are made available using the following form:

(require (planet williams/science/histogram-graphics))

procedure
(histogram-plot h [title]) → any
h : histogram?
title : string? = "Histogram"

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 Racket.

procedure
(histogram-plot-scaled h [title]) → any
h : histogram?
title : string? = "Histogram"

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 bins—generally, twn or less. The plot is produced by the histogram plotting extension to the plot collection provided with Racket.

9.1.5 Histogram Examples

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

#lang racket
(require (planet williams/science/random-distributions/gaussian)
         (planet williams/science/histogram-with-graphics))

(let ((h (make-histogram-with-ranges-uniform 40 -3.0 3.0)))
  (for ((i (in-range 10000)))
    (histogram-increment! h (random-unit-gaussian)))
  (histogram-plot h "Histogram of the Unit Gaussian (Normal) Distribution"))

The following figure shows the resulting histogram:

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

#lang racket
(require (planet williams/science/random-distributions/exponential)
         (planet williams/science/histogram-with-graphics))

(let ((h (make-histogram-with-ranges-uniform 10 0.0 8.0)))
  (for ((i (in-range 10000)))
    (histogram-increment! h (random-exponential 1.0)))
  (histogram-plot-scaled h "Histogram of the Exponential Distribution"))

The following figure shows the resulting histogram:

9.2 2D Histograms

The 2D histogram functions described in this section are defined in the "histogram-2d.rkt" file in the Science Collection and are made available using the form:

(require (planet williams/science/histogram-2d))

procedure
(histogram-2d? x) → boolean?
x : any/c

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

9.2.1 Creating 2D Histograms

procedure
(make-histogram-2d nx ny) → histogram-2d?
nx : exact-positive-integer?
ny : exact-positive-integer?

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!.

procedure
(make-histogram-2d-with-ranges-uniform nx
xy
x-min
x-max
y-min
y-max) → histogram-2d?
  nx : exact-positive-integer?
  xy : exact-positive-integer?
  x-min : real?
  x-max : (>/c x-min)
  y-min : real?
  y-max : (>/c y-min)

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

procedure
(histogram-2d-nx h) → exact-positive-integer?
h : histogram-2d?

Returns the number of bins in the x direction in the 2D histogram h.

procedure
(histogram-2d-ny h) → exact-positive-integer?
h : histogram-2d?

Returns the number of bins in the y direction in the 2D histogram h.

procedure
(histogram-2d-x-ranges h) → (vectorof real?)
h : histogram-2d?

Returns a 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.

procedure
(histogram-2d-y-ranges h) → (vectorof real?)
h : histogram-2d?

Returns a 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.

procedure
(set-histogram-2d-ranges! h
x-ranges
y-ranges) → void?
  h : histogram?
   x-ranges :
(and/c (vectorof real?)
       (lambda (x)
         (= (vector-length x-ranges)
            (+ (histogram-2d-nx h) 1))))
   y-ranges :
(and/c (vectorof real?)
       (lambda (x)
         (= (vector-length y-ranges)
            (+ (histogram-2d-ny h) 1))))

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 equal the number of bins in the x direction in h plus one. The length of the y-ranges vector must equal the number of bins in the y direction in h plus one. The bins in h are also reset.

procedure
(set-histogram-2d-ranges-uniform! h
x-min
x-max
y-min
y-max) → void?
  h : histogram?
  x-min : real?
  x-max : (>/c x-min)
  y-min : real?
  y-max : (>/c y-min)

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.

procedure
(histogram-2d-bins h) → (vectorof real?)
h : histogram?

Returns the vector of bins for the 2D histogram h. The length of the vector is nx * ny, where nx is the number of bins in the x direction in h and ny is the number of bins in the y direction in h. The (i, j)th index is computed as (i * ny) + j.

procedure
(histogram-2d-increment! h x y) → void?
  h : histogram?
  x : real?
  y : real?
(unchecked-histogram-2d-increment! h x y) → void?
  h : histogram?
  x : real?
  y : real?

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

procedure
(histogram-2d-accumulate! h x y weight) → void?
  h : histogram?
  x : real?
  y : real?
  weight : (>=/c 0.0)
(unchecked-histogram-2d-accumulate! h
x
y
weight) → void?
  h : histogram?
  x : real?
  y : real?
  weight : (>=/c 0.0)

Increments the bin in the 2D histogram h containing (x, y) by the specified weight. Since in this implementation bin values are non-megative, the weight must be non-negative.

procedure
(histogram-2d-get h i j) → (>=/c 0.0)
  h : histogram?
   i :
(and/c exact-nonnegative-integer?
       (</c (histogram-nx h)))
   j :
(and/c exact-nonnegative-integer?
       (</c (histogram-ny h)))

Returns the contents of the (i, j)th bin of the histogram h.

procedure
(histogram-2d-get-x-range h i j) →
real? real?
  h : histogram?
   i :
(and/c exact-non-negative-integer?
       (</c (histogram-nx h)))
   j :
(and/c exact-non-negative-integer?
       (</c (histogram-ny h)))

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

procedure
(histogram-2d-get-y-range h i j) →
real? real?
  h : histogram?
   i :
(and/c exact-non-negative-integer?
       (</c (histogram-nx h)))
   j :
(and/c exact-non-negative-integer?
       (</c (histogram-ny h)))

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

9.2.3 2D Histogram Statistics

procedure
(histogram-2d-max h) → (>=/c 0.0)
h : histogram-2d?

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

procedure
(histogram-2d-min h) → (>=/c 0.0)
h : histogram-2d?

Returns the minimum bin value for the histogram h. Since in this implementation bin values are non-negative, the minimum value is also non-negative.

procedure
(histogram-2d-sum h) → (>=/c 0.0)
h : histogram-2d?

Returns the sum of the data in the 2D histogram h. Since in this implementation bin values are non-negative, the sum is also non-negative.

procedure
(histogram-2d-x-mean h) → (>=/c 0.0)
h : histogram-2d?

Returns the mean of the data in the x direction in the 2D histogram h. Since in this implementation bin values are non-negative, the mean is also non-negative.

procedure
(histogram-2d-y-mean h) → (>=/c 0.0)
h : histogram-2d?

Returns the mean of the data in the y direction in the 2D histogram h. Since in this implementation bin values are non-negative, the mean is also non-negative.

procedure
(histogram-2d-x-sigma h) → (>=/c 0.0)
h : histogram-2d?

Returns the standard deviation of the data in the x direction in the 2D histogram h.

procedure
(histogram-2d-y-sigma h) → (>=/c 0.0)
h : histogram-2d?

Returns the standard deviation of the data in the y direction in the 2D histogram h.

procedure
(histogram-2d-covariance h) → (>=/c 0.0)
h : histogram-2d?

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.rkt" in the Science Collection and are made available using the following form:

(require (planet williams/science/histogram-2d-graphics))

procedure
(histogram-2d-plot h [title]) → any
h : histogram-2d?
title : string? = "Histogram"

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 histogram plotting extension to the plot collection provided with Racket.

9.2.5 2D Histogram Examples

Example: 2D histogram of random variates from the bivariate Gaussian distribution with standard deviation 1.0 in both the x and y direction and correlation coefficient 0.0.

#lang racket
(require (planet williams/science/random-distributions/bivariate)
         (planet williams/science/histogram-2d-with-graphics))

(let ((h (make-histogram-2d-with-ranges-uniform
          20 20 -3.0 3.0 -3.0 3.0)))
  (for ((i (in-range 10000)))
    (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 the Bivariate Gaussian Distribution"))

The following figure shows the resulting histogram:

9.3 Discrete Histograms

The discrete histogram functions described in this section are defined in the "discrete-histogram.rkt" file in the Science Collection and are made available using the form:

(require (planet williams/science/discrete-histogram))

procedure
(discrete-histogram? x) → boolean?
x : any/c

Returns true, #t, if x is a discrete histogram and false, #f, otherwise.

9.3.1 Creating Discrete Histograms

procedure
(make-discrete-histogram n1 n2 [dynamic?]) → discrete-histogram?
  n1 : integer?
  n2 : (and/c integer? (>=/c n1))
  dynamic? : boolean = #t
(make-discrete-histogram) → discrete-histogram?

Returns a new, empty discrete histogram with range n1 to n2. If dynamic? 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

procedure
(discrete-histogram-n1 h) → integer?
h : discrete-histogram?

Returns the lower range of the discrete histogram h.

procedure
(discrete-histogram-n2 h) → integer?
h : discrete-histogram?

Returns the upper range of the discrete histogram h.

procedure
(discrete-histogram-dynamic? h) → boolean?
h : discrete-histogram?

Returns true, #t, if the discrete histogram h is dynamic and false, #f, otherwise.

procedure
(discrete-histogram-bins h) → (vectorof real?)
h : discrete-histogram?

Returns the vector of bins for the discrete histogram h.

procedure
(discrete-histogram-increment! h i) → void?
  h : discrete-histogram?
  i : integer?
(unchecked-discrete-histogram-increment! h
i) → void?
  h : discrete-histogram?
  i : integer?

Increments the bin in the discrete histogram h containing i. The bin value is incremented by one.

procedure
(discrete-histogram-accumulate! h i weight) → void?
  h : discrete-histogram?
  i : integer?
  weight : (>=/c 0.0)
(unchecked-discrete-histogram-accumulate! h
i
weight) → void?
  h : discrete-histogram?
  i : integer?
  weight : (>=/c 0.0)

Increments the bin in the discrete histogram h containing i by the specified weight. Since in this implementation bin values are non-megative, the weight must be non-negative.

procedure
(discrete-histogram-get h i) → (>=/c 0.0)
  h : discrete-histogram?
   i :
(and/c integer?
       (>=/c (discrete-histogram-n1 h))
       (<=/c (discrete-histogram-n2 h)))

Returns the contents of the bin of the discrete histogram h containing i.

9.3.3 Discrete Histogram Statistics

procedure
(discrete-histogram-max h) → (>=/c 0.0)
h : discrete-histogram?

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

procedure
(discrete-histogram-min h) → (>=/c 0.0)
h : discrete-histogram?

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

procedure
(discrete-histogram-sum h) → (>=/c 0.0)
h : discrete-histogram?

Returns the sum of the data in the discrete histogram h. Since in this implementation bin values are non-negative, the sum is also non-negative.

procedure
(discrete-histogram-mean h) → (>=/c 0.0)
h : discrete-histogram?

Returns the mean of the data in the discrete histogram h. Since in this implementation bin values are non-negative, the mean is also non-negative.

procedure
(discrete-histogram-sigma h) → (>=/c 0.0)
h : discrete-histogram?

Returns the standard deviation 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.rkt" in the Science Collection and are made available using the following form:

(require (planet williams/science/discrete-histogram-graphics))

procedure
(discrete-histogram-plot h [title]) → any
h : discrete-histogram?
title : string? = "Histogram"

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 histogram plotting extension to the plot collection provided with Racket.

procedure
(discrete-histogram-plot-scaled h [title]) → any
h : discrete-histogram?
title : string? = "Histogram"

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 bins—generally, twn or less. The plot is produced by the histogram plotting extension to the plot collection provided with Racket.

9.3.5 Discrete Histogram Examples

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

#lang racket
(require (planet williams/science/random-distributions/poisson)
         (planet williams/science/discrete-histogram-with-graphics))

(let ((h (make-discrete-histogram)))
  (for ((i (in-range 10000)))
    (discrete-histogram-increment! h (random-poisson 10.0)))
  (histogram-plot h "Histogram of the Poisson Distribution"))

The following figure shows the resulting histogram:

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

#lang racket
(require (planet williams/science/random-distributions/logarithmic)
         (planet williams/science/discrete-histogram-with-graphics))

(let ((h (make-discrete-histogram)))
  (for ((i (in-range 10000)))
    (discrete-histogram-increment! h (random-logarithmic 0.5)))
  (discrete-histogram-plot-scaled
   h "Histogram of the Logarithmic Distribution"))

The following figure shows the resulting histogram:

← prev up next →

1	Introduction
2	Using the Science Collection
3	Error Handling
4	Mathematical Functions
5	Special Functions
6	Random Number Generation
7	Random Number Distributions
8	Statistics
9	Histograms
10	Ordinary Differential Equations
11	Chebyshev Approximations
12	Fast Fourier Transforms
13	Physical Constants
14	Unsafe Operations Utilities
15	GNU Free Documentation License
	Bibliography
	Index