% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lkjcorr_marginal.R
\name{lkjcorr_marginal}
\alias{lkjcorr_marginal}
\alias{dlkjcorr_marginal}
\alias{plkjcorr_marginal}
\alias{qlkjcorr_marginal}
\alias{rlkjcorr_marginal}
\title{Marginal distribution of a single correlation from an LKJ distribution}
\usage{
dlkjcorr_marginal(x, K, eta, log = FALSE)

plkjcorr_marginal(q, K, eta, lower.tail = TRUE, log.p = FALSE)

qlkjcorr_marginal(p, K, eta, lower.tail = TRUE, log.p = FALSE)

rlkjcorr_marginal(n, K, eta)
}
\arguments{
\item{x, q}{vector of quantiles.}

\item{K}{<\link{numeric}> Dimension of the correlation matrix. Must be greater than or equal to 2.}

\item{eta}{<\link{numeric}> Parameter controlling the shape of the distribution}

\item{log, log.p}{logical; if TRUE, probabilities p are given as log(p).}

\item{lower.tail}{logical; if TRUE (default), probabilities are
    \eqn{P[X \le x]} otherwise, \eqn{P[X > x]}.}

\item{p}{vector of probabilities.}

\item{n}{number of observations. If \code{length(n) > 1}, the length
    is taken to be the number required.}
}
\value{
\itemize{
\item \code{dlkjcorr_marginal} gives the density
\item \code{plkjcorr_marginal} gives the cumulative distribution function (CDF)
\item \code{qlkjcorr_marginal} gives the quantile function (inverse CDF)
\item \code{rlkjcorr_marginal} generates random draws.
}

The length of the result is determined by \code{n} for \code{rlkjcorr_marginal}, and is the maximum of the lengths of
the numerical arguments for the other functions.

The numerical arguments other than \code{n} are recycled to the length of the result. Only the first elements
of the logical arguments are used.
}
\description{
Marginal distribution for the correlation in a single cell from a correlation
matrix distributed according to an LKJ distribution.
}
\details{
The LKJ distribution is a distribution over correlation matrices with a single parameter, \eqn{\eta}{eta}.
For a given \eqn{\eta}{eta} and a \eqn{K \times K}{KxK} correlation matrix \eqn{R}{R}:

\deqn{R \sim \textrm{LKJ}(\eta)}{R ~ LKJ(eta)}

Each off-diagonal entry of \eqn{R}{R}, \eqn{r_{ij}: i \ne j}{r[i,j]: i != j}, has the
following marginal distribution (Lewandowski, Kurowicka, and Joe 2009):

\deqn{\frac{r_{ij} + 1}{2} \sim \textrm{Beta}\left(\eta - 1 + \frac{K}{2}, \eta - 1 + \frac{K}{2}\right)
}{(r[i,j] + 1)/2 ~ Beta(eta - 1 + K/2, eta - 1 + K/2)}

In other words, \eqn{r_{ij}}{r[i,j]} is marginally distributed according to the above Beta
distribution scaled into \eqn{(-1,1)}{(-1,1)}.
}
\examples{

library(dplyr)
library(ggplot2)

theme_set(theme_ggdist())

expand.grid(
  eta = 1:6,
  K = 2:6
) \%>\%
  ggplot(aes(y = ordered(eta), dist = "lkjcorr_marginal", arg1 = K, arg2 = eta)) +
  stat_slab() +
  facet_grid(~ paste0(K, "x", K)) +
  scale_y_discrete(limits = rev) +
  labs(
    title = paste0(
      "Marginal correlation for LKJ(eta) prior on different matrix sizes:\n",
      "dlkjcorr_marginal(K, eta)"
    ),
    subtitle = "Correlation matrix size (KxK)",
    y = "eta",
    x = "Marginal correlation"
  ) +
  theme(axis.title = element_text(hjust = 0))

}
\references{
Lewandowski, D., Kurowicka, D., & Joe, H. (2009). Generating random correlation matrices based on vines
and extended onion method. \emph{Journal of Multivariate Analysis}, 100(9), 1989--2001.
\doi{10.1016/j.jmva.2009.04.008}.
}
\seealso{
\code{\link[=parse_dist]{parse_dist()}} and \code{\link[=marginalize_lkjcorr]{marginalize_lkjcorr()}} for parsing specs that use the
LKJ correlation distribution and the \code{\link[=stat_slabinterval]{stat_slabinterval()}} family of stats for visualizing them.
}
