% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/network_estimation.R
\name{network_estimation}
\alias{network_estimation}
\title{L0 Norm Regularized Network Estimation}
\usage{
network_estimation(
  data,
  n = NULL,
  corr = c("auto", "pearson", "spearman"),
  na_data = c("pairwise", "listwise"),
  penalty = c("atan", "exp", "gumbel", "log", "weibull"),
  gamma = NULL,
  adaptive = TRUE,
  nlambda = 50,
  lambda_min_ratio = 0.01,
  penalize_diagonal = TRUE,
  ic = c("AIC", "AICc", "BIC", "BIC0", "EBIC", "MBIC"),
  ebic_gamma = 0.5,
  fast = TRUE,
  LLA = FALSE,
  LLA_threshold = 0.001,
  LLA_iter = 10000,
  network_only = TRUE,
  verbose = FALSE,
  ...
)
}
\arguments{
\item{data}{Matrix or data frame.
Should consist only of variables to be used in the analysis}

\item{n}{Numeric (length = 1).
Sample size \strong{must} be provided if \code{data} provided is a correlation matrix}

\item{corr}{Character (length = 1).
Method to compute correlations.
Defaults to \code{"auto"}.
Available options:

\itemize{

\item \code{"auto"} --- Automatically computes appropriate correlations for
the data using Pearson's for continuous, polychoric for ordinal,
tetrachoric for binary, and polyserial/biserial for ordinal/binary with
continuous. To change the number of categories that are considered
ordinal, use \code{ordinal_categories}
(see \code{\link[L0ggm]{polychoric_matrix}} for more details)

\item \code{"pearson"} --- Pearson's correlation is computed for all
variables regardless of categories

\item \code{"spearman"} --- Spearman's rank-order correlation is computed
for all variables regardless of categories

}

For other similarity measures, compute them first and input them
into \code{data} with the sample size (\code{n})}

\item{na_data}{Character (length = 1).
How should missing data be handled?
Defaults to \code{"pairwise"}.
Available options:

\itemize{

\item \code{"pairwise"} --- Computes correlation for all available cases between
two variables

\item \code{"listwise"} --- Computes correlation for all complete cases in the dataset

}}

\item{penalty}{Character (length = 1).
Defaults to \code{"weibull"}.
Available options:

\itemize{

\item \code{"atan"} --- Arctangent (Wang & Zhu, 2016)
\deqn{\lambda \cdot (\gamma + \frac{2}{\pi}) \cdot \arctan\left(\frac{|x|}{\gamma}\right)}

\item \code{"exp"} --- EXP (Wang, Fan, & Zhu, 2018)
\deqn{\lambda \cdot (1 - e^{-\frac{|x|}{\gamma}})}

\item \code{"gumbel"} --- Gumbel
\deqn{\frac{\lambda}{1 - e^{-1}} \cdot \left(e^{-e^{-\frac{|x|}{\gamma}}} - e^{-1}\right)}

\item \code{"log"} --- Log (Candes, Wakin, & Boyd, 2008)
\deqn{\frac{\lambda \cdot \log\left(1 + \frac{|x|}{\gamma}\right)}{\log\left(1 + \frac{1}{\gamma}\right)}}

\item \code{"weibull"} --- Weibull
\deqn{\lambda \cdot \left(1 - e^{-\left(\frac{|x|}{\gamma}\right)^k}\right)}

}}

\item{gamma}{Numeric (length = 1).
Adjusts the shape of the penalty.
Defaults:

\itemize{

\item \code{"atan"} = 0.01

\item \code{"exp"} = 0.01

\item \code{"gumbel"} = 0.01

\item \code{"log"} = 0.10

\item \code{"weibull"} = 0.01

}}

\item{adaptive}{Boolean (length = 1).
Whether data-adaptive (gamma) parameters should be used.
Defaults to \code{TRUE}.
Set to \code{FALSE} to apply default gamma parameters for
adaptive penalties.
Available options:

\itemize{

\item \code{"exp"}

\item \code{"gumbel"}

\item \code{"weibull"}

}

When \code{adaptive = TRUE}, gamma is set to the 10th percentile of the
distribution fitted to the empirical partial correlations}

\item{nlambda}{Numeric (length = 1).
Number of lambda values to test.
Defaults to \code{50}}

\item{lambda_min_ratio}{Numeric (length = 1).
Ratio of lowest lambda value compared to maximal lambda.
Defaults to \code{0.01}}

\item{penalize_diagonal}{Boolean (length = 1).
Should the diagonal be penalized?
Defaults to \code{TRUE}}

\item{ic}{Character (length = 1).
What information criterion should be used for model selection?
Available options include:

\itemize{

\item \code{"AIC"} --- Akaike's information criterion: \eqn{-2L + 2E}

\item \code{"AICc"} --- AIC corrected: \eqn{AIC + \frac{2E^2 + 2E}{n - E - 1}}

\item \code{"BIC"} --- Bayesian information criterion: \eqn{-2L + E \cdot \log{(n)}}

\item \code{"BIC0"} --- Bayesian information criterion not (Dicker et al., 2013): \eqn{\log{\large(\frac{D}{n - E}\large)} + \large(\frac{\log{(n)}}{n}\large) \cdot E}

\item \code{"EBIC"} --- Extended BIC: \eqn{BIC + 4E \cdot \gamma \cdot \log{(E)}}

\item \code{"MBIC"} --- Modified Bayesian information criterion (Wang et al., 2018):  \eqn{\log{\large(\frac{D}{n - E}\large)} + \large(\frac{\log{(n)} \cdot E}{n}\large) \cdot \log{(\log{(p)}})}

}

Term definitions:

\itemize{

\item \eqn{n} --- sample size

\item \eqn{p} --- number of variables

\item \eqn{E} --- edges

\item \eqn{S} --- empirical correlation matrix

\item \eqn{K} --- estimated inverse covariance matrix (network)

\item \eqn{L = \frac{n}{2} \cdot \log \text{det} K - \sum_{i=1}^p (SK)_{ii}}

\item \eqn{D = n \cdot \sum_{i=1}^p (SK)_{ii} - \log \text{det} K}

}

Defaults to \code{"BIC"}}

\item{ebic_gamma}{Numeric (length = 1)
Value to set gamma parameter in EBIC (see above).
Defaults to \code{0.50}

\emph{Only used if \code{ic = "EBIC"}}}

\item{fast}{Boolean (length = 1).
Whether the \code{\link[glassoFast]{glassoFast}} version should be used
to estimate the GLASSO.
Defaults to \code{TRUE}.

The fast results \emph{may} differ by less than floating point of the original
GLASSO implemented by \code{\link[glasso]{glasso}} and should not impact reproducibility much (set to \code{FALSE} if concerned)}

\item{LLA}{Boolean (length = 1).
Should Local Linear Approximation be used to find optimal minimum?
Defaults to \code{FALSE} or a single-pass approximation, which can be
significantly faster (Zou & Li, 2008).
Set to \code{TRUE} to find global minimum based on convergence (\code{LLA_threshold})}

\item{LLA_threshold}{Numeric (length = 1).
When performing the Local Linear Approximation, the maximum threshold
until convergence is met.
Defaults to \code{1e-03}}

\item{LLA_iter}{Numeric (length = 1).
Maximum number of iterations to perform to reach convergence.
Defaults to \code{10000}}

\item{network_only}{Boolean (length = 1).
Whether the network only should be output.
Defaults to \code{TRUE}.
Set to \code{FALSE} to obtain all output for the
network estimation method}

\item{verbose}{Boolean (length = 1).
Whether messages and (insignificant) warnings should be output.
Defaults to \code{FALSE} (silent calls).
Set to \code{TRUE} to see all messages and warnings for every function call}

\item{...}{Additional arguments to be passed on to \code{auto.correlate}}
}
\value{
When \code{network_only = TRUE} (default), returns a \eqn{p \times p}
numeric matrix of partial correlations representing the estimated Gaussian
graphical model. Off-diagonal entry \eqn{[i,j]} is the partial correlation
between variables \eqn{i} and \eqn{j} controlling for all other variables,
with values in \eqn{[-1, 1]}; a value of zero indicates the absence of an
edge. Diagonal entries are zero. Row and column names are inherited from
\code{data}.

When \code{network_only = FALSE}, returns a named list with the following
elements:

\describe{

\item{\code{network}}{The \eqn{p \times p} partial correlation matrix
described above}

\item{\code{K}}{The \eqn{p \times p} estimated inverse covariance
(precision) matrix at the optimal lambda. Diagonal entries are the
conditional precisions; off-diagonal entries are proportional to
partial covariances}

\item{\code{R}}{The \eqn{p \times p} regularized covariance matrix
returned by GLASSO at the optimal lambda (the \code{w} component of the
GLASSO solution)}

\item{\code{penalty}}{Character string naming the penalty function used
(one of \code{"atan"}, \code{"exp"}, \code{"gumbel"}, \code{"log"},
\code{"weibull"})}

\item{\code{lambda}}{Numeric scalar giving the regularization parameter
value selected by the information criterion. Larger values correspond
to sparser networks}

\item{\code{gamma}}{Numeric scalar giving the shape parameter of the
penalty actually used. For adaptive penalties (\code{adaptive = TRUE}),
this is the data-derived value; otherwise it is the default or
user-supplied value}

\item{\code{correlation}}{The \eqn{p \times p} empirical correlation
matrix computed from \code{data}, used as input to the GLASSO}

\item{\code{criterion}}{Character string naming the information criterion
used for model selection (e.g., \code{"bic"})}

\item{\code{IC}}{Numeric scalar giving the value of the information
criterion at the optimal lambda}

}
}
\description{
A general function to estimate Gaussian graphical models using
L0 penalty approximations. All penalties are implemented using
either single-pass or full Local Linear Approximation (LLA: Fan & Li, 2001; Zou & Li, 2008)
}
\examples{
# Obtain default estimator (adaptive Weibull)
weibull_network <- network_estimation(
  data = basic_smallworld, LLA = TRUE
)

# Obtain Atan network
atan_network <- network_estimation(
  data = basic_smallworld, penalty = "atan", LLA = TRUE
)

# Obtain static EXP network
exp_network <- network_estimation(
  data = basic_smallworld, penalty = "exp",
  adaptive = FALSE, LLA = TRUE
)

}
\references{
\strong{Log penalty} \cr
Candes, E. J., Wakin, M. B., & Boyd, S. P. (2008).
Enhancing sparsity by reweighted l1 minimization.
\emph{Journal of Fourier Analysis and Applications}, \emph{14}(5), 877--905.

\strong{BIC0} \cr
Dicker, L., Huang, B., & Lin, X. (2013).
Variable selection and estimation with the seamless-L0 penalty.
\emph{Statistica Sinica}, \emph{23}(2), 929--962.

\strong{Local Linear Approximation} \cr
Fan, J., & Li, R. (2001).
Variable selection via nonconcave penalized likelihood and its oracle properties.
\emph{Journal of the American Statistical Association}, \emph{96}(456), 1348--1360.

\strong{EXP penalty} \cr
Wang, Y., Fan, Q., & Zhu, L. (2018).
Variable selection and estimation using a continuous approximation to the L0 penalty.
\emph{Annals of the Institute of Statistical Mathematics}, \emph{70}(1), 191--214.

\strong{Atan penalty} \cr
Wang, Y., & Zhu, L. (2016).
Variable selection and parameter estimation with the Atan regularization method.
\emph{Journal of Probability and Statistics}, \emph{2016}, 1--12.

\strong{Seminal simulation in network psychometrics} \cr
Williams, D. R. (2020).
Beyond lasso: A survey of nonconvex regularization in Gaussian graphical models.
\emph{PsyArXiv}.

\strong{One-step Local Linear Approximation} \cr
Zou, H., & Li, R. (2008).
One-step sparse estimates in nonconcave penalized likelihood models.
\emph{Annals of Statistics}, \emph{36}(4), 1509--1533.
}
\author{
Alexander P. Christensen <alexpaulchristensen@gmail.com>
}
