R/fviz_cos2.R

In factoextra: Extract and Visualize the Results of Multivariate Data Analyses

#' @include facto_summarize.R
NULL
#' Visualize the quality of representation of rows/columns
#' 
#' @description This function can be used to visualize the quality of
#' representation (cos2) of rows/columns from the results of Principal Component
#' Analysis (PCA), Correspondence Analysis (CA), Multiple Correspondence
#' Analysis (MCA), Factor Analysis of Mixed Data (FAMD), Multiple Factor
#' Analysis (MFA) and Hierarchical Multiple Factor Analysis (HMFA) functions.
#'
#' Read more: \href{https://www.datanovia.com/learn/machine-learning/dimension-reduction/principal-component-analysis}{Principal Component Analysis (PCA) in R: Compute, Visualize & Interpret}.
#'
#' @param X an object of class PCA, CA, MCA, FAMD, MFA and HMFA [FactoMineR];
#'   prcomp and princomp [stats]; dudi, pca, coa and acm [ade4]; ca [ca
#'   package].
#' @param choice allowed values are "row" and "col" for CA;  "var" and "ind" for
#'   PCA or MCA; "var", "ind", "quanti.var", "quali.var" and "group" for FAMD, MFA and HMFA.
#' @param axes a numeric vector specifying the dimension(s) of interest.
#' @param fill a fill color for the bar plot.
#' @param color an outline color for the bar plot.
#' @param sort.val a string specifying whether the value should be sorted. 
#'   Allowed values are "none" (no sorting), "asc" (for ascending) or "desc"
#'   (for descending).
#' @param top a numeric value specifying the number of top elements to be shown.
#' @param xtickslab.rt rotation angle for x axis tick labels. Default is 45 degrees.
#' @param display how to display the values. \code{"bar"} (default) draws the
#'   usual barplot of the cos2/contribution summed over \code{axes}.
#'   \code{"heatmap"} draws a grid with one tile per element and dimension,
#'   filled by the per-dimension cos2/contribution and labelled with its value,
#'   so several dimensions can be read at once. With \code{"heatmap"}, elements
#'   are ordered by their (unweighted) total over the requested \code{axes} and
#'   \code{top} keeps the leading ones; the bar-specific \code{sort.val} and
#'   \code{color} arguments are ignored, and \code{fill} sets the high end of the
#'   white-to-colour gradient.
#' @inheritParams ggpubr::ggpar
#'   
#' @return a ggplot
#' @author Alboukadel Kassambara \email{alboukadel.kassambara@@gmail.com}
#' @references \url{https://www.datanovia.com/learn/}
#' @seealso \code{\link{fviz_contrib}}, \code{\link{get_pca}}.
#'   Online tutorial: \href{https://www.datanovia.com/learn/machine-learning/dimension-reduction/principal-component-analysis}{Principal Component Analysis (PCA) in R: Compute, Visualize & Interpret}.
#' @examples
#' \donttest{
#' # Principal component analysis
#' # ++++++++++++++++++++++++++
#' data(decathlon2)
#' decathlon2.active <- decathlon2[1:23, 1:10]
#' res.pca <- prcomp(decathlon2.active,  scale = TRUE)
#' 
#' # variable cos2 on axis 1
#' fviz_cos2(res.pca, choice="var", axes = 1, top = 10 )
#' 
#' # Change color
#' fviz_cos2(res.pca, choice="var", axes = 1,
#'          fill = "lightgray", color = "black") 
#'          
#' # Variable cos2 on axes 1 + 2
#' fviz_cos2(res.pca, choice="var", axes = 1:2)
#'
#' # Heat-grid of cos2 across several dimensions
#' fviz_cos2(res.pca, choice = "var", axes = 1:4, display = "heatmap")
#'
#' # cos2 of individuals on axis 1
#' fviz_cos2(res.pca, choice="ind", axes = 1)
#' 
#' \dontrun{
#' # Correspondence Analysis
#' # ++++++++++++++++++++++++++
#' library("FactoMineR")
#' data("housetasks")
#' res.ca <- CA(housetasks, graph = FALSE)
#' 
#' # Visualize row cos2 on axes 1
#' fviz_cos2(res.ca, choice ="row", axes = 1)
#' # Visualize column cos2 on axes 1
#' fviz_cos2(res.ca, choice ="col", axes = 1)
#' 
#' # Multiple Correspondence Analysis
#' # +++++++++++++++++++++++++++++++++
#' library(FactoMineR)
#' data(poison)
#' res.mca <- MCA(poison, quanti.sup = 1:2, 
#'               quali.sup = 3:4, graph=FALSE)
#'               
#' # Visualize individual cos2 on axes 1
#' fviz_cos2(res.mca, choice ="ind", axes = 1, top = 20)
#' # Visualize variable category cos2 on axes 1
#' fviz_cos2(res.mca, choice ="var", axes = 1)
#' 
#' # Multiple Factor Analysis
#' # ++++++++++++++++++++++++
#' library(FactoMineR)
#' data(poison)
#' res.mfa <- MFA(poison, group=c(2,2,5,6), type=c("s","n","n","n"),
#'                name.group=c("desc","desc2","symptom","eat"),
#'                num.group.sup=1:2, graph=FALSE)
#' # Visualize individual cos2 on axes 1
#' # Select the top 20
#' fviz_cos2(res.mfa, choice ="ind", axes = 1, top = 20)
#' # Visualize categorical variable category cos2 on axes 1
#' fviz_cos2(res.mfa, choice ="quali.var", axes = 1)
#' }
#'                
#'  }
#' @export
fviz_cos2 <- function(X, choice = c("row", "col", "var", "ind", "quanti.var", "quali.var", "group"), axes=1,
                   fill="steelblue", color = "steelblue",
                   sort.val = c("desc", "asc", "none"), top = Inf,
                   xtickslab.rt = 45, ggtheme = theme_minimal(),
                   display = c("bar", "heatmap"), ...)
{
   sort.val <- match.arg(sort.val)
   display <- match.arg(display)
   title <- .build_title(choice[1], "Cos2", axes)

   # display = "heatmap": one tile per (element, dimension), instead of a bar
   # of the cos2 summed over the axes. Barplot path below is unchanged.
   if(display == "heatmap")
     return(.fviz_result_heatmap(X, choice = choice[1], result = "cos2",
                                 axes = axes, top = top, fill = fill,
                                 ggtheme = ggtheme,
                                 title = sub(" to Dim-.*$", " per dimension", title),
                                 legend.title = "cos2"))

   dd <- facto_summarize(X, element = choice, result = "cos2", axes = axes)
   cos2 <- dd$cos2
   
   names(cos2) <-rownames(dd)
   
   df <- data.frame(name = factor(names(cos2), levels = names(cos2)), cos2 = cos2)
   
   p <- ggpubr::ggbarplot(df, x = "name", y = "cos2", fill = fill, color = color,
                          sort.val = sort.val, top = top,
                          main = title, xlab = FALSE, ylab ="Cos2 - Quality of representation",
                          xtickslab.rt = xtickslab.rt, ggtheme = ggtheme, ...
   )
  p 
}