\name{plotcpfa}
\alias{plotcpfa}
\title{
Plot Optimal Model from Classification with Parallel Factor Analysis
}
\description{
Plots optimal model based on results from a 'wrapcpfa' object generated by 
function \code{cpfa}. 
}
\usage{
plotcpfa(object, cmeasure = "acc", meanvalue = TRUE, supNum = FALSE, 
         cmode = NULL, parallel = FALSE, cl = NULL, scale.remode = NULL, 
         newscales = 1, scale.abmode = NULL, sign.remode = NULL, newsigns = 1, 
         sign.abmode = NULL, ...)
}
\arguments{
\item{object}{
  An object of class 'wrapcpfa' from function \code{cpfa}.
}
\item{cmeasure}{
  Classification performance measure used to select the optimal number of 
  components. Options include \code{c("err", "acc", "tpr", "fpr", "tnr", "fnr", 
  "ppv", "npv", "fdr", "fom", "fs")}. If \code{cmeasure} is in \code{c("err", 
  "fpr", "fnr", "fdr", "fom")}, the number of components that minimized 
  \code{cmeasure} is selected among all classification methods. Otherwise, the 
  number that maximized \code{cmeasure} is selected.
}
\item{meanvalue}{
  Logical indicating whether to find the optimal number of components based on 
  the mean performance across replications from the results generated by 
  \code{cpfa}. If \code{meanvalue = FALSE}, the median is used. 
}
\item{supNum}{
  Logical indicating whether to suppress text displaying component weight values 
  within plot cells. If TRUE, values are not displayed.
}
\item{cmode}{
  Integer value of 1, 2, or 3 (or 4 if \code{x} is a four-way array) specifying 
  the mode whose component weights were predictors for classification when
  generating the 'wrapcpfa' object using function \code{cpfa}. If the original 
  input \code{model} from function \code{cpfa} was \code{pca}, \code{cmode} must 
  be 1 or 2 when the original input \code{x} was a two-way matrix. If the 
  original input \code{x} was a three-way or four-way array, \code{cmode} values 
  greater than 2 are ignored with a warning.
}
\item{parallel}{
  Logical indicating whether parallel computing should be used. If TRUE, 
  parallel computing is used.
}
\item{cl}{
  Cluster for parallel computing, which is used when \code{parallel = TRUE}. 
  Note that if \code{parallel = TRUE} and \code{cl = NULL}, then the cluster 
  is defined as \code{makeCluster(detectCores())}.
}
\item{scale.remode}{
  Character that indicates a mode to rescale. Must be one of \code{c("A", "B", 
  "C", "D")}. Sent directly to argument \code{mode} in function \code{rescale} 
  from package \bold{multiway}. See help file for \code{rescale} for additional 
  details. Ignored when function \code{cpfa} argument \code{model = 'pca'}. 
  If supplied, argument \code{scale.abmode} must also be supplied.
}
\item{newscales}{
  The root mean-square for columns of the mode indicated by \code{scale.remode}. 
  See help file for \code{rescale} for additional details. Ignored when function 
  \code{cpfa} argument \code{model = 'pca'}.
}
\item{scale.abmode}{
  Character that indicates the mode that absorbs the inverse of rescalings 
  applied to the mode indicated by \code{scale.remode}. Must be one of 
  \code{c("A", "B", "C", "D")}. Sent directly to argument \code{absorb} in 
  function \code{rescale} from package \bold{multiway}. See help file for 
  \code{rescale} for additional details. Ignored when function \code{cpfa} 
  argument \code{model = 'pca'}. If supplied, argument \code{scale.remode} must 
  also be supplied.
}
\item{sign.remode}{
  Character that indicates a mode to resign. Must be one of \code{c("A", "B", 
  "C", "D")}. Sent directly to argument \code{mode} in function \code{resign} 
  from package \bold{multiway}. See help file for \code{resign} for additional 
  details. Ignored when function \code{cpfa} argument \code{model = 'pca'}. 
  If supplied, argument \code{sign.abmode} must also be supplied.
}
\item{newsigns}{
  Scalar or vector indicating resignings for columns of the mode indicated by 
  \code{sign.remode}. See help file for \code{resign} for additional details. 
  Ignored when function \code{cpfa} argument \code{model = 'pca'}.
}
\item{sign.abmode}{
  Character that indicates the mode that absorbs the negation of the resignings 
  applied to the mode indicated by \code{sign.remode}. Must be one of 
  \code{c("A", "B", "C", "D")}. Sent directly to argument \code{absorb} in 
  function \code{resign} from package \bold{multiway}. See help file for 
  \code{resign} for additional details. Ignored when function \code{cpfa} 
  argument \code{model = 'pca'}. If supplied, argument \code{sign.remode} must 
  also be supplied.
}
\item{...}{
  Additional arguments to be passed to function \code{parafac} for fitting a 
  Parafac model or function \code{parafac2} for fitting a Parafac2 model. See 
  help file for function \code{parafac} or for function \code{parafac2} for 
  additional details.
}
}
\details{
Selects the number of components that optimized a performance measure across 
all classification methods used by \code{cpfa}. With this optimal number of 
components, fits the component model that was used by \code{cpfa} to 
create the input 'wrapcpfa' object. Uses same constraints used in \code{cpfa}. 
Plots component weights for this optimal model using heatmaps. Darker red 
indicates component weights that are more negative while darker green indicates 
component weights that are more positive. For three-way Parafac, plots A and B 
weights. For four-way Parafac, plots A, B, and C weights. For three-way 
Parafac2, plots B weights. For four-way Parafac2, plots B and C weights. For
PCA, plots loadings (i.e., A weights).
}
\value{
Returns one or more heatmap plots of component weights for the optimal component
model. Returns list of estimated component weights from the optimal model.
\item{Aweights}{
  Estimated A mode weights for optimal Parafac or Parafac2 model. For PCA, 
  contains the component loadings.
}
\item{Bweights}{
  Estimated B mode weights for optimal Parafac or Parafac2 model. For PCA, 
  contains the component scores.
}
\item{Cweights}{
  Estimated C mode weights for optimal Parafac or Parafac2 model. For PCA, 
  returns NULL.
}
\item{Dweights}{
  Estimated D mode weights for optimal Parafac or Parafac2 model. For PCA, 
  returns NULL.
}
}
\note{
Applications of this function to real datasets can be explored at the following
repository: \url{https://github.com/matthewasisgress/multiway-classification/}.
}
\author{
Matthew Asisgress <mattgress@protonmail.ch>
}
\references{
See help file for function \code{cpfa} for a list of references.
}
\examples{
########## Parafac2 example with 4-way array and multiclass response ##########
\dontrun{
# set seed and simulate a four-way ragged array related to a multiclass response
set.seed(5)

# define list of arguments specifying distributions for A and G weights
techlist <- list(distA = list(dname = "poisson", 
                              lambda = 3),                 # for A weights
                 distG = list(dname = "gamma", shape = 2, 
                              scale = 4))                  # for G weights

# define target correlation matrix for columns of D mode weights matrix
cormat <- matrix(c(1, .6, .6, .6, 1, .6, .6, .6, 1), nrow = 3, ncol = 3)

# simulate a four-way ragged array connected to a response
data <- simcpfa(arraydim = c(10, 11, 12, 100), model = "parafac2", nfac = 3, 
                nclass = 3, nreps = 1e2, onreps = 10, corresp = rep(.6, 3), 
                meanpred = rep(2, 3), modes = 4, corrpred = cormat,
                technical = techlist, smethod = "eigende")

# initialize
alpha <- seq(0, 1, length = 2)
gamma <- c(0, 1)
cost <- c(0.1, 5)
rda.alpha <- seq(0.1, 0.9, length = 2)
delta <- c(0.1, 2)
method <- c("PLR", "SVM", "RDA")
family <- "multinomial"
parameters <- list(alpha = alpha, gamma = gamma, cost = cost, 
                   rda.alpha = rda.alpha, delta = delta)
model <- "parafac2"
nfolds <- 3
nstart <- 3

# constrain first mode weights to be orthogonal, fourth mode to be nonnegative
const <- c("orthog", "uncons", "uncons", "nonneg")

# fit Parafac2 model and use fourth mode weights to tune classification
# methods, to predict class labels, and to return classification 
# performance measures pooled across multiple train-test splits
output <- cpfa(x = data$X, y = data$y, model = model, nfac = 3, 
               nrep = 2, ratio = 0.8, nfolds = nfolds, method = method, 
               family = family, parameters = parameters, 
               type.out = "descriptives", seeds = NULL, plot.out = TRUE, 
               parallel = FALSE, const = const, nstart = nstart, ctol = 1e-2)

# plot heatmap of component weights for optimal model
plotcpfa(output, nstart = nstart, ctol = 1e-3)
}
}