pal.copulas module
Copula Module.
This module contains classes for representing and generating samples from various copulas. It includes both elliptical (Gaussian and Student’s T) and Archimedean copulas.
- class pal.copulas.Copula[source]
Bases:
ABCBase class for copula implementations.
A copula is a multivariate probability distribution that describes the dependence structure between random variables, separate from their individual marginal distributions. Copulas are used in risk modeling to simulate correlated stochastic variables.
All copula implementations generate ProteusVariable containers with VectorLike values (typically StochasticScalar instances) that represent correlated uniform random samples on [0,1].
- abstractmethod generate(n_sims=None, rng=None)[source]
Generate correlated uniform samples from the copula.
- Parameters:
- Return type:
- Returns:
ProteusVariable containing VectorLike values (typically StochasticScalar) with uniform marginal distributions on [0,1] and the copula’s correlation structure.
- apply(variables)[source]
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.EllipticalCopula(matrix, *args, matrix_type='linear', **kwargs)[source]
-
A base class to represent an elliptical copula.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- abstractmethod generate(n_sims=None, rng=None)
Generate correlated uniform samples from the copula.
- Parameters:
- Return type:
- Returns:
ProteusVariable containing VectorLike values (typically StochasticScalar) with uniform marginal distributions on [0,1] and the copula’s correlation structure.
- class pal.copulas.GaussianCopula(matrix, matrix_type='linear')[source]
Bases:
EllipticalCopulaGaussian (Normal) Copula.
The Gaussian copula has the cumulative distribution function:
\[C(u_1, \ldots, u_d) = \Phi_R\left(\Phi^{-1}(u_1), \ldots, \Phi^{-1}(u_d)\right)\]where \(\Phi\) is the standard normal CDF, \(\Phi^{-1}\) is its inverse, and \(\Phi_R\) is the multivariate normal CDF with correlation matrix \(R\).
The Gaussian copula is an elliptical copula that models dependence through a multivariate normal distribution.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.StudentsTCopula(matrix, dof, matrix_type='linear')[source]
Bases:
EllipticalCopulaStudent’s T Copula.
The cumulative distribution function (CDF) is:
\[C(u_1, \ldots, u_d) = t_{\nu,R}\left(t_{\nu}^{-1}(u_1), \ldots, t_{\nu}^{-1}(u_d)\right)\]where \(t_\nu\) is the univariate Student’s t CDF with \(\nu\) degrees of freedom, \(t_\nu^{-1}\) is its inverse, and \(t_{\nu,R}\) is the multivariate Student’s t CDF with \(\nu\) degrees of freedom and correlation matrix \(R\).
The Student’s t copula exhibits symmetric tail dependence, making it useful for modeling joint extreme events. The upper and lower tail dependence coefficients are given by: .. math:
\lambda_U = \lambda_L = 2t_{\nu+1}\left(-\sqrt{\frac{(\nu+1)(1-\rho)}{1+\rho}}\right)
where \(\nu\) is the degrees of freedom and \(\rho\) is the correlation parameter.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.ArchimedeanCopula[source]
-
A base class to represent an Archimedean copula.
- abstractmethod generate_latent_distribution(n_sims, rng)[source]
Generate samples from the latent distribution of the copula.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.ClaytonCopula(theta, dimension=None)[source]
Bases:
ArchimedeanCopulaClayton Copula.
The Clayton copula has the cumulative distribution function:
\[C(u_1, \ldots, u_n) = \left(\sum_{i=1}^d u_i^{-\theta} - n + 1\right)^{-1/\theta}\]where \(\theta \geq 0\) is the dependence parameter. The Clayton copula exhibits lower tail dependence and is part of the Archimedean family.
The lower tail dependence coefficient between any pair of variables in the Clayton copula is given by: .. math:
\lambda_L = 2^{-1/\theta}
The upper tail dependence coefficient is zero for all \(\theta > 0\), and the copula reduces to the independence copula when \(\theta = 0\).
The generator function is:
\[\phi(t) = \frac{1}{\theta}(t^{-\theta} - 1)\]For \(\theta = 0\), the copula reduces to the independence copula.
- generate_latent_distribution(n_sims, rng)[source]
Generate samples from the latent distribution.
For Clayton copula, when theta=0, the copula reduces to the independence copula, and the latent distribution returns a constant value of 1.0 for all simulations.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- generate(n_sims=None, rng=None)
Generate samples from the Archimedean copula.
- Return type:
- pal.copulas.levy_stable(alpha, beta, size, rng)[source]
Simulate samples from a Lévy stable distribution using Chambers-Mallows-Stuck.
- class pal.copulas.GumbelCopula(theta, dimension=None)[source]
Bases:
ArchimedeanCopulaGumbel Copula.
The Gumbel copula has the cumulative distribution function:
\[C(u_1, \ldots, u_d) = \exp\left[-\left(\sum_{i=1}^d (-\ln u_i)^\theta\right)^{1/\theta}\right]\]where \(\theta \geq 1\) is the dependence parameter. The Gumbel copula exhibits upper tail dependence and is part of the Archimedean family. The
upper tail dependence coefficient between any pair of variables in the Gumbel copula is given by:
\[\lambda_U = 2 - 2^{1/\theta}\]The generator function is:
\[\phi(t) = (-\ln t)^\theta\]- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- generate(n_sims=None, rng=None)
Generate samples from the Archimedean copula.
- Return type:
- class pal.copulas.FrankCopula(theta, dimension=None)[source]
Bases:
ArchimedeanCopulaFrank Copula.
The Frank copula has the cumulative distribution function:
\[C(u_1, \ldots, u_d) = -\frac{1}{\theta} \ln\left(1 + \frac{\prod_{i=1}^d (e^{-\theta u_i} - 1)}{(e^{-\theta} - 1)^{d-1}} \right)\]where \(\theta \in \mathbb{R} \setminus \{0\}\) is the dependence parameter. The Frank copula is symmetric and does not exhibit tail dependence.
The generator function is:
\[\phi(t) = -\ln\left(\frac{e^{-\theta t} - 1}{e^{-\theta} - 1}\right)\]- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- generate(n_sims=None, rng=None)
Generate samples from the Archimedean copula.
- Return type:
- class pal.copulas.JoeCopula(theta, dimension=None)[source]
Bases:
ArchimedeanCopulaA class to represent a Joe copula.
The Joe copula has the cumulative distribution function:
\[\]C(u_1, ldots, u_d) = 1 - left(1-prod_{i=1}^d (1 - u_i)^{theta} right)^{1/theta}
where \(\theta \geq 1\) is the dependence parameter.
The Joe copula is an Archimedean copula with generator function:
\[\psi(t) = 1 - (1 - e^{-t})^{1/\theta}\]where \(\theta \geq 1\) is the dependence parameter. The copula exhibits upper tail dependence with coefficient \(2 - 2^{1/\theta}\).
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- generate(n_sims=None, rng=None)
Generate samples from the Archimedean copula.
- Return type:
- class pal.copulas.MM1Copula(delta_matrix, theta)[source]
Bases:
CopulaA multivariate max-mixture copula, denoted MM1 by Joe.
The MM1 copula is a multivariate copula which allows for different upper tail dependence structures between each pair of dimensions. It can be regarded as an extension of the Gumbel copula to more flexible dependence.
The cumulative distribution function of the MM1 copula is given by:
\[\]- C(u_1, ldots, u_d) = expleft{
- -left[
- sum_{i<j}left{ left(frac{-ln u_i}{d-1}right)^{delta_{ij}}
+left(frac{-ln u_j}{d-1}right)^{delta_{ij} } right}^{1/delta_{ij}}
right]^{1/theta}
right}
for a symmetric matrix:math:delta_{ij} geq 1 and \(\theta \geq 1\). The MM1 copula reduces to the Gumbel copula when all \(\delta_{ij} = 1\).
The upper tail dependence coefficient between any pair of variables \(i\) and \(j\) in the MM1 copula is given by:
\[\lambda_{ij} = 2 - \left(\frac{2^{1/\delta_{ij}}}{d-1} + \frac{2(d-2)}{d-1}\right)^{1/\theta}\]where \(\delta_{ij}\) is the pairwise parameter from the delta_matrix, \(d\) is the dimension of the copula, and \(\theta\) is the overall mixing parameter.
The simulation approach uses the max-mixture representation of the MM1 copula, detailed in Joe (2015, Chapter 6).
References
Joe, H. (1997). Multivariate Models and Dependence Concepts. Chapman and Hall. Joe, H. (2015). Dependence Modeling with Copulas. Chapman and Hall.
- generate(n_sims=None, rng=None)[source]
Generate samples from a multivariate max-mixture copula, denoted MM1 by Joe.
The MM1 copula is a multivariate copula which allows for different tail dependence structures between each pair of dimensions. It can be regarded as an extension of the Gumbel copula to more general tail dependence.
The simulation approach uses the max-mixture representation of the MM1 copula, detailed in Joe (2015, Chapter 6).
References: Joe, H. (1997). Multivariate Models and Dependence Concepts. Chapman and Hall. Joe, H. (2015). Dependence Modeling with Copulas. Chapman and Hall.
- Parameters:
- Return type:
- Returns:
- ProteusVariable containing VectorLike values (typically StochasticScalar)
with uniform marginal distributions on [0,1] and the copula’s dependency structure.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.GalambosCopula(theta, dimension=None)[source]
Bases:
CopulaA class to represent a Galambos copula.
The Galambos copula is an example of a multivariate extreme value copula, which is particularly suited for modeling upper tail dependence between random variables.
The bivariate cumulative distribution function (CDF) of the Galambos copula is given by:
\[\]C(u, v) = uvexpleft(-left[(-ln u)^{-theta} + (-ln v)^{-theta}right]^{-1/theta}right)
Its dependence structure is characterized by a single parameter, \(\theta > 0\), which controls the strength of the upper tail dependence.
The upper tail dependence coefficient between any pair of variables in the Galambos copula is given by:
\[\lambda_U = 2^{-1/\theta}\]where \(\theta > 0\) is the copula parameter.
The multivariate extension to \(d\) dimensions is a complicated expression given in Joe (1997, Chapter 5), but it can be simulated using the max stable / reciprocal Archimedean representation detailed in Mai (2018).
References
Galambos, János. The Asymptotic Theory of Extreme Order Statistics. New York: John Wiley & Sons, 1978. Joe, H. (1997). Multivariate Models and Dependence Concepts. Chapman and Hall. Mai, Jan-Frederik. “Exact Simulation of Reciprocal Archimedean Copulas.” Statistical Probability Letters (2018). arXiv preprint arXiv:1802.09996
- generate(n_sims=None, rng=None)[source]
Generate samples from the Galambos copula.
Exact algorithm based on the max stable / reciprocal Archimedean representation in Mai (2018).
Mai, Jan-Frederik. “Exact Simulation of Reciprocal Archimedean Copulas.” Statistical Probability Letters (2018). arXiv preprint arXiv:1802.09996
- Parameters:
- Return type:
- Returns:
ProteusVariable with StochasticScalar values representing samples from the Galambos copula.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.PlackettCopula(delta)[source]
Bases:
CopulaA class to represent a Plackett copula.
The Plackett copula is a bivariate copula that can model both positive and negative dependence between two random variables. It is characterized by a single parameter, \(\delta > 0\), which controls the strength and direction of the dependence.
The bivariate cumulative distribution function is:
\[C(u, v) = \frac{S - \sqrt{S^2 - 4uv\delta(\delta-1)}}{2(\delta-1)}\]where \(S = 1 + (u+v)(\delta-1)\) and \(\delta \neq 1\). When \(\delta = 1\), the copula reduces to the independence copula.
Currently, only the bivariate case is implemented for the Plackett copula.
References
Plackett, R. L. (1965). A class of bivariate distributions. Journal of the American Statistical Association, 60(310), 516-522.
- __init__(delta)[source]
Initialize a Plackett copula.
- Parameters:
delta (
float) – Copula parameter (must be > 0).
- generate(n_sims=None, rng=None)[source]
Generate samples from the Plackett copula.
This uses the exact simulation algorithm for the Plackett copula from Johnson (1987).
References: Johnson ME (1987) Multivariate Statistical Simulation. J. Wiley & Sons, New York
- Parameters:
- Return type:
- Returns:
ProteusVariable with StochasticScalar values representing samples from the Plackett copula.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- class pal.copulas.HuslerReissCopula(lambda_matrix)[source]
Bases:
CopulaA class to represent a Hüsler-Reiss copula.
The Hüsler-Reiss copula is an example of a multivariate extreme value copula, which is suited for modeling upper tail dependence between random variables and allows for a flexible specification of tail dependency for each bivariate pair of variables.
The bivariate cumulative distribution function (CDF) of the Hüsler-Reiss copula is given by:
\[\]- C(u_i, u_j) = expleft[
- ln u_i Phileft(lambda_{ij} + frac{1}{2}lambda_{ij}^{-1}ln[(-ln u_i)/(-ln u_j)]right)
+ln u_j Phileft(lambda_{ij} + frac{1}{2lambda_{ij}}ln[(-ln u_j)/(-ln u_i)]right) right])
where \(\Phi\) is the standard normal CDF and \(\lambda_{ij}\) is the parameter controlling the dependence between the two variables.
Its dependence structure is characterized by a matrix \(\lambda_{ij}\) which controls the strength of the upper tail dependence between each pair of variables. Lower values in the matrix correspond to stronger dependence.
The upper tail dependence coefficient between any pair of variables \(i\) and \(j\) in the Hüsler-Reiss copula is given by:
\[\chi_{ij} = 2\left(1 - \Phi(\lambda_{ij})\right)\]where \(\Phi\) is the standard normal CDF and \(\lambda_{ij}\) are the elements of the lambda matrix.
References
Hüsler, J., & Reiss, R. D. (1989). Maxima of normal random vectors: between independence and complete dependence. Statistics & Probability Letters, 7(4), 283-286.
- __init__(lambda_matrix)[source]
Initialize a Hüsler-Reiss copula.
Its dependence structure is characterized by a matrix \(\Lambda_{ij}\) which controls the strength of the upper tail dependence between each pair of variables. Lower values in the matrix correspond to stronger dependence.
The upper tail dependence coefficient between any pair of variables \(i\) and \(j\) in the Hüsler-Reiss copula is given by:
\[\chi_{ij} = 2\left(1 - \Phi(\lambda_{ij})\right)\]where \(\Phi\) is the standard normal CDF.
The parameters \(\lambda_{ij}\) must be non-negative, and the matrix must be symmetric. The diagonal elements \(\lambda_{ij}\) must always be zero. Values of \(\lambda_{ij}\) are capped at 100 to avoid numerical issues during simulation.
The matrix \(\lambda_{ij}\) must satisfy certain conditions to ensure it corresponds to a valid Hüsler-Reiss copula. In particular, the matrix must be conditionally negative definite. That is, its square must correspond to a valid variogram of a random field \(Z_j\):
\[\lambda_{ij}^2 = 2\left(\text{Var}(Z_i) + \text{Var}(Z_j) - 2\text{Cov}(Z_i, Z_j)\right)\]This is checked during initialization by attempting to construct a valid covariance matrix for the random process \(Z_i\) from the provided \(\lambda_{ij}\) matrix.
If the provided matrix does not satisfy these conditions, it is adjusted to the nearest valid matrix by modifying the eigenvalues of the corresponding covariance matrix. The is_adjusted attribute will be set to True in this case.
References
Hüsler, J., & Reiss, R. D. (1989). Maxima of normal random vectors: between independence and complete dependence. Statistics & Probability Letters, 7(4), 283-286.
- is_adjusted: bool = False
Indicates whether the provided lambda matrix was adjusted to ensure validity.
- adjusted_lambda_matrix: ndarray[tuple[Any, ...], dtype[floating]]
The adjusted lambda matrix after ensuring validity.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- property tail_dependence_matrix: ndarray[tuple[Any, ...], dtype[floating]]
Calculate the upper tail dependence matrix for the Hüsler-Reiss copula.
The upper tail dependence coefficient between any pair of variables i and j in the Hüsler-Reiss copula is given by:
χ_ij = 2 * (1 - Phi( λ_ij )),
where Phi is the standard normal CDF.
- Returns:
A 2D array representing the upper tail dependence coefficients between each pair of variables.
- Return type:
npt.NDArray[np.floating]
- static calculate_lambda_from_tail_dependence(tail_dependence_matrix)[source]
Calculate the lambda matrix from a given upper tail dependence matrix.
The upper tail dependence coefficient between any pair of variables i and j in the Hüsler-Reiss copula is given by:
χ_ij = 2 * (1 - Phi( λ_ij )),
where Phi is the standard normal CDF.
This method inverts the above relationship to compute the lambda matrix from the provided upper tail dependence coefficients. λ_ij = Phi^(-1)(1 - χ_ij / 2)
where Phi^(-1) is the inverse standard normal CDF.
- Parameters:
tail_dependence_matrix (
ndarray[tuple[Any,...],dtype[floating]]) – A 2D array representing the upper tail dependence coefficients between each pair of variables.- Returns:
A 2D array representing the lambda matrix corresponding to the given upper tail dependence coefficients.
- Return type:
- classmethod from_tail_dependence_matrix(tail_dependence_matrix)[source]
Create a Hüsler-Reiss copula from a given upper tail dependence matrix.
The upper tail dependence coefficient between any pair of variables i and j in the Hüsler-Reiss copula is given by:
χ_ij = 2 * (1 - Phi( λ_ij )),
where Phi is the standard normal CDF.
- Parameters:
tail_dependence_matrix (
ndarray[tuple[Any,...],dtype[floating]]) – A 2D array representing the upper tail dependence coefficients between each pair of variables.- Returns:
An instance of the Hüsler-Reiss copula initialized with the lambda matrix corresponding to the given upper tail dependence coefficients.
- Return type:
- generate(n_sims=None, rng=None)[source]
Generate samples from the Hüsler-Reiss copula.
The simulation uses the exact algorithm from Dombry-Engelke-Oesting (2016)
References: Dombry, C., Engelke, S., & Oesting, M. (2016). Exact simulation of max-stable processes. Biometrika 103, no. 2 (2016): 303-17.
- Parameters:
- Return type:
- Returns:
ProteusVariable with StochasticScalar values representing samples from the Hüsler-Reiss copula.
- class pal.copulas.ExtremalTCopula(correlation_matrix, nu)[source]
Bases:
CopulaA class to represent an Extremal-t copula.
The Extremal-t copula, also known as the t-EV copula, is an example of a multivariate extreme value copula, which is suited for modeling upper tail dependence between random variables.
The bivariate cumulative distribution function (CDF) of the Extremal-t copula is given by: .. math:
C(u_i, u_j) = \exp\left( \ln u_i \, t_{\nu+1}\left( -\sqrt{\frac{(\nu+1)(1-\rho_{ij}^2)}}(-\ln u_i)^{-1/\nu}(-\ln u_j)^{1/\nu}}-\rho_{ij} \right) +\ln u_j \, t_{\nu+1}\left( -\sqrt{\frac{(\nu+1)(1-\rho_{ij}^2)}}(-\ln u_j)^{-1/\nu}(-\ln u_i)^{1/\nu}}-\rho_{ij} \right) \right)
Its dependence structure is characterized by a correlation matrix and a degrees of freedom parameter \(\nu > 0\), which controls the strength of the upper tail dependence.
The upper tail dependence coefficient between any pair of variables \(i\) and \(j\) in the Extremal-t copula is given by:
\[\lambda_{ij} = 2 \, t_{\nu+1}\left(-\sqrt{ \frac{(\nu+1)(1-\rho_{ij})}{1+\rho_{ij}}}\right)\]where \(t_{\nu+1}\) is the CDF of a univariate t-distribution with \(\nu+1\) degrees of freedom and \(\rho_{ij}\) is the correlation between variables \(i\) and \(j\).
The lower tail dependence coefficient is zero for all pairs of variables.
References
Nikoloulopoulos, A. K., Joe, H., & Li, H. (2009). Extreme value properties of multivariate t copulas. Extremes, 12(2), 129-148.
- apply(variables)
Apply the copula’s correlation structure to existing variables.
This method modifies the input variables in-place to exhibit the correlation structure defined by this copula while preserving their marginal distributions.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – Either a ProteusVariable containing VectorLike values or a list of VectorLike instances.- Raises:
TypeError – If list contains non-StochasticScalar values.
ValueError – If variables have inconsistent simulation counts.
- Return type:
- generate(n_sims=None, rng=None)[source]
Generate samples from the Extremal-t copula.
The simulation uses the exact algorithm from Dombry et al. (2016).
References: Nikoloulopoulos, A. K., Joe, H., & Li, H. (2009). Extreme value properties of multivariate t copulas. Extremes, 12(2), 129-148. Dombry, C., Engelke, S., & Oesting, M. (2016). Exact simulation of max-stable processes. Biometrika 103, no. 2 (2016): 303-17.
- Parameters:
- Return type:
- Returns:
ProteusVariable with StochasticScalar values representing samples from the Extremal-t copula.
- classmethod from_tail_dependence_matrix(tail_dependence_matrix, nu)[source]
Create an Extremal-t copula from a given upper tail dependence matrix.
The upper tail dependence coefficient between any pair of variables i and j in the Extremal-t copula is given by:
χ_ij = 2 * t_{nu+1}(-sqrt((nu+1)(1-rho_ij)/(1+rho_ij))),
where t_{nu+1} is the CDF of a univariate t-distribution with nu+1 degrees of freedom and rho_ij is the correlation between variables i and j.
This method inverts the above relationship to compute the correlation matrix from the provided upper tail dependence coefficients.
- Parameters:
- Returns:
An instance of the Extremal-t copula initialized with the correlation matrix corresponding to the given upper tail dependence coefficients.
- Return type:
- pal.copulas.apply_copula(variables, copula_samples)[source]
Apply a reordering from a copula to a list of variables.
- Parameters:
variables (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – List of StochasticScalar variables.copula_samples (
Union[ProteusVariable[StochasticScalar],list[StochasticScalar]]) – List of StochasticScalar samples from the copula.
- Return type: