rethinking (version 2.13)

dlkjcorr: LKJ correlation matrix probability density

Description

Functions for computing density and producing random samples from the LKJ onion method correlation matrix distribution.

Usage

dlkjcorr( x , eta=1 , log=TRUE )
rlkjcorr( n , K , eta=1 )

Arguments

x

Matrix to compute probability density for

eta

Parameter controlling shape of distribution

K

Dimension of correlation matrix

log

If TRUE, returns log-probability instead of probability

n

Number of random matrices to sample

Details

The LKJ correlation matrix distribution is based upon work by Lewandowski, Kurowicka, and Joe. When the parameter eta is equal to 1, it defines a flat distribution of correlation matrices. When eta > 1, the distribution is instead concentrated towards to identity matrix. When eta < 1, the distribution is more concentrated towards extreme correlations at -1 or +1.

It can be easier to understand this distribution if we recognize that the individual correlations within the matrix follow a beta distribution defined on -1 to +1. Thus eta resembles theta in the beta parameterization with a mean p and scale (sample size) theta.

The function rlkjcorr returns an 3-dimensional array in which the first dimension indexes matrices. In the event that n=1, it returns instead a single matrix.

References

Lewandowski, Kurowicka, and Joe. 2009. Generating random correlation matrices based on vines and extended onion method. Journal of Multivariate Analysis. 100:1989-2001.

Stan Modeling Language User's Guide and Reference Manual, v2.6.2

Examples

# NOT RUN {
R <- rlkjcorr(n=1,K=2,eta=4)
dlkjcorr(R,4)

# plot density of correlation
R <- rlkjcorr(1e4,K=2,eta=4)
dens( R[,1,2] )

# visualize 3x3 matrix
R <- rlkjcorr(1e3,K=3,eta=2)
plot( R[,1,2] , R[,1,3] , col=col.alpha("black",0.2) , pch=16 )
# }