Struct distimate::Normal

pub struct Normal { /* private fields */ }

Represents a modified Normal distribution for estimation purposes.

This Normal distribution is defined by minimum, most likely (mode), and maximum values. It uses these to create an underlying standard Normal distribution, but provides methods to work within the specified range.

Examples

use distimate::prelude::*;
use distimate::Normal;
use approx::assert_relative_eq;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.min(), 1.0);
assert_eq!(normal.mode(), 2.0);
assert_eq!(normal.max(), 3.0);

Implementations

impl Normal

pub fn new(min: f64, likely: f64, max: f64) -> Result<Self>

Creates a new Normal distribution with the given minimum, most likely (mode), and maximum values.

Arguments

• min - The minimum value of the distribution
• likely - The most likely value (mode) of the distribution
• max - The maximum value of the distribution

Returns

Returns a Result containing the new Normal instance if the parameters are valid, or an Error if the parameters are invalid.

Errors

Returns an error if:

• min is greater than or equal to max
• likely is less than min or greater than max

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.min(), 1.0);
assert_eq!(normal.mode(), 2.0);
assert_eq!(normal.max(), 3.0);

Trait Implementations

impl Clone for Normal

fn clone(&self) -> Normal

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Continuous<f64, f64> for Normal

Implementation of the Continuous trait for the Normal distribution.

This implementation provides methods to calculate the probability density function (PDF) and its natural logarithm for the Normal distribution, adapted for estimation scenarios with specified minimum and maximum values.

fn pdf(&self, x: f64) -> f64

Calculates the probability density function (PDF) of the Normal distribution at a given point.

The PDF represents the relative likelihood of the distribution taking on a specific value. For this adapted Normal distribution, the PDF is set to 0 for values outside the [min, max] range.

Arguments

• x - The point at which to calculate the PDF

Returns

The value of the PDF at the given point as an f64. Returns 0 if x is outside the [min, max] range.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert!(normal.pdf(2.0) > 0.0);
assert_eq!(normal.pdf(0.0), 0.0); // Outside the distribution's range

fn ln_pdf(&self, x: f64) -> f64

Calculates the natural logarithm of the probability density function (PDF) of the Normal distribution at a given point.

This method is particularly useful for numerical stability in calculations involving very small probability densities. For this adapted Normal distribution, the ln_pdf is set to negative infinity for values outside the [min, max] range.

Arguments

• x - The point at which to calculate the log PDF

Returns

The natural logarithm of the PDF at the given point as an f64. Returns negative infinity if x is outside the [min, max] range.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert!(normal.ln_pdf(2.0).is_finite());
assert_eq!(normal.ln_pdf(0.0), f64::NEG_INFINITY); // Outside the distribution's range

impl ContinuousCDF<f64, f64> for Normal

Implementation of the ContinuousCDF trait for the Normal distribution.

This implementation provides methods to calculate the cumulative distribution function (CDF) and its inverse for the Normal distribution, adapted for estimation scenarios with specified minimum and maximum values.

fn cdf(&self, x: f64) -> f64

Calculates the cumulative distribution function (CDF) of the Normal distribution at a given point.

The CDF represents the probability that a random variable from this distribution will be less than or equal to the given value. For this adapted Normal distribution, the CDF is clamped to 0 for values below the minimum and to 1 for values above the maximum.

Arguments

• x - The point at which to calculate the CDF

Returns

The value of the CDF at the given point as an f64, in the range [0, 1].

Examples

use distimate::prelude::*;
use distimate::Normal;
use approx::assert_relative_eq;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_relative_eq!(normal.cdf(2.0), 0.5, epsilon = 1e-6);
assert_eq!(normal.cdf(0.0), 0.0); // Below minimum
assert_eq!(normal.cdf(4.0), 1.0); // Above maximum

fn inverse_cdf(&self, p: f64) -> f64

Calculates the inverse of the cumulative distribution function (inverse CDF) of the Normal distribution for a given probability.

This function is also known as the quantile function. It returns the value x for which P(X ≤ x) = p, where p is the given probability. For this adapted Normal distribution, the result is clamped to the [min, max] range.

Arguments

• p - The probability for which to calculate the inverse CDF, must be in the range [0, 1]

Returns

The value x for which the CDF of the distribution equals the given probability, clamped to the [min, max] range of the distribution.

Examples

use distimate::prelude::*;
use distimate::Normal;
use approx::assert_relative_eq;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_relative_eq!(normal.inverse_cdf(0.5), 2.0, epsilon = 1e-6);
assert_eq!(normal.inverse_cdf(0.0), 1.0); // Clamped to minimum
assert_eq!(normal.inverse_cdf(1.0), 3.0); // Clamped to maximum

fn sf(&self, x: K) -> T

Returns the survival function calculated at x for a given distribution. May panic depending on the implementor.

impl Debug for Normal

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

Formats the value using the given formatter.

impl Distribution<f64> for Normal

Implementation of the Distribution trait for the Normal distribution.

This implementation provides methods to calculate various statistical properties of the Normal distribution, adapted for estimation scenarios with specified minimum, most likely (mode), and maximum values.

Note

The calculated values are based on the underlying Normal distribution and may theoretically extend beyond the specified [min, max] range. For practical estimation purposes, you may want to consider clamping extreme values.

fn mean(&self) -> Option<f64>

Calculates the mean of the Normal distribution.

For this adapted Normal distribution, the mean is equal to the most likely value (mode).

Returns

Returns Some(mean) where mean is the most likely value specified during construction.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.mean(), Some(2.0));

fn variance(&self) -> Option<f64>

Calculates the variance of the Normal distribution.

The variance is calculated based on the standard deviation derived from the specified min and max values during construction.

Returns

Returns Some(variance) where variance is the square of the standard deviation.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.variance().unwrap(), 0.1111111111111111); // (1/3)^2

fn skewness(&self) -> Option<f64>

Calculates the skewness of the Normal distribution.

The Normal distribution is always symmetric, so the skewness is always 0.

Returns

Always returns Some(0.0).

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.skewness(), Some(0.0));

fn entropy(&self) -> Option<f64>

Calculates the entropy of the Normal distribution.

The entropy is a measure of the average amount of information contained in the distribution. For a Normal distribution, it depends on the standard deviation.

Returns

Returns Some(entropy) where entropy is calculated based on the standard deviation of the distribution.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert!(normal.entropy().is_some());

fn std_dev(&self) -> Option<T>

Returns the standard deviation, if it exists.

impl Distribution<f64> for Normal

Implementation of the rand::distributions::Distribution trait for the Normal distribution.

This implementation allows for random sampling from the Normal distribution adapted for estimation scenarios, using any random number generator that implements the rand::Rng trait.

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> f64

Generates a random sample from the Normal distribution.

This method uses the underlying Normal distribution to generate a sample, then clamps the result to ensure it falls within the specified [min, max] range. This approach maintains the shape of the Normal distribution within the specified range while ensuring all samples are valid for the estimation scenario.

Arguments

• rng - A mutable reference to a random number generator that implements the rand::Rng trait

Returns

A random sample from the Normal distribution as an f64, guaranteed to be within the [min, max] range specified during the distribution’s construction.

Examples

use distimate::prelude::*;
use distimate::Normal;
use rand::prelude::*;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
let mut rng = StdRng::seed_from_u64(42);  // For reproducibility

let sample = normal.sample(&mut rng);
assert!(sample >= 1.0 && sample <= 3.0);

Note

While this method ensures all samples fall within the specified range, it may lead to a slight overrepresentation of the minimum and maximum values compared to a true Normal distribution. This trade-off is often acceptable in practical estimation scenarios where staying within the specified range is crucial.

fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>

where R: Rng, Self: Sized,

Create an iterator that generates random values of T, using rng as the source of randomness.

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Create a distribution of values of ‘S’ by mapping the output of Self through the closure F

impl EstimationDistribution for Normal

Implementation of the EstimationDistribution trait for the Normal distribution.

This trait marks the Normal distribution as suitable for use in estimation contexts. It doesn’t add any new methods, but signals that this distribution is appropriate for modeling uncertain estimates or measurements within a specified range.

The Normal distribution in this context is particularly useful when:

• There’s a most likely value (mode) with symmetric uncertainty around it.
• The minimum and maximum values represent extreme scenarios.
• The underlying process is believed to follow a bell-shaped curve.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
// The Normal distribution can now be used in contexts requiring an EstimationDistribution

fn percentile_estimate(&self, p: f64) -> Result<f64>

Returns the estimate at a given percentile.

fn optimistic_estimate(&self) -> f64

Returns the optimistic (best-case) estimate, typically the 5th percentile.

fn pessimistic_estimate(&self) -> f64

Returns the pessimistic (worst-case) estimate, typically the 95th percentile.

fn most_likely_estimate(&self) -> f64

Returns the most likely estimate (mode).

fn expected_value(&self) -> f64

Returns the expected value (mean) of the distribution.

fn uncertainty(&self) -> f64

Returns the standard deviation of the distribution.

fn probability_of_completion(&self, estimate: f64) -> f64

Calculates the probability of completing a task or project by a given estimate.

fn risk_of_overrun(&self, estimate: f64) -> f64

Calculates the risk of exceeding a given estimate.

fn confidence_interval(&self, confidence_level: f64) -> (f64, f64)

Returns a confidence interval for the estimate.

fn evaluate_fit_quality(&self, data: &[f64]) -> Result<EstimationFitQuality>

Evaluates how well the distribution fits a given dataset in the context of estimation.

fn calculate_within_interval( &self, data: &[f64], lower_percentile: f64, upper_percentile: f64, ) -> Result<f64>

Helper method to calculate the proportion of data within a given interval.

impl Max<f64> for Normal

Implementation of the Max trait for the Normal distribution.

This implementation provides a method to retrieve the maximum value of the Normal distribution adapted for estimation scenarios.

fn max(&self) -> f64

Returns the maximum value of the Normal distribution.

In the context of this estimation-focused Normal distribution, the maximum value represents the upper bound of the possible outcomes. It’s one of the three key parameters (along with the minimum value and the most likely value) used to define this adapted Normal distribution.

Returns

The maximum value of the distribution as an f64.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.max(), 3.0);

Note

While a standard Normal distribution extends infinitely in both directions, this adapted version for estimation purposes has a defined maximum value. This allows for more practical modeling in scenarios where there’s a known upper limit to possible outcomes.

impl Median<f64> for Normal

Implementation of the Median trait for the Normal distribution.

For a Normal distribution adapted for estimation purposes, the median is equal to the most likely value (mode) specified during construction. This is because the Normal distribution is symmetric around its mean, which in this case is set to the most likely value.

fn median(&self) -> f64

Calculates the median of the Normal distribution.

For this adapted Normal distribution, the median is equal to the most likely value (mode) specified during construction.

Returns

Returns the median of the distribution as an f64 value.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.median(), 2.0);

Note

In a standard Normal distribution, the median, mean, and mode are all equal. In this adapted version for estimation, we maintain this property by setting all of these to the most likely value provided during construction.

impl Min<f64> for Normal

Implementation of the Min trait for the Normal distribution.

This implementation provides a method to retrieve the minimum value of the Normal distribution adapted for estimation scenarios.

fn min(&self) -> f64

Returns the minimum value of the Normal distribution.

In the context of this estimation-focused Normal distribution, the minimum value represents the lower bound of the possible outcomes. It’s one of the three key parameters (along with the most likely value and the maximum) used to define this adapted Normal distribution.

Returns

The minimum value of the distribution as an f64.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.min(), 1.0);

Note

While a standard Normal distribution extends infinitely in both directions, this adapted version for estimation purposes has a defined minimum value. This allows for more practical modeling in scenarios where there’s a known lower limit to possible outcomes.

impl Mode<f64> for Normal

Implementation of the Mode trait for the Normal distribution.

For a Normal distribution adapted for estimation purposes, the mode is set to the most likely value specified during construction. This aligns with the typical use case in estimation scenarios where the most likely value is known.

fn mode(&self) -> f64

Returns the mode of the Normal distribution.

The mode is the most likely value of the distribution, which in this case is explicitly set during the construction of the Normal distribution instance.

Returns

Returns the mode of the distribution as an f64 value, which is equal to the ‘likely’ value provided when creating the distribution.

Examples

use distimate::prelude::*;
use distimate::Normal;

let normal = Normal::new(1.0, 2.0, 3.0).unwrap();
assert_eq!(normal.mode(), 2.0);

Note

In a standard Normal distribution, the mode, median, and mean are all equal. In this adapted version for estimation, we maintain this property by setting all of these to the most likely value provided during construction.