% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/partial.isotropy.core.R
\name{pi.rank_r.core}
\alias{pi.rank_r.core}
\title{Partial-isotropy rank-r core.}
\usage{
pi.rank_r.core(p1, p2, r, lambda.gen = TRUE)
}
\arguments{
\item{p1}{the row dimension.}

\item{p2}{the column dimension.}

\item{r}{the partial-isotropy rank.}

\item{lambda.gen}{logical, whether to generate a non-spiked eigenvalue or not; TRUE by default.}
}
\value{
\code{pi.rank_r.core} returns a list with the following elements:
\describe{
\item{K1}{the row covariance matrix of dimension \eqn{p1 \times p1};}
\item{K2}{the column covariance matrix of dimension \eqn{p2 \times p2};}
\item{A}{an array of factor matrices of a rank-r core of dimension \eqn{p1 \times p2 \times r};}
\item{lambda}{If \code{lambda.gen}=TRUE, the non-spiked eigenvalue \eqn{\lambda \in (0,1)}. Otherwise, \code{NULL}.}
}
}
\description{
Randomly generate a list of parameters for the covariance matrix  with a partial-isotropy rank-\eqn{r} core for matrix-variate data.
}
\details{
If a core covariance matrix is of rank-\eqn{r} for general \eqn{r}, the dimension \eqn{(p_1, p_2)} should satisfy one of the followings: \eqn{p_1/p_2 + p_2/p_1 <r} or \eqn{p_1 = p_2 r} \eqn{(p_1 \geq p_2)}, or \eqn{p_2 = p_1 r} \eqn{(p_2 \geq p_1)}.
The covariance matrix \eqn{\Sigma} with a partial-isotropy rank-\eqn{r} core takes the form of
\deqn{\Sigma = (K_2 \otimes K_1)^{1/2}((1- \lambda) A A^\top + \lambda I_{p_1 p_2})(K_2 \otimes K_1)^{1/2, \top}}
for \eqn{\lambda \in (0,1)}, positive definite matrices \eqn{K_1} and \eqn{K_2} of the dimensions \eqn{p_1 \times p_1} and \eqn{p_2 \times p_2}, respectively, and \eqn{A \in \mathbb{R}^{p_1p_2\times r}} whose \eqn{i}th column is a vectorization of \eqn{p_1 \times p_2} matrix \eqn{A_i} such that \eqn{AA^\top} is a rank-\eqn{r} core.
Here \eqn{M^{1/2}} denotes either symmetric square root or the Cholesky factor of a positive definite matrix \eqn{M}.
The separable and core components of \eqn{\Sigma}, denoted \eqn{K} and \eqn{C}, are
\deqn{K=K_2\otimes K_1,\quad C=(1- \lambda) A A^\top + \lambda I_{p_1p_2}.}
For the exact formula when \eqn{p_1=p_2 r} or \eqn{p_2=p_1 r}, see Theorem 1 of Sung and Hoff (2025).
}
\examples{

set.seed(100)
# It must be that p1/p2+p2/p1<r or p1=p2r or p2=p1r
p1=12; p2=8; r=3
pi.rank_r.core(p1,p2,r)

}
\references{
Sung, B. and Hoff, P. (2025). Testing Separability of High-Dimensional Covariance Matrices.
arXiv preprint arXiv:2506.17463.
}
\author{
Bongjung Sung
}
