# copulastat

Copula rank correlation

## Syntax

``r = copulastat('Gaussian',rho)``
``r = copulastat('t',rho,nu)``
``r = copulastat(family,alpha)``
``r = copulastat(___,Name,Value)``

## Description

example

````r = copulastat('Gaussian',rho)` returns the Kendall’s rank correlation, `r`, that corresponds to a Gaussian copula with linear correlation parameters `rho`.```
````r = copulastat('t',rho,nu)` returns the Kendall’s rank correlation, `r`, that corresponds to a t copula with linear correlation parameters, `rho`, and degrees of freedom parameter, `nu`.```
````r = copulastat(family,alpha)` returns the Kendall’s rank correlation, `r`, that corresponds to a bivariate Archimedean copula that has the type specified by `family` and scalar parameter `alpha`.```
````r = copulastat(___,Name,Value)` returns the copula rank correlation with additional options specified by one or more `Name,Value` pair arguments, using any of the previous syntaxes. For example, you can return Spearman’s rho rank correlation.```

## Examples

collapse all

Compute the rank correlation for a Gaussian copula with the specified linear correlation parameter `rho`.

```rho = -.7071; tau = copulastat('gaussian',rho)```
```tau = -0.5000 ```

Use the copula to generate dependent random values from a beta distribution that has parameters a and b equal to 2.

```rng default % For reproducibility u = copularnd('gaussian',rho,100); b = betainv(u,2,2);```

Verify that the sample has a rank correlation approximately equal to `tau`.

`tau_sample = corr(b,'type','k')`
```tau_sample = 2×2 1.0000 -0.5135 -0.5135 1.0000 ```

## Input Arguments

collapse all

Linear correlation parameters for the copula, specified as a scalar value or matrix of scalar values.

• If `rho` is a scalar correlation coefficient, then `r` is a scalar correlation coefficient corresponding to a bivariate copula.

• If `rho` is a p-by-p correlation matrix, then `r` is a p-by-p correlation matrix.

Data Types: `single` | `double`

Degrees of freedom for the t copula, specified as a positive integer value.

Data Types: `single` | `double`

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

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

Bivariate Archimedean copula parameter, specified as a scalar value. Permitted values for `alpha` depend on the specified copula family.

Copula FamilyPermitted Alpha Values
`'Clayton'`[0,∞)
`'Frank'`(-∞,∞)
`'Gumbel'`[1,∞)

Data Types: `single` | `double`

### 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: `'type','Spearman'` computes Spearman’s rank correlation.

Type of rank correlation, specified as the comma-separated pair consisting of `'type'` and one of the following.

• `'Kendall'` — Compute Kendall’s tau.

• `'Spearman'` — Compute Spearman’s rho (rank correlation).

`copulastat` uses an approximation to Spearman’s rank correlation for copula families that do not have an existing analytic formula. The approximation is based on a smooth fit to values computed at discrete values of the copula parameters. For a t copula, the approximation is accurate for degrees of freedom larger than 0.05.

Example: `'type','Spearman'`

## Output Arguments

collapse all

Copula rank correlation, returned as a scalar value or matrix of scalar values.

• If `rho` is a scalar correlation coefficient, then `r` is a scalar correlation coefficient corresponding to a bivariate copula.

• If `rho` is a p-by-p correlation matrix, then `r` is a p-by-p correlation matrix.

## Version History

Introduced in R2006a