NEW Deflation for CCA and LDA

R/moma-R6.R

@@ -0,0 +1,220 @@
+#' 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