EventBasedTally

class pydsol.core.statistics.EventBasedTally(name: str)[source]

Bases: EventProducer, EventListener, Tally

The EventBasedTally can receive its observations by subscribing (listening) to one or more EventProducers that provides the values for the statistic using the EventProducer’s fire(…) method. This way, the statistic gathering and processing is decoupled from the process in the simulation that generates the data: there can be zero, one, or many statistics listeners for each data producing object in the simulation.

This event-based statistic object also fire events with the values of the calculated statistics values, so a GUI-element such as a graph or table can subscribe to this event-based statistics object and be automatically updated when values of the statistic change. Again, this provides decoupling and flexibility where on beforehand it is not known whether zero, one, or many (graphics or simulation) objects are interested in the values that this statistics object calculates.

The EventBasedTally is a statistics object that calculates descriptive statistics for a number of observations, such as mean, variance, minimum, maximum, skewness, etc.

The initialize() method resets the statistics object. The initialize method can, for instance, be called when the warmup period of the simulation experiment has completed.

The mean of the EventBasedTally is calculated with the formula:

\[\mu = \sum_{i=1}^{n} {x_{i}} / n\]

where n is the number of observations and \(x_{i}\) are the observations.

Example

In discrete-event simulation, the EventBasedTally can be used to calculate statistical values for waiting times in queues, time in system of entities, processing times at a server, and throughput times of partial processes. When objects such as Servers or Entities are EventProducers, they can easily feed the EventBasedTally when their internal state changes.

Attributes:

_name (str) – the name by which the statistics object can be identified
_n (int) – the number of observations
_sum (float) – the sum of the observation values
_min (float) – the lowest value in the current observations
_max (float) – the highest value in the current observations
_m1, _m2, _m3, _m4 (float) – the 1st to 4th moment of the observations

__init__(name: str)[source]

Construct a new EventBasedTally statistics object. The EventBasedTally can receive its observations by subscribing (listening) to one or more EventProducers that provides the values for the statistic using the EventProducer’s fire(…) method. This way, the statistic gathering and processing is decoupled from the process in the simulation that generates the data: there can be zero, one, or many statistics listeners for each data producing object in the simulation.

This event-based statistic object also fire events with the values of the calculated statistics values, so a GUI-element such as a graph or table can subscribe to this event-based statistics object and be automatically updated when values of the statistic change. Again, this provides decoupling and flexibility where on beforehand it is not known whether zero, one, or many (graphics or simulation) objects are interested in the values that this statistics object calculates.

The EventBasedTally is a a statistics object that calculates descriptive statistics for a number of observations, such as mean, variance, minimum, maximum, skewness, etc.

Parameters:: name (str) – The name by which the statistics object can be identified.
Raises:: TypeError – when name is not a string

initialize()[source]: Initialize the statistics object, resetting all values to the state where no observations have been made. This method can, for instance, be called when the warmup period of the simulation experiment has completed.

notify(event: Event)[source]

The notify method is the method that is called by the EventProducer to register an observation. The EventType for the observation should be the StatEvents.DATA_EVENT and the payload should be a single float value. This value will be registered by the tally.

Parameters:

event (Event) – The event fired by the EventProducer to provide data to the statistic. The event’s content should be a single float with the value.

Raises:

TypeError – when event is not of the type Event
ValueError – when the event’s event_type is not a DATA_EVENT
TypeError – when the event’s payload is not a float

register(value: float)[source]

The event-based classes still have a register method. This method is called by the notify method, but can also be called separately. The method processes one observation.

The method records a single observation value, and calculate all statistics up to and including the last value (mean, standard deviation, minimum, maximum, skewness, etc.).

Parameters:

value (float) – The value of the observation.

Raises:

TypeError – when value is not a number
ValueError – when value is NaN

add_listener(event_type: EventType, listener: EventListener)

Add an EventListener to this EventProducer for a given EventType. If the listener already is registered for this EventType, this will be ignored.

Parameters:

event_type (EventType) – the EventType for which this listener subscribes
listener (EventListener) – the subscriber to register for the provided Eventtype

Raises:

EventError – if any of the arguments is of the wrong type

confidence_interval(alpha: float) → Tuple[float]

Return the confidence interval around the mean with the provided alpha. When fewer than two observations were registered, (NaN, NaN) is returned.

Parameters:

alpha (float) – Alpha is the significance level used to compute the confidence level. The confidence level equals \(100 * (1 - alpha)\%\), or in other words, an alpha of 0.05 indicates a 95 percent confidence level.

Returns:

The confidence interval around the mean, or (NaN, NaN) when fewer than two observations were registered.

Return type:

(float, float)

Raises:

TypeError – when alpha is not a float
ValueError – when alpha is not between 0 and 1, inclusive

excess_kurtosis(biased: bool = True) → float

Return the excess kurtosis of the registered data. The kurtosis value of the normal distribution is 3. The (biased) excess kurtosis is the kurtosis value shifted by -3 to be 0 for the normal distribution. The biased excess kurtosis needs three observations; if fewer observations were registered, NaN is returned.

The formula for the biased (population) excess kurtosis is:

\[ExcessKurt_{biased} = Kurt_{biased} - 3\]

The unbiased (sample) excess kurtosis is the sample-corrected value of the biased excess kurtosis. When fewer than four observations were registered, NaN is returned for the unbiased excess kurtosis. Several formulas exist to calculate the sample excess kurtosis from the biased excess kurtosis. Here we use:

\[ExcessKurt_{unbiased} = \frac{n - 1}{(n - 2) (n - 3)} \left( (n + 1) ExcessKurt_{biased} + 6 \right)\]

This is the excess kurtosis that is calculated by, for instance, SAS, SPSS and Excel.

Parameters:: biased (bool) – Whether to return the biased (population) excess kurtosis or the unbiased (sample) excess kurtosis. By default, biased is True and the population excess kurtosis is returned.
Returns:: The excess kurtosis of all observations since the initialization, or NaN when too few observations were registered.
Return type:: float

has_listeners() → bool: indicate whether this producer has any listeners or not

kurtosis(biased: bool = True) → float

Return the kurtosis of all observations since the statistic initialization. The biased (sample) kurtosis calculation needs three observations, and the unbiased (population) calculation needs four observations. When too few observations were registered, NaN is returned.

The formula for the biased (population) kurtosis is:

\[kurt_{biased} = \frac{\sum{(x_{i} - \mu)^4}}{n.\sigma^4}\]

where \(\sigma^2\) is the population variance. So the denominator is equal to \(n . pop\_var^2\).

The formula for the unbiased (sample) kurtosis is:

\[kurt_{unbiased} = \frac{\sum{(x_{i} - \mu)^4}}{(n-1).S^4}\]

where \(S^2\) is the sample variance. So the denominator is equal to \((n - 1) . sample\_var^2\).

Parameters:: biased (bool) – Whether to return the biased (population) kurtosis or the unbiased (sample) kurtosis. By default, biased is True and the population kurtosis is returned.
Returns:: The kurtosis of all observations since the initialization, or NaN when too few observations were registered.
Return type:: float

max() → float

Return the observation with the highest value. When no observations were registered, NaN is returned.

Returns:: The observation with the highest value, or NaN when no observations were registered.
Return type:: float

mean() → float

Return the mean. When no observations were registered, NaN is returned.

The mean of the Tally is calculated with the formula:

\[\mu = \sum_{i=1}^{n} {x_{i}} / n\]

where n is the number of observations and \(x_{i}\) are the observations.

Returns:: The mean, or NaN when no observations were registered.
Return type:: float

min() → float

Return the observation with the lowest value. When no observations were registered, NaN is returned.

Returns:: The observation with the lowest value, or NaN when no observations were registered.
Return type:: float

n() → int

Return the number of observations.

Returns:: The number of observations.
Return type:: int

property name

Return the name of this statistics object.

Returns:: The name of this statistics object.
Return type:: str

remove_all_listeners(event_type: EventType | None = None, listener: EventListener | None = None)

Remove an EventListener (if given) for a provided EventType (if given) for this EventProducer. It is no problem if there are no matches. There are four situations:

event_type == None and listener == None: all listeners for all event types are removed
event_type == None and listener is specified: the listener is removed for any event for which it was registered
event_type is specified and listener == None: all listeners are removed for the given event_type
event_type and listener are both specified: the listener for the given event type is removed, if it was registered; in essence this is the same as remove_listener

Parameters:

event_type (EventType, optional) – the EventType for which this listener unsubscribes
listener (EventListener, optional) – the subscriber to remove for the provided EventType

Raises:

EventError – if any of the arguments is of the wrong type

remove_listener(event_type: EventType, listener: EventListener)

Remove an EventListener of this EventProducer for a given EventType. If the listener is not registered for this EventType, this will be ignored.

Parameters:

event_type (EventType) – the EventType for which this listener unsubscribes
listener (EventListener) – the subscriber to remove for the provided Eventtype

Raises:

EventError – if any of the arguments is of the wrong type

classmethod report_footer() → str: Return a string representing a footer for a textual table with a monospaced font that can contain multiple tallies.

classmethod report_header() → str: Return a string representing a header for a textual table with a monospaced font that can contain multiple tallies.

report_line() → str: Return a string representing a line with important statistics values for this tally, for a textual table with a monospaced font that can contain multiple tallies.

skewness(biased: bool = True) → float

Return the skewness of all observations since the statistic initialization. For the biased (population) skewness, at least two observations are needed; for the unbiased (sample) skewness, at least three observations are needed. If there are too few observations, NaN is returned. The method returns the biased (population) skewness as the default.

The formula for the biased (population) skewness is:

\[Skew_{biased} = \frac{ \sum{(x_{i} - \mu)^3} }{n . \sigma^3}\]

where \(\sigma^2\) is the biased (population) variance. So the denominator is equal to \(n . population\_var^{3/2}\).

There are different formulas to calculate the unbiased (sample) skewness from the biased (population) skewness. Minitab, for instance calculates unbiased skewness as:

\[Skew_{unbiased} = Skew_{biased} {\left( \frac{n - 1}{n} \right)} ^{3/2}\]

whereas SAS, SPSS and Excel calculate it as:

\[Skew_{unbiased} = Skew_{biased} \sqrt{\frac{n (n - 1)}{n - 2} }\]

Here we follow the last mentioned formula. All formulas converge to the same value with larger n.

Parameters:: biased (bool) – Whether to return the biased (population) skewness or the unbiased (sample) skewness. By default, biased is True and the population skewness is returned.
Returns:: The skewness of all observations since the initialization, or NaN when too few observations were registered.
Return type:: float

stdev(biased: bool = True) → float

Return the standard deviation of all observations since the initialization. The sample standard deviation is defined as the square root of the variance. The biased standard deviation needs at least 1 observation, the unbiased version needs at least 2.

The formula for the biased (population) standard deviation is:

\[\sigma = \sqrt{ {\frac{1}{n}} \left( \sum{x_{i}^2} - \left( \sum{x_{i}} \right)^2 / n \right) }\]

The formula for the unbiased (sample) standard deviation is:

\[S = \sqrt{ {\frac{1}{n - 1}} \left( \sum{x_{i}^2} - \left( \sum{x_{i}} \right)^2 / n \right) }\]

Parameters:: biased (bool) – Whether to return the biased (population) standard deviation or the unbiased (sample) standard deviation. By default, biased is True and the population standard deviation is returned.
Returns:: The (unbiased) sample standard deviation of all observations since the initialization, or NaN when not enough observations were registered.
Return type:: float

sum() → float

Return the sum of all observations since the statistic initialization.

Returns:: The sum of the observations.
Return type:: float

variance(biased: bool = True) → float

Return the variance of all observations since the statistic initialization. By default, the biased (population) variance is returned. The biased variance needs at least 1 observation, the unbiased variance needs at least 2.

The formula for the biased (or population) variance is:

\[\sigma^2 = { {\frac{1}{n}} \left( \sum{x_{i}^2} - \left( \sum{x_{i}} \right)^2 / n \right) }\]

The formula for the unbiased (or sample) variance is:

\[S^2 = { {\frac{1}{n-1}} \left( \sum{x_{i}^2} - \left( \sum{x_{i}} \right)^2 / n \right) }\]

Parameters:: biased (bool) – Whether to return the biased (population) variance or the unbiased (sample) variance. By default, biased is True and the population variance is returned.
Returns:: The biassed or unbiased variance of all observations since the initialization, or NaN when too few observations were registered.
Return type:: float