Click or drag to resize
Accord.NET (logo)

MultivariateNormalDistribution Class

Multivariate Normal (Gaussian) distribution.
Inheritance Hierarchy
SystemObject
  Accord.Statistics.DistributionsDistributionBase
    Accord.Statistics.Distributions.MultivariateMultivariateContinuousDistribution
      Accord.Statistics.Distributions.MultivariateMultivariateNormalDistribution

Namespace:  Accord.Statistics.Distributions.Multivariate
Assembly:  Accord.Statistics (in Accord.Statistics.dll) Version: 3.5.0
Syntax
[SerializableAttribute]
public class MultivariateNormalDistribution : MultivariateContinuousDistribution, 
	IFittableDistribution<double[], NormalOptions>, IFittable<double[], NormalOptions>, 
	IFittable<double[]>, IFittableDistribution<double[]>, IDistribution<double[]>, 
	IDistribution, ICloneable, ISampleableDistribution<double[]>, IRandomNumberGenerator<double[]>
Request Example View Source

The MultivariateNormalDistribution type exposes the following members.

Constructors
Properties
  NameDescription
Public propertyCovariance
Gets the variance-covariance matrix Σ (sigma) for the Gaussian distribution.
(Overrides MultivariateContinuousDistributionCovariance.)
Public propertyDimension
Gets the number of variables for this distribution.
(Inherited from MultivariateContinuousDistribution.)
Public propertyMean
Gets the Mean vector μ (mu) for the Gaussian distribution.
(Overrides MultivariateContinuousDistributionMean.)
Public propertyMedian
Gets the median for this distribution.
(Inherited from MultivariateContinuousDistribution.)
Public propertyMode
Gets the mode for this distribution.
(Inherited from MultivariateContinuousDistribution.)
Public propertyVariance
Gets the Variance vector diag(Σ), the diagonal of the sigma matrix, for the Gaussian distribution.
(Overrides MultivariateContinuousDistributionVariance.)
Top
Methods
  NameDescription
Public methodStatic memberBivariate
Creates a new bivariate Normal distribution.
Public methodClone
Creates a new object that is a copy of the current instance.
(Overrides DistributionBaseClone.)
Public methodComplementaryDistributionFunction
Gets the complementary cumulative distribution function (ccdf) for this distribution evaluated at point x. This function is also known as the Survival function.
(Overrides MultivariateContinuousDistributionComplementaryDistributionFunction(Double).)
Public methodDistributionFunction
Computes the cumulative distribution function for distributions up to two dimensions. For more than two dimensions, this method is not supported.
(Overrides MultivariateContinuousDistributionDistributionFunction(Double).)
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Public methodStatic memberEstimate(Double)
Estimates a new Normal distribution from a given set of observations.
Public methodStatic memberCode exampleEstimate(Double, NormalOptions)
Estimates a new Normal distribution from a given set of observations.
Public methodStatic memberCode exampleEstimate(Double, Double)
Estimates a new Normal distribution from a given set of observations.
Public methodStatic memberCode exampleEstimate(Double, Double, NormalOptions)
Estimates a new Normal distribution from a given set of observations.
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodFit(Double)
Fits the underlying distribution to a given set of observations.
(Inherited from MultivariateContinuousDistribution.)
Public methodFit(Double, IFittingOptions)
Fits the underlying distribution to a given set of observations.
(Inherited from MultivariateContinuousDistribution.)
Public methodFit(Double, Double)
Fits the underlying distribution to a given set of observations.
(Inherited from MultivariateContinuousDistribution.)
Public methodFit(Double, Int32)
Fits the underlying distribution to a given set of observations.
(Inherited from MultivariateContinuousDistribution.)
Public methodFit(Double, Int32, IFittingOptions)
Fits the underlying distribution to a given set of observations.
(Inherited from MultivariateContinuousDistribution.)
Public methodCode exampleFit(Double, Double, IFittingOptions)
Fits the underlying distribution to a given set of observations.
(Overrides MultivariateContinuousDistributionFit(Double, Double, IFittingOptions).)
Public methodCode exampleFit(Double, Double, NormalOptions)
Fits the underlying distribution to a given set of observations.
Public methodGenerate
Generates a random observation from the current distribution.
(Inherited from MultivariateContinuousDistribution.)
Public methodGenerate(Double)
Generates a random observation from the current distribution.
(Inherited from MultivariateContinuousDistribution.)
Public methodGenerate(Int32)
Generates a random vector of observations from the current distribution.
(Inherited from MultivariateContinuousDistribution.)
Public methodGenerate(Int32)
Generates a random observation from the current distribution.
(Inherited from MultivariateContinuousDistribution.)
Public methodGenerate(Int32, Int32)
Generates a random vector of observations from the current distribution.
(Inherited from MultivariateContinuousDistribution.)
Public methodGenerate(Int32, Double)
Generates a random vector of observations from the current distribution.
(Overrides MultivariateContinuousDistributionGenerate(Int32, Double).)
Public methodStatic memberGenerate(Int32, Double, Double)
Generates a random vector of observations from a distribution with the given parameters.
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodLogProbabilityDensityFunction
Gets the log-probability density function (pdf) for this distribution evaluated at point x.
(Overrides MultivariateContinuousDistributionLogProbabilityDensityFunction(Double).)
Public methodMahalanobis
Gets the Mahalanobis distance between a sample and this distribution.
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodProbabilityDensityFunction
Gets the probability density function (pdf) for this distribution evaluated at point x.
(Overrides MultivariateContinuousDistributionProbabilityDensityFunction(Double).)
Public methodToIndependentNormalDistribution
Converts this multivariate normal distribution into a joint distribution of independentnormal distributions.
Public methodToString
Returns a String that represents this instance.
(Inherited from DistributionBase.)
Public methodToString(IFormatProvider)
Returns a String that represents this instance.
(Inherited from DistributionBase.)
Public methodToString(String)
Returns a String that represents this instance.
(Inherited from DistributionBase.)
Public methodToString(String, IFormatProvider)
Returns a String that represents this instance.
(Overrides DistributionBaseToString(String, IFormatProvider).)
Public methodStatic memberUnivariate
Creates a new univariate Normal distribution.
Top
Extension Methods
  NameDescription
Public Extension MethodHasMethod
Checks whether an object implements a method with the given name.
(Defined by ExtensionMethods.)
Public Extension MethodIsEqual
Compares two objects for equality, performing an elementwise comparison if the elements are vectors or matrices.
(Defined by Matrix.)
Public Extension MethodToTOverloaded.
Converts an object into another type, irrespective of whether the conversion can be done at compile time or not. This can be used to convert generic types to numeric types during runtime.
(Defined by ExtensionMethods.)
Public Extension MethodToTOverloaded.
Converts an object into another type, irrespective of whether the conversion can be done at compile time or not. This can be used to convert generic types to numeric types during runtime.
(Defined by Matrix.)
Top
Remarks

The Gaussian is the most widely used distribution for continuous variables. In the case of many variables, it is governed by two parameters, the mean vector and the variance-covariance matrix.

When a covariance matrix given to the class constructor is not positive definite, the distribution is degenerate and this may be an indication indication that it may be entirely contained in a r-dimensional subspace. Applying a rotation to an orthogonal basis to recover a non-degenerate r-dimensional distribution may help in this case.

References:

Examples

The following example shows how to create a Multivariate Gaussian distribution with known parameters mean vector and covariance matrix

// Create a multivariate Gaussian distribution 
var dist = new MultivariateNormalDistribution(

    // mean vector mu
    mean: new double[] 
    {
        4, 2 
    },

    // covariance matrix sigma
    covariance: new double[,] 
    {
        { 0.3, 0.1 },
        { 0.1, 0.7 }
    }
);

// Common measures
double[] mean = dist.Mean;     // { 4, 2 }
double[] median = dist.Median; // { 4, 2 }
double[] var = dist.Variance;  // { 0.3, 0.7 } (diagonal from cov)
double[,] cov = dist.Covariance; // { { 0.3, 0.1 }, { 0.1, 0.7 } }

// Probability mass functions
double pdf1 = dist.ProbabilityDensityFunction(new double[] { 2, 5 }); // 0.000000018917884164743237
double pdf2 = dist.ProbabilityDensityFunction(new double[] { 4, 2 }); // 0.35588127170858852
double pdf3 = dist.ProbabilityDensityFunction(new double[] { 3, 7 }); // 0.000000000036520107734505265
double lpdf = dist.LogProbabilityDensityFunction(new double[] { 3, 7 }); // -24.033158110192296

// Cumulative distribution function (for up to two dimensions)
double cdf = dist.DistributionFunction(new double[] { 3, 5 }); // 0.033944035782101548

// Generate samples from this distribution:
double[][] sample = dist.Generate(1000000);

The following example demonstrates how to fit a multivariate Gaussian to a set of observations. Since those observations would lead to numerical difficulties, the example also demonstrates how to specify a regularization constant to avoid getting a NonPositiveDefiniteMatrixException.

double[][] observations = 
{
    new double[] { 1, 2 },
    new double[] { 1, 2 },
    new double[] { 1, 2 },
    new double[] { 1, 2 }
};

// Create a multivariate Gaussian for 2 dimensions
var normal = new MultivariateNormalDistribution(2);

// Specify a regularization constant in the fitting options
NormalOptions options = new NormalOptions() { Regularization = double.Epsilon };

// Fit the distribution to the data
normal.Fit(observations, options);

// Check distribution parameters
double[] mean = normal.Mean;     // { 1, 2 }
double[] var  = normal.Variance; // { 4.9E-324, 4.9E-324 } (almost machine zero)

The next example shows how to estimate a Gaussian distribution from data available inside a Microsoft Excel spreadsheet using the ExcelReader class.

// Create a new Excel reader to read data from a spreadsheet
ExcelReader reader = new ExcelReader(@"test.xls", hasHeaders: false);

// Extract the "Data" worksheet from the xls
DataTable table = reader.GetWorksheet("Data");

// Convert the data table to a jagged matrix
double[][] observations = table.ToArray();


// Estimate a new Multivariate Normal Distribution from the observations
var dist = MultivariateNormalDistribution.Estimate(observations, new NormalOptions()
{
    Regularization = 1e-10 // this value will be added to the diagonal until it becomes positive-definite
});
See Also