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`.```

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

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 = 3.2727e+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

collapse all

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`

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.

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 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'`

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

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

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

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.

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

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