MoMA: MoMA - Modern Multivariate Analysis in R

#' R6 objects for storing and accessing the results of SFPCA / SFLDA /
#' SFCCA
#'
#' During initialization of an \code{SFPCA} object, \code{R}
#' calls the \code{C++}-side function, \code{cpp_multirank_BIC_grid_search},
#' and wraps the results returned. The \code{SFPCA} object also records
#' penalty levels and selection schemes of tuning parameters. Several
#' helper methods are provivded to facilitate access to results.
#' Initialization is delegated to \code{\link{moma_sfpca}}.
#'
#' The following table lists the supported methods for
#' R6 objects generated by \code{moma_*pca}, \code{moma_*cca}
#' and \code{moma_*lda} family of functions.
#' \tabular{lccccccc}{
#'    \tab \code{get_mat_by_index} \tab \code{interpolate}
#'    \tab \code{print} \tab \code{plot} \tab \code{X_project} \tab
#'    \code{Y_project} \tab \code{left_project}
#'  \cr
#'  \code{moma_*pca} \tab Yes \tab Yes
#'   \tab Yes \tab Yes \tab  \tab \tab  Yes
#'  \cr
#'   \code{moma_*cca} \tab Yes \tab
#'  \tab Yes \tab Yes \tab Yes  \tab Yes \tab
#'  \cr
#'   \code{moma_*lda} \tab Yes \tab
#'  \tab Yes \tab Yes \tab Yes \tab  \tab
#'  \cr
#' }
#'
#' @seealso \code{\link{moma_sfpca}},
#' \code{\link{moma_sflda}},
#' \code{\link{moma_sfcca}}
#'
#' @section Members:
#'
#' \describe{
#'   \item{
#'      \code{center,scale}
#'   }{
#'      The attributes "\code{scaled:center}" and "\code{scaled:scale}"
#'      of function \code{scale}. The numeric centering and scalings
#'      used (if any) of the data matrix.
#'  }
#'
#'  \item{
#'      \code{grid_result}
#'  }{
#'      A 5-D list containing the results evaluated on the parameter grid.
#'  }
#'
#'  \item{
#'      \code{select_scheme_list}
#'  }{
#'      A list with elements
#'      \code{select_scheme_alpha_u}, \code{select_scheme_alpha_v},
#'      \code{select_scheme_lambda_u}, \code{select_scheme_lambda_v}.
#'      Each of them is either 0 or 1. 0 stands for grid search
#'      and 1 stands for BIC search. Please see the \code{select_scheme}
#'      argument in the function \code{moma_sfpca}.
#'  }
#' }
#'
#' @section Methods:
#' \describe{
#'      \item{
#'          \code{get_mat_by_index}
#'      }{
#'         \describe{
#'              \item{
#'                  Arguments
#'              }{
#'                  For \code{moma_*pca}: \code{alpha_u}, \code{alpha_v},
#'                  \code{lambda_u}, \code{lambda_v}.
#'
#'                  \cr\cr
#'
#'                  For \code{moma_*cca} and \code{moma_*lda}: \code{alpha_x},
#'                  \code{alpha_y}, \code{lambda_x}, \code{lambda_y}.
#'
#'                  \cr\cr
#'
#'                  Indices of the parameters in the paramter grid, which have
#'                  been specified during initialization.
#'              }
#'              \item{
#'                  Functionality
#'              }{
#'                  Obtain the right and left penalized sigular vectors
#'                  located by the set of
#'                  indices (\code{alpha_u}, \code{alpha_v}, \code{lambda_u},
#'                  \code{lambda_v}) or (\code{alpha_x},
#'                  \code{alpha_y}, \code{lambda_x}, \code{lambda_y}). Penalized
#'                  sigular vectors are packed into matrices \code{U} and \code{V}.
#'              }
#'              \item{
#'                  Value
#'              }{
#'                  For \code{moma_*pca}, it is a list containing \code{U},
#'                  \code{V}, \code{d}, \code{chosen_lambda_u}, \code{chosen_lambda_u},
#'                  \code{chosen_lambda_v}, \code{chosen_alpha_u},
#'                  \code{chosen_alpha_v}.
#'
#'                  \cr\cr
#'
#'                  For \code{moma_*lda}, it is a list containing \code{X_PC_loadings},
#'                  \code{Y_group_scores}, \code{d}, \code{chosen_lambda_x},
#'                  \code{chosen_lambda_y}, \code{chosen_alpha_x},
#'                  \code{chosen_alpha_y}.
#'
#'                  \cr\cr
#'
#'                  For \code{moma_*cca}, it is a list containing \code{X_PC_loadings},
#'                  \code{Y_PC_loadings}, \code{d}, \code{chosen_lambda_x},
#'                  \code{chosen_lambda_y}, \code{chosen_alpha_x},
#'                  \code{chosen_alpha_y}.
#'              }
#'          }
#'      }
#'      \item{
#'          \code{*_project}
#'      }{
#'         \describe{
#'              \item{
#'                  Arguments
#'              }{
#'                  For \code{left_project} (available for \code{moma_*pca}):
#'                  \code{newX}, \code{alpha_u},
#'                  \code{alpha_v}, \code{lambda_u}, \code{lambda_v}.
#'
#'                  \cr\cr
#'
#'                  For \code{X_project} (available for \code{moma_*cca} and
#'                  \code{moma_*lda})): \code{newX}, \code{alpha_x},
#'                  \code{alpha_y}, \code{lambda_x}, \code{lambda_y}.
#'
#'                  \cr\cr
#'
#'                  For \code{Y_project} (available for \code{moma_*cca}):
#'                  \code{newY}, \code{alpha_x},
#'                  \code{alpha_y}, \code{lambda_x}, \code{lambda_y}.
#'
#'                  \cr\cr
#'
#'                  \code{newX} or \code{newY} is a new raw data matrix
#'                  (un-centered and un-scaled) of
#'                  an appropriate number of columns. (\code{alpha_u},
#'                  \code{alpha_v}, \code{lambda_u}, \code{lambda_v})
#'                  or (\code{alpha_x},
#'                  \code{alpha_y}, \code{lambda_x}, \code{lambda_y}) is the set of
#'                  indices to locate the penalalized singular vectors used to form
#'                  the basis of the low dimensional space.
#'              }
#'              \item{
#'                  Functionality
#'              }{
#'                  Project the new data into the space spaned by the
#'                  penalized left singular vectors, after scaling and
#'                  centering as needed.
#'              }
#'              \item{
#'                  Value
#'              }{
#'                  A list containing the scaled and centered data (as needed)
#'                  \code{scaled_data} and the projected data \code{proj_data}.
#'              }
#'          }
#'      }
#'      \item{
#'          \code{interpolate}
#'      }{
#'         \describe{
#'              \item{
#'                  Arguments
#'              }{
#'                  \code{alpha_u}, \code{alpha_v},
#'                  \code{lambda_u}, \code{lambda_v}, \code{exact}.
#'
#'                  \cr\cr
#'
#'                  \code{exact} is a logical scalar. (\code{alpha_u},
#'                  \code{alpha_v}, \code{lambda_u}, \code{lambda_v}) is the
#'                  set of new paramters of interest.
#'
#'                  \cr\cr
#'
#'                  When \code{exact = TRUE}, a new solution will be calculated
#'                   exactly with the parameters set to (\code{alpha_u},
#'                  \code{alpha_v}, \code{lambda_u}, \code{lambda_v}).
#'
#'                  \cr\cr
#'
#'                  When \code{exact = FALSE}, an approximate solution
#'                  will be given by taking the average of two solutions
#'                  whose parameters' values are "closest" to the ones
#'                  specified by the user.
#'              }
#'              \item{
#'                  Functionality
#'              }{
#'                  For a set of new parameters, give an approximate
#'                  solution of SFPCA based on
#'                  pre-calculated solutions, or just perform
#'                  exact calculation.
#'              }
#'              \item{
#'                  Value
#'              }{
#'                  A list containing the exact (if \code{exact = TURE} has been
#'                  used) or approximate solution (if \code{exact = FALSE} has
#'                  been used) solution \code{U} and \code{V}.
#'              }
#'          }
#'      }
#'      \item{\code{print}}{Display tuning parameters and selection schemes.}
#'      \item{\code{plot}}{Start a Shiny application and visualize penalized
#'                          singular vectors and projected data.}
#'
#'  }
#' @name moma_R6
NULL