Documentation

copulaparam

Copula parameters as function of rank correlation

Syntax

  • rho = copulaparam('Gaussian',r) example
  • rho = copulaparam('t',r,nu)
  • alpha = copulaparam(family,r)
  • ___ = copulaparam(___,Name,Value)

Description

example

rho = copulaparam('Gaussian',r) returns the linear correlation parameters, rho, that correspond to a Gaussian copula with Kendall's rank correlation, r.

rho = copulaparam('t',r,nu) returns the linear correlation parameters, rho, that correspond to a t copula with Kendall's rank correlation, r, and degrees of freedom, nu.

alpha = copulaparam(family,r) returns the copula parameter, alpha, that corresponds to a bivariate Archimedean copula of the type specified by family, with Kendall's rank correlation, r.

___ = copulaparam(___,Name,Value) returns the correlation parameter using any of the previous syntaxes, with additional options specified by one or more Name,Value pair arguments. For example, you can specify whether the input rank correlation value is Spearman's rho or Kendell's tau.

Examples

collapse all

Generate Correlated Data Using the Inverse cdf

Generate correlated random data from a beta distribution using a bivariate Gaussian copula with Kendall's tau rank correlation equal to -0.5.

Compute the linear correlation parameter from the rank correlation value.

rng default  % For reproducibility
tau = -0.5;
rho = copulaparam('Gaussian',tau)
rho =

   -0.7071

Use a Gaussian copula to generate a two-column matrix of dependent random values.

u = copularnd('gaussian',rho,100);

Each column contains 100 random values between 0 and 1, inclusive, sampled from a continuous uniform distribution.

Create a scatterhist plot to visualize the random numbers generated using the copula.

figure
scatterhist(u(:,1),u(:,2))

The histograms show that the data in each column of the copula has a marginal uniform distribution. The scatterplot shows that the data in the two columns is negatively correlated.

Use the inverse cdf function betainv to transform each column of the uniform marginal distributions into random numbers from a beta distribution. In the first column, the first shape parameter A is equal to 1, and a second shape parameter B is equal to 2. In the second column, the first shape parameter A is equal to 1.5, and a second shape parameter B is equal to 2.

b = [betainv(u(:,1),1,2), betainv(u(:,2),1.5,2)];

Create a scatterhist plot to visualize the correlated beta distribution data.

figure
scatterhist(b(:,1),b(:,2))

The histograms show the marginal beta distributions for each variable. The scatterplot shows the negative correlation.

Verify that the sample has a rank correlation approximately equal to the initial value for Kendall's tau.

tau_sample = corr(b,'type','kendall')
tau_sample =

    1.0000   -0.5135
   -0.5135    1.0000

The sample rank correlation of -0.5135 is approximately equal to the -0.5 initial value for tau.

Related Examples

Input Arguments

collapse all

r — Copula rank correlationscalar value | matrix of scalar values

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

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

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

If the copula is specified as one of the bivariate Archimedean copula types ('Clayton', 'Frank', or 'Gumbel'), then r is a scalar value.

nu — Degrees of freedompositive 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

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: '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' — Indicates that the input value for r is a Kendall's tau correlation value

  • 'Spearman' — Indicates that the input value for r is a Spearman's rho rank correlation value

copulaparam 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

rho — Linear correlation parameterscalar value | matrix of scalar values

Linear correlation parameter, returned as a scalar value or matrix of scalar values.

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

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

alpha — Bivariate Archimedian copula parameterscalar value

Bivariate Archimedian copula parameter, returned 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

Was this topic helpful?