biplot_3d: 3D biplot

In Andros-Spica/biplot2d3d: Create and Customize Ordination Plots (Biplots) in 2D and 3D

Description

Generates a 3D biplot using a rgl device, representing the default points/scores and loadings of an ordination object, such as a PCA produced by princomp).

Usage

biplot_3d(ordination_object, ordination_method = "PCA",
  biplot_type = "default", rows_over_columns = 0.5, groups = NULL,
  vips = NULL, detach_arrows = TRUE, show_group_legend = FALSE,
  show_vip_legend = FALSE, show_arrows = TRUE, show_fitAnalysis = TRUE,
  show_axes = c("X", "Y", "Z"), show_planes = NULL, show_bbox = FALSE,
  invert_coordinates = c(FALSE, FALSE, FALSE), aspect = c(1, 1, 1),
  symmetric_axes = FALSE, adapt_axes_origin = TRUE,
  axes_colors = "darkgrey", axes_head_size = 3, axes_titles = "",
  axes_titles_cex = 2, axes_titles_font = 2, axes_titles_adj = list(x =
  c(-0.1, 0), y = c(0.5, -0.5), z = c(1.1, 0)), axes_titles_alpha = 1,
  planes_colors = c("lightgrey", "lightgrey", "lightgrey"),
  planes_textures = NULL, planes_alpha = 0.5, planes_lit = TRUE,
  planes_shininess = 50, bbox_color = c("#333377", "black"),
  bbox_alpha = 0.5, bbox_shininess = 5, bbox_xat = NULL,
  bbox_xlab = NULL, bbox_xunit = 0, bbox_xlen = 3, bbox_yat = NULL,
  bbox_ylab = NULL, bbox_yunit = 0, bbox_ylen = 3, bbox_zat = NULL,
  bbox_zlab = NULL, bbox_zunit = 0, bbox_zlen = 3, bbox_marklen = 15,
  bbox_marklen_rel = TRUE, bbox_expand = 1, bbox_draw_front = FALSE,
  title = "", title_color = "black", title_line = -2, title_size = 3,
  title_font = 20, title_adj = 0.5, subtitle = NULL,
  subtitle_color = "black", subtitle_position = c(0.03, 0.005),
  subtitle_cex = 2, subtitle_font = 2, subtitle_adj = 0,
  point_type = "point", point_label = NULL, point_size = 5,
  point_alpha = 1, point_label_cex = 0.8, point_label_font = 3,
  point_label_adj = c(0.5, 0.5), point_label_alpha = 1,
  group_color = NULL, group_representation = NULL,
  ellipsoid_type = "wire and shade", ellipsoid_level = 0.95,
  ellipsoid_singleton_color = NULL, ellipsoid_singleton_radius = 0.1,
  ellipsoid_wire_alpha = 0.2, ellipsoid_wire_lit = FALSE,
  ellipsoid_shade_alpha = 0.1, ellipsoid_shade_lit = FALSE,
  ellipsoid_label_cex = 1, ellipsoid_label_font = 2,
  ellipsoid_label_adj = c(-0.25, 0.5), ellipsoid_label_alpha = 1,
  star_centroid_radius = 0.005, star_centroid_alpha = 0.5,
  star_link_width = 1, star_link_alpha = 1, star_label_cex = 1,
  star_label_font = 2, star_label_adj = c(-0.25, 0.5),
  star_label_alpha = 1, group_legend_title = "Groups",
  group_legend_title_pos = c(0.5, 0.85), group_legend_title_cex = 2,
  group_legend_title_font = 3, group_legend_title_adj = 0.5,
  group_legend_box_color = "white", group_legend_key_pch = 15,
  group_legend_key_lwd = 1, group_legend_key_margin = 0.15,
  group_legend_key_cex = 3, group_legend_text_margin = 0.25,
  group_legend_text_color = "black", group_legend_text_cex = 1.5,
  group_legend_text_font = 1, group_legend_text_adj = 0, vip_pch = c("/",
  "\\", "o", "_", "|", "O"), vip_cex = c(2, 2, 2, 2, 2, 2),
  vip_colors = "black", vip_font = 3, vip_adj = c(0.5, 0.5),
  vip_alpha = 0.8, vip_legend_title = "Outliers",
  vip_legend_title_pos = c(0.5, 0.85), vip_legend_title_cex = 2,
  vip_legend_title_font = 3, vip_legend_title_adj = 0.5,
  vip_legend_box_color = "white", vip_legend_key_margin = 0.15,
  vip_legend_key_cexFactor = 0.8, vip_legend_text_margin = 0.25,
  vip_legend_text_cex = 1, vip_legend_text_font = 1,
  vip_legend_text_adj = 0, arrow_color = "darkorange", arrow_min_dist = 0,
  arrow_center_pos = c(1, 0, 1), arrow_head_shape_theta = pi/6,
  arrow_head_shape_n = 3, arrow_head_size = 0.1, arrow_body_length = 0.2,
  arrow_body_width = 1, arrow_label_color = "black",
  arrow_label_cex = 0.8, arrow_label_font = 2, arrow_label_adj = 0.5,
  arrow_label_alpha = 1, fitAnalysis_cex = 3, fitAnalysis_lwd = 3,
  fitAnalysis_screePlot_color = "white",
  fitAnalysis_stress_p_color = "darkgrey",
  fitAnalysis_stress_l_color = "black", test_text = NULL,
  test_spacing_paragraph = 0.8, test_spacing_line = 0.8, test_cex = 1,
  test_font = 1, test_adj = 0.5, group_legend_fig = c(0.73, 0.99, 0.6,
  0.9), vip_legend_fig = c(0.03, 0.25, 0.1, 0.3), fitAnalysis_fig = c(0.02,
  0.35, 0.08, 0.3), test_fig = c(0, 0.3, 0.8, 0.99), new_device = FALSE,
  bg_color = "white", view_theta = 15, view_phi = 20, view_fov = 60,
  view_zoom = 0.8, width = 800, height = 600, family = "sans")

Arguments

ordination_object	A R object containing a direct and named reference to default ordination outputs (i.e. ordination_object$scores or ordination_object$points, ordination_object$loadings and ordination_object$sdev) available for at least 3 dimensions. Alternatively, a data frame or matrix with three columns is accepted, provided that ordination_method = NULL), which will create a three-dimensional scatter plot.
ordination_method	Character, the ordination method that was used to generate the ordination object: "PCA" for Principal Components Analysis (default), "PCoA" for Principal Coordinates Analysis, "NMDS" for Non-metric Multidimensional Scaling, and "LDA" for Linear Discriminant Analysis.
biplot_type	Character, indicating the type of biplot scalling of data: "default" and "pc.biplot", corresponding to the transformations performed in biplot.princomp with pc.biplot = FALSE ("default") and pc.biplot = TRUE ("pc.biplot"). If NULL, no processing is performed, assuming that data within ordination_object was previously prepared.
rows_over_columns	Numeric, the value defining the degree in which distances between observations have priority over distances between variables (0 = variable-focused, 1 = observation-focused). It corresponds to the argument scale in biplot.princomp. It will be ignored if biplot_type = NULL.
groups	A factor variable containing the group assignation of each point.
vips	A list of logical (Boolean) vectors identifying the "Very Important Points" under different methods or criteria.
detach_arrows	Logical, wheter to display covariance arrows a independent miniature plot, overlapping the main plot and placed according to arrow_fig.
show_group_legend	Logical, whether to display a legend for groups?
show_vip_legend	Logical, whether to display a legend for vip criteria?
show_arrows	Logical, whether to show variable covariance arrows.
show_fitAnalysis	Logical, whether to display the fit analysis plot corresponding to the ordination method given (Scree plot or Shepard plot).
show_axes, show_planes	Character, vectors indicating which axes and planes to draw (See rgl_format).
show_bbox	Logical, wheter to display a bounding box (See rgl_format).
invert_coordinates	Logical, vector of length three expressing which dimensions, if any, must be inverted before plotting (e.g. for aesthetical reasons).
aspect, symmetric_axes, adapt_axes_origin, axes_colors, axes_head_size, axes_titles, axes_titles_cex, axes_titles_font, axes_titles_adj, axes_titles_alpha	The arguments passed to rgl_format to configure the space and create axes.
planes_colors, planes_textures, planes_alpha, planes_lit, planes_shininess	The arguments passed to rgl_format to create dimensional planes.
bbox_color, bbox_alpha, bbox_shininess, bbox_xat, bbox_xlab, bbox_xunit, bbox_xlen, bbox_yat, bbox_ylab, bbox_yunit, bbox_ylen, bbox_zat, bbox_zlab, bbox_zunit, bbox_zlen, bbox_marklen, bbox_marklen_rel, bbox_expand, bbox_draw_front	The arguments passed to rgl_format to create a bounding box.
title	Character, title to be placed in the fixed 2D canvas ('main' in title).
title_line, title_color, title_size, title_font, title_adj	the line, color, size, font, and justification of the title (line, col.main, cex.main, font.main, and adj in title, par).
subtitle	Character, subtitle to be placed in the fixed 2D canvas ('main' in text).
subtitle_color, subtitle_cex, subtitle_font, subtitle_adj	the color, size, font, and justification of the subtitle ('col', 'cex', font and adj in text, par).
subtitle_position	Numeric verctor of length two indicating the position of the subtitle in the fixed 2D canvas ('main' in text).
point_type	Character, accepting three values: "point", the default points3d; "label", displaying the content of point_label; and "point and label", placing both points and labels.
point_label	Character, vector labelling every observation. It's length must be equal to the number of rows in the points/scores of the ordination object. (nrow(ordination_object$points) == length(point_label)).
point_size	The size or scale given to size in points3d
point_alpha	The alpha of points given to alpha in points3d
point_label_cex, point_label_font, point_label_adj, point_label_alpha	The text parameters and the alpha of the arrows' labels. (text3d, rgl.material).
group_color	A vector containing the color or colors to be used in each group (applied to points, labels, stars and ellipsoids).
group_representation	Character, indicating which group representation to draw: "stars", "ellipsoids", or "stars and ellipsoids". Neither stars or ellipsoids are drawn, if NULL is given instead.
ellipsoid_type, ellipsoid_level, ellipsoid_singleton_color, ellipsoid_singleton_radius, ellipsoid_wire_alpha, ellipsoid_wire_lit, ellipsoid_shade_alpha, ellipsoid_shade_lit, ellipsoid_label_cex, ellipsoid_label_font, ellipsoid_label_adj, ellipsoid_label_alpha	When ellipsoids are drawn, parameters given to ellipsoids_3d.
star_centroid_radius, star_centroid_alpha, star_link_width, star_link_alpha, star_label_cex, star_label_font, star_label_adj, star_label_alpha	When stars are drawn, parameters given to stars_3d.
group_legend_title	Character, the title of the groups legend. If equal NULL or "", no title is displayed.
group_legend_title_pos	A numeric vector of length two, the xy position of the title within the groups legend box.
group_legend_title_cex, group_legend_title_font, group_legend_title_adj	The text parameters to be applied in the groups legend title (par).
group_legend_box_color	The background color of the groups legend box.
group_legend_key_pch, group_legend_key_lwd, group_legend_key_cex	The type, line width and sizing factor of the keys in the groups legend.
group_legend_key_margin	The x position of the keys within the groups legend box. Values from 0 to 1.
group_legend_text_margin	The x position of the text entries in the groups legend. Values from 0 to 1.
group_legend_text_color	The color or colors of the text entries in the groups legend.
group_legend_text_cex, group_legend_text_font, group_legend_text_adj	The text parameters of the text entries in the groups legend.
vip_pch	A character vector containing the characters used for the vips markings under each criterion.
vip_cex, vip_colors, vip_font, vip_adj, vip_alpha	The graphical parameters of the vips markings.
vip_legend_title	Character, the title of the vips legend.
vip_legend_title_pos	A numeric vector of length two, the xy position of the title within the vips legend box.
vip_legend_title_cex, vip_legend_title_font, vip_legend_title_adj	The text parameters to be applied in the vips legend title (par).
vip_legend_box_color	The background color of the vips legend box.
vip_legend_key_margin	The x position of the keys within the vips legend box. Values from 0 to 1.
vip_legend_key_cexFactor	The sizing factor of the keys in the vips legend respect to the vips marking in the plot.
vip_legend_text_margin	The x position of the text entries in the vips legend box. Values from 0 to 1.
vip_legend_text_cex, vip_legend_text_font, vip_legend_text_adj	The text parameters of the text entries in the vips legend.
arrow_color	The color or colors to be used in covariance arrows (pass to radial_arrows_3d).
arrow_min_dist	The minimum distance of a variable arrow from the origin of arrows, in order for it to be displayed (range [0 = all arrows are displayed, 1 = no arrows are displayed]).
arrow_center_pos	A numeric vector of length three, containing the position of the origin of covariance arrows, expressed in relation to the 3D space represented (e.g. c(.5, .5, .5) will place the arrows in the center).
arrow_head_shape_theta, arrow_head_shape_n, arrow_head_size, arrow_body_width, arrow_body_length, arrow_label_color, arrow_label_cex, arrow_label_font, arrow_label_adj, arrow_label_alpha	When the covariance arrows are displayed, parameters given to radial_arrows_3d.
fitAnalysis_cex, fitAnalysis_lwd, fitAnalysis_screePlot_color, fitAnalysis_stress_p_color, fitAnalysis_stress_l_color	The graphical parameters of the plot for fit analysis of the ordination method (par, stressplot of the vegan package).
test_text	A list of character vectors or expressions with the lines of text presenting the results of statistical tests. A example structure would be: list(c("first line", "second line"), "second paragraph"), bquote("third paragraph" ~ alpha == 2).
test_spacing_paragraph, test_spacing_line	Numeric, relative spacing between paragraphs (list elements) and lines (character elements within a list element, if more than one).
test_cex, test_font, test_adj	The parameters of the text with the test results (par).
group_legend_fig, vip_legend_fig, fitAnalysis_fig, test_fig	The fig parameter (par) to place in the display region of the graphics device, respectively, the group and vip legends, the fit analysis plot, and the tests results.
new_device, bg_color, view_theta, view_phi, view_fov, view_zoom, width, height	The arguments passed to rgl_init.
family	The font family used in every text in the plot, (par).

Details

This function allows customising virtually every graphical parameter in a 3D biplot, including several extra elements that may be useful for multivariate explorations. It is focused mainly on improving basic visualization aspects of ordination methods through 'classical' biplots. There are several packages that address the creation of other variations of biplot: BiplotGUI, GGEBiplotGUI, multibiplotGUI, biplotbootGUI, NominalLogisticBiplot, OrdinalLogisticBiplot, ade4, vegan, MultBiplotR. When biplot_type = "default", the biplot processing is done as in biplot.princomp, which follows the definition of Gabriel (1971). As in this method, when biplot_type = "pc.biplot", this function creates biplots according with Gabriel and Odoroff (1990). Since there are several types of biplot transformations, it is possible to use 'scores' and 'loadings' that were already transformed, passing biplot_type = NULL. Groups can be represented as stars (stars_3d), ellipsoids (ellipsoids_3d), and/or colors, which can be tracked by a fully-customisable legend (group_legend arguments). Individual observations deemed exceptional (vip = Very Important Points) can be marked with custom characters. Whenever there are more than one type of marking (e.g. different methods/criteria of outlier detection), different characters can be presented in a legend (vip legend). When desired, it is possible to display a Scree plot representing the eigenvalues (Principal Components Analysis, Principal Coordinates Analysis) or a Shepard or stress plot (Nonmetric Multidimensional Scaling, metaMDS in the vegan package) by enabling show_fit_analysis. It is also possible to display statistical test results (enabling show.tests and introducing lines of text in tests.text). Every 2D element (legend boxes, title and subtitle, fit analysis plot and tests) are placed in a fixed 2D canvas (i.e. viewport) using bgplot3d.

References

Gabriel, K. R. (1971). The biplot graphical display of matrices with applications to principal component analysis. Biometrika, 58, 453-467.

Examples

## Not run: 

# Use iris data
data("iris")

# get an ordination object
# ("PCA" is the default input of this function)
pca <- princomp(iris[, 1:4])

# Default plot using Species as the groups
biplot_3d(pca, groups = iris$Species)

# ---------------------------------------------------------
# Plot groups as ellipsoids, make group label invisible and
# add a groups legend with no title.
# Customize the covariance arrows default setting.
biplot_3d(pca,
          groups = iris$Species,
          group_representation = "ellipsoids",
          ellipsoid_label_alpha = 0,
          show_group_legend = TRUE,
          group_legend_title = "",
          arrow_center_pos = c(.5, 0, .5),
          arrow_body_length = 1,
          arrow_body_width = 2,
          view_theta = 0,
          view_zoom = 0.9)

# ---------------------------------------------------------
# Plot observations using their names and groups as
# stars but adding a legend instead of labels.
# Modify the aspect to normalize the variability
# of axes and do not show them. Zoom out a little.
biplot_3d(pca, groups = iris$Species,
          point_type = "label", point_label = row.names(iris),
          star_label_alpha = 0,
          show_group_legend = TRUE, group_legend_title = "",
          arrow_center_pos = c(.5, 0, .5),
          arrow_body_length = 2, arrow_body_width = 2,
          show_axes = FALSE, view_zoom = 1)

# ---------------------------------------------------------
# Get arbitrary Very Important Points
irisVIP <- list(setosa = (1:nrow(iris) == 16 |
                          1:nrow(iris) == 42),
                versicolor=(1:nrow(iris) == 61),
                virginica=(1:nrow(iris) == 107 |
                           1:nrow(iris) == 118 |
                           1:nrow(iris) == 132))

# Plot observations using their names and group by
# Species using only color. Mark the VIP and add the
# respective legend with custom characters.
# Rotate the theta view angle to fit the arrows
# in the default setting.
biplot_3d(pca,
          groups = iris$Species,
          point_type = "label",
          point_label = row.names(iris),
          group_representation = NULL,
          show_group_legend = TRUE,
          group_legend_title = "",
          vips = irisVIP,
          vip_pch = c("X", "O", "+"),
          vip_cex = c(2, 2, 3),
          show_axes = FALSE, view_theta = 340)

# ---------------------------------------------------------
# Test the setosa separation
irisDist <- dist(iris[, 1:4])

setosaSeparation <- iris$Species == "setosa"

## multivariate test for the setosa separation
require(vegan)
irisTests <- NULL
irisTests$permanova <- adonis(irisDist ~ setosaSeparation)
irisTests$permdisp2 <- permutest(betadisper(irisDist,
                                            setosaSeparation),
                                 pairwise = TRUE)

# The following function prepares a list of character vectors
# containing test results
getTestText <- function(tests){
  permanova_F <- as.character(round(tests$permanova$aov.tab$F.Model[1], 3))
  permanova_pvalue <- as.character(round(tests$permanova$aov.tab$"Pr(>F)"[1], 3))
  permanova_rSquared <- as.character(round(tests$permanova$aov.tab$R2[1], 3))
  permdisp2_F <- as.character(round(tests$permdisp2$tab$F[1], 3))
  permdisp2_pvalue <- as.character(round(tests$permdisp2$tab$"Pr(>F)"[1], 3))
  text <- list(c(paste("PERMANOVA:\n   F = ", permanova_F,
                       " (p = ", permanova_pvalue, ")\n",
                       sep = ""),
                 c(expression(paste("   ", R^2, " =",
                 sep = "")),
                   paste("          ", permanova_rSquared,
                   sep = ""))),
               paste("PERMDISP2:\n   F = ", permdisp2_F,
                     " (p = ", permdisp2_pvalue,")",
                     sep = ""))
  return(text)
}

# Plot observations using points and
# groups as stars with no labels.
# Place tests results in the bottom left corner
# and give a custom title.
biplot_3d(pca,
          groups = iris$Species,
          point_type = "point",
          star_label_alpha = 0,
          show_group_legend = TRUE,
          group_legend_title = "",
          test_text = getTestText(irisTests),
          test_cex = 1.5,
          test_fig = c(0.01, 0.5, 0.7, 1),
          show_axes = FALSE,
          view_theta = 340,
          title = "testing setosa separation")


## End(Not run)

Andros-Spica/biplot2d3d documentation built on June 10, 2020, 1:38 p.m.