Create an interactive 3-D BGA plotly visualization

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 = TRUE,
  ...
)

Arguments

bgaInfo	object of class `"bga"` as 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	the 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	named color vector, 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, where `"centroids"` draws a vector from the origin to each group centroid; and `"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.
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	parameters 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	parameters 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	parameters 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	vector of character or factor values. The names are expected to contain values in `rownames(bgaInfo$ord$ord$tab)`, which are also the colnames of the data matrix used in `made4::bga()`. 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.
verbose	logical indicating whether to print verbose output.
...	additional parameters are ignored
elipseType	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.

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.

Create an interactive 3-D BGA plotly visualization

Arguments

Value

Details

See also