copulafit

Fit copula to data

Syntax

rhohat = copulafit('Gaussian',u)

[rhohat,nuhat] = copulafit('t',u)

[rhohat,nuhat,nuci] = copulafit('t',u)

paramhat = copulafit(family,u)

[paramhat,paramci] = copulafit(family,u)

___ = copulafit(___,Name,Value)

Description

rhohat = copulafit('Gaussian',u) returns an estimate, rhohat, of the matrix of linear correlation parameters for a Gaussian copula, given the data in u.

[rhohat,nuhat] = copulafit('t',u) returns an estimate, rhohat, of the matrix of linear correlation parameters for a t copula, and an estimate of the degrees of freedom parameter, nuhat, given the data in u.

[rhohat,nuhat,nuci] = copulafit('t',u) also returns an approximate 95% confidence interval, nuci, for the degrees of freedom estimated in nuhat.

paramhat = copulafit(family,u) returns an estimate, paramhat, of the copula parameter for a bivariate Archimedean copula of the type specified by family, given the data in u.

[paramhat,paramci] = copulafit(family,u) also returns an approximate 95% confidence interval, paramci, for the copula parameter estimated in paramhat.

___ = copulafit(___,Name,Value) returns any of the previous syntaxes, with additional options specified by one or more Name,Value pair arguments. For example, you can specify the confidence interval to compute, or specify control parameters for the iterative parameter estimation algorithm using a options structure.

Examples

Fit a t Copula to Data

Load and plot simulated stock return data.

load stockreturns
x = stocks(:,1);
y = stocks(:,2);

figure;
scatterhist(x,y)

Transform the data to the copula scale (unit square) using a kernel estimator of the cumulative distribution function.

u = ksdensity(x,x,'function','cdf');
v = ksdensity(y,y,'function','cdf');

figure;
scatterhist(u,v)
xlabel('u')
ylabel('v')

Fit a t copula to the data.

rng default  % For reproducibility
[Rho,nu] = copulafit('t',[u v],'Method','ApproximateML')

Rho =

    1.0000    0.7220
    0.7220    1.0000


nu =

   2.6133e+06

Generate a random sample from the t copula.

r = copularnd('t',Rho,nu,1000);
u1 = r(:,1);
v1 = r(:,2);

figure;
scatterhist(u1,v1)
xlabel('u')
ylabel('v')
set(get(gca,'children'),'marker','.')

Transform the random sample back to the original scale of the data.

x1 = ksdensity(x,u1,'function','icdf');
y1 = ksdensity(y,v1,'function','icdf');

figure;
scatterhist(x1,y1)
set(get(gca,'children'),'marker','.')

Input Arguments

u — Copula values

matrix of scalar values in the range (0,1)

Copula values, specified as a matrix of scalar values in the range (0,1). If u is an n-by-p matrix, then its values represent n points in the p-dimensional unit hypercube. If u is an n-by-2 matrix, then its values represent n points in the unit square.

If you specify a bivariate Archimedean copula type ('Clayton', 'Frank', or 'Gumbel'), then u must be an n-by-2 matrix.

Data Types: single | double

family — Bivariate Archimedean copula family

'Clayton' | 'Frank' | 'Gumbel'

Bivariate Archimedean copula family, specified as one of the following.

'Clayton'	Clayton copula
'Frank'	Frank copula
'Gumbel'	Gumbel copula

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Alpha',0.01,'Method','ApproximateML' computes 99% confidence intervals for the estimated copula parameter and uses an approximation method to fit the copula.

Alpha — Significance level for confidence intervals

0.05 (default) | scalar value in the range (0,1)

Significance level for confidence intervals, specified as the comma-separated pair consisting of 'Alpha' and a scalar value in the range (0,1). copulafit returns approximate 100 × (1–Alpha)% confidence intervals.

Example: 'Alpha',0.01

Data Types: single | double

Method — Method for fitting t copula

'ML' (default) | 'ApproximateML'

Method for fitting t copula, specified as the comma-separated pair consisting of 'Method' and either 'ML' or 'ApproximateML'.

If you specify 'ApproximateML', then copulafit fits a t copula for large samples by maximizing an objective function that approximates the profile log likelihood for the degrees of freedom parameter [1]. This method can be significantly faster than maximum likelihood ('ML'), but the estimates and confidence limits may not be accurate for small to moderate sample sizes.

Example: 'Method','ApproximateML'

Options — Control parameter specifications

structure

Control parameter specifications, specified as the comma-separated pair consisting of 'Options' and an options structure created by statset. To see the fields and default values used by copulafit, type statset('copulafit') at the command prompt.

This name-value pair is not applicable when you specify the copula type as 'Gaussian'.

Data Types: struct

Output Arguments

rhohat — Estimated correlation parameters for the fitted Gaussian copula

matrix of scalar values

Estimated correlation parameters for the fitted Gaussian copula, given the data in u, returned as a matrix of scalar values.

nuhat — Estimated degrees of freedom parameter for the fitted t copula

scalar value

Estimated degrees of freedom parameter for the fitted t copula, returned as a scalar value.

nuci — Approximate confidence interval for the degrees of freedom parameter

1-by-2 matrix of scalar values

Approximate confidence interval for the degrees of freedom parameter, returned as a 1-by-2 matrix of scalar values. The first column contains the lower boundary, and the second column contains the upper boundary. By default, copulafit returns the approximate 95% confidence interval. You can specify a different confidence interval using the 'Alpha' name-value pair.

paramhat — Estimated copula parameter for the fitted Archimedean copula

scalar value

Estimated copula parameter for the fitted Archimedean copula, returned as a scalar value.

paramci — Approximate confidence interval for the copula parameter

1-by-2 matrix of scalar values

Approximate confidence interval for the copula parameter, returned as a 1-by-2 matrix of scalar values. The first column contains the lower boundary, and the second column contains the upper boundary. By default, copulafit returns the approximate 95% confidence interval. You can specify a different confidence interval using the 'Alpha' name-value pair.

Algorithms

By default, copulafit uses maximum likelihood to fit a copula to u. When u contains data transformed to the unit hypercube by parametric estimates of their marginal cumulative distribution functions, this is known as the Inference Functions for Margins (IFM) method. When u contains data transformed by the empirical cdf (see ecdf), this is known as Canonical Maximum Likelihood (CML).

References

[1] Bouyé, E., V. Durrleman, A. Nikeghbali, G. Riboulet, and T. Roncalli. “Copulas for Finance: A Reading Guide and Some Applications.” Working Paper. Groupe de Recherche Opérationnelle, Crédit Lyonnais, Paris, 2000.

Version History

Introduced in R2007b