SSJ  3.2.1
Stochastic Simulation in Java
Public Member Functions | List of all members
DEHistogram Class Reference

Histogram density estimator for a univariate density. More...

Inheritance diagram for DEHistogram:
[legend]
Collaboration diagram for DEHistogram:
[legend]

Public Member Functions

 DEHistogram (int numBins)
 Constructor for a histogram estimator with numBins bins. More...
 
ScaledHistogram getScaledHistogram ()
 Returns the underlying ScaledHistogram. More...
 
int getNumBins ()
 Gives the number of bins \(s\). More...
 
void setNumBins (int numBins)
 Sets the number of bins to numBins. More...
 
double getH ()
 Gives the bin width \(h\). More...
 
void setH (double h)
 Sets the bin width to h. More...
 
double getA ()
 Gives the left boundary \(a\) of the histogram. More...
 
double getB ()
 Gives the right boundary \(b\) of the histogram. More...
 
void constructDensity (double[] data, double a, double b)
 
void constructDensity (TallyHistogram tallyHist)
 Constructs a histogram from a umontreal.ssj.stat.TallyHistogram tallyHist. More...
 
void constructDensity (ScaledHistogram scaledHist)
 Constructs a histogram from a umontreal.ssj.stat.ScaledHistogram scaledHist. More...
 
String toString ()
 
double evalDensity (double x, double[] data, double a, double b)
 
double [] evalDensity (double[] evalPoints, double[] data, double a, double b)
 Constructs a histogram density estimator over the interval \([a,b]\) based on the observations data and evaluates it at the points in evalPoints. More...
 
double [] evalDensity (double[] data, double a, double b)
 Constructs a histogram density estimator over the interval \([a,b]\) based on the observations data and evaluates it at one point in each bin. More...
 
double [][] evalDensity (double[][] data, double a, double b)
 Same as umontreal.ssj.stat.density.DensityEstimator::evalDensity(double[], double[][], double, double) but with one evaluation point per bin. More...
 
double evalDensity (double x, TallyHistogram tallyHist)
 Constructs a histogram estimator from tallyHist and evaluates it at x. More...
 
double [] evalDensity (TallyHistogram tallyHist)
 Constructs a histogram density estimator from tallyHist and evaluates it at one point in each bin. More...
 
double [] evalDensity (double[] evalPoints, TallyHistogram tallyHist)
 Constructs a histogram estimator from tallyHist and evaluates it at each evaluation point in evalPoints. More...
 
double [][] evalDensity (TallyHistogram[] tallyHistArray)
 Same as evalDensity(double[][], double, double) but here, each realization of the histogram is constructed from a umontreal.ssj.stat.TallyHistogram. More...
 
double evalDensity (double x, ScaledHistogram scaledHist)
 Constructs a histogram estimator from scaledHist and evaluates it at x. More...
 
double [] evalDensity (ScaledHistogram scaledHist)
 Constructs a histogram density estimator from scaledHist and evaluates it at one point in each bin. More...
 
double [] evalDensity (double[] evalPoints, ScaledHistogram scaledHist)
 Constructs a histogram estimator from scaledHist and evaluates it at each evaluation point in evalPoints. More...
 
double [][] evalDensity (ScaledHistogram[] scaledHistArray)
 Same as evalDensity(double[][], double, double) but here, each realization of the histogram is constructed from a umontreal.ssj.stat.ScaledHistogram. More...
 
- Public Member Functions inherited from DensityEstimator
abstract double evalDensity (double x, double data[], double a, double b)
 Constructs a density estimator over the interval \([a,b]\) based on the observations data if necessary, and evaluates it at x. More...
 
double [] evalDensity (double[] evalPoints, double[] data, double a, double b)
 Constructs a density estimator over the interval \([a,b]\) based on the observations data if necessary, and evaluates it at the points in evalPoints. More...
 
double [][] evalDensity (double[] evalPoints, double[][] data, double a, double b)
 This method is particularly designed to evaluate the density estimator in such a way that the result can be easily used to estimate the empirical IV and other convergence-related quantities. More...
 
abstract String toString ()
 Gives a short description of the estimator. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from DensityEstimator
static void evalDensity (ArrayList< DensityEstimator > listDE, double[] evalPoints, double[][] data, double a, double b, ArrayList< double[][]> listDensity)
 This function is particularly designed for experiments with many different types of density estimators, as it evaluates all of these estimators at the points in evalPoints. More...
 
static double [] computeVariance (double[][] density)
 This method computes the empirical variance based on the values given in data. More...
 
static double computeIV (double[][] density, double a, double b, double[] variance)
 This method estimates the empirical IV over the interval \([a,b]\). More...
 
static void computeIV (ArrayList< double[][]> listDensity, double a, double b, ArrayList< Double > listIV)
 This method estimates the empirical IV over the interval \([a,b]\) for a collection of different estimators. More...
 
static double [] computeMISE (ContinuousDistribution dist, double[] evalPoints, double[][] density, double a, double b, double[] variance, double[] sqBias, double[] mse)
 In situations where the true density is known this method can estimate the empirical MISE over the interval \([a,b]\). More...
 
static void computeMISE (ContinuousDistribution dist, double[] evalPoints, ArrayList< double[][]> listDensity, double a, double b, ArrayList< double[]> listMISE)
 This method estimates the empirical MISE over the interval \([a,b]\) for a collection of different estimators. More...
 
static String plotDensity (double[] evalPoints, double[] density, String plotTitle, String[] axisTitles)
 Gives a plot of the estimated density. More...
 
static double roughnessFunctional (double[] density, double a, double b)
 Estimates the roughness functional. More...
 
- Static Protected Member Functions inherited from DensityEstimator
static double coefficientOfDetermination (double[] data, double[] dataEstimated)
 Computes the Coefficient of determination \(R^2\) of the observed data data and the estimated data dataEstimated. More...
 
- Protected Attributes inherited from DensityEstimator
double [] data
 The data associated with this DensityEstimator object, if any.
 

Detailed Description

Histogram density estimator for a univariate density.

This class provides methods to construct, manipulate, and evaluate a histogram from a set of \(n\) real-valued observations \(x_0,\dots, x_{n-1}\). The constructor of a DEHistogram object takes the data, a finite interval \([a,b]\) over which we want the histogram, and the number of bins (intervals), and it constructs the histogram as a density estimator over this interval. For that, it computes the number of observations in each bin and rescale the heights of the bins so that the total area of the histogram is equal to the proportion of the observations that fall into the interval \([a,b]\). When all the observations are in \([a,b]\), then this area should be 1. The density estimator is represented internally as a umontreal.ssj.stat.ScaledHistogram, which can be recovered by the getScaledHistogram() method.

Remarks
: What if some observations are outside the interval?
Then the surface of the histogram over the interval [a,b] should be less than 1. Is this what we do?

More specifically, if we ask for \(s\) bins over the interval \([a,b]\), then the interval is partitioned over \(s\) intervals of equal lengths \(h=(b-a)/s\), and the density estimator is defined by

\[ \hat{f}_{n}(x) = \hat{f}_{n,h}(x) = \frac{n_j}{nh}, \quad\text{ for } x\in[a+(j-1)h, a+jh), \qquad j=1,\dots,s. \]

where \(n_j\) denotes the number of observations that fall in interval \(j\). Observe that changing \([a,b]\), \(h\), or \(s\) changes the structure of the histogram completely. Thus, after altering any of these parameters the histogram needs to be constructed afresh.

The constructor can take as input an array that contains the raw data, together with the parameters \(a, b, s\). It can also take a umontreal.ssj.stat.TallyHistogram or a umontreal.ssj.stat.ScaledHistogram instead.


??? As histograms are constant within one bin, certain quantities such as the variance are not affected by shifting an evaluation point within its bin. Hence, selecting one evaluation point per bin is sufficient for such methods.

Remarks
: This is not clear!!! To this end, this class provides methods to evaluate the density estimator once in each bin, without having to explicitly specify an array of evaluation points.

It needs to be added that, due to the fact that the partition into \(s\) bins relies on half-open intervals, the boundary \(b\) is not included in any of these intervals. Since the probability of an observation being exactly equal to \(b\) is zero, we can effectively ignore this subtlety.

Author
puchhamf

Constructor & Destructor Documentation

◆ DEHistogram()

DEHistogram ( int  numBins)

Constructor for a histogram estimator with numBins bins.

Parameters
numBinsthe number of bins.

Member Function Documentation

◆ constructDensity() [1/3]

void constructDensity ( double []  data,
double  a,
double  b 
)
Remarks
: this must be the constructor!!! Constructs a histogram over the interval \([a,b]\) from the observations passed in data. The number of bins is taken as the value of getNumBins(). Note that the individual observations are not being stored.
Parameters
datathe observations from the underlying model.
athe left boundary of the histogram.
bthe right boundary of the histogram

◆ constructDensity() [2/3]

void constructDensity ( TallyHistogram  tallyHist)

Constructs a histogram from a umontreal.ssj.stat.TallyHistogram tallyHist.

The method extracts all defining parameters such as the number of bins, the endpoints, etc. from tallyHist directly.

Parameters
tallyHista umontreal.ssj.stat.TallyHistogram from which the estimator is constructed.

◆ constructDensity() [3/3]

void constructDensity ( ScaledHistogram  scaledHist)

Constructs a histogram from a umontreal.ssj.stat.ScaledHistogram scaledHist.

The method extracts all defining parameters such as the number of bins, the endpoints, etc. from scaledHist directly.

Parameters
scaledHista umontreal.ssj.stat.ScaledHistogram from which the estimator is constructed.

◆ evalDensity() [1/11]

double [] evalDensity ( double []  evalPoints,
double []  data,
double  a,
double  b 
)

Constructs a histogram density estimator over the interval \([a,b]\) based on the observations data and evaluates it at the points in evalPoints.

Parameters
evalPointsthe evaluation points.
datathe observations for constructing the histogram.
athe left boundary of the interval.
bthe right boundary of the interval
Returns
the histogram density estimator evaluated at the points x.

◆ evalDensity() [2/11]

double [] evalDensity ( double []  data,
double  a,
double  b 
)

Constructs a histogram density estimator over the interval \([a,b]\) based on the observations data and evaluates it at one point in each bin.

Since the histogram is constant within its bins, it is of no concern for this method, which evaluation point is actually selected in each bin.

Parameters
datathe observations for constructing the histogram.
athe left boundary of the interval.
bthe right boundary of the interval
Returns
the histogram density estimator evaluated at the points x.

◆ evalDensity() [3/11]

double [][] evalDensity ( double  data[][],
double  a,
double  b 
)

Same as umontreal.ssj.stat.density.DensityEstimator::evalDensity(double[], double[][], double, double) but with one evaluation point per bin.

Since the histogram is constant within its bins, it is of no concern for this method, which evaluation point is actually selected in each bin.

Parameters
datathe two-dimensional array carrying the observations of \(m\) independent realizations of the underlying model.
athe left boundary of the interval.
bthe right boundary of the interval.
Returns
the histogram density estimator for each realization evaluated once in each bin.

◆ evalDensity() [4/11]

double evalDensity ( double  x,
TallyHistogram  tallyHist 
)

Constructs a histogram estimator from tallyHist and evaluates it at x.

Parameters
xthe evaluation point.
tallyHistthe umontreal.ssj.stat.TallyHistogram from which the estimator is constructed.
Returns
the histogram density estimator evaluated at x.

◆ evalDensity() [5/11]

double [] evalDensity ( TallyHistogram  tallyHist)

Constructs a histogram density estimator from tallyHist and evaluates it at one point in each bin.

Since the histogram is constant within its bins, it is of no concern for this method, which evaluation point is actually selected in each bin.

Parameters
tallyHistthe umontreal.ssj.stat.TallyHistogram from which the estimator is constructed.
Returns
the histogram density estimator evaluated once in each bin.

◆ evalDensity() [6/11]

double [] evalDensity ( double []  evalPoints,
TallyHistogram  tallyHist 
)

Constructs a histogram estimator from tallyHist and evaluates it at each evaluation point in evalPoints.

Parameters
evalPointsthe evaluation points.
tallyHistthe umontreal.ssj.stat.TallyHistogram from which the estimator is constructed.
Returns
the histogram density estimator evaluated at evalPoints.

◆ evalDensity() [7/11]

double [][] evalDensity ( TallyHistogram []  tallyHistArray)

Same as evalDensity(double[][], double, double) but here, each realization of the histogram is constructed from a umontreal.ssj.stat.TallyHistogram.

Parameters
tallyHistArraythe array of umontreal.ssj.stat.TallyHistogram from which the realizations of the estimator is constructed.
Returns
the histogram density estimator for each realization evaluated once in each bin.

◆ evalDensity() [8/11]

double evalDensity ( double  x,
ScaledHistogram  scaledHist 
)

Constructs a histogram estimator from scaledHist and evaluates it at x.

Parameters
xthe evaluation point.
scaledHistthe umontreal.ssj.stat.ScaledHistogram from which the estimator is constructed.
Returns
the histogram density estimator evaluated at x.

◆ evalDensity() [9/11]

double [] evalDensity ( ScaledHistogram  scaledHist)

Constructs a histogram density estimator from scaledHist and evaluates it at one point in each bin.

Since the histogram is constant within its bins, it is of no concern for this method, which evaluation point is actually selected in each bin.

Parameters
scaledHistthe umontreal.ssj.stat.ScaledHistogram from which the estimator is constructed.
Returns
the histogram density estimator evaluated once in each bin.

◆ evalDensity() [10/11]

double [] evalDensity ( double []  evalPoints,
ScaledHistogram  scaledHist 
)

Constructs a histogram estimator from scaledHist and evaluates it at each evaluation point in evalPoints.

Parameters
evalPointsthe evaluation points.
scaledHistthe umontreal.ssj.stat.ScaledHistogram from which the estimator is constructed.
Returns
the histogram density estimator evaluated at evalPoints.

◆ evalDensity() [11/11]

double [][] evalDensity ( ScaledHistogram []  scaledHistArray)

Same as evalDensity(double[][], double, double) but here, each realization of the histogram is constructed from a umontreal.ssj.stat.ScaledHistogram.

Parameters
scaledHistArraythe array of umontreal.ssj.stat.ScaledHistogram from which the realizations of the estimator is constructed.
Returns
the histogram density estimator for each realization evaluated once in each bin.

◆ getA()

double getA ( )

Gives the left boundary \(a\) of the histogram.

Returns
the left boundary of the histogram.

◆ getB()

double getB ( )

Gives the right boundary \(b\) of the histogram.

Returns
the right boundary of the histogram.

◆ getH()

double getH ( )

Gives the bin width \(h\).

Returns
the desired bin width.

◆ getNumBins()

int getNumBins ( )

Gives the number of bins \(s\).

Returns
the number of bins.

◆ getScaledHistogram()

ScaledHistogram getScaledHistogram ( )

Returns the underlying ScaledHistogram.

Returns
underlying ScaledHistogram object.

◆ setH()

void setH ( double  h)

Sets the bin width to h.

The actual value used may differ from the one being passed since numBins \(=(b-a)/h\) has to be an integer. Note that setting the bin width is only meaningful if the entire histogram will be reconstructed.

Parameters
hthe desired bin width.

◆ setNumBins()

void setNumBins ( int  numBins)

Sets the number of bins to numBins.

Note that this is only meaningful if the entire histogram will be reconstructed.

Parameters
numBinsthe number of bins.

The documentation for this class was generated from the following file: