covar.plot: covar.plot
In TGuillerme/dispRity: Measuring Disparity

covar.plot

R Documentation

covar.plot

Description

Visualising components of a dispRity object with covar.

Usage

covar.plot(
  data,
  n,
  points = TRUE,
  major.axes = FALSE,
  ellipses = FALSE,
  level = 0.95,
  dimensions = c(1, 2),
  centres = colMeans,
  scale,
  transparent.scale,
  add = FALSE,
  apply.to.VCV = FALSE,
  ...
)

Arguments

`data`	an `dispRity` object with a covar component.
`n`	optional, a number of random posteriors to use.
`points`	logical, whether to plot the observed elements (`TRUE`; default) or not (`FALSE`).
`major.axes`	can be either logical for plotting all (or `n`) major.axes (`TRUE`) or none (`FALSE`; default) or a `function` for displaying one summarised major axis. See details.
`ellipses`	can be either logical for plotting all (or `n`) ellipses (`TRUE`) or none (`FALSE`; default) or a `function` for displaying one summarised ellipse. See details.
`level`	the confidence interval level of the major axes and ellipses (default is `0.95`).
`dimensions`	which dimensions (default is `c(1,2)`).
`centres`	optional, a way to determine ellipses or major axes positions. Can be either a `function` (default is `colMeans`), a `vector` or a `list` of coordinates vectors or `"intercept"`. See details.
`scale`	optional, the name of a group from `data` on which to scale the ellipses and major axis to be the same size.
`transparent.scale`	optional, if multiple major axes and/or ellipses are plotted, a scaling factor for the transparency. If left empty, the transparency is set to `1/n` or `0.1` (whichever is higher).
`add`	logical, whether to add the plot to an existing plot (`TRUE`) or not (`FALSE`; default).
`apply.to.VCV`	logical, if `ellipse` and/or `major.axes` is a `function`, whether to apply it on all the estimated ellipses/major axes (`FALSE`; default) or on the variance covariance matrices directly (`TRUE`). In other words, whether to apply the function to the ellipses/major axis or the the VCV first (e.g. the average ellipses or the ellipse of the average VCV).
`...`	any graphical options to be passed to `plot`, `lines` or `points`. See details.

Details

When specifying optional arguments with ... in a graph with multiple elements (e.g. points, lines, etc...) you can specify which specific element to affect using the syntax <element>.<argument>. For example if you want everything in the plot to be in blue at the exception of the points to be red, you can use covar.plot(..., col = "blue", points.col = "red").

The arguments major.axes and ellipses can intake a function for summarising the display of multiple variance covariance matrices (if n is missing or greater than one). This can be any central tendency function such as mean, median or mode.val.

The argument centres allows to determine how to calculate the centre of each ellipses or major axes. The argument can be either:

A function to calculate the centre from a group like the default colMeans function that calculates the centroid coordinates of each group;
A numeric value to be replicated as the coordinates for the centre of each group (e.g. centres = 0 sets all the centres at the coordinates c(0,0,0,...)); or a vector of numeric values to be directly used as the coordinates for each group (e.g. centres = c(1,2,3) sets all the centres at the coordinates c(1,2,3)); or a list of numeric values or numeric vectors to be used as the coordinates for the centres of each group;
"intercept" for using the estimated posterior intercept for each sample.

NOTE that if the input contains more dimensions than the visualised dimensions (by default dimensions = c(1,2)) the ellipses and major axes are projected from an n-dimensional space onto a 2D space which might make them look incorrect. NOTE also that the ellipses and major axes are measured independently, when summarising both parameters (e.g. by using ellipses = mean and major.axes = mean), the displayed summarised major axes is not calculated from the summarised ellipse but from the coordinates of all major axes (and therefore might not match the coordinates of the ellipse).

Author(s)

Thomas Guillerme

Examples

data(charadriiformes)

## Creating a dispRity object from the charadriiformes model
covar <- MCMCglmm.subsets(data       = charadriiformes$data,
                          posteriors = charadriiformes$posteriors,
                          group      = MCMCglmm.levels(
                                         charadriiformes$posteriors)[1:4],
                          rename.groups = c("gulls", "plovers",
                                            "sandpipers", "phylogeny"))

## Default plot
covar.plot(covar)

## Same plot with more options
covar.plot(covar, n = 50, ellipses = mean, major.axes = TRUE, 
           col = c("orange", "blue", "darkgreen", "grey", "grey"),
           legend = TRUE, points = TRUE, points.cex = 0.2,
           main = "Charadriiformes shapespace")

TGuillerme/dispRity documentation built on Dec. 21, 2024, 4:05 a.m.