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 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.ss" file in the science collection and are made available using the form:
| (require (planet williams/science/histogram)) |
| (histogram? x) → boolean? |
| x : any/c |
Returns true, #t, if x is a histogram and false, #f, otherwise.
9.1.1 Creating Histograms
| (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!.
| |||||||||||||||||||||
| 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
| (histogram-n h) → exact-positive-integer? |
| h : histogram? |
Returns the number of bins in the histogram h.
| (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.
| (set-histogram-ranges! h ranges) → void? | ||||||||||
| h : histogram? | ||||||||||
|
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.
| |||||||||||||||||||||
| 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.
| (histogram-bins h) → (vectorof real?) |
| h : histogram? |
Returns the vector of bins for the histogram h.
Increments the bin in the histogram h containing x. The bin value is incremented by one.
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.
| (histogram-get h i) → (>=/c 0.0) | ||||||||
| h : histogram? | ||||||||
|
Returns the contents of the ith bin of the histogram h.
| ||||||||
| h : histogram? | ||||||||
|
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
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.
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.
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.
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.
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.ss" in the science collection and are made available using the following form:
| (require (planet williams/science/histogram-graphics)) |
| (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 PLT Scheme.
| (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 PLT Scheme.
9.1.5 Histogram Examples
Example: Histogram of random variates from the unit Gaussian (normal) distribution.
| #lang scheme |
| (require (planet williams/science/random-distributions/gaussian)) |
| (require (planet williams/science/histogram-with-graphics)) |
| (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 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 scheme |
| (require (planet williams/science/random-distributions/exponential)) |
| (require (planet williams/science/histogram-with-graphics)) |
| (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 "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.ss" file in the science collection and are made available using the form:
| (require (planet williams/science/histogram-2d)) |
| (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
| (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!.
| ||||||||||||||||||||||||||||||||||||||||||
| 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
| (histogram-nx h) → exact-positive-integer? |
| h : histogram-2d? |
Returns the number of bins in the x direction in the 2D histogram h.
| (histogram-ny h) → exact-positive-integer? |
| h : histogram-2d? |
Returns the number of bins in the y direction in the 2D histogram h.
| (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.
| (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.
| |||||||||||||||||||||
| h : histogram? | |||||||||||||||||||||
| |||||||||||||||||||||
|
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.
| |||||||||||||||||||||||||||||||||||
| 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.
| (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.
Increments the bin in the 2D histogram h containing (x, y). The bin value is incremented by one.
| (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.
| (histogram-2d-get h i j) → (>=/c 0.0) | ||||||||
| h : histogram? | ||||||||
| ||||||||
|
Returns the contents of the (i, j)th bin of the histogram h.
| ||||||||
| h : histogram? | ||||||||
| ||||||||
|
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.
| ||||||||
| h : histogram? | ||||||||
| ||||||||
|
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
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.
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.
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.
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.
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.
Returns the standard deviation of the data in the x direction in the 2D histogram h.
Returns the standard deviation of the data in the y direction in the 2D histogram h.
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 williams/science/histogram-2d-graphics)) |
| (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 PLT Scheme.
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 scheme |
| (require (planet williams/science/random-distributions/bivariate)) |
| (require (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))) |
| (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 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.ss" file in the science collection and are made available using the form:
| (require (planet williams/science/discrete-histogram)) |
| (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
| (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
| (discrete-histogram-n1 h) → integer? |
| h : discrete-histogram? |
Returns the lower range of the discrete histogram h.
| (discrete-histogram-n2 h) → integer? |
| h : discrete-histogram? |
Returns the upper range of the discrete histogram h.
| (discrete-histogram-dynamic? h) → boolean? |
| h : discrete-histogram? |
Returns true, #t, if the discrete histogram h is dynamic and false, #f, otherwise.
| (discrete-histogram-bins h) → (vectorof real?) |
| h : discrete-histogram? |
Returns the vector of bins for the discrete histogram h.
Increments the bin in the discrete histogram h containing i. The bin value is incremented by one.
| (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.
| (discrete-histogram-get h i) → (>=/c 0.0) | |||||||||
| h : discrete-histogram? | |||||||||
|
Returns the contents of the bin of the discrete histogram h containing i.
9.3.3 Discrete Histogram Statistics
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.
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.
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.
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.
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.ss" in the science collection and are made available using the following form:
| (require (planet williams/science/discrete-histogram-graphics)) |
| (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 PLT Scheme.
| (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 PLT Scheme.
9.3.5 Discrete Histogram Examples
Example: Discrete histogram of random variates from the Poisson distribution with mean 10.0.
| #lang scheme |
| (require (planet williams/science/random-distributions/poisson)) |
| (require (planet williams/science/discrete-histogram-with-graphics)) |
| (let ((h (make-discrete-histogram))) |
| (do ((i 0 (+ i 1))) |
| ((= i 10000) (void)) |
| (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 scheme |
| (require (planet williams/science/random-distributions/logarithmic)) |
| (require (planet williams/science/discrete-histogram-with-graphics)) |
| (let ((h (make-discrete-histogram))) |
| (do ((i 0 (+ i 1))) |
| ((= i 10000) (void)) |
| (discrete-histogram-increment! h (random-logarithmic 0.5))) |
| (histogram-plot h "Histogram of the Logarithmic Distribution")) |
The following figure shows the resulting histogram:
