copulastat

Copula rank correlation

Syntax

r = copulastat('Gaussian',rho)

r = copulastat('t',rho,nu)

r = copulastat(family,alpha)

r = copulastat(___,Name,Value)

Description

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

Compute the Gaussian Copula Rank Correlation

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

rho — Linear correlation parameters

scalar values | matrix of scalar values

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

nu — Degrees of freedom

positive integer value

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

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

alpha — Bivariate Archimedean copula parameter

scalar value

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

Copula Family	Permitted Alpha Values
'Clayton'	[0,∞)
'Frank'	(-∞,∞)
'Gumbel'	[1,∞)

Data Types: single | double

Name-Value 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 quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'type','Spearman' computes Spearman’s rank correlation.

type — Type of rank correlation

'Kendall' (default) | 'Spearman'

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

r — Copula rank correlation

scalar value | matrix of scalar values

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.