% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jackstraw_irlba.R
\name{jackstraw_irlba}
\alias{jackstraw_irlba}
\title{Non-Parametric Jackstraw for Principal Component Analysis (PCA) using the augmented implicitly restarted Lanczos bidiagonalization algorithm (IRLBA)}
\usage{
jackstraw_irlba(
  dat,
  r = NULL,
  r1 = NULL,
  s = NULL,
  B = NULL,
  covariate = NULL,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{dat}{a data matrix with \code{m} rows as variables and \code{n} columns as observations.}

\item{r}{a number (a positive integer) of significant principal components. See \link{permutationPA} and other methods.}

\item{r1}{a numeric vector of principal components of interest. Choose a subset of \code{r} significant PCs to be used.}

\item{s}{a number (a positive integer) of ``synthetic'' null variables. Out of \code{m} variables, \code{s} variables are independently permuted.}

\item{B}{a number (a positive integer) of resampling iterations. There will be a total of \code{s*B} null statistics.}

\item{covariate}{a data matrix of covariates with corresponding \code{n} observations (do not include an intercept term).}

\item{verbose}{a logical specifying to print the computational progress.}

\item{...}{additional arguments to \code{\link[irlba]{irlba}}.}
}
\value{
\code{jackstraw_irlba} returns a list consisting of
\item{p.value}{\code{m} p-values of association tests between variables and their principal components}
\item{obs.stat}{\code{m} observed F-test statistics}
\item{null.stat}{\code{s*B} null F-test statistics}
}
\description{
Test association between the observed variables and their latent variables captured by principal components (PCs). PCs are computed using the augmented implicitly restarted Lanczos bidiagonalization algorithm (IRLBA; see \code{\link[irlba]{irlba}}).
}
\details{
This function computes \code{m} p-values of linear association between \code{m} variables and their PCs.
Its resampling strategy accounts for the over-fitting characteristics due to direct computation of PCs from the observed data
and protects against an anti-conservative bias.

Provide the data matrix, with \code{m} variables as rows and \code{n} observations as columns.
Given that there are \code{r} significant PCs, this function tests for linear association between
\code{m} variables and their \code{r} PCs.

You could specify a subset of significant PCs that you are interested in (\code{r1}). If \code{r1} is given,
then this function computes statistical significance of association between \code{m} variables and \code{r1},
while adjusting for other PCs (i.e., significant PCs that are not your interest).
For example, if you want to identify variables associated with first and second PCs,
when your data contains three significant PCs, set \code{r=3} and \code{r1=c(1,2)}.

Please take a careful look at your data and use appropriate graphical and statistical criteria
to determine a number of significant PCs, \code{r}. The number of significant PCs depends on the data structure and the context.
In a case when you fail to specify \code{r}, it will be estimated from a permutation test (Buja and Eyuboglu, 1992)
using a function \link{permutationPA}.

If \code{s} is not supplied, \code{s} is set to about 10\\% of \code{m} variables.
If \code{B} is not supplied, \code{B} is set to \code{m*10/s}.
}
\examples{
## simulate data from a latent variable model: Y = BL + E
B = c(rep(1,10),rep(-1,10), rep(0,180))
L = rnorm(20)
E = matrix(rnorm(200*20), nrow=200)
dat = B \%*\% t(L) + E
dat = t(scale(t(dat), center=TRUE, scale=TRUE))

## apply the jackstraw
out = jackstraw_irlba(dat, r=1)

## Use optional arguments
## For example, set s and B for a balance between speed of the algorithm and accuracy of p-values
\dontrun{
## out = jackstraw_irlba(dat, r=1, s=10, B=200)
}

}
\references{
Chung and Storey (2015) Statistical significance of variables driving systematic variation in high-dimensional data. Bioinformatics, 31(4): 545-554 \doi{10.1093/bioinformatics/btu674}
}
\seealso{
\link{jackstraw} \link{jackstraw_subspace} \link{permutationPA}
}
\author{
Neo Christopher Chung \email{nchchung@gmail.com}
}
