# NAME

Quantum::Superpositions::Lazy::Statistics - statistical measures on superpositions

# DESCRIPTION

This package contains implementations of basic statistical measures available directly from the superposition object via the *stats* method. Upon calling any method on the statistics object, the full set of states will be created on the superposition.

# METHODS

All the methods results are cached on the first call. Most methods use other methods internally to avoid multiple invocations of possibly costly calculations. Modifying the returned reference contents will change the value stored in the cache and will thus lead to wrong values being returned.

Any method that returns states will no longer return the weight of the state, but instead will reuse that field for the calculated probability (a float value in between 0 and 1). The value can still be treated as weight (and weight sum is then 1), but the information on the original weight will not be accessible.

For example, if we use the *most_probable* method on a superposition that has a state with a weight of 3 and the total weight sum is 6, the resulting state in the superposition returned by the method will have its *weight* field equal to 0.5.

## parent

Returns the superposition which is used for getting the states data, a consumer of Quantum::Superpositions::Lazy::Role::Collapsible.

## sorted_by_probability

Returns all the states sorted by probability in ascending order.

## sorted_by_value

## sorted_by_value_str

## sorted_by_value_num

Returns all the states sorted by their value in ascending order. Values can be treated either as numbers or strings in the comparison.

The *sorted_by_value* method is an alias for *sorted_by_value_str*.

## most_probable

## least_probable

Returns the border elements based on weight - the most or the least probable elements. The return value is a new superposition which contains the border elements. Multiple border elements will be grouped in this superposition.

## median

## median_str

## median_num

Returns the weighted median of the superposition states (a floating point value). The string variant and the numerical variant differ in two ways:

the method of sorting used when calculating the median

the numerical variant will average the result if the data set has two elements that meet the criteria

The *median* method is an alias for *median_str*.

## mean

## expected_value

Returns the weighted mean of the data set (a floating point value). The expected value of the discrete set is equal to its weighted mean, hence the *expected_value* is just an alias for convenience.

## variance

Returns the variance of the data set (a floating point value).

## standard_deviation

Returns the standard deviation of the data set - a square root of variance (a floating point value).

# EXTENDING

The class can be extended by replacing the value of `$Quantum::Superpositions::Lazy::Statistics::implementation`

with another package name. `$superposition->stats`

call will instantiate and return anything that is present in that variable. The package should already be loaded, the module will not try to load it. It has to inherit from *Quantum::Superpositions::Lazy::Statistics*.

An example class that replaces the implementation on use:

```
package MyStatistics;
use parent 'Quantum::Superpositions::Lazy::Statistics';
$Quantum::Superpositions::Lazy::Statistics::implementation = __PACKAGE__;
sub my_statistical_measure {
my ($self) = @_;
return ...;
}
1;
```

Also note that a *local* keyword can be used to replace the implementation only for a given lexical scope:

```
my $superpos = superpos(1, 2, 3);
{
local $Quantum::Superpositions::Lazy::Statistics::implementation = 'Some::Class';
$superpos->stats; # stats are lazily built and cached
}
$superpos->stats->some_method; # will also be another class implementation because of caching
```

# CAVEATS

*parent* is a weak ref. Because of this, this (and many others) will explode:

` superpos(1)->stats->most_probable;`