Clayton Copula Distribution. More...

#include <ClaytonCopula.h>

Inheritance diagram for Multivariate::ClaytonCopula:

Public Member Functions
	ClaytonCopula (unsigned int Dimension)
	Construct a Clayton copula with parameter 1. More...

	ClaytonCopula (unsigned int Dimension, double theta)
	Construct a Clayton copula with the given parameters. More...

double	GetKendallTau () const
	Get the implied Kendall's tau. More...

double	GetLowerTailDependence () const
	Get the implied Lower Tail Dependence. More...

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

bool	SetKendallTau (double t)
	Set the dependence parameter through the Kendall's tau. More...

bool	SetLowerTailDependence (double ltd)
	Set the dependence parameter through the Lower Tail Dependence. More...

bool	SetTheta (double t)
	Set the dependence parameter. More...

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

virtual Eigen::MatrixXd	ExtractSamples (unsigned int NumSamples) const
	Generates multiple simulations 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...

virtual double	GetCumulativeDesity (const Eigen::VectorXd &Coordinates) const
	Computes the copula function in correspondence of the supplied coordinates. 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...

virtual double	GetDensity (const Eigen::VectorXd &Coordinates) const
	Computes the probability density function of the copula in correspondence of the supplied coordinates. 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...

double	GetTheta () const
	Get the dependence parameter. 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...

Friends
template<class F , class T >
void	boost::math::tools::detail::handle_zero_derivative (F f, T &last_f0, const T &f0, T &delta, T &result, T &guess, const T &min, const T &max)

template<class F , class T >
T	boost::math::tools::newton_raphson_iterate (F f, T guess, T min, T max, int digits)

template<class F , class T >
T	boost::math::tools::newton_raphson_iterate (F f, T guess, T min, T max, int digits, boost::uintmax_t &max_iter)

Detailed Description

Clayton 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 Clayton copula.

Defining:

\( k \) as the dimensionality of the copula
\( \theta \) as the parameter that models the dependence. \( \theta=\frac{2 \tau}{1- \tau} \) where \( \tau \) is the Kendall's tau statistic
\( \psi(x) \) as \( \frac{x^{- \theta} -1}{\theta} \)
\( \psi^{-1} (x) \) as \( (1+ \theta x)^{-1/ \theta} \)

The Clayton copula funtion is defined as: \( C(x_1 , \cdots ,x_k )= \psi^{-1}( \psi(x_1) + \cdots + \psi(x_k)) \)

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

ClaytonCopula::ClaytonCopula ( unsigned int Dimension )

Construct a Clayton copula with parameter 1.

Parameters

Dimension The dimensionality of the copula

Construct a Clayton copula distribution with unitary dependence parameter

In case the Dimension is 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.

ClaytonCopula::ClaytonCopula	(	unsigned int	Dimension,
		double	theta
	)

Construct a Clayton copula with the given parameters.

Parameters

Dimension	The dimensionality of the copula
theta	The dependence parameter.

Construct a Clayton copula distribution with the dependence parameter theta.

\( \theta=\frac{2 \tau}{1- \tau} \) where \( \tau \) is the Kendall's tau statistic

In case:

The Dimension is less than 2
theta is less or equal to 0

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

double Multivariate::ClaytonCopula::GetKendallTau ( ) const

inline

Get the implied Kendall's tau.

Returns: The value of the Kendall's tau of the distribution

This function returns the value of the Kendall's tau statistic implied by the dependence parameter according to the relation \( \tau = \frac{\theta}{2+ \theta} \)

If the distribution is invalid -1.0 is returned;

See Also: SetKendallTau()

double ClaytonCopula::GetLowerTailDependence ( ) const

Get the implied Lower Tail Dependence.

Returns: The value of the Lower Tail Dependence of the distribution

This function returns the value of the Lower Tail Dependence statistic implied by the dependence parameter according to the relation \( \lambda_L = 2^{- \frac{1}{\theta} }\)

If the distribution is invalid -1.0 is returned;

See Also: SetLowerTailDependence()

Eigen::VectorXd ClaytonCopula::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 all the coordinates must be equal.

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::AbstractArchimedean.

bool ClaytonCopula::SetKendallTau ( double t )

Set the dependence parameter through the Kendall's tau.

Parameters

t	The Kendall's tau statistic

Returns: A boolean that indicates if the parameter was changed successfully

This function tries to set \( \theta \), the dependence parameter of the distribution, according to \( \theta = \frac{2 \tau}{1- \tau}\)

If the parameter tau is not within the interval (0,1) the function will return false and the parameter will not be changed.

See Also: SetTheta()

bool ClaytonCopula::SetLowerTailDependence ( double ltd )

Set the dependence parameter through the Lower Tail Dependence.

Parameters

ltd	The Lower Tail Dependence statistic

Returns: A boolean that indicates if the parameter was changed successfully

This function tries to set \( \theta \), the dependence parameter of the distribution, according to \( \theta =- \frac{ln(2)}{ln(\lambda_U)}\)

If the parameter is not within the interval [0,1] the function will return false and the parameter will not be changed.

See Also: SetTheta()

bool Multivariate::ClaytonCopula::SetTheta ( double t )

inlinevirtual

Set the dependence parameter.

Parameters

t	The new dependence parameter

Returns: A boolean that indicates if the parameter was changed successfully

This function tries to set the dependence parameter of the distribution to the new value

If the parameter is less or equal to 0 the function will return false and the parameter will not be changed.

See Also: SetKendallTau()

Reimplemented from Multivariate::AbstractArchimedean.

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation