Archimedean Copulas base class. More...

#include <AbstarctArchimedeanCopula.h>

Inheritance diagram for Multivariate::AbstractArchimedean:

Public Member Functions
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...

virtual Eigen::VectorXd	GetQuantile (double Prob) const =0
	Computes the inverse copula function in correspondence of the supplied probability. 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...

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

Unsafe Methods
The methods in this group use unsafe memory access or return arrays allocated on the heap that must be manually deleted. These functions are normally not compiled for safety reasons. To use them, the mvPackageUnsafeMethods symbol must be defined at compile time
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

Archimedean Copulas base class.

Class that works as an interface to Archimedean copulas.

An Archimedean copula of dimension k is defined as:
\( C(u_1 , \cdots , u_k ; \theta)=\psi^{-1}(\psi(u_1 ; \theta)+ \cdots + \psi(u_k ; \theta); \theta) \)
where \( \theta \) is the dependence parameter ruling the distribution and \( \psi(.) \) is the generator function.

To generate samples a boost::random::mt19937 random number generator is used and seeded with std::time(NULL).
If you construct multiple instances of derived classes, 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);

Note: This class is abstract

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.

Member Function Documentation

Eigen::RowVectorXd Multivariate::AbstractArchimedean::ExtractSample ( ) const

inline

Generates a single simulation from the copula.

Returns: A row vector with number of elements equal to the dimensionality of the distribution representing a single extraction from the copula

This is equal to calling ExtractSamples(1U)

See Also: ExtractSamples()

double * AbstractArchimedean::ExtractSampleArray ( ) const

Generates a single simulation from the copula.

Returns: A dynamically allocated array with number of elements equal to the dimensionality of the copula representing a single extraction from the distribution

This is equivalent to ExtractSample() but returns an array intead of an Eigen::RowVectorXd. If it can't be calculated, NULL is returned

Warning: This function will return an array allocated on the heap. If the user doesn't take care of deleting it, this will lead to memory leaks

Eigen::MatrixXd AbstractArchimedean::ExtractSamples ( unsigned int NumSamples ) const

virtual

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 copula and rows equal to the number of simulations

This function uses the algorithm described by Albert W. Marshall and Ingram Olkin, Families of Multivariate Distributions, Journal of the American Statistical Association, Vol. 83, No. 403 (Sep., 1988), pp. 834-841 to sample from the copula distribution.

If NumSamples is less than 1 or the distribution is invalid, an empty matrix will be returned

std::map< unsigned int, std::vector< double > > AbstractArchimedean::ExtractSamplesMap ( unsigned int NumSamples ) const

Generates multiple simulations from the copula.

Parameters

NumSamples The number of simulation to run

Returns: A map that has as keys the index of the dimension (starting from 0) and as values a vector containing the simulation results for that dimension

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

If NumSamples is 0 or the distribution is invalid, an empty map is returned

double ** AbstractArchimedean::ExtractSamplesMatix ( unsigned int NumSamples ) const

Generates a single simulation from the copula.

Parameters

NumSamples The number of simulation to run

Returns: A dynamically allocated matrix with number of columns equal to the dimensionality of the copula and number of rows equal to the number of simulations representing multiple draws from the copula

This is equivalent to ExtractSamples() but returns a matrix intead of an Eigen::MatrixXd. If it can't be calculated, NULL is returned

Warning: This function will return a matrix allocated on the heap. If the user doesn't take care of deleting it, this will lead to memory leaks

std::vector< double > AbstractArchimedean::ExtractSampleVector ( ) const

Generates a single simulation from the copula.

Returns: A vector with number of elements equal to the dimensionality of the distribution representing a single extraction from the copula

This is equivalent to ExtractSample() but returns an std::vector intead of an Eigen::RowVectorXd

See Also: ExtractSamples()

double AbstractArchimedean::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 cdf should be computed

Returns: The value of the copula function

This is a pure virtual function. Refer to child documentation for specific implementation details

double AbstractArchimedean::GetCumulativeDesity ( const std::vector< double > & Coordinates ) const

Computes the copula function in correspondence of the supplied coordinates.

Parameters

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

Returns: The value of the copula function

This is an overloaded version of GetCumulativeDesity(const Eigen::VectorXd&, bool, unsigned int)const

double AbstractArchimedean::GetCumulativeDesity ( double * Coordinates ) const

Computes the copula function in correspondence of the supplied coordinates.

Parameters

Coordinates An array containing the coordinates of the point for which the cdf should be computed

Returns: The value of the copula function

This is an overloaded version of GetCumulativeDesity(const Eigen::VectorXd& Coordinates, bool UseGenz, unsigned int NumSimul)

Warning: This function will search for a number of elements equal to the dimensionality of the distribution in the array. This may mean accessing unallocated memory blocks if the supplied array is not big enough

unsigned int Multivariate::AbstractArchimedean::GetCurrentSeed ( ) const

inline

Get the random number generator seed.

Returns: The random number generator seed.

This function return the seed that was used to initialize the random number generator.

Note: This seed is different from the srand() seed and, even with the same seed, random number generated by the internal generator will be different by those generated by rand()

See Also: SetRandomSeed()

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

virtual

Computes the probability density function of the copula 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 probability density function

This is a pure virtual function. Refer to child documentation for specific implementation details

double AbstractArchimedean::GetDensity ( const std::vector< double > & Coordinates ) const

Computes the probability density function of the copula 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 probability density function

This is an overloaded version of GetDensity(const Eigen::VectorXd& Coordinates, bool GetLogDensity)const

double AbstractArchimedean::GetDensity ( double * Coordinates ) const

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

Parameters

Coordinates An array containing the coordinates of the point for which the pdf should be computed

Returns: The value of the probability density function

This is an overloaded version of GetDensity(const Eigen::VectorXd&, bool)

Warning: This function will search for a number of elements equal to the dimensionality of the distribution in the array. This may mean accessing unallocated memory blocks if the supplied array is not big enough

unsigned int Multivariate::AbstractArchimedean::GetDimension ( ) const

inline

Get the dimensionality of the copula.

Returns: The current dimensionality of the copula

See Also: SetDimension()

virtual Eigen::VectorXd Multivariate::AbstractArchimedean::GetQuantile ( double Prob ) const

pure 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

This is a pure virtual function. Refer to child documentation for specific implementation details

Implemented in Multivariate::ClaytonCopula, and Multivariate::GumbelCopula.

double * AbstractArchimedean::GetQuantileArray ( double Prob )

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

Returns: A dynamically allocated array containing the coordinates of the quantile

This is equivalent to GetQuantile() but returns an array intead of an Eigen::VectorXd. If it can't be calculated, NULL is returned

Warning: This function will return a matrix allocated on the heap. If the user doesn't take care of deleting it, this will lead to memory leaks

std::vector< double > AbstractArchimedean::GetQuantileVector ( double Prob ) const

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

Returns: A vector containing the coordinates of the quantile

This is equivalent to GetQuantile() but returns an std::vector intead of an Eigen::VectorXd

double Multivariate::AbstractArchimedean::GetTheta ( ) const

inline

Get the dependence parameter.

Returns: The dependence parameter

This function returns the value of the parameter \( \theta \) that governs the dependence

See Also: SetTheta()

bool Multivariate::AbstractArchimedean::IsValid ( ) const

inline

Check if the copula is valid.

Returns: A boolean determining if the structure of the copula is valid

If this function returns false the structure of the copula is meaningless and no result will be produced until the invalid parameters are cured.

bool Multivariate::AbstractArchimedean::SetDimension ( unsigned int Dimension )

inline

Set the dimensionality of the copula.

Parameters

Dimension the new dimensionality of the copula

Returns: A boolean determining if the dimensionality was changed successfully

This function will try to change the dimensionality of the copula (e.g. 2 for bivariate, 3 for trivariate, etc.)

If the argument passed is less than 2 the dimensionality will not be changed and the function will return false

See Also: GetDimension()

void AbstractArchimedean::SetRandomSeed ( unsigned int NewSeed )

Set the random number generator seed.

Parameters

NewSeed the new random seed

Note: This seed is different from the srand() seed and, even with the same seed, random number generated by the internal generator will be different by those generated by rand()

See Also: GetCurrentSeed()

virtual bool Multivariate::AbstractArchimedean::SetTheta ( double t )

inlinevirtual

Set the dependence parameter.

Returns: Always true

This function sets the value of the parameter \( \theta \) that governs the dependence

This implementation won't perform any check on \( \theta \). See the derived class documentation for specific restrictions

See Also: GetTheta()

Reimplemented in Multivariate::ClaytonCopula, and Multivariate::GumbelCopula.

Public Member Functions

Detailed Description

Member Function Documentation