Struct rv::dist::MvGaussian

pub struct MvGaussian { /* private fields */ }

Multivariate Gaussian/Normal Distribution, 𝒩(μ, Σ).

Example

Generate a Wishart random 3x3 matrix Σ ~ W_ν(S)

use nalgebra::{DMatrix, DVector};
use rv::prelude::*;

let k = 3;   // number of dimensions
let df = 6;  // The degrees of freedom is an unsigned int > k

// The scale matrix of the Wishart distribution
let scale_mat: DMatrix<f64> = DMatrix::identity(k, k);

// The draw procedure outlined in the appendices of "Bayesian Data
// Analysis" by Andrew Gelman and colleagues.
let mut rng = rand::thread_rng();

// 1. Create a multivariate normal with zero mean and covariance matrix S
let mvg = MvGaussian::new(DVector::zeros(k), scale_mat).unwrap();

// 2. Draw ν (df) vectors {x_1, ..., x_ν}
let xs = mvg.sample(df, &mut rng);

// 3. Compute the sum Σ xx'
let mat = xs
    .iter()
    .fold(DMatrix::<f64>::zeros(k, k), |acc, x: &DVector<f64>| {
        acc +x*x.transpose()
    });

// Check that the matrix is square and has the right size
assert_eq!(mat.nrows(), k);
assert_eq!(mat.ncols(), k);

// check that the matrix is positive definite by attempting a Cholesky
// decomposition.
assert!(mat.cholesky().is_some());

Implementations

impl MvGaussian

pub fn new(mu: DVector<f64>, cov: DMatrix<f64>) -> Result<Self, MvGaussianError>

Create a new multivariate Gaussian distribution

Arguments

• mu: k-length mean vector
• cov: k-by-k positive-definite covariance matrix

pub fn new_cholesky( mu: DVector<f64>, cov_chol: Cholesky<f64, Dyn>, ) -> Result<Self, MvGaussianError>

Create a new multivariate Gaussian distribution from Cholesky factorized Dov

Arguments

• mu: k-length mean vector
• cov_chol: Cholesky decomposition of k-by-k positive-definite covariance matrix

use nalgebra::{DMatrix, DVector};
use rv::prelude::*;

let mu = DVector::zeros(3);
let cov = DMatrix::from_row_slice(3, 3, &[
    2.0, 1.0, 0.0,
    1.0, 2.0, 0.0,
    0.0, 0.0, 1.0
]);

let chol = cov.clone().cholesky().unwrap();
let mvg_r = MvGaussian::new_cholesky(mu, chol);

assert!(mvg_r.is_ok());
let mvg = mvg_r.unwrap();
assert!(cov.relative_eq(mvg.cov(), 1E-8, 1E-8));

pub fn new_unchecked(mu: DVector<f64>, cov: DMatrix<f64>) -> Self

Creates a new MvGaussian from mean and covariance without checking whether the parameters are valid.

pub fn new_cholesky_unchecked( mu: DVector<f64>, cov_chol: Cholesky<f64, Dyn>, ) -> Self

Creates a new MvGaussian from mean and covariance’s Cholesky factorization without checking whether the parameters are valid.

pub fn standard(dims: usize) -> Result<Self, MvGaussianError>

Create a standard Gaussian distribution with zero mean and identity covariance matrix.

pub fn ndims(&self) -> usize

Get the number of dimensions

Example

let mvg = MvGaussian::standard(4).unwrap();
assert_eq!(mvg.ndims(), 4);

pub fn mu(&self) -> &DVector<f64>

Get a reference to the mean

pub fn cov(&self) -> &DMatrix<f64>

Get a reference to the covariance

pub fn set_mu(&mut self, mu: DVector<f64>) -> Result<(), MvGaussianError>

Set the mean

Example

let mut mvg = MvGaussian::standard(3).unwrap();
let x = DVector::<f64>::zeros(3);

assert::close(mvg.ln_f(&x), -2.756815599614018, 1E-8);

let cov_vals = vec![
    1.01742788,
    0.36586652,
    -0.65620486,
    0.36586652,
    1.00564553,
    -0.42597261,
    -0.65620486,
    -0.42597261,
    1.27247972,
];
let cov: DMatrix<f64> = DMatrix::from_row_slice(3, 3, &cov_vals);
let mu = DVector::<f64>::from_column_slice(&vec![0.5, 3.1, -6.2]);

mvg.set_mu(mu).unwrap();
mvg.set_cov(cov).unwrap();

assert::close(mvg.ln_f(&x), -24.602370253215661, 1E-8);

pub fn set_mu_unchecked(&mut self, mu: DVector<f64>)

pub fn set_cov(&mut self, cov: DMatrix<f64>) -> Result<(), MvGaussianError>

Set the covariance matrix

Example

let mut mvg = MvGaussian::standard(3).unwrap();
let x = DVector::<f64>::zeros(3);

assert::close(mvg.ln_f(&x), -2.756815599614018, 1E-8);

let cov_vals = vec![
    1.01742788,
    0.36586652,
    -0.65620486,
    0.36586652,
    1.00564553,
    -0.42597261,
    -0.65620486,
    -0.42597261,
    1.27247972,
];
let cov: DMatrix<f64> = DMatrix::from_row_slice(3, 3, &cov_vals);
let mu = DVector::<f64>::from_column_slice(&vec![0.5, 3.1, -6.2]);

mvg.set_mu(mu).unwrap();
mvg.set_cov(cov).unwrap();

assert::close(mvg.ln_f(&x), -24.602370253215661, 1E-8);

pub fn set_cov_unchecked(&mut self, cov: DMatrix<f64>)

Set the covariance matrix without input validation

Trait Implementations

impl Clone for MvGaussian

fn clone(&self) -> MvGaussian

Returns a copy of the value.

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

Performs copy-assignment from source.

impl ConjugatePrior<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>, MvGaussian> for NormalInvWishart

type Posterior = NormalInvWishart

Type of the posterior distribution

type MCache = f64

Type of the cache for the marginal likelihood

type PpCache = (NormalInvWishart, f64)

Type of the cache for the posterior predictive

fn posterior( &self, x: &DataOrSuffStat<'_, DVector<f64>, MvGaussian>, ) -> NormalInvWishart

fn ln_m_cache(&self) -> f64

Compute the cache for the log marginal likelihood.

fn ln_m_with_cache( &self, cache: &Self::MCache, x: &DataOrSuffStat<'_, DVector<f64>, MvGaussian>, ) -> f64

Log marginal likelihood with supplied cache.

fn ln_pp_cache( &self, x: &DataOrSuffStat<'_, DVector<f64>, MvGaussian>, ) -> Self::PpCache

Compute the cache for the Log posterior predictive of y given x.

fn ln_pp_with_cache(&self, cache: &Self::PpCache, y: &DVector<f64>) -> f64

Log posterior predictive of y given x with supplied ln(norm)

fn posterior_from_suffstat(&self, stat: &Fx::Stat) -> Self::Posterior

Computes the posterior distribution from the data

fn ln_m(&self, x: &DataOrSuffStat<'_, X, Fx>) -> f64

The log marginal likelihood

fn ln_pp(&self, y: &X, x: &DataOrSuffStat<'_, X, Fx>) -> f64

Log posterior predictive of y given x

fn m(&self, x: &DataOrSuffStat<'_, X, Fx>) -> f64

Marginal likelihood of x

fn pp_with_cache(&self, cache: &Self::PpCache, y: &X) -> f64

fn pp(&self, y: &X, x: &DataOrSuffStat<'_, X, Fx>) -> f64

Posterior Predictive distribution

impl ContinuousDistr<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

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

The value of the Probability Density Function (PDF) at x

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

The value of the log Probability Density Function (PDF) at x

impl ContinuousDistr<MvGaussian> for NormalInvWishart

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

The value of the Probability Density Function (PDF) at x

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

The value of the log Probability Density Function (PDF) at x

impl Debug for MvGaussian

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MvGaussian

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for MvGaussian

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

Formats the value using the given formatter.

impl Entropy for MvGaussian

fn entropy(&self) -> f64

The entropy, H(X)

impl From<&MvGaussian> for String

fn from(mvg: &MvGaussian) -> String

Converts to this type from the input type.

impl HasDensity<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

fn ln_f(&self, x: &DVector<f64>) -> f64

Probability function

fn f(&self, x: &X) -> f64

Probability function

impl HasDensity<MvGaussian> for NormalInvWishart

fn ln_f(&self, x: &MvGaussian) -> f64

Probability function

fn f(&self, x: &X) -> f64

Probability function

impl HasSuffStat<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

type Stat = MvGaussianSuffStat

fn empty_suffstat(&self) -> Self::Stat

fn ln_f_stat(&self, stat: &Self::Stat) -> f64

Return the log likelihood for the data represented by the sufficient statistic.

impl Mean<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

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

Returns None if the mean is undefined

impl Mode<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

fn mode(&self) -> Option<DVector<f64>>

Returns None if the mode is undefined or is not a single value

impl Parameterized for MvGaussian

type Parameters = MvGaussianParameters

fn emit_params(&self) -> Self::Parameters

fn from_params(params: Self::Parameters) -> Self

impl PartialEq for MvGaussian

fn eq(&self, other: &MvGaussian) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl Sampleable<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

fn draw<R: Rng>(&self, rng: &mut R) -> DVector<f64>

Single draw from the Rv

fn sample<R: Rng>(&self, n: usize, rng: &mut R) -> Vec<X>

Multiple draws of the Rv

fn sample_stream<'r, R: Rng>( &'r self, rng: &'r mut R, ) -> Box<dyn Iterator<Item = X> + 'r>

Create a never-ending iterator of samples

impl Sampleable<MvGaussian> for NormalInvWishart

fn draw<R: Rng>(&self, rng: &mut R) -> MvGaussian

Single draw from the Rv

fn sample<R: Rng>(&self, n: usize, rng: &mut R) -> Vec<X>

Multiple draws of the Rv

fn sample_stream<'r, R: Rng>( &'r self, rng: &'r mut R, ) -> Box<dyn Iterator<Item = X> + 'r>

Create a never-ending iterator of samples

impl Serialize for MvGaussian

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Support<Matrix<f64, Dyn, Const<1>, VecStorage<f64, Dyn, Const<1>>>> for MvGaussian

fn supports(&self, x: &DVector<f64>) -> bool

Returns true if x is in the support of the Rv

impl Support<MvGaussian> for NormalInvWishart

fn supports(&self, x: &MvGaussian) -> bool

Returns true if x is in the support of the Rv

impl Variance<Matrix<f64, Dyn, Dyn, VecStorage<f64, Dyn, Dyn>>> for MvGaussian

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

Returns None if the variance is undefined