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 noninteger 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")))
Function:
(histogram? x) 
Contract: (> any? boolean?) 

9.1.1 Creating 1D Histograms
Function:
(makehistogram n) 
Contract: (> (integerin 1 +inf.0) histogram?) 

makehistogramwithrangesuniform
Function:
(makehistogramwithrangesuniform n xmin xmax) 
Contract: (>r ((n (integerin 1 +inf.0) (xmin real?) (xmax (>/c xmin))) histogram?) 

9.1.2 Updating and Accessing 1D Histogram Elements
Function:
(histogramn h) 
Contract: (> histogram? (integerin 1 +inf.0)) 

Function:
(histogramranges h) 
Contract: (> histogram? (vectorof real?)) 

Function:
(sethistogramranges! h ranges) 
Contract: (> histogram? (vectorof real?) void?) 

Function:
(sethistogramrangesuniform! h xmin xmax) 
Contract: (>r ((h histogram?) (xmin real?) (xmax (>/c xmin))) void?) 

Function:
(histogrambins h) 
Contract: (> histogram? (vectorof real?)) 

Function:
(histogramincrement! h x) 
Contract: (> histogram? real? void?) 

Function:
(histogramaccumulate! h x weight) 
Contract: (> histogram? real (>/c 0.0) void?) 

Function:
(histogramget h i) 
Contract: (> histogram? naturalnumber? (>=/c 0.0)) 

Function:
(histogramgetrange h i) 
Contract: (> histogram? naturalnumber? (values real? real?)) 

9.1.3 1D Histogram Statistics
Function:
(histogrammax h) 
Contract: (> histogram? (>=/c 0.0)) 

Function:
(histogrammin h) 
Contract: (> histogram? (>=/c 0.0)) 

Function:
(histogrammean h) 
Contract: (> histogram? (>=/c 0.0)) 

Function:
(histogramsigma h) 
Contract: (> histogram? (>=/c 0.0)) 

Function:
(histogramsum h) 
Contract: (> histogram? (>=/c 0.0)) 

9.1.4 1D Histogram Graphics
The histogram graphics functions are defined in the file histogramgraphics.ss in the science collection and are made available using the following form:
(require (planet "histogramgraphics.ss" ("williams" "science.plt")))
Function:
(histogramplot h title) (histogramplot h) 
Contract: (case> (> histogram? string? any) (> histogram? any)) 

Function:
(histogramplotscaled h title) (histogramplotscaled h) 
Contract: (case> (> histogram? string? any) (> histogram? any)) 

9.1.5 Examples
Example: Plot of histogram of random variates from the unit Gaussian (normal) distribution.
(require (planet "gaussian.ss" ("williams" "science.plt") "randomdistributions")) (require (planet "histogramwithgraphics.ss" ("williams" "science.plt"))) (let ((h (makehistogramwithrangesuniform 40 3.0 3.0))) (do ((i 0 (+ i 1))) ((= i 10000) (void)) (histogramincrement! h (randomunitgaussian))) (histogramplot h "Histogram of Unit Gaussian Distribution"))
Figure 62 shows the resulting histogram.

Example: Scaled plot of histogram of random variates from the exponential distribution with mean 1.0.
(require (planet "exponential.ss" ("williams" "science.plt") "randomdistributions")) (require (planet "histogramwithgraphics.ss" ("williams" "science.plt"))) (let ((h (makehistogramwithrangesuniform 10 0.0 8.0))) (do ((i 0 (+ i 1))) ((= i 10000) (void)) (histogramincrement! h (randomexponential 1.0))) (histogramplotscaled h "Scaled Histogram of Exponential Distribution"))
Figure 63 shows the resulting histogram.

9.2 2D Histograms
The 2D histogram functions described in this chapter are defined in the histogram2d .ss file in the science collection and are made available using the following form:
(require (planet "histogram2d.ss" ("williams" "science.plt")))
Function:
(histogram2d? x) 
Contract: (> any? boolean?) 

9.2.1 Creating 2D Histograms
Function:
(makehistogram2d nx ny) 
Contract: (> (integerin 1 +inf.0) (integerin 1 +inf.0) histogram2d?) 

makehistogram2dwithrangesuniform
Function:
(makehistogram2dwithrangesuniform nx ny xmin xmax ymin ymax) 
Contract: (>r ((nx (integerin 1 +inf.0)) (ny (integerin 1 +inf.0)) (xmin real?) (xmax (>/c xmin)) (ymin real?) (ymax (>/c ymin))) histogram2d?) 

9.2.2 Updating and Accessing 2D Histogram Elements
Function:
(histogram2dnx h) 
Contract: (> histogram2d? (integerin 1 +inf.0)) 

Function:
(histogram2dny h) 
Contract: (> histogram2d? (integerin 1 +inf.0)) 

Function:
(histogram2dxranges h) 
Contract: (> histogram2d? (vectorof real?)) 

Function:
(histogram2dyranges h) 
Contract: (> histogram2d? (vectorof real?)) 

Function:
(sethistogram2dranges! h xranges yranges) 
Contract: (> histogram2d? (vectorof real?) (vectorof real?) void?) 

sethistogram2drangesuniform!
Function:
(sethistogram2drangesuniform! h xmin xmax ymin ymax) 
Contract: (>r ((h histogram2d?) (xmin real?) (xmax (>/c xmin)) (ymin real?) (ymax (>/c ymax))) void?) 

Function:
(histogrambins h) 
Contract: (> histogram2d? (vectorof real?)) 

Function:
(histogramincrement! h x y) 
Contract: (> histogram2d? real? real? void?) 

Function:
(histogram2daccumulate! h x y weight) 
Contract: (> histogram2d? real? real? (>/c 0.0) void?) 

Function:
(histogram2dget h i j) 
Contract: (> histogram2d? naturalnumber? naturalnumber? (>=/c 0.0)) 

Function:
(histogram2dgetxrange h i j) 
Contract: (> histogram2d? naturalnumber? naturalnumber? (values real? real?)) 

Function:
(histogram2dgetyrange h i j) 
Contract: (> histogram2d? naturalnumber? naturalnumber? (values real? real?)) 

9.2.3 2D Histogram Statistics
Function:
(histogram2dmax h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dmin h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dsum h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dxmean h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dymean h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dxsigma h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dysigma h) 
Contract: (> histogram2d? (>=/c 0.0)) 

Function:
(histogram2dcovariance h) 
Contract: (> histogram2d? (>=/c 0.0)) 

9.2.4 2D Histogram Graphics
The 2D histogram graphics functions are defined in the file histogram2dgraphics.ss in the science collection and are made available using the following form:
(require (planet "histogram2dgraphics.ss" ("williams" "science.plt" 2 0)))
Function:
(histogram2dplot h title) (histogram2dplot h) 
Contract: (case> (> histogram2d? string? any) (> histogram2d? any)) 

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 "bivariategaussian.ss" ("williams" "science.plt") "randomdistributions")) (require (planet "histogram2dwithgraphics.ss" ("williams" "science.plt"))) (let ((h (makehistogram2dwithrangesuniform 20 20 3.0 3.0 3.0 3.0))) (do ((i 0 (+ i 1))) ((= i 10000) (void)) (letvalues (((x y) (randombivariategaussian 1.0 1.0 0.0))) (histogram2dincrement! h x y))) (histogram2dplot h "Histogram of Bivariate Gaussian Distribution"))
Figure 64 shows the resulting 2D histogram.

9.3 Discrete Histograms
The discrete histogram functions described in this section are defined in the discretehistogram.ss file in the science collection and are made available using the following form:
(require (planet "discretehistogram.ss" ("williams" "science.plt")))
Function:
(discretehistogram? x) 
Contract: (> any? boolean?) 

9.3.1 Creating Discrete Histograms
Function:
(makediscretehistogram n1 n2 dynamic?) (makediscretehistogram n1 n2) (makediscretehistogram) 
Contract: (case> (>r ((n1 integer?) (n2 (and/c integer? (>=/c n1))) (dynamic? boolean?)) discretehistogram?) (>r ((n1 integer?) (n2 (and/c integer? (>=/c n1)))) discretehistogram?) (>r discretehistogram?))) 

9.3.2 Updating and Accessing Discrete Histogram Elements
Function:
(discretehistogramn1 h) 
Contract: (> discretehistogram? integer?) 

Function:
(discretehistogramn2 h) 
Contract: (> discretehistogram? integer?) 

Function:
(discretehistogramdynamic? h) 
Contract: (> discretehistogram? boolean?) 

Function:
(discretehistogrambins h) 
Contract: (> discretehistogram? (vectorof real?)) 

Function:
(discretehistogramincrement! h i) 
Contract: (> discretehistogram? integer? void?) 

discretehistogramaccumulate!
Function:
(discretehistogramaccumulate! h i weight) 
Contract: (> discretehistogram? integer? (>/c 0.0) void?) 

Function:
(discretehistogramget h i) 
Contract: (> discretehistogram? integer? (>=/c 0.0)) 

9.3.3 Discrete Histogram Statistics
Function:
(discretehistogrammax h) 
Contract: (> discretehistogram? (>=/c 0.0)) 

Function:
(discretehistogrammin h) 
Contract: (> discretehistogram? (>=/c 0.0)) 

Function:
(discretehistogramsum h) 
Contract: (> discretehistogram? (>=/c 0.0)) 

9.3.4 Discrete Histogram Graphics
The discrete histogram graphics functions are defined in the file discretehistogramgraphics.ss in the science collection and are made available using the following form:
(require (planet "discretehistogramgraphics.ss" ("williams" "science.plt" 2 0)))
Function:
(discretehistogramplot h title) (discretehistogramplot h) 
Contract: (case> (> discretehistogram? string? any) (> discretehistogram? any)) 

discretehistogramplotscaled
Function:
(discretehistogramplotscaled h title) (discretehistogramplotscaled h) 
Contract: (case> (> discretehistogram? string? any) (> discretehistogram? any)) 

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") "randomdistributions")) (require (planet "discretehistogramwithgraphics.ss" ("williams" "science.plt"))) (let ((h (makediscretehistogram))) (do ((i 0 (+ i 1))) ((= i 10000) (void)) (discretehistogramincrement! h (randompoisson 10.0))) (discretehistogramplot h "Histogram of Poisson Distribution"))
Figure 65 shows the resulting histogram.

Example: Scaled plot of discrete histogram of random variates from the logarithmic distribution with probability 0.5.
(require (planet "logarithmic.ss" ("williams" "science.plt") "randomdistributions")) (require (planet "discretehistogramwithgraphics.ss" ("williams" "science.plt"))) (let ((h (makediscretehistogram))) (do ((i 0 (+ i 1))) ((= i 10000) (void)) (discretehistogramincrement! h (randomlogarithmic 0.5))) (discretehistogramplotscaled h "Histogram of Logarithmic Distribution"))
Figure 66 shows the resulting histogram.
