copulaFitGumbel

copulaFitGumbel(X, [alpha=0.05])

Fits a Gumbel Copula and estimates the shape parameter alpha. This function only supports two-dimensional input and does not support negative dependence.

Gumbel Copula exhibits upper tail dependence and is used to model joint extreme movements in the upper quantile region. The shape parameter θ ∈ [1, ∞), where θ = 1 corresponds to independence.

X is a non-empty two-dimensional numeric matrix or table with dimensions n×2. All elements must be finite and strictly within (0, 1), and no column can be constant or nearly constant.

alpha (optional) is a DOUBLE scalar, default 0.05. Significance level for the confidence interval, in the range (0, 1).

Returns a dictionary with the following key-value pairs:

• alpha: A DOUBLE scalar indicating the estimated shape parameter θ. Note: Here, alpha refers to the shape parameter, which is different from the function parameter alpha representing the significance level.
• alphaCI: A DOUBLE vector indicating the confidence interval for the parameter: [lower, upper].
• logLikelihood: A DOUBLE scalar indicating the log-likelihood value.
• converged: A BOOL scalar indicating whether the optimizer converged.

Note: The outputs in the following examples are for illustration only. Actual results may vary.

Example 1. Generate Gumbel Copula data with shape parameter θ=2.0 and fit the model to verify estimation accuracy.

X = copulaRandGumbel(2.0, 1000)
res = copulaFitGumbel(X)
res.alpha
// Output: 2.025062
res.alphaCI
// Output: [1.926904,2.123219]
res.logLikelihood
// Output: 381.010467
res.converged
// Output: true

Example 2. Generate strongly upper-tail dependent data with shape parameter θ=4.0 (2000 samples) and fit a Gumbel Copula to evaluate estimation performance under high-dependence scenarios.

Xstrong = copulaRandGumbel(4.0, 2000)
resStrong = copulaFitGumbel(Xstrong)
resStrong.alpha
// Output: 4.191253
resStrong.alphaCI
// Output: [4.041576,4.340929]
resStrong.logLikelihood
// Output: 2056.065288
resStrong.converged
// Output: true

Example 3. Generate weakly dependent data with shape parameter θ=1.1 (near independence) and fit a Gumbel Copula to evaluate model performance under low-dependence scenarios.

Xweak = copulaRandGumbel(1.1, 2000)
resWeak = copulaFitGumbel(Xweak)
resWeak.alpha
// Output: 1.066562
resWeak.alphaCI
// Output: [1.037314,1.095811]
resWeak.logLikelihood
// Output: 15.801724
resWeak.converged
// Output: true

Example 4. Simulate daily returns of two stocks, convert them to pseudo-observations, and fit a Gumbel Copula using a table as input to evaluate the upper-tail risk of simultaneous surges.

n = 1000
retA = norm(0.0005, 0.02, n)
retB = 0.6 * retA + sqrt(1 - 0.36) * norm(0.0003, 0.015, n)
uA = (rank(retA) + 1) \ (n + 1.0)
uB = (rank(retB) + 1) \ (n + 1.0)

stockReturns = table(uA as stockA, uB as stockB)
res = copulaFitGumbel(stockReturns)
res.alpha
// Output: 1.834549
res.alphaCI
// Output: [1.744109,1.924989]
res.logLikelihood
// Output: 293.783339
res.converged
// Output: true

Related functions: copulaFitGaussian, copulaFitStudent, copulaFitClayton, copulaFitFrank, copulaRandGumbel, copulaPdfGumbel, copulaCdfGumbel