Statrs

https://github.com/statrs-dev/statrs
Admin
Statrs is a statistical computing library for Rust that provides common probability distributions,...
Tokens:88,283
Snippets:573
Trust Score:-
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Harmonic module usage examples

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-misc.md

Usage examples for the harmonic module functions. Shows expected results for `harmonic` and `gen_harmonic`.

```rust
use statrs::function::harmonic;

assert!((harmonic::harmonic(1) - 1.0).abs() < 1e-12);
assert!((harmonic::gen_harmonic(2, 2) - 1.25).abs() < 1e-12);
```

--------------------------------

### 1-D density estimation example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/density.md

Example from the source docs showing both knn_pdf and kde_pdf on a 1-D sample set with a fixed bandwidth. Asserts both densities are positive.

```rust
use statrs::density::knn::knn_pdf;
use statrs::density::kde::kde_pdf;

let samples: Vec<[f64; 1]> = vec![[-1.0], [0.0], [1.0]];
let knn = knn_pdf(&[0.0], &samples, Some(1.0)).unwrap();
let kde = kde_pdf(&[0.0], &samples, Some(1.0)).unwrap();
assert!(knn > 0.0 && kde > 0.0);
```

--------------------------------

### Basic Binomial example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-binomial.md

Basic usage example: creates a Binomial with p=0.5 and n=10, then checks mean, variance, p, and n accessors.

```rust
use statrs::distribution::Binomial;
use statrs::statistics::Distribution;

let n = Binomial::new(0.5, 10).unwrap();
assert_eq!(n.mean(), Some(5.0));
assert_eq!(n.variance(), Some(2.5));
assert_eq!(n.p(), 0.5);
assert_eq!(n.n(), 10);
```

--------------------------------

### Factorial module usage examples

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-misc.md

Usage examples for the factorial module functions. Shows expected results for `factorial`, `binomial`, `multinomial`, and `checked_multinomial`.

```rust
use statrs::function::factorial;

assert_eq!(factorial::factorial(5), 120.0);
assert_eq!(factorial::binomial(10, 3), 120.0);
assert_eq!(factorial::multinomial(10, &[2, 2]), 1260.0);
assert_eq!(factorial::checked_multinomial(10, &[1, 2, 3]), Some(12600.0));
```

--------------------------------

### Kernel usage example with Gaussian and Epanechnikov

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-misc.md

Demonstrates using the `Gaussian` and `Epanechnikov` kernels. The example checks the Gaussian evaluation at zero, its unbounded support, bandwidth scaling, and the bounded support of `Epanechnikov`.

```rust
use statrs::function::kernel::{Gaussian, Kernel};

let g = Gaussian;
// Gaussian evaluates to (1/sqrt(2π)) * exp(-x²/2); at x = 0: 1/sqrt(2π)
assert!((g.evaluate(0.0) - 1.0 / (2.0 * std::f64::consts::PI).sqrt()).abs() < 1e-15);
assert_eq!(g.support(), None);
assert_eq!(g.evaluate_with_bandwidth(0.0, 2.0), g.evaluate(0.0) / 2.0);
// bounded kernel example
use statrs::function::kernel::Epanechnikov;
assert_eq!(Epanechnikov.support(), Some((-1.0, 1.0)));
```

--------------------------------

### Binomial error handling example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-binomial.md

Error handling example: attempts to create a Binomial with p=1.5 (invalid) and matches on the error variant.

```rust
use statrs::distribution::{Binomial, BinomialError};

match Binomial::new(1.5, 10) {
    Err(BinomialError::ProbabilityInvalid) => println!("p must be in [0, 1]"),
    Ok(b) => println!("mean {}", b.mean().unwrap()),
    Err(_) => unreachable!(),
}
```

--------------------------------

### 2-D kde_pdf with nalgebra vectors

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/density.md

2-D example using nalgebra Vector2 samples and automatic bandwidth (None). Asserts the result is finite.

```rust
use statrs::density::kde::kde_pdf;
use nalgebra::Vector2;

let samples = vec![Vector2::new(0.0, 0.0), Vector2::new(1.0, 1.0), Vector2::new(-1.0, 1.0)];
let d = kde_pdf(&Vector2::new(0.0, 0.0), &samples, None).unwrap();
assert!(d.is_finite());
```

--------------------------------

### Logistic and logit usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-misc.md

Shows how to use `logistic`, `logit`, and `checked_logit` from `statrs::function::logistic`. The example asserts expected values, including `None` for an out-of-range input.

```rust
use statrs::function::logistic;

assert_eq!(logistic::logistic(0.0), 0.5);
assert_eq!(logistic::logit(0.5), 0.0);
assert_eq!(logistic::checked_logit(1.5), None); // out of range
```

--------------------------------

### Beta usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-1.md

Creates a Beta distribution with shape_a=2.0 and shape_b=3.0, verifies accessors, and checks that invalid parameters return an error.

```rust
use statrs::distribution::Beta;

let b = Beta::new(2.0, 3.0).unwrap();
assert_eq!(b.shape_a(), 2.0);
assert_eq!(b.shape_b(), 3.0);
assert!(Beta::new(0.0, 3.0).is_err()); // BetaError::ShapeAInvalid
```

--------------------------------

### ContinuousCDF usage example with Uniform

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-traits.md

Example from the trait docs showing how to use cdf and sf on a Uniform distribution. It creates a Uniform(0,1) distribution and asserts that both cdf(0.5) and sf(0.5) equal 0.5.

```rust
use statrs::distribution::{ContinuousCDF, Uniform};

let n = Uniform::new(0.0, 1.0).unwrap();
assert_eq!(0.5, n.cdf(0.5));
assert_eq!(0.5, n.sf(0.5));
```

--------------------------------

### Min trait usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-traits.md

Example usage of the Min trait on a Uniform distribution. Creates a uniform distribution over [0.0, 1.0] and asserts that the minimum is 0.0.

```rust
use statrs::statistics::Min;
use statrs::distribution::Uniform;

let n = Uniform::new(0.0, 1.0).unwrap();
assert_eq!(0.0, n.min());
```

--------------------------------

### Order statistics example with Data

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-data.md

Demonstrates using Data with OrderStatistics methods: median, quantile, percentile, and ranks with different tie breakers. Note that ranks requires cloning because methods take &mut self.

```rust
use statrs::statistics::{Data, OrderStatistics, RankTieBreaker};

let mut y = Data::new([1.0, 3.0, 2.0, 2.0]);
assert_eq!(y.median(), 2.0);
assert_eq!(y.quantile(0.5), 2.0);
assert_eq!(y.percentile(100), 3.0);
assert_eq!(y.clone().ranks(RankTieBreaker::Average), [1.0, 4.0, 2.5, 2.5]);
assert_eq!(y.clone().ranks(RankTieBreaker::Min), [1.0, 4.0, 2.0, 2.0]);
```

--------------------------------

### Bernoulli usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a Bernoulli distribution with p=0.5, checks the probability and PMF, and verifies that an invalid probability returns an error.

```rust
use statrs::distribution::Bernoulli;
use statrs::distribution::Discrete;

let coin = Bernoulli::new(0.5).unwrap();
assert_eq!(coin.p(), 0.5);
assert_eq!(coin.pmf(1), 0.5);
let bad = Bernoulli::new(-0.5);
assert!(bad.is_err()); // BinomialError::ProbabilityInvalid
```

--------------------------------

### Median usage example with Normal

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-traits.md

Shows how to use the Median trait with a Normal distribution. Creates a standard normal and asserts its median is 0.0.

```rust
use statrs::statistics::Median;
use statrs::distribution::Normal;

let n = Normal::new(0.0, 1.0).unwrap();
assert_eq!(0.0, n.median());
```

--------------------------------

### Max trait usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-traits.md

Example usage of the Max trait on a Uniform distribution. Creates a uniform distribution over [0.0, 1.0] and asserts that the maximum is 1.0.

```rust
use statrs::statistics::Max;
use statrs::distribution::Uniform;

let n = Uniform::new(0.0, 1.0).unwrap();
assert_eq!(1.0, n.max());
```

--------------------------------

### Chi usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-1.md

Creates a Chi distribution with freedom=3, verifies the accessor, and checks that freedom=0 returns an error.

```rust
use statrs::distribution::Chi;

let chi = Chi::new(3).unwrap();
assert_eq!(chi.freedom(), 3);
assert!(Chi::new(0).is_err());
```

--------------------------------

### NegativeBinomial::new example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a NegativeBinomial with r=5.0 and p=0.5, then verifies the accessors r() and p() return the expected values. Requires the statrs crate.

```rust
use statrs::distribution::NegativeBinomial;

let nb = NegativeBinomial::new(5.0, 0.5).unwrap();
assert_eq!(nb.r(), 5.0);
assert_eq!(nb.p(), 0.5);
```

--------------------------------

### Poisson::new example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a Poisson with lambda=3.5 and verifies the lambda() accessor. Also checks that constructing with lambda=0.0 returns an error (PoissonError::LambdaInvalid).

```rust
use statrs::distribution::Poisson;

let p = Poisson::new(3.5).unwrap();
assert_eq!(p.lambda(), 3.5);
assert!(Poisson::new(0.0).is_err()); // PoissonError::LambdaInvalid
```

--------------------------------

### Handling DensityError::EmptySample

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/density.md

Error-handling example: calling kde_pdf with an empty sample set returns DensityError::EmptySample, which is matched explicitly.

```rust
use statrs::density::{kde::kde_pdf, DensityError};

let empty: Vec<[f64; 1]> = vec![];
match kde_pdf(&[0.0], &empty, Some(1.0)) {
    Err(DensityError::EmptySample) => println!("provide samples"),
    Ok(d) => println!("density = {d}"),
    Err(e) => println!("other: {e}"),
}
```

--------------------------------

### Exponential integral usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-misc.md

Demonstrates exponential::integral with x=1, n=1 returning a positive value, and with x=-1 returning None.

```rust
use statrs::function::exponential;

let e = exponential::integral(1.0, 1).unwrap(); // E1(1) ≈ 0.21938
assert!(e > 0.0);
assert!(exponential::integral(-1.0, 1).is_none());
```

--------------------------------

### Distribution trait usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-traits.md

Example usage of the Distribution trait on an exponential distribution. Creates an Exp distribution with rate 1.0 and asserts that mean, variance, entropy, and skewness return the expected Some values.

```rust
use statrs::distribution::Exp;
use statrs::statistics::Distribution;

let n = Exp::new(1.0).unwrap();
assert_eq!(n.mean(), Some(1.0));
assert_eq!(n.variance(), Some(1.0));
assert_eq!(n.entropy(), Some(1.0));
assert_eq!(n.skewness(), Some(2.0));
```

--------------------------------

### gamma_lr and gamma_ur usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-gamma.md

Basic usage of the regularized lower and upper incomplete gamma functions. Verifies that P(a,x) + Q(a,x) equals 1 within 1e-12 for a=2.0 and x=1.5.

```rust
use statrs::function::gamma::{gamma_lr, gamma_ur};

// P(a,x) + Q(a,x) == 1
let a = 2.0;
let x = 1.5;
assert!((gamma_lr(a, x) + gamma_ur(a, x) - 1.0).abs() < 1e-12);
```

--------------------------------

### Categorical usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a Categorical distribution from an unnormalized probability slice and verifies the PMF after auto-normalization.

```rust
use statrs::distribution::{Categorical, Discrete};

let c = Categorical::new(&[0.0, 1.0, 2.0]).unwrap(); // auto-normalized
assert_eq!(c.pmf(2), 0.5);
```

--------------------------------

### gamma and ln_gamma usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-gamma.md

Basic usage of gamma and ln_gamma. Verifies that gamma(5.0) equals 24.0 and ln_gamma(5.0) equals the natural log of 24.

```rust
use statrs::function::gamma;

assert_eq!(gamma::gamma(5.0), 24.0);
assert_eq!(gamma::ln_gamma(5.0), 24f64.ln());
```

--------------------------------

### MultivariateStudent example usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-multivariate.md

Creates a 2-dimensional MultivariateStudent with location [0,0], scale identity (row-major 2x2), and freedom 5.0. Asserts dimension and freedom values.

```rust
use statrs::distribution::MultivariateStudent;

let t = MultivariateStudent::new(
    vec![0.0, 0.0],                    // location
    vec![1.0, 0.0, 0.0, 1.0],         // scale (row-major 2x2)
    5.0,                                // freedom
).unwrap();
assert_eq!(t.dim(), 2);
assert_eq!(t.freedom(), 5.0);
```

--------------------------------

### Random sampling with Exp and rand::distr::Distribution

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/index.md

Shows how to sample from an exponential distribution using statrs and rand. Requires the rand feature and bringing rand::distr::Distribution into scope. The example seeds a StdRng with seed 0 and prints the sampled value.

```rust
use statrs::distribution::Exp;
use rand::distr::Distribution;
use rand::SeedableRng;
let mut r = rand::rngs::StdRng::seed_from_u64(0);
let n = Exp::new(0.5).unwrap();
print!("{}", n.sample(&mut r));
```

--------------------------------

### DiscreteCDF usage example with DiscreteUniform

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-traits.md

Shows how to use the DiscreteCDF trait with a DiscreteUniform distribution. Creates a uniform distribution from 1 to 10 and checks the CDF and survival function at x=6.

```rust
use statrs::distribution::{DiscreteCDF, DiscreteUniform};

let n = DiscreteUniform::new(1, 10).unwrap();
assert_eq!(0.6, n.cdf(6));
assert_eq!(0.4, n.sf(6));
```

--------------------------------

### checked_gamma_lr error handling example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-gamma.md

Error handling example for checked_gamma_lr. Passing a=-1.0 triggers GammaFuncError::AInvalid, printing "a must be > 0". The Ok arm prints the value and the catch-all Err is unreachable.

```rust
use statrs::function::gamma::{checked_gamma_lr, GammaFuncError};

match checked_gamma_lr(-1.0, 1.0) {
    Err(GammaFuncError::AInvalid) => println!("a must be > 0"),
    Ok(p) => println!("P = {p}"),
    Err(_) => unreachable!(),
}
```

--------------------------------

### Geometric usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a Geometric with p=0.25, checks the p accessor, and verifies that p=1.5 returns a ProbabilityInvalid error.

```rust
use statrs::distribution::Geometric;

let g = Geometric::new(0.25).unwrap();
assert_eq!(g.p(), 0.25);
assert!(Geometric::new(1.5).is_err()); // GeometricError::ProbabilityInvalid
```

--------------------------------

### Hypergeometric usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a Hypergeometric with population=50, successes=10, draws=5, checks the population accessor, and verifies that successes>population returns a TooManySuccesses error.

```rust
use statrs::distribution::Hypergeometric;

let h = Hypergeometric::new(50, 10, 5).unwrap();
assert_eq!(h.population(), 50);
assert!(Hypergeometric::new(10, 20, 5).is_err()); // TooManySuccesses
```

--------------------------------

### Exp struct and usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-1.md

Exp is the exponential distribution. The constructor returns ExpError::RateInvalid when rate is NaN or <= 0. The example creates an Exp with rate 1.0, checks the rate accessor and mean, and verifies that a zero rate is an error.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Exp { rate: f64 }
```

```rust
use statrs::distribution::Exp;
use statrs::statistics::Distribution;

let e = Exp::new(1.0).unwrap();
assert_eq!(e.rate(), 1.0);
assert_eq!(e.mean(), Some(1.0));
assert!(Exp::new(0.0).is_err()); // ExpError::RateInvalid
```

--------------------------------

### Use Discrete trait with Binomial distribution

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-traits.md

Example from trait docs showing how to use the `Discrete` trait. It creates a `Binomial` distribution with success probability 0.5 and 10 trials, then verifies the pmf at 5 successes using an approximate equality assertion from `approx`.

```rust
use statrs::distribution::{Discrete, Binomial};
use approx::assert_abs_diff_eq;

let n = Binomial::new(0.5, 10).unwrap();
assert_abs_diff_eq!(n.pmf(5), 0.24609375, epsilon = 1e-15);
```

--------------------------------

### Normal error handling example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

Error handling for Normal::new when the standard deviation is zero. The match handles the StandardDeviationInvalid error and prints a message.

```rust
use statrs::distribution::{Normal, NormalError};

match Normal::new(0.0, 0.0) {
    Err(NormalError::StandardDeviationInvalid) => println!("std_dev must be > 0"),
    Ok(n) => println!("mean {}", n.mean().unwrap()),
    Err(_) => unreachable!(),
}
```

--------------------------------

### DiscreteUniform usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Creates a DiscreteUniform with min=1 and max=6, checks min/max accessors, computes the CDF at 3 (0.5), and verifies that an invalid range (6,1) returns an error.

```rust
use statrs::distribution::{DiscreteCDF, DiscreteUniform};

let die = DiscreteUniform::new(1, 6).unwrap();
assert_eq!(die.min(), 1);
assert_eq!(die.max(), 6);
assert_eq!(die.cdf(3), 0.5);
assert!(DiscreteUniform::new(6, 1).is_err());
```

--------------------------------

### Discrete Distributions: Bernoulli and Categorical

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-discrete.md

Documentation for the Bernoulli and Categorical discrete distributions from the statrs Rust library, including constructors, methods, error handling, and usage examples.

```APIDOC
## Bernoulli

### Description
A Bernoulli distribution, which is a Binomial with n = 1. It represents a single trial with a given probability of success.

### Constructor
`new(p: f64) -> Result<Bernoulli, BinomialError>`

### Parameters
- **p** (f64) - Required - Probability of success. Must be in the range [0, 1] and not NaN.

### Errors
- Returns `BinomialError` if `p` is NaN or outside `[0, 1]`.

### Methods
- `p(&self) -> f64` - Returns the probability of success.
- `n(&self) -> u64` - Returns the number of trials, always 1.

### Example
```rust
use statrs::distribution::Bernoulli;
use statrs::distribution::Discrete;

let coin = Bernoulli::new(0.5).unwrap();
assert_eq!(coin.p(), 0.5);
assert_eq!(coin.pmf(1), 0.5);
let bad = Bernoulli::new(-0.5);
assert!(bad.is_err()); // BinomialError::ProbabilityInvalid
```

## Categorical

### Description
A categorical distribution over a set of categories with given probabilities. The probabilities need not be normalized; they are automatically normalized.

### Constructor
`new(prob_mass: &[f64]) -> Result<Categorical, CategoricalError>`

### Parameters
- **prob_mass** (&[f64]) - Required - Slice of probabilities for each category. Must not be empty, must sum to a non-zero value, and must not contain NaN or negative values.

### Errors
- `ProbMassEmpty` - if the slice is empty.
- `ProbMassSumZero` - if the sum of probabilities is zero.
- `ProbMassHasInvalidElements` - if any element is NaN or negative.

### Example
```rust
use statrs::distribution::{Categorical, Discrete};

let c = Categorical::new(&[0.0, 1.0, 2.0]).unwrap(); // auto-normalized
assert_eq!(c.pmf(2), 0.5);
```

### Error Handling Example
```rust
use statrs::distribution::{Categorical, CategoricalError};

match Categorical::new(&[0.0, -1.0, 2.0]) {
    Err(CategoricalError::ProbMassHasInvalidElements) => println!("negative probability"),
    Err(e) => println!("{e}"),
    Ok(_) => unreachable!(),
}
```
```

--------------------------------

### Use Continuous trait with Uniform distribution

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-traits.md

Example from trait docs showing how to use the `Continuous` trait. It creates a `Uniform` distribution and computes `pdf` and `ln_pdf` at a point. Note that `ln_pdf(0.5)` returns `0.0` for a standard uniform distribution.

```rust
use statrs::distribution::{Continuous, Uniform};

let n = Uniform::new(0.0, 1.0).unwrap();
assert_eq!(1.0, n.pdf(0.5));
assert_eq!(0.0, n.ln_pdf(0.5));
```

--------------------------------

### Error function usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-misc.md

Demonstrates erf and erfc with assertions: erf(0.0) is 0, erf(inf) is 1, and erf(1.0) + erfc(1.0) equals 1 within tolerance.

```rust
use statrs::function::erf;

assert!((erf(0.0) - 0.0).abs() < 1e-15);
assert_eq!(erf(f64::INFINITY), 1.0);
assert!((erf(1.0) + erfc(1.0) - 1.0).abs() < 1e-12);
```

--------------------------------

### Dirichlet construction and error example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-multivariate.md

Constructs Dirichlet from a Vec and from a constant concentration, checks alpha lengths, and verifies that a negative element yields an AlphaHasInvalidElements error.

```rust
use statrs::distribution::Dirichlet;

let d = Dirichlet::new(vec![2.0, 3.0, 4.0]).unwrap();
assert_eq!(d.alpha().len(), 3);
let d2 = Dirichlet::new_with_param(2.0, 5).unwrap();
assert_eq!(d2.alpha().len(), 5);
assert!(Dirichlet::new(vec![1.0, -1.0]).is_err()); // AlphaHasInvalidElements
```

--------------------------------

### digamma and inv_digamma usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/function-gamma.md

Usage of digamma and inv_digamma. Checks that digamma(1.0) is near -0.577 (Euler's constant) and that inv_digamma(0.0) yields a value whose digamma is near 0.

```rust
use statrs::function::gamma::{digamma, inv_digamma};

assert!((digamma(1.0).abs() < 1e-10); // ψ(1) = -γ, -0.577...
let x = inv_digamma(0.0);              // ≈ 1.4616...
assert!((digamma(x) - 0.0).abs() < 1e-6);
```

--------------------------------

### MultivariateNormal distribution: struct, constructors, errors, methods, and examples

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-multivariate.md

MultivariateNormal distribution: struct, constructors, error enum, methods, and two usage examples. The constructors validate covariance symmetry and positive-definiteness (except new_from_cholesky which uses the lower triangle only). The basic example creates a 2D normal and checks mu length and entropy. The error-handling example matches CovInvalid for a non-symmetric covariance.

```rust
pub struct MultivariateNormal<D> { /* private */ }
```

```rust
pub fn new(mean: Vec<f64>, cov: Vec<f64>) -> Result<Self, MultivariateNormalError>
pub fn new_from_nalgebra(mean: OVector<f64, D>, cov: OMatrix<f64, D, D>) -> Result<Self, MultivariateNormalError>
pub fn new_from_cholesky(mean: OVector<f64, D>, cholesky: Cholesky<f64, D>) -> Result<Self, MultivariateNormalError>
```

```rust
pub enum MultivariateNormalError {
    CovInvalid,        // covariance asymmetric or contains NaN
    MeanInvalid,       // mean contains NaN
    DimensionMismatch, // mean rows != covariance rows
    CholeskyFailed,    // Cholesky decomposition failed
}
```

```rust
pub fn entropy(&self) -> Option<f64>
pub fn clone_cov_chol_decomp(&self) -> OMatrix<f64, D, D>
pub fn mu(&self) -> &OVector<f64, D>
pub fn cov(&self) -> &OMatrix<f64, D, D>
pub fn precision(&self) -> &OMatrix<f64, D, D>
```

```rust
use statrs::distribution::MultivariateNormal;

let mvn = MultivariateNormal::new(vec![0.0, 0.0], vec![1.0, 0.0, 0.0, 0.5]).unwrap();
assert_eq!(mvn.mu().len(), 2);
assert!(mvn.entropy().is_some());
```

```rust
use statrs::distribution::{MultivariateNormal, MultivariateNormalError};

match MultivariateNormal::new(vec![0.0, 0.0], vec![1.0, 1.0, 1.0, 1.0]) {
    Err(MultivariateNormalError::CovInvalid) => println!("covariance not symmetric/positive-definite"),
    Ok(mvn) => println!("entropy {:?}", mvn.entropy()),
    Err(_) => unreachable!(),
}
```

--------------------------------

### Usage example for Statistics methods

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-data.md

Shows how to use the Statistics trait on arrays and iterators, including mean, variance, population_variance, std_dev, and covariance. Note that covariance returns a negative value for inversely correlated data.

```rust
use statrs::statistics::Statistics;

let data = [1.0, 2.0, 3.0, 4.0, 5.0];
assert_eq!(data.mean(), 3.0);
assert_eq!(data.variance(), 2.5);          // sample (n-1)
assert_eq!(data.population_variance(), 2.0);
assert_eq!(data.std_dev(), 2.5f64.sqrt());

// iterators work too
let mean = (0..100).map(|i| i as f64).mean();
assert!(data.covariance([5.0, 4.0, 3.0, 2.0, 1.0]) < 0.0);
```

--------------------------------

### Two statistics in one fold with Accumulate

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-online.md

Example from source docs: computes mean and variance in a single fold using a tuple of OnlineMean and OnlineVariance with Accumulate::push. Asserts that both mean and variance are Some.

```rust
use statrs::statistics::{Accumulate, OnlineMean, OnlineVariance};

let data = [3.0_f64, -1.0, 4.0, 1.0, -5.0];
let (mean, var): (OnlineMean, OnlineVariance) =
    data.iter().copied().fold(Default::default(), Accumulate::push);

assert!(mean.mean().is_some());
assert!(var.variance().is_some());
```

--------------------------------

### Basic sampling with BinomialAlgorithm::Rejection

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-binomial.md

Shows basic usage of `BinomialSampler` with a non-trivial algorithm selection. Creates a `Binomial` distribution with `p=0.3` and `n=1000`, then builds a sampler using `BinomialAlgorithm::Rejection`. Draws 5 samples from a seeded `StdRng` and asserts the count.

```rust
use rand::{SeedableRng, distr::Distribution, rngs::StdRng};
use statrs::distribution::{Binomial, BinomialAlgorithm};

let dist = Binomial::new(0.3, 1_000).unwrap();
let sampler = dist.sampler(BinomialAlgorithm::Rejection).unwrap();
let mut rng = StdRng::seed_from_u64(0);
let draws: Vec<u64> = sampler.sample_iter(&mut rng).take(5).collect();
assert_eq!(draws.len(), 5);
```

--------------------------------

### Run all suggested tests including NIST

Source: https://github.com/statrs-dev/statrs/blob/main/README.md

Run all suggested tests. First run cargo test, then download NIST data and run ignored NIST tests. Use the STATRS_NIST_DATA_DIR environment variable to modify where data is downloaded.

```sh
cargo test
./tests/gather_nist_data.sh && cargo test -- --include-ignored nist_
```

--------------------------------

### Multinomial distribution: struct, constructors, methods, and example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-multivariate.md

Multinomial distribution: struct definition, constructors, accessors, and a basic usage example. The constructors return errors for invalid probabilities (NotEnoughProbabilities, ProbabilitySumZero, ProbabilityInvalid). The example creates a distribution with probabilities [0.2, 0.3, 0.5] and n=100, then checks n and p length.

```rust
pub struct Multinomial<D> { p: OVector<f64, D>, n: u64 } // private fields
```

```rust
pub fn new(p: Vec<f64>, n: u64) -> Result<Self, MultinomialError>
pub fn new_from_nalgebra(mut p: OVector<f64, D>, n: u64) -> Result<Self, MultinomialError>
```

```rust
pub fn p(&self) -> &OVector<f64, D>
pub fn n(&self) -> u64
```

```rust
use statrs::distribution::Multinomial;

let m = Multinomial::new(vec![0.2, 0.3, 0.5], 100).unwrap();
assert_eq!(m.n(), 100);
assert_eq!(m.p().len(), 3);
```

--------------------------------

### Distribution trait returning None example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-traits.md

Example showing that moments may not exist for all parameters. Creates a FisherSnedecor distribution with freedom_1=1.0 and freedom_2=1.0, and asserts that variance() returns None.

```rust
use statrs::distribution::FisherSnedecor;
use statrs::statistics::Distribution;

let n = FisherSnedecor::new(1.0, 1.0).unwrap();
assert!(n.variance().is_none());
```

--------------------------------

### ttest_onesample usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/stats-tests.md

Example usage of ttest_onesample with a sample vector, a population mean of 13.0, a two-sided alternative, and NaNPolicy::Error. The result is unwrapped to obtain the statistic and p-value.

```rust
use statrs::stats_tests::ttest_onesample::ttest_onesample;
use statrs::stats_tests::{Alternative, NaNPolicy};

let data = Vec::from([13f64, 9f64, 11f64, 8f64, 7f64, 12f64]);
let (statistic, pvalue) = ttest_onesample(data, 13.0, Alternative::TwoSided, NaNPolicy::Error).unwrap();
```

--------------------------------

### Laplace struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

The Laplace struct definition and a usage example. The struct stores location and scale as f64. The example creates a Laplace with location=0.0 and scale=1.0, then checks the location accessor.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Laplace { location: f64, scale: f64 }
```

```rust
use statrs::distribution::Laplace;

let l = Laplace::new(0.0, 1.0).unwrap();
assert_eq!(l.location(), 0.0);
```

--------------------------------

### Gumbel struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

The Gumbel struct definition and a usage example. The struct stores location and scale as f64. The example creates a Gumbel with location=0.0 and scale=1.0, then checks the scale accessor.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Gumbel { location: f64, scale: f64 }
```

```rust
use statrs::distribution::Gumbel;

let g = Gumbel::new(0.0, 1.0).unwrap();
assert_eq!(g.scale(), 1.0);
```

--------------------------------

### Enable nalgebra feature for no_std matrix-backed distributions

Source: https://github.com/statrs-dev/statrs/blob/main/README.md

Enable matrix-backed distributions without std by enabling the nalgebra feature directly. Requires the nalgebra feature in addition to disabling default features.

```toml
[dependencies]
statrs = { version = "*", default-features = false, features = ["nalgebra"] }
```

--------------------------------

### Anderson-Darling test example with Normal distribution

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/stats-tests.md

Example usage of `anderson_darling` with a normal distribution. It creates a sample dataset, runs the test against `Normal::new(0.0, 1.0)`, and asserts the p-value is between 0 and 1.

```rust
use statrs::stats_tests::anderson_darling::anderson_darling;
use statrs::distribution::Normal;

let data = vec![0.1, -0.4, 0.5, 1.2, -0.9, 0.0, 0.3];
let (ad, p) = anderson_darling(&data, &Normal::new(0.0, 1.0).unwrap()).unwrap();
assert!(p > 0.0 && p <= 1.0);
```

--------------------------------

### MultivariateStudent constructors

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-multivariate.md

Constructors for MultivariateStudent. `new` takes a Vec-based location and scale (row-major) with freedom; `new_from_nalgebra` accepts nalgebra vectors and matrices. Validation order for `new_from_nalgebra`: NaN in location → LocationInvalid; scale not square/asymmetric/NaN → ScaleInvalid; freedom NaN or <= 0 → FreedomInvalid; row mismatch → DimensionMismatch; Cholesky failure → CholeskyFailed.

```rust
// impl MultivariateStudent<Dyn>
pub fn new(location: Vec<f64>, scale: Vec<f64>, freedom: f64) -> Result<Self, MultivariateStudentError>
pub fn dim(&self) -> usize   // dimension of the location vector

// impl<D: DimMin<D, Output = D>, DefaultAllocator: ...>
pub fn new_from_nalgebra(
    location: OVector<f64, D>,
    scale: OMatrix<f64, D, D>,
    freedom: f64,
) -> Result<Self, MultivariateStudentError>
```

--------------------------------

### Weibull distribution struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

The Weibull distribution struct definition and a usage example. The struct has private fields shape and scale. The example creates a Weibull distribution with shape 1.5 and scale 1.0, then checks the shape accessor.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Weibull { shape: f64, scale: f64 }
```

```rust
use statrs::distribution::Weibull;

let w = Weibull::new(1.5, 1.0).unwrap();
assert_eq!(w.shape(), 1.5);
```

--------------------------------

### Erlang struct and usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-1.md

Erlang is a gamma distribution with an integer shape. The constructor returns GammaError::ShapeInvalid or RateInvalid when rate is NaN or <= 0. The example creates an Erlang with shape 2 and rate 1.0 and checks the accessors.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Erlang { shape: u64, rate: f64 }
```

```rust
use statrs::distribution::Erlang;

let e = Erlang::new(2, 1.0).unwrap();
assert_eq!(e.shape(), 2);
assert_eq!(e.rate(), 1.0);
```

--------------------------------

### FisherSnedecor struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

The FisherSnedecor struct definition and a usage example. The struct stores freedom_1 and freedom_2 as f64. The example creates a FisherSnedecor with freedom_1=5.0 and freedom_2=10.0, checks the accessor, and verifies that variance() returns None when freedom_2 is 1.0 (which is <= 2).

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct FisherSnedecor { freedom_1: f64, freedom_2: f64 }
```

```rust
use statrs::distribution::FisherSnedecor;
use statrs::statistics::Distribution;

let f = FisherSnedecor::new(5.0, 10.0).unwrap();
assert_eq!(f.freedom_1(), 5.0);
assert!(FisherSnedecor::new(1.0, 1.0).unwrap().variance().is_none());
```

--------------------------------

### Data::new and utility methods

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/statistics-data.md

Shows the implementation of Data<D> with methods new, swap, len, is_empty, and iter. These methods are available when D implements AsMut<[f64]> and AsRef<[f64]>.

```rust
impl<D: AsMut<[f64]> + AsRef<[f64]>> Data<D> {
    pub fn new(data: D) -> Self
    pub fn swap(&mut self, i: usize, j: usize)
    pub fn len(&self) -> usize
    pub fn is_empty(&self) -> bool
    pub fn iter(&self) -> core::slice::Iter<'_, f64>
}
```

--------------------------------

### Cauchy distribution struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

Cauchy distribution struct definition and usage example. The struct has private fields for location and scale. The example shows construction with Cauchy::new(0.0, 1.0), accessing location, and checking that mean is None while entropy is Some.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Cauchy { location: f64, scale: f64 }
```

```rust
use statrs::distribution::Cauchy;
use statrs::statistics::Distribution;

let c = Cauchy::new(0.0, 1.0).unwrap();
assert_eq!(c.location(), 0.0);
assert!(c.mean().is_none());
assert!(c.entropy().is_some()); // (4π·scale).ln()
```

--------------------------------

### Uniform distribution struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

The Uniform distribution struct definition and a usage example. The struct has private fields min and max. The example creates a uniform distribution with min 0.0 and max 1.0, obtains the standard uniform, and checks the mean and max accessor.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct Uniform { min: f64, max: f64 }
```

```rust
use statrs::distribution::Uniform;
use statrs::statistics::Distribution;

let u = Uniform::new(0.0, 1.0).unwrap();
let std_u = Uniform::standard();
assert_eq!(u.mean(), Some(0.5));
assert_eq!(std_u.max(), 1.0);
```

--------------------------------

### Dirac distribution struct and usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-2.md

Dirac distribution struct definition and usage example. The struct is a tuple struct with a private field. The example shows construction with Dirac::new(3.0), accessing the value with v(), and verifying that NaN input returns an error (DiracError::ValueInvalid).

```rust
pub struct Dirac(f64); // tuple struct, private field
```

```rust
use statrs::distribution::Dirac;

let d = Dirac::new(3.0).unwrap();
assert_eq!(d.v(), 3.0);
assert!(Dirac::new(f64::NAN).is_err()); // DiracError::ValueInvalid
```

--------------------------------

### ChiSquared struct and usage example

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-1.md

ChiSquared is a special case of Gamma with shape = freedom/2 and rate = 1/2. The constructor returns GammaError::ShapeInvalid when freedom is NaN, infinite, zero, or negative. The example shows creating a ChiSquared with freedom 1.0 and verifying the accessor and error case.

```rust
#[derive(Copy, Clone, PartialEq, Debug)]
pub struct ChiSquared { /* private */ }
```

```rust
use statrs::distribution::ChiSquared;

let c = ChiSquared::new(1.0).unwrap();
assert_eq!(c.freedom(), 1.0);
assert!(ChiSquared::new(-1.0).is_err()); // GammaError::ShapeInvalid
```

--------------------------------

### Error handling for RejectionMeanTooSmall

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-binomial.md

Demonstrates error handling when the BTPE rejection algorithm is undefined. With `p=0.04` and `n=100`, the mean is 4, which is too small; the sampler returns `BinomialAlgorithmError::RejectionMeanTooSmall`. The match handles the error, a successful sampler, and an unreachable fallback.

```rust
use rand::distr::Distribution;
use statrs::distribution::{Binomial, BinomialAlgorithm, BinomialAlgorithmError};

// mean = 100 * 0.04 = 4 is too small for BTPE
let dist = Binomial::new(0.04, 100).unwrap();
match dist.sampler(BinomialAlgorithm::Rejection) {
    Err(BinomialAlgorithmError::RejectionMeanTooSmall) => println!("BTPE undefined here"),
    Ok(s) => drop(s.sample(&mut rand::rng())),
    Err(_) => unreachable!(),
}
```

--------------------------------

### InfiniteSawtooth

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/generate.md

Sawtooth wave starting with the lowest sample. Implements `Iterator<Item = f64>` (infinite, no `None`).

```APIDOC
## Struct: `InfiniteSawtooth`

### Description
Sawtooth wave starting with the lowest sample. Implements `Iterator<Item = f64>` (infinite, no `None`).

### Constructor
```rust
pub fn new(period: i64, high_value: f64, low_value: f64, delay: i64) -> InfiniteSawtooth
```

### Parameters
- `period` (i64) - Required - period of the wave
- `high_value` (f64) - Required - value at peak
- `low_value` (f64) - Required - value at trough
- `delay` (i64) - Required - sample delay

### Example
```rust
use statrs::generate::InfiniteSawtooth;

let x = InfiniteSawtooth::new(5, 1.0, -1.0, 1).take(5).collect::<Vec<f64>>();
assert_eq!(x, [1.0, -1.0, -0.5, 0.0, 0.5]);
```
```

--------------------------------

### InfiniteSquare

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/generate.md

Square wave starting with the high phase. Implements `Iterator<Item = f64>` (infinite, no `None`).

```APIDOC
## Struct: `InfiniteSquare`

### Description
Square wave starting with the high phase. Implements `Iterator<Item = f64>` (infinite, no `None`).

### Constructor
```rust
pub fn new(high_duration: i64, low_duration: i64, high_value: f64, low_value: f64, delay: i64) -> InfiniteSquare
```

### Parameters
- `high_duration` (i64) - Required - duration of high phase
- `low_duration` (i64) - Required - duration of low phase
- `high_value` (f64) - Required - value during high phase
- `low_value` (f64) - Required - value during low phase
- `delay` (i64) - Required - sample delay

### Example
```rust
use statrs::generate::InfiniteSquare;

let x = InfiniteSquare::new(3, 7, 1.0, -1.0, 1).take(12).collect::<Vec<f64>>();
assert_eq!(x, [-1.0, 1.0, 1.0, 1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, -1.0, 1.0]);
```
```

--------------------------------

### Create a feature branch from main

Source: https://github.com/statrs-dev/statrs/blob/main/README.md

Creates a new feature branch from the main branch. Replace <feature_branch> with a descriptive branch name.

```sh
git checkout -b <feature_branch> main
```

--------------------------------

### Gamma basic usage

Source: https://github.com/statrs-dev/statrs/blob/main/_autodocs/api-reference/distribution-continuous-1.md

Creates a Gamma distribution with shape 2.0 and rate 1.0, then checks the mean.

```rust
use statrs::distribution::Gamma;
use statrs::statistics::Distribution;

let g = Gamma::new(2.0, 1.0).unwrap();
assert_eq!(g.mean(), Some(2.0));
```
Tokens:
Raw