Create an interactive 3-D BGA plotly visualization

Usage

bgaPlotly3d(
  bgaInfo,
  axes = c(1, 2, 3),
  superGroups = NULL,
  superGroupAlpha = 0.3,
  superGroupLwd = 25,
  arrowSmoothFactor = 8,
  colorSub = NULL,
  drawVectors = c("none", "centroids", "genes"),
  highlightGenes = NULL,
  drawSampleLabels = TRUE,
  ellipseType = c("ellipsoid", "alphahull", "none"),
  ellipseOpacity = 0.2,
  useScaledCoords = FALSE,
  geneColor = "#555555",
  geneScaleFactor = 1,
  geneLwd = 2,
  geneAlpha = 0.7,
  geneLabels = NULL,
  maxGenes = 50,
  centroidLwd = 15,
  centroidAlpha = 0.3,
  textposition_centroid = "top center",
  textposition_sample = "middle right",
  sceneX = -1.25,
  sceneY = 1.25,
  sceneZ = 1.25,
  main = "",
  plot_bgcolor = "#eeeeee",
  paper_bgcolor = "#dddddd",
  sampleGroups = NULL,
  debug = FALSE,
  verbose = FALSE,
  ...
)

Arguments

bgaInfo

object of class c("coa", "bga") created by made4::bga().

axes

integer vector length 3 indicating the BGA axes to use for the 3-D visualization. It is sometimes helpful to use axes=c(2,3,4) especially when the first component suggests a large experimental batch effect, for example when combining data from multiple GEO studies, often the first BGA component is indicative of the different experimental platforms.

superGroups

character or factor vector with length length(bgaInfo$fac), in the same order. A super group consists of multiple sample groups, as defined by values in bgaInfo$fac.

superGroupAlpha

numeric value between 0 and 1 indicating the alpha transparency to use for the vector that connects groups within each super group.

superGroupLwd

numeric line width when connecting sample group centroids by superGroups.

arrowSmoothFactor

numeric value typically ranging from 1 to 5, affecting the amount of curve smoothing when generating a 3-D spline curve to connect more than two super groups. When there are only two group members in one super group, the two groups will always use a straight line. For three or more groups, a 3-D spline is used, in order to help visualize trends by means of a curve.

colorSub

character vector of R colors, whose names contain values in bgaInfo$fac. These colors are used for the samples, sample centroids, and are shaded via a gradient when connecting multiple centroids using superGroups.

drawVectors

character vector of one or more types of vectors:

"centroids" draws a vector from the origin to each group centroid.
"genes" draws a vector from the origin to each gene.

drawSampleLabels

logical indicating whether to label each individual sample point, as opposed to labeling only the sample group centroid.

ellipseType

character value indicating how to draw sample centroid ellipses, where "none" draws no ellipse; "alphahull" draws a wireframe; and "ellipsoid" draws a partially transparent shell. Note that plotly does not handle transparency well in 3-D space, sometimes fully obscuring background components.

ellipseOpacity

numeric value between 0 and 1 indicating the transparency of the ellipse, when ellipseType is not "none"; 0 is fully transparent, and 1 is non-transparent.

useScaledCoords

logical indicating whether to use the BGA scaled coordinates, or the raw coordinates. By default the raw coordinates are used in order to preserve the relative contribution of each BGA component to the overall variability (or inertial moment.)

geneColor

character color used when displaying gene points.

geneScaleFactor

numeric value used to expand the position of genes relative to the origin, intended to help visualize the vector position of genes relative to the origin.

geneLwd, geneAlpha

numeric used to customize the line width and alpha transparency of gene points, respectively.

geneLabels

character vector of gene labels to use instead of rownames. The names(geneLabels) are expected to match rownames(bgaInfo$bet$co). This option is intended to allow display of gene symbols, instead of an assay identifier like probe set name.

maxGenes

integer maximum number of genes to display.

centroidLwd, centroidAlpha

numeric used to customize the line width and alpha transparency of vectors drawn to sample centroids, respectively.

textposition_centroid, textposition_sample

character vector containing values used as the plotly argument "textposition" to position text labels for centroids, and samples. Each vector is extended to the number of labels, which allows each label to be individually positioned.

sceneX, sceneY, sceneZ

numeric used to define the camera position in 3-D space as defined by plotly. Frankly, the ability to customize the starting position is fairly confusing, but these values are faithfully passed along to the corresponding plotly call.

main

character string used as a title on the plotly visualization.

sampleGroups

character or factor vector, whose names are expected to contain values in rownames(bgaInfo$ord$ord$tab), which should also be colnames(x) of the input data to made4::bga(x, ...). The values in sampleGroups are used to re-group samples, which effectively calculates new sample group centroids used in this visualization. It is intended to be used when the made4::bga() is used without grouping, for example when each sample replicate is defined as its own group. The end result is that centroids and ellipsoids are calculated for each group during visualization, to help organize the points displayed.

verbose

logical indicating whether to print verbose output.

...

additional parameters are ignored

Value

plotly object sufficient to render an HTML page containing a 3-D BGA plot.

Details

This function takes the output from made4::bga() (class "bga") and creates a 3D plotly visualization which shows the samples, sample centroids, and optionally a subset of genes in the same BGA component space.

For general guidance, when the data contains four or more sample groups, this function can be called to produce a 3-D plot. BGA itself produces n-1 dimensions, therefore when there are fewer than four groups, a 3-D plot cannot be produced.

When analyzing data with fewer than four groups, it is sometimes helpful to cluster samples individually. This approach is roughly equivalent to performing PCA or COA directly, but is sometimes convenient in being consistent with calling made4::bga(), as it also applies the same scaling method used in made4:bga() prior to calling PCA or COA. In that case, the groups can still be displayed by bgaPlotly3d() by defining the sampleGroups argument. The result will display typical PCA or COA coordinates, but visually displays the centroid of each sample group.

This function is especially useful when there are multiple sample groups that belong to a "supergroup" – a higher level of grouping. Consider an experiment with two cell lines treated over multiple time points. The samples would be assigned to a group based upon cell_line and time, then each group would be assigned to a supergroup based upon cell_line. The output plot will display each sample group, group centroid, then connect group centroids in order by the supergroup. The order of groups within each supergroup is determined either by factor levels, or by the order returned by jamba::mixedSort() which performs a proper alphanumeric sort.

Background on `bga` object content

Output from made4::bga() is an object with class containing "bga". It is a list with three elements:

"ord": ordination, the initial clustering results from either "coa" (default) or "pca" clustering across all individual samples. This data is fed into the second phase, group-based clustering.
"bet": the between group analysis result, derived from "ord".
"fac": factor vector of groups across the colnames(x) of input data.

The "bet" contents are described below, assuming the results of made::bga() are stored as bgaInfo:

gene (row) coordinates are stored:
- bgaInfo$bet$co: unscaled coordinates for each component axis
- bgaInfo$bet$c1: scaled coordinates for each component axis
group centroid coordinates are stored:
- bgaInfo$bet$li: unscaled group centroid coordinates
- bgaInfo$bet$ls: scaled group centroid coordinates
sample centroid coordinates are stored:
- bgaInfo$bet$ls: scaled coordinates for each component axis