Documentation

copulafit

Fit copula to data

Syntax

  • rhohat = copulafit('Gaussian',u)
  • [rhohat,nuhat] = copulafit('t',u) example
  • [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.

example

[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

collapse all

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','.')

Related Examples

Input Arguments

collapse all

u — Copula valuesmatrix 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

Data Types: single | double

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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 intervals0.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 specificationsstructure

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

collapse all

rhohat — Estimated correlation parameters for the fitted Gaussian copulamatrix 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 copulascalar 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 parameter1-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 copulascalar value

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

paramci — Approximate confidence interval for the copula parameter1-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.

More About

collapse all

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.

Was this topic helpful?