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

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

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.