Struct RandomVariable 

pub struct RandomVariable<S = f64, const M: usize = 2>
where
    S: Weighable,
{ /* private fields */ }

A simple collector for statistical data, inspired by SLX’s random_variable and generalized to numerical data points of an arbitrary type.

This implementation uses numerically stable online algorithms using sums of differences to the estimated mean described in Pébaÿ et al. rather than SLX’s naïve approach of using sums directly. It supports the sampling of weighted values and the subsequent estimation of up to four statistical moments (arithmetic mean, variance, skew, and kurtosis). The user can select the number of statistical moments they want to estimate by supplying a compile-time constant between 0 (only estimating the minimum and maximum) and 4 (additionally estimating mean, variance, skew, and kurtosis).

All four moments are useful to describe the kind of distribution:

• mean tells us the location of the distribution by giving us its center,
• variance measures the size of the distribution by giving us the location-independent distance from the mean,
• skew describes the asymmetry of the distribution by giving us a location and variance-independent measure for the balance of values left and right of the arithmetic mean, and
• kurtosis is a measure for the number and severity of outliers by weighing samples higher the further from the mean they get.

To sum it up: the former two statistical moments talk about the location and size, and the latter two statistical moments talk about the shape of the distribution. Since we usually cannot sample the whole population of values, efforts have been made to numerically correct the sampling bias inherent in sampling only a subset of a population.

Implementations

impl<S> RandomVariable<S>

where S: Weighable,

pub const fn new<const M: usize>() -> RandomVariable<S, M>

Creates a new, empty random variable.

impl<S, const M: usize> RandomVariable<S, M>

where S: Weighable,

pub fn reset(&self)

Resets the stored statistical moments.

pub fn tabulate(&self, value: S)

where CentralMoments<M>: Univariate,

Adds another value to the statistical collection.

pub fn try_tabulate(&self, value: S) -> Result<(), <S as Weighable>::Error>

where CentralMoments<M>: Univariate,

Adds a value to the statistical collection and returns an error if it fails.

pub fn join(self, other: RandomVariable<S, M>) -> RandomVariable<S, M>

where CentralMoments<M>: Univariate,

Combines another equally typed random variable with this one, consuming both and returning a new random variable representing the aggregated statistical collection.

pub fn count(&self) -> usize

Returns the number of tabulated observations.

pub fn min(&self) -> Option<<S as Weighable>::Sample>

Returns the smallest tabulated observation or None if no observations have occurred.

pub fn max(&self) -> Option<<S as Weighable>::Sample>

Returns the largest tabulated observation or None if no observations have occurred.

pub fn weight(&self) -> f64

Returns the sum of the weights of the observations.

pub fn sum(&self) -> <S as Weighable>::Sample

where CentralMoments<M>: Mean,

Returns the weighted sum of the observations.

pub fn mean(&self) -> f64

where CentralMoments<M>: Mean,

Returns the estimated arithmetic mean of the observations.

pub fn variance(&self) -> f64

where CentralMoments<M>: Variance,

Returns the unbiased sample variance of the observations under the assumption that the samples were taken from an infinite population.

Note

If you know that you have sampled the whole population, i.e., all possible samples, use Self::population_variance to determine the real (not estimated) variance.

pub fn std_dev(&self) -> f64

where CentralMoments<M>: Variance,

Available on crate features std or libm only.

Returns the corrected sample standard deviation of the observations under the assumption that the samples were taken from an infinite population.

Note

If you know that you have sampled the whole population, i.e., all possible samples, use Self::population_std_dev to determine the real (not estimated) standard deviation.

pub fn skew(&self) -> f64

where CentralMoments<M>: Skewness,

Available on crate features std or libm only.

Returns the skewness of the observations under the assumption that the samples were taken from an infinite population.

Note

If you know that you have sampled the whole population, i.e., all possible samples, use Self::population_skew to determine the real (not estimated) skewness.

pub fn kurtosis(&self) -> f64

where CentralMoments<M>: Kurtosis,

Returns the sample kurtosis of the observations under the assumption that the samples were taken from an infinite population.

Note

If you know that you have sampled the whole population, i.e., all possible samples, use Self::population_kurtosis to determine the real (not estimated) kurtosis.

pub fn excess_kurtosis(&self) -> f64

where CentralMoments<M>: Kurtosis,

Returns the excess kurtosis of the observations under the assumption that the samples were taken from an infinite population.

Note

If you know that you have sampled the whole population, i.e., all possible samples, use Self::population_excess_kurtosis to determine the real (not estimated) kurtosis.

pub fn population_variance(&self) -> f64

where CentralMoments<M>: Variance,

Returns the population variance of the observations under the assumption that the whole population has been sampled.

Note

This is likely not what you want since you will usually only be able to sample a limited subset of all possible observations and will therefore want to use Self::variance instead. However, both values will eventually converge to the same number.

pub fn population_std_dev(&self) -> f64

where CentralMoments<M>: Variance,

Available on crate features std or libm only.

Returns the population standard deviation of the observations under the assumption that the whole population has been sampled.

Note

This is likely not what you want since you will usually only be able to sample a limited subset of all possible observations and will therefore want to use Self::std_dev instead. However, both values will eventually converge to the same number.

pub fn population_skew(&self) -> f64

where CentralMoments<M>: Skewness,

Available on crate features std or libm only.

Returns the skewness of the observations under the assumption that the whole population has been sampled.

Note

This is likely not what you want since you will usually only be able to sample a limited subset of all possible observations and will therefore want to use Self::skew instead. However, both values will eventually converge to the same number.

pub fn population_kurtosis(&self) -> f64

where CentralMoments<M>: Kurtosis,

Returns the kurtosis of the observations under the assumption that the whole population has been sampled.

Note

This is likely not what you want since you will usually only be able to sample a limited subset of all possible observations and will therefore want to use Self::kurtosis instead. However, both values will eventually converge to the same number.

pub fn population_excess_kurtosis(&self) -> f64

where CentralMoments<M>: Kurtosis,

Returns the excess kurtosis of the observations under the assumption that the whole population has been sampled.

Note

The excess kurtosis of a population is just the population kurtosis minus 3. This is usually not what you want since you will usually only be able to sample a limited subset of all possible observations and will therefore want to use Self::excess_kurtosis instead. However, both values will eventually converge to the same number.

impl<T, S, const M: usize> RandomVariable<Utilized<T, S>, M>

where T: Sample + Add<Output = T> + Sub<Output = T>, S: Sample,

pub fn tracked(&self) -> Option<S>

Returns the currently tracked value within the most recent interval.

pub fn update(&self, time: T)

where CentralMoments<M>: Univariate,

Updates the temporal random variable’s state to the current time without changing the tracked value and panics if the given time is before the previous tabulation.

pub fn try_update(&self, time: T) -> Result<(), Causality<T>>

where CentralMoments<M>: Univariate,

Updates the temporal random variable’s state to the current time without changing the tracked value and returns an error if the given time is before the previous tabulation.

impl<D, U, V, const M: usize> RandomVariable<Quantity<D, U, V>, M>

where Quantity<D, U, V>: Sample, D: Dimension + ?Sized, U: Units<V> + ?Sized, V: Conversion<V> + Num,

pub fn display<N>( &self, unit: N, ) -> RandomQuantity<&RandomVariable<Quantity<D, U, V>, M>, D, U, V, N, M>

where N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,

Returns a borrowed displayable object that can be used as a format argument and displays the computed statistical moments with units of measurement in abbreviated form.

pub fn displayed<N>( self, unit: N, ) -> RandomQuantity<RandomVariable<Quantity<D, U, V>, M>, D, U, V, N, M>

where N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,

Returns an owning displayable object that can be used as a format argument and displays the computed statistical moments with units of measurement in abbreviated form.

pub fn display_full<N>( &self, unit: N, ) -> RandomQuantity<&RandomVariable<Quantity<D, U, V>, M>, D, U, V, N, M>

where N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,

Returns a borrowed displayable object that can be used as a format argument and displays the computed statistical moments with units of measurement in descriptive form.

pub fn displayed_full<N>( self, unit: N, ) -> RandomQuantity<RandomVariable<Quantity<D, U, V>, M>, D, U, V, N, M>

where N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,

Returns an owned displayable object that can be used as a format argument and displays the computed statistical moments with units of measurement in descriptive form.

Trait Implementations

impl<S, const M: usize> Clone for RandomVariable<S, M>

where S: Weighable,

fn clone(&self) -> RandomVariable<S, M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> Debug for RandomVariable<S>

where S: Weighable, <S as Weighable>::Sample: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S> Debug for RandomVariable<S, 0>

where S: Weighable, <S as Weighable>::Sample: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S> Debug for RandomVariable<S, 1>

where S: Weighable, <S as Weighable>::Sample: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S> Debug for RandomVariable<S, 3>

where S: Weighable, <S as Weighable>::Sample: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S> Debug for RandomVariable<S, 4>

where S: Weighable, <S as Weighable>::Sample: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S, const M: usize> Default for RandomVariable<S, M>

where S: Weighable,

fn default() -> RandomVariable<S, M>

Returns the “default value” for a type.

impl<S1, S2> PartialEq<RandomVariable<S2>> for RandomVariable<S1>

where S1: Weighable, S2: Weighable<Sample = <S1 as Weighable>::Sample>,

fn eq(&self, other: &RandomVariable<S2>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.