WeightedTally

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

Bases: StatisticsInterface

The WeightedTally is a statistics object that calculates descriptive statistics for weighted observations, such as weighted mean, weighted variance, minimum observation, maximum observation, 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.

In a sense, the weighted tally can be seen as a normal Tally where the observations are multiplied by their weights. But instead of dividing by the number of observations to calculate the mean, the sum of weights times observations is divided by the sum of the weights. Note that when the weights are all set to 1, the WeghtedTally reduces to the ordinary Tally.

Example

In discrete-event simulation, the WeightedTally is often used with elapsed time as the weights (See the EventBasedTimestampWeightedTally class and the ‘SimPersistent’ class later in this module). This creates a time-weighted statistic that can for instance be used to calculate statistics for (average) queue length, or (average) utilization of a server.

Attributes:

_name (str) – the name by which the statistics object can be identified
_n (int) – the number of observations
_n_nonzero (int) – the number of non-zero weights
_sum_of_weights (float) – the sum of the weights
_weighted_sum (float) – the sum of the observation values times their weights
_weight_times_variance (float) – the weighted variant of the second moment of the statistic
_min (float) – the lowest value in the current observations
_max (float) – the highest value in the current observations

__init__(name: str)[source]

Construct a new WeightedTally statistics object. The WeightedTally is a statistics object that calculates descriptive statistics for weighted observations, such as weighted mean, weighted variance, minimum, and maximum.

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.

property name: str

Return the name of this statistics object.

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

register(weight: float, value: float)[source]

Process one observation value and a corresponding weight, and calculate all statistics up to and including the last weight-value pair (mean, standard deviation, minimum, maximum, sum, etc.). Weight has to be >= 0.

Note

When weight equals zero, the value is counted towards the number of observations, and for the minimum and maximum observation value, but it does not contribute to the other statistics.

Parameters:

weight (float) – The weight of this observation (has to be >= 0).
value (float) – The value of the observation.

Raises:

TypeError – when weight or value is not a number
ValueError – when weight or value is NaN
ValueError – when weight < 0

n() → int[source]

Return the number of observations.

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

min() → float[source]

Return the (unweighted) 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

max() → float[source]

Return the (unweighted) 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

weighted_sum() → float[source]

Return the sum of all observations times their weights since the statistic initialization.

Returns:: The sum of the observations times their weights.
Return type:: float

weighted_mean() → float[source]

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

The weighted mean of the WeightedTally is calculated with the formula:

\[\mu_{W} = \frac{\sum_{i=1}^{n} w_{i}.x_{i}}{\sum_{i=1}^{n} w_{i}}\]

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

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

weighted_variance(biased: bool = True) → float[source]

Return the weighted population variance of all observations since the statistic initialization. The biased version needs at least one observation. For the unbiased version, two observations with non-zero weights are needed. When too few observations were registered, NaN is returned.

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

\[\sigma^{2}_{W} = \frac{\sum_{i=1}^{n}{w_i (x_i - \mu_{W})^2}} {\sum_{i=1}^{n}{w_i}}\]

where \(w_i\) are the weights, \(x_i\) are the observations, \(n\) is the number of observations, and \(\mu_W\) is the weighted mean of the observations.

For the unbiased (sample) weighted variance, different algorithms are suggested by the literature. As an example, R and MATLAB calculate weighted sample variance differently. SPSS rounds the sum of weights to the nearest integer and counts that as the ‘sample size’ in the unbiased formula. When weights are used as so-called reliability weights (non-integer) rather than as frequency weights (integer), rounding to the nearest integer and using that to calculate a ‘sample size’ is obviously incorrect. See the discussion at https://en.wikipedia.org/wiki/Weighted_arithmetic_mean#Weighted_sample_variance and at https://stats.stackexchange.com/questions/51442/weighted-variance-one-more-time. Here we have chosen to implement the version that uses reliability weights. The reason is that the weights in simulation study are most usually time intervals that can be on any (non-integer) scale.

The formula used for the unbiased (sample) weighted variance is:

\[S^{2}_{W} = \frac{M}{M - 1} . \sigma^2_{W}\]

or as a complete formula:

\[S^{2}_{W} = \frac{M}{M - 1} . \frac{\sum_{i=1}^{n}{w_i (x_i-\mu_{W})^2}} {\sum_{i=1}^{n}{w_i}}\]

where \(w_i\) are the weights, \(x_i\) are the observations, \(n\) is the number of observations, \(M\) is the number of non-zero observations, and \(\mu_W\) is the weighted mean of the observations.

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 weighted variance of all observations since the initialization, or NaN when too few (non-zero) observations were registered.
Return type:: float

weighted_stdev(biased: bool = True) → float[source]

Return the (biased) weighted population standard deviation of all observations since the statistic initialization. The biased version needs at least one observation. For the unbiased version, two observations are needed. When too few observations were registered, NaN is returned.

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

\[\sigma_{W} = \sqrt{ \frac{\sum_{i=1}^{n}{w_i (x_i - \mu_{W})^2}} {\sum_{i=1}^{n}{w_i}} }\]

where \(w_i\) are the weights, \(x_i\) are the observations, \(n\) is the number of observations, and \(\mu_W\) is the weighted mean of the observations.

For the unbiased (sample) weighted variance (and, hence, for the standard deviation), different algorithms are suggested by the literature. As an example, R and MATLAB calculate weighted sample variance differently. SPSS rounds the sum of weights to the nearest integer and counts that as the ‘sample size’ in the unbiased formula. When weights are used as so-called reliability weights (non-integer) rather than as frequency weights (integer), rounding to the nearest integer and using that to calculate a ‘sample size’ is obviously incorrect. See the discussion at https://en.wikipedia.org/wiki/Weighted_arithmetic_mean#Weighted_sample_variance and at https://stats.stackexchange.com/questions/51442/weighted-variance-one-more-time. Here we have chosen to implement the version that uses reliability weights. The reason is that the weights in simulation study are most usually time intervals that can be on any (non-integer) scale.

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

\[S_{W} = \sqrt{ \frac{M}{M - 1} . \sigma^2_{W} }\]

or as a complete formula:

\[S_{W} = \sqrt{ \frac{M}{M - 1} . \frac{\sum_{i=1}^{n}{w_i (x_i - \mu_{W})^2}} {\sum_{i=1}^{n}{w_i}} }\]

where \(w_i\) are the weights, \(x_i\) are the observations, \(n\) is the number of observations, \(M\) is the number of non-zero observations, and \(\mu_W\) is the weighted mean of the observations.

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 weighted standard deviation of all observations since the initialization, or NaN when too few (non-zero) observations were registered.
Return type:: float

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

report_line() → str[source]: 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.

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