covar.plot: covar.plot

View source: R/covar.plot.R

covar.plotR 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

See Also

MCMCglmm.subsets covar.utilities

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 Nov. 16, 2024, 1:49 a.m.