desmoj.core.statistic

Class Histogram

java.lang.Object

desmoj.core.simulator.NamedObject

desmoj.core.simulator.ModelComponent

desmoj.core.simulator.Reportable

desmoj.core.statistic.StatisticObject

desmoj.core.statistic.StatisticObjectSupportingTimeSpans

desmoj.core.statistic.ValueStatistics

desmoj.core.statistic.Tally

desmoj.core.statistic.Histogram

All Implemented Interfaces:

java.util.Observer

Direct Known Subclasses:

HistogramAnimation

public class Histogram
extends Tally

The Histogram class is providing a statistic analysis about values. An interval is divided into sections with an under- and an overflow section. When a value is updated it will be decided to which section it belongs to and the counter for that section will be updated. In the end the report will show how many values belong to which section.

Version:

DESMO-J, Ver. 2.5.1c copyright (c) 2015

Author:

Soenke Claassen, based on DESMO-C from Thomas Schniewind, 1998, edited by Lorna Slawski (changes in implementation and added possibility of non-equidistant sections as well as the Chi-squared test) Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Field Summary

Fields inherited from class desmoj.core.statistic.StatisticObject

UNDEFINED

Constructor Summary

Constructors

Constructor and Description
Histogram(Model ownerModel, java.lang.String name, double[] range, boolean showInReport, boolean showInTrace) Constructor for a Histogram object with user-defined interval cells that will NOT be connected to a ValueSupplier.
Histogram(Model ownerModel, java.lang.String name, double lowerEnd, double upperEnd, int cells, boolean showInReport, boolean showInTrace) Constructor for a Histogram object with equidistant interval cells that will NOT be connected to a ValueSupplier.
Histogram(Model ownerModel, java.lang.String name, ValueSupplier valSup, double[] range, boolean showInReport, boolean showInTrace) Constructor for a Histogram object with user-defined interval cells that will be connected to a ValueSupplier.
Histogram(Model ownerModel, java.lang.String name, ValueSupplier valSup, double lowerEnd, double upperEnd, int cells, boolean showInReport, boolean showInTrace) Constructor for a Histogram object with equidistant interval cells that will be connected to a ValueSupplier.

Method Summary

Modifier and Type	Method and Description
void	changeParameters(double[] range) Changes the parameters of the interval and its number of segments.
void	changeParameters(double low, double up, int cel) Changes the parameters of the interval and its number of segments.
boolean	chiSquareTest(long[] values, double confidence) Performs Pearson's Chi-square test on given frequencies, a fixed degree of freedom and desired probability.
boolean	chiSquareTest(long[] values, int degFreedom, double confidence) Performs Pearson's Chi-square test on given frequencies, degrees of freedom and desired probability.
Reporter	createDefaultReporter() Returns a Reporter to produce a report about this Histogram.
int	getCells() Returns the number of cells the interval is divided into.
double	getCellWidth() Deprecated. The same functionality is given by getMeanWidth().
double	getLowerLimit(int cell) Returns the lower limit of the given cell.
double	getMeanWidth() Returns the mean width of all cells.
int	getMostFrequentedCell() Deprecated. Gives the same result as the first entry of the returned array of getMostFrequentedCells().
int[]	getMostFrequentedCells() Returns the numbers of the most frequented cells, so far.
long	getObservationsInCell(int cell) Returns the observations made for the given cell, so far.
double	getUpperLimit() Returns the upper limit of the whole interval.
boolean	isCondensed() Returns whether output is condensed, i.e.\ empty cells on the right tail not shown.
void	reset() Resets this Histogram object by resetting the counters for each cell to zero.
void	setCondensed(boolean condensed) Sets whether output should be condensed, i.e.\ empty cells on the right tail not shown.
void	update() Updates this Histogram object by fetching the actual value of the ValueSupplier and processing it.
void	update(double val) Updates this Histogram object with the double value given as parameter.
void	update(java.util.Observable o, java.lang.Object arg) Implementation of the virtual update(Observable, Object) method of the Observer interface.

Methods inherited from class desmoj.core.statistic.Tally

getMean, getStdDev

Methods inherited from class desmoj.core.statistic.ValueStatistics

getLastValue, getMaximum, getMinimum, update

Methods inherited from class desmoj.core.statistic.StatisticObjectSupportingTimeSpans

getShowTimeSpansInReport, getUnit, setShowTimeSpansInReport

Methods inherited from class desmoj.core.statistic.StatisticObject

getUnitText, round, setUnit

Methods inherited from class desmoj.core.simulator.Reportable

getCorrespondingSchedulable, getDescription, getObservations, getReporter, incrementObservations, incrementObservations, reportIsOn, reportOff, reportOn, resetAt, setCorrespondingSchedulable, setDescription, setReporter

Methods inherited from class desmoj.core.simulator.ModelComponent

current, currentEntity, currentEntityAll, currentEvent, currentModel, currentSimProcess, debugIsOn, debugOff, debugOn, getModel, isExperimentCompatible, isModelCompatible, presentTime, sendDebugNote, sendMessage, sendTraceNote, sendWarning, skipTraceNote, skipTraceNote, traceIsOn, traceOff, traceOn

Methods inherited from class desmoj.core.simulator.NamedObject

getName, getQuotedName, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Histogram

public Histogram(Model ownerModel,
                 java.lang.String name,
                 double lowerEnd,
                 double upperEnd,
                 int cells,
                 boolean showInReport,
                 boolean showInTrace)

Constructor for a Histogram object with equidistant interval cells that will NOT be connected to a ValueSupplier.

Parameters:

ownerModel - Model : The model this Histogram is associated to.

name - java.lang.String : The name of this Histogram object.

lowerEnd - double : The lower end of the interval.

upperEnd - double : The upper end of the interval.

cells - int : The number of cells (sections) the given interval will be divided into.

showInReport - boolean : Flag for showing the report about this Histogram.

showInTrace - boolean : Flag for showing the trace output of this Histogram.

Histogram

public Histogram(Model ownerModel,
                 java.lang.String name,
                 ValueSupplier valSup,
                 double lowerEnd,
                 double upperEnd,
                 int cells,
                 boolean showInReport,
                 boolean showInTrace)

Constructor for a Histogram object with equidistant interval cells that will be connected to a ValueSupplier.

Parameters:

ownerModel - Model : The model this Histogram is associated to.

name - java.lang.String : The name of this Histogram object.

valSup - ValueSupplier : The ValueSupplier providing the value for this Histogram. The given ValueSupplier will be observed by this Histogram object.

lowerEnd - double : The lower end of the interval.

upperEnd - double : The upper end of the interval.

cells - int : The number of cells (sections) the given interval will be divided into.

showInReport - boolean : Flag for showing the report about this Histogram.

showInTrace - boolean : Flag for showing the trace output of this Histogram.

Histogram

public Histogram(Model ownerModel,
                 java.lang.String name,
                 double[] range,
                 boolean showInReport,
                 boolean showInTrace)

Constructor for a Histogram object with user-defined interval cells that will NOT be connected to a ValueSupplier.

Parameters:

ownerModel - Model : The model this Histogram is associated to.

name - java.lang.String : The name of this Histogram object.

range - double[] : The interval with the lower limit of each cell and the upper limit of the interval as the final value.

showInReport - boolean : Flag for showing the report about this Histogram.

showInTrace - boolean : Flag for showing the trace output of this Histogram.

Histogram

public Histogram(Model ownerModel,
                 java.lang.String name,
                 ValueSupplier valSup,
                 double[] range,
                 boolean showInReport,
                 boolean showInTrace)

Constructor for a Histogram object with user-defined interval cells that will be connected to a ValueSupplier.

Parameters:

ownerModel - Model : The model this Histogram is associated to.

name - java.lang.String : The name of this Histogram object.

valSup - ValueSupplier : The ValueSupplier providing the value for this Histogram. The given ValueSupplier will be observed by this Histogram object.

range - double[] : The interval with the lower limit of each cell and the upper limit of the interval as the final value.

showInReport - boolean : Flag for showing the report about this Histogram.

showInTrace - boolean : Flag for showing the trace output of this Histogram.

Method Detail

isCondensed

public boolean isCondensed()

Returns whether output is condensed, i.e.\ empty cells on the right tail not shown.

Returns:

boolean : Not displaying unused cells in report view (true) or printing all cells (false).

setCondensed

public void setCondensed(boolean condensed)

Sets whether output should be condensed, i.e.\ empty cells on the right tail not shown.

Parameters:

condensed - boolean: Not displaying unused cells in report view (true) or printing all cells (false).

changeParameters

public void changeParameters(double low,
                             double up,
                             int cel)

Changes the parameters of the interval and its number of segments. Can only be done after construction of a Histogram or after a reset.

Parameters:

low - double : The lower end of the interval.

up - double : The upper end of the interval.

cel - int : The number of cells (sections) the given interval will be divided into.

changeParameters

public void changeParameters(double[] range)

Changes the parameters of the interval and its number of segments. Can only be done after construction of a Histogram or after a reset.

Parameters:

range - double[] : The array holding the lower limits of the interval sections and the upper limit as the final value.

chiSquareTest

public boolean chiSquareTest(long[] values,
                             double confidence)

Performs Pearson's Chi-square test on given frequencies, a fixed degree of freedom and desired probability. The frequencies are given in an array either including under- and overflow cells or not. The degree of freedom is set to 1 deducted from the number of given cells. On an error the Chi-squared test is not performed and false is returned. Details on errors are given out in the error message log. The result is true if the null hypothesis can not be rejected.

Parameters:

values - long[]: Array of assumed frequencies for each cell.

confidence - double: (1-alpha) probability level.

Returns:

boolean : true if the the null hypothesis can not be rejected. false on error or if the null hypothesis has to be rejected.

chiSquareTest

public boolean chiSquareTest(long[] values,
                             int degFreedom,
                             double confidence)

Performs Pearson's Chi-square test on given frequencies, degrees of freedom and desired probability. The frequencies are given in an array either including under- and overflow cells or not. On error the Chi-squared test is not performed and false is returned. Details on errors are given out in the error message log. The result is true if the null hypothesis can not be rejected.

Parameters:

values - long[]: Array of assumed frequencies for each cell.

degFreedom - int: Degrees of freedom of the test.

confidence - double: (1-alpha) probability level.

Returns:

boolean : true if the the null hypothesis can not be rejected. false on error or if the null hypothesis has to be rejected.

createDefaultReporter

public Reporter createDefaultReporter()

Returns a Reporter to produce a report about this Histogram.

Overrides:

createDefaultReporter in class Tally

Returns:

desmoj.report.Reporter : The Reporter for this Histogram.

getCells

public int getCells()

Returns the number of cells the interval is divided into.

Returns:

int : The number of cells the interval is divided into.

getCellWidth

@Deprecated
public double getCellWidth()

Deprecated. The same functionality is given by getMeanWidth().

Returns the mean width of all cells.

Returns:

double : The mean width of all cells.

getMeanWidth

public double getMeanWidth()

Returns the mean width of all cells.

Returns:

double : The mean width of all cells.

getLowerLimit

public double getLowerLimit(int cell)

Returns the lower limit of the given cell. If the given cell is negative, UNDEFINED (-1) will be returned.

Parameters:

cell - int : The cell for which we want to know its lower limit. Should be zero or positive.

Returns:

double : The lower limit of the given cell.

getMostFrequentedCell

@Deprecated
public int getMostFrequentedCell()

Deprecated. Gives the same result as the first entry of the returned array of getMostFrequentedCells().

Returns the number of the first cell holding the maximum value.

Returns:

int : The number of one cell holding the maximum value.

getMostFrequentedCells

public int[] getMostFrequentedCells()

Returns the numbers of the most frequented cells, so far.

Returns:

int[] : An array with the numbers of the most frequented cells.

getObservationsInCell

public long getObservationsInCell(int cell)

Returns the observations made for the given cell, so far.

Parameters:

cell - int : The cell of which want to get the number of observations made for.

Returns:

long : The observations made for the given cell.

getUpperLimit

public double getUpperLimit()

Returns the upper limit of the whole interval.

Returns:

double : The upper limit of the whole interval.

reset

public void reset()

Resets this Histogram object by resetting the counters for each cell to zero. That means the array of the cell counters will be reset, but the interval and the number of sections this interval is divided into will remain the same. The parameters of the interval can be changed with the changeParameters method after the reset.

Overrides:

reset in class Tally

update

public void update()

Updates this Histogram object by fetching the actual value of the ValueSupplier and processing it. The ValueSupplier is passed in the constructor of this Histogram object. This update() method complies with the one described in DESMO, see [Page91].

Overrides:

update in class Tally

update

public void update(double val)

Updates this Histogram object with the double value given as parameter. In some cases it might be more convenient to pass the value this Histogram will be updated with directly within the update(double val) method instead of going via the ValueSupplier.

Overrides:

update in class Tally

Parameters:

val - double : The value with which this Histogram will be updated.

update

public void update(java.util.Observable o,
                   java.lang.Object arg)

Implementation of the virtual update(Observable, Object) method of the Observer interface. This method will be called automatically from an Observable object within its notifyObservers() method.
If no Object (anull value) is passed as arg, the actual value of the ValueSupplier will be fetched with the value() method of the ValueSupplier. Otherwise it is expected that the actual value is passed in the Object arg.

Specified by:

update in interface java.util.Observer

Overrides:

update in class Tally

Parameters:

o - java.util.Observable : The Observable calling this method within its own notifyObservers() method.

arg - Object : The Object with which this Tally is updated. Normally a double number which is added to the statistics or null.