Gaussian Copula Distribution. More...

#include <GaussianCopula.h>

Inheritance diagram for Multivariate::GaussianCopula:

Public Member Functions
	GaussianCopula (unsigned int Dimension=2U)
	Constructs a standard Gaussian copula. More...

	GaussianCopula (unsigned int Dimension, const Eigen::MatrixXd &CovMatr)
	Construct a Gaussian copula with the given parameters. More...

Eigen::MatrixXd	ExtractSamples (unsigned int NumSamples) const
	Generates multiple simulations from the copula. More...

double	GetCumulativeDesity (const Eigen::VectorXd &Coordinates) const
	Computes the copula function in correspondence of the supplied coordinates. More...

double	GetDensity (const Eigen::VectorXd &Coordinates) const
	Computes the copula density function in correspondence of the supplied coordinates. More...

Eigen::VectorXd	GetQuantile (double Prob) const
	Computes the inverse copula function in correspondence of the supplied probability. More...

const Eigen::MatrixXd &	GetVarCovMatrix () const
	Get the standardized covariance matrix of the distribution. More...

bool	SetVarCovMatrix (const Eigen::MatrixXd &CovMatr)
	Set the covariance matrix of the distribution. More...

bool	SetVarCovMatrix (const Eigen::MatrixXd &CorrelationMatrix, const Eigen::VectorXd &Variances)
	Set the covariance matrix of the distribution. More...

bool	SetVarCovMatrix (const std::vector< double > &mVect, bool RowWise=true)
	Set the covariance matrix of the distribution. More...

Public Member Functions inherited from Multivariate::AbstarctCopula
Eigen::RowVectorXd	ExtractSample () const
	Generates a single simulation from the copula. More...

std::map< unsigned int, std::vector< double > >	ExtractSamplesMap (unsigned int NumSamples) const
	Generates multiple simulations from the copula. More...

std::vector< double >	ExtractSampleVector () const
	Generates a single simulation from the copula. More...

double	GetCumulativeDesity (const std::vector< double > &Coordinates) const
	Computes the copula function in correspondence of the supplied coordinates. More...

unsigned int	GetCurrentSeed () const
	Get the random number generator seed. More...

double	GetDensity (const std::vector< double > &Coordinates) const
	Computes the probability density function of the copula in correspondence of the supplied coordinates. More...

unsigned int	GetDimension () const
	Get the dimensionality of the copula. More...

std::vector< double >	GetQuantileVector (double Prob) const
	Computes the inverse copula function in correspondence of the supplied probability. More...

bool	IsValid () const
	Check if the copula is valid. More...

bool	SetDimension (unsigned int Dimension)
	Set the dimensionality of the copula. More...

void	SetRandomSeed (unsigned int NewSeed)
	Set the random number generator seed. More...

double *	GetQuantileArray (double Prob)
	Computes the inverse copula function in correspondence of the supplied probability. More...

double	GetCumulativeDesity (double *Coordinates) const
	Computes the copula function in correspondence of the supplied coordinates. More...

double	GetDensity (double *Coordinates) const
	Computes the probability density function of the copula in correspondence of the supplied coordinates. More...

double *	ExtractSampleArray () const
	Generates a single simulation from the copula. More...

double **	ExtractSamplesMatix (unsigned int NumSamples) const
	Generates a single simulation from the copula. More...

Detailed Description

Gaussian Copula Distribution.

This class provides the functionality of calculating the probability density value, cumulative probability density value, inverse cumulative probability density and generate random samples from a Gaussian copula.

Defining:

\( k \) as the dimensionality of the copula
\( \Phi^{-1} \) as the inverse of the cumulative density function of the standard normal
\( \Phi_{\rho} \) as the cumulative density function of the multivariate normal with mean \( \textbf{0} \) and covariance matix \( \rho \)
\( \boldsymbol{\Sigma}=\begin{bmatrix} \sigma^2_1 & \cdots & \sigma_{1,k}\\ \vdots & \ddots & \vdots \\ \sigma_{k,1} & \cdots & \sigma^2_k \end{bmatrix} \) as the variance-covariance matrix

We can define \( \boldsymbol{\rho}(\boldsymbol{\Sigma})=\begin{bmatrix} 1 & \cdots & \frac{\sigma_{1,k}}{\sigma_1 \sigma_k}\\ \vdots & \ddots & \vdots \\ \frac{\sigma_{k,1}}{\sigma_k \sigma_1} & \cdots & 1 \end{bmatrix} \)
The gaussian copula distribution funtion is defined as: \( C(\textbf{x})=\Phi_{\rho}(((2\pi)^{-\frac{k}{2}} |\boldsymbol{\Sigma}|^{-\frac{1}{2}} e^{(-\frac{1}{2} \boldsymbol{\Phi}^{-1}(\textbf{x}') \boldsymbol{\Sigma}^{-1} \boldsymbol{\Phi}^{-1}(\textbf{x}))}) \) for \( \textbf{x} \in \textbf{(0,1)} \)

If you construct multiple instances of this class, to avoid the generated samples to be the same, you should supply a different seed. To do so, for example, you can call MyDistribution.SetRandomSeed(MyDistribution.GetCurrentSeed()+1U);

Please refer to the Examples page for usage examples.

Remarks: This class is re-entrant

Date: November 2013

License: This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

Here, you can find a copy of the GNU Lesser General Public License. Alternatively, see gnu.org.

Constructor & Destructor Documentation

Multivariate::GaussianCopula::GaussianCopula ( unsigned int Dimension = 2U )

inline

Constructs a standard Gaussian copula.

Parameters

Dimension The dimensionality of the copula

Construct a Gaussian copula with variance-covariance matrix set to the identity matrix.

In case The Dimension less than 2 the class will be considered invalid (it can be checked using IsValid()) and won't produce any result until the problem is fixed.

If dimension is unspecified, a bivariate copula is constructed

GaussianCopula::GaussianCopula	(	unsigned int	Dimension,
		const Eigen::MatrixXd &	CovMatr
	)

Construct a Gaussian copula with the given parameters.

Parameters

Dimension	The dimensionality of the Gaussian copula
CovMatr	The variance-covariance

Construct a Gaussian copula distribution.

In case:

The Dimension is less than 2
The variance-covariance is not square
The variance-covariance is not symmetric
The variance-covariance is not semi-positive definite
The variance-covariance has a number of rows different from the Dimension

The class will be considered invalid (it can be checked using IsValid()) and won't produce any result until the problem is fixed.

Member Function Documentation

Eigen::MatrixXd Multivariate::GaussianCopula::ExtractSamples ( unsigned int NumSamples ) const

inlinevirtual

Generates multiple simulations from the copula.

Parameters

NumSamples The number of simulation to run

Returns: A matrix with columns equal to the dimensionality of the distribution and rows equal to the number of simulations

This function generates NumSamples simulation from the current copula and returns them in matrix form.

If NumSamples is 0 or the copula is invalid, a null matrix is returned

Implements Multivariate::AbstarctCopula.

double GaussianCopula::GetCumulativeDesity ( const Eigen::VectorXd & Coordinates ) const

virtual

Computes the copula function in correspondence of the supplied coordinates.

Parameters

Coordinates A vector containing the coordinates of the point for which the pdf should be computed

Returns: The value of the copula function

This function computes the probability density function of the current copula associated with the given coordinates.

The coordinates must all be in the interval (0,1)

If the number of elements in Coordinates is different from the dimensionality of the distribution or the distribution is invalid, -1 is returned

Implements Multivariate::AbstarctCopula.

double GaussianCopula::GetDensity ( const Eigen::VectorXd & Coordinates ) const

virtual

Computes the copula density function in correspondence of the supplied coordinates.

Parameters

Coordinates A vector containing the coordinates of the point for which the pdf should be computed

Returns: The value of the copula density function

This function computes the probability density function of the current copula associated with the given coordinates.

The coordinates must all be in the interval (0,1)

If the number of elements in Coordinates is different from the dimensionality of the distribution or the distribution is invalid, -1 is returned

Implements Multivariate::AbstarctCopula.

Eigen::VectorXd GaussianCopula::GetQuantile ( double Prob ) const

virtual

Computes the inverse copula function in correspondence of the supplied probability.

Parameters

Prob	The probability for which the corresponding quantile must be found

Returns: A vector containing the coordinates of the quantile in the intervall [0;1]

This function computes the inverse cumulative density function of the current distribution associated with the given probability.

The solution is not unique.
Generally the system of equations \( C^{-1}(Coordinates_1 \cdots Coordinates_k)=Prob \) has k-1 degrees of freedom, where k is the dimensionality of the distribution.
The additional restriction imposed to get to an unique solution is that each coordinate has equal distance from it's mean.

If the coordinates supplied have any component that is greater than 1 or less than 0 or the distribution is invalid, an empty vector is returned.

Implements Multivariate::AbstarctCopula.

const Eigen::MatrixXd& Multivariate::GaussianCopula::GetVarCovMatrix ( ) const

inline

Get the standardized covariance matrix of the distribution.

Returns: The current variance-covariance matrix of the distribution

See Also: SetVarCovMatrix(const Eigen::MatrixXd&); SetVarCovMatrix(const std::vector<double>&,bool); SetVarCovMatrix(const Eigen::MatrixXd&, const Eigen::VectorXd&)

bool GaussianCopula::SetVarCovMatrix ( const Eigen::MatrixXd & CovMatr )

Set the covariance matrix of the distribution.

Parameters

CovMatr the new variance covariance matrix of the distribution

Returns: A boolean determining if the variance covariance matrix of the distribution was changed successfully

This function tries to set the variance covariance matrix of the distribution to the new one.

The Variance-Covariance matrix is then standardized to have unitary diagonal

In case:

The variance-covariance is not square
The variance-covariance is not symmetric
The variance-covariance is not semi-positive definite
The variance-covariance has a number of rows different from the Dimension

The variance covariance matrix of the distribution will not be changed and this function will return false

See Also: GetVarCovMatrix()

bool Multivariate::GaussianCopula::SetVarCovMatrix	(	const Eigen::MatrixXd &	CorrelationMatrix,
		const Eigen::VectorXd &	Variances
	)

inline

Set the covariance matrix of the distribution.

Parameters

CorrelationMatrix	The correlation coefficients matrix
Variances	the vector of variances

Returns: A boolean determining if the variance covariance matrix of the distribution was changed successfully

This function tries to set the variance covariance matrix of the distribution according to the correlation matrix supplied.

Sets the covariance matrix to the supplied CorrelationMatrix

In case:

The size of the vector of variances is different from the distribution dimensionality
The correlation matrix is not symmetric
The correlation matrix has elements different from 1 on the diagonal
The correlation matrix has a number of rows different from the Dimension
The correlation matrix is not squared
The correlation matrix has off-diagonal elements greater than 1 in absolute value

The variance covariance matrix of the distribution will not be changed and this function will return false

See Also: GetVarCovMatrix()

bool GaussianCopula::SetVarCovMatrix	(	const std::vector< double > &	mVect,
		bool	RowWise = `true`
	)

Set the covariance matrix of the distribution.

Parameters

mVect	a vector containing the elements of the new variance covariance matrix of the distribution
RowWise	if it's set to true (the default) the matrix will be filled by row. If it's false it will be filled by columns

Returns: A boolean determining if the variance covariance matrix of the distribution was changed successfully

This function tries to set the variance covariance matrix of the distribution to the new one.

Constructs a square matrix with number of rows equal to the dimensionality of the distribution, it is then filled with the values supplied in order according to the RowWise parameter

The Variance-Covariance matrix is then standardized to have unitary diagonal

In case:

The vector size is different from the square of the distribution dimensionality
The variance-covariance is not symmetric
The variance-covariance is not semi-positive definite
The variance-covariance has a number of rows different from the Dimension

The variance covariance matrix of the distribution will not be changed and this function will return false

See Also: GetVarCovMatrix()

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation