fps: Fantope Projection and Selection

# This file was generated by Rcpp::compileAttributes
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Fantope Projection and Selection
#'
#' This function computes a solution path of the Fantope Projection and
#' Selection (FPS) estimator.  It takes a symmetric matrix \code{S} as input 
#' and returns an object containing a list of projection matrices 
#' estimated by FPS over a sequence of regularization parameter values.
#'
#' By default, a sensible minimum value of the regularization parameter 
#' is automatically chosen so that the minimally regularized solution
#' is different from PCA.
#'
#' @param S              Input matrix (assumed to be symmetric)
#' @param ndim           Target subspace dimension (can be fractional)
#' @param nsol           Number of solutions to compute
#' @param maxnvar        Suggested maximum number of variables to include 
#'                       (ignored if \code{maxnvar <= 0})
#' @param lambdamin      Minimum value of lambda (set automatically if 
#'                       \code{lambdamin < 0})
#' @param lambda         Vector of regularization parameter values; overrides //'                       nsol, maxnvar, and lambdamin if nonempty
#' @param maxiter        Maximum number of iterations for each solution
#' @param tolerance      Convergence threshold
#' @param verbose        Level of verbosity; Silent if \code{verbose = 0}, otherwise 
#'                       display more messages and progress indicators as \code{verbose} 
#'                       increases
#'
#' @return An S3 object of class \code{fps} which is a list with the 
#'         following components:
#'   \item{ndim}{trace (dimension) of the estimate}
#'   \item{lambda}{a vector containing the regularization parameters of each 
#'                 estimate}
#'   \item{projection}{a list containing the the projection matrix estimates}
#'   \item{leverage}{a matrix whose columns are the diagonal entries of the 
#'                   projection matrix estimates}
#'   \item{L1}{a vector of the sum of absolute values of each estimate}
#'   \item{var.explained}{variance explained by each estimate (trace inner 
#'                        product of the projection and \code{S})}
#'   \item{var.total}{total variance (trace of \code{S})}
#'   \item{niter}{a vector containing the number of ADMM iterations for each 
#'                estimate}
#'
#' @details
#' For large input matrices (1000-by-1000 or larger) it is recommended 
#' that the \code{maxnvar} argument be set to a reasonably small number.
#'
#' @export
#'
#' @examples
#' # Apply FPS to the standardized wine data from the UCI ML repository
#' data(wine)
#' out <- fps(cor(wine), ndim = 2)
#' print(out)
#' plot(out)
#'
#' # Create a synthetic dataset by adding noise variables to the wine data
#' j <- sample(1:ncol(wine), size = 500 - ncol(wine), replace = TRUE)
#' noise <- apply(wine[, j], 2, sample, replace = TRUE)
#' colnames(noise) <- rep('noise', ncol(noise))
#' x <- cbind(wine, noise)
#' out <- fps(cor(x), ndim = 2, maxnvar = 50, verbose = 1)
#'
#' \dontrun{
#' # Choose lambda by cross-validation (this may take a few minutes)
#' cvout <- cv(out, x, FUN = cor, verbose = 1)
#' plot(cvout)
#' v <- coef(out, lambda = cvout$lambda.cv)
#' print(v)
#' }
#'
fps <- function(S, ndim, nsol = 50L, maxnvar = -1L, lambdamin = -1, lambda = as.numeric( c()), maxiter = 100L, tolerance = 1e-3, verbose = 0L) {
    .Call('fps_fps', PACKAGE = 'fps', S, ndim, nsol, maxnvar, lambdamin, lambda, maxiter, tolerance, verbose)
}