\name{SQUIC}
\alias{SQUIC}

\title{
\packageTitle{SQUIC}
}

\description{
SQUIC is a second-order, L1-regularized maximum likelihood method for performant 
large-scale sparse precision matrix estimation.
}

\usage{
 SQUIC(Y,lambda,max_iter=100,tol=1e-3,tol_inv=1e-4,verbose=1,M=NULL,X0=NULL,W0=NULL)
}
 
\arguments{
 \item{Y}{Input data in the form p (dimensions) x n (samples).}
 \item{lambda}{Scalar tuning parameter a non-zero positive number.}
 \item{max_iter}{Maximum number of Newton iterations. Default to 100.}
 \item{tol}{Tolerance for convergence. Default to 1e-3.}
 \item{tol_inv}{Tolerance for approximate inversion. Default to 1e-4.}
 \item{verbose}{Level of printing output (0 or 1). Default to 1.}
 \item{M}{A symmetric sparse(p x p); See note (3) below for details.}
 \item{X0}{Initial guess of the precision matrix as a sparse matrix (p x p). Default to Identity (denote by NULL).}
 \item{W0}{Initial guess of the inverse precision matrix as a sparse matrix (p x p). Default to Identity (denote by NULL).}
}

\details{
SQUIC is a fast precision matrix estimation package intended for large-scale 
applications. The algorithm utilizes second-order information in conjunction with 
a highly optimized, supernodal Cholesky factorization routine (CHOLMOD), a 
block-oriented computational approach for both the coordinate descent and the 
approximate matrix inversion, and finally, a sparse representation of the sample 
covariance matrix. The library is implemented in C++ with shared-memory 
parallelization using OpenMP.

For further details, please see the listed references.

NOTE:
(1) If max_iter=0, the value of the inverse of the precision matrix (W) is the 
sparse sample covariance matrix (S).
(2) The number of threads used by SQUIC can be defined by setting the 
environment variable OMP_NUM_THREADS (e.g., base> export OMP_NUM_THREADS=12). 
This may require a restart of the session.
(3) The matrix tuning paramter Lambda:=M_{ij} for M_{ij} != 0 and 
Lambda_{ij}:=lambda, if otherwise. When M=NULL we have Lambda_{ij}=lambda.
}
 
\value{
 \item{X}{Estimated precision matrix (p x p).}
 \item{W}{Estimated inverse of the precision matrix (p x p).}
 \item{info_time_total}{Total runtime.}
 \item{info_time_sample_cov}{Runtime of the sample covariance matrix.}
 \item{info_time_optimize}{Runtime of the Newton steps.}
 \item{info_time_factor}{Runtime of the matrix factorization.}
 \item{info_time_approximate_inv}{Runtime of the approximate matrix inversion.}
 \item{info_time_coordinate_upd}{Runtime of the coordinate descent update.}
 \item{info_objective}{Objective value at each Newton iteration.}
 \item{info_logdetX}{Log determinant of the estimated precision matrix.}
 \item{info_trSX}{Trace of sample cov. matrix times the estimated prec. matrix.}
 }

\references{

Eftekhari, A., Gaedke-Merzhaeuser, L., Pasadakis, D.,  Bollhöfer, M., Scheidegger, S. and Schenk, O., 2023. 
Large-Scale Precision Matrix Estimation With SQUIC. ACM Trans. Math. Softw. [Forthcoming], 2023.

Bollhöfer, M., Eftekhari, A., Scheidegger, S. and Schenk, O., 2019. Large-Scale 
Sparse Inverse Covariance Matrix Estimation. SIAM Journal on Scientific 
Computing, 41(1), pp.A380-A401.

Eftekhari, A., Bollhöfer, M. and Schenk, O., 2018, November. Distributed Memory 
Sparse Inverse Covariance Matrix Estimation on High-performance Computing 
Architectures. In SC18: International Conference for High Performance Computing, 
Networking, Storage and Analysis (pp. 253-264). IEEE.

Eftekhari, A., Pasadakis, D., Bollhöfer, M., Scheidegger, S. and Schenk, O., 
2021. Block-Enhanced Precision Matrix Estimation for Large-Scale Datasets. 
Journal of Computational Science, p. 101389.
}

\examples{
library(SQUIC)

p <- 1024
n <- 100
lambda <- .4

# generate a tridiagonal matrix
iC_star <- Matrix::bandSparse(p, p, (-1):1, list(rep(-.5, p-1), rep(1.25,   p), rep(-.5, p-1)))

# generate the data
set.seed(1)
z    <- replicate(n,rnorm(p))
iC_L <- chol(iC_star)
Y    <- matrix(solve(iC_L,z),p,n)

# run SQUIC
out <- SQUIC(Y,lambda)
}

\keyword{sparse precision matrix estimation}
\keyword{multivariate analysis}
\keyword{graphical lasso}
