plot.funspace {funspace}

Functional space plotting

Description

Takes a funspace object produced by funspace() or funspaceGAM() and plots the trait probability distribution (TPD) or the map of the response variable (depending of which kind of funspace object is provided) in a functional space.

Usage

## S3 method for class 'funspace'
plot(
  x = NULL,
  type = "global",
  which.group = NULL,
  quant.plot = FALSE,
  quant = NULL,
  quant.lty = 1,
  quant.col = "grey30",
  quant.lwd = 1,
  quant.labels = TRUE,
  colors = NULL,
  ncolors = 100,
  pnt = FALSE,
  pnt.pch = 19,
  pnt.cex = 0.5,
  pnt.col = "grey80",
  arrows = FALSE,
  arrows.length = 1,
  arrows.head = 0.08,
  arrows.col = "black",
  arrows.label.col = "black",
  arrows.label.pos = 1.1,
  arrows.label.cex = 1,
  axis.title = TRUE,
  axis.title.x = NULL,
  axis.title.y = NULL,
  axis.title.cex = 1,
  axis.title.line = 2,
  axis.cex = 1,
  globalContour = TRUE,
  globalContour.quant = NULL,
  globalContour.lwd = 3,
  globalContour.lty = 1,
  globalContour.col = "grey50",
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

x

A funspace object produced by funspace() or funspaceGAM().

type

character indicating whether the plots should represent the global distribution of observations (type = "global"), or be separated by the groups (type = "groups") provided when the funspace object was created. Defaults to "global". In the case of funspace objects based on a TPD function created with the TPD package, only groups are plotted (there is no "global" distribution).

which.group

when plotting groups, either a character or a number indicating the name (character) or position (number) of a single group to be plotted individually.

quant.plot

Logical, Default is TRUE. Should contour lines representing quantiles (specified in quant) be plotted?

quant

A vector specifying the quantiles to be plotted (in case quant.plot is set to TRUE. In case a TPD function is plotted, the quantiles represent the quantiles of the trait probability density function (lower quantiles indicate areas with higher probability density). In case a GAM object is plotted, the quantiles of the fitted response variable are plotted. In case a TPD function is plotted, default quantiles are 0.99 (or the selected threshold if it is lower), 0.5 and 0.25. In the GAM alternative, default quantiles are 0.99, 0.5 and 0.25.

quant.lty

type of line to be used to represent quantiles. See lty argument in graphics::par().

quant.col

Color to be used in the quantile lines. Defaults to "grey30".

quant.lwd

Line width to be used in the quantile lines. Defaults to 1.

quant.labels

Logical, Default is TRUE. Should labels be added to quantile lines?

colors

A vector defining the colors of plotted quantiles in the TPD case. Only two colors need to be specified. The first color is automatically assigned to the highest quantile in quantiles (e.g. 0.99), the second color is assigned to the lowest quantile. These colors are then used to automatically generate a gradient from the greatest to the lowest quantile. Any color is admitted. Default is NULL, in which case c("yellow", "red") is used in case a trait probability density function is plotted and to viridis::viridis(5) in the GAM case.

ncolors

number of colors to include in the color gradients set by colors. Defaults to 100.

pnt

Logical, defaults to FALSE. Should data points be added to the functional space?

pnt.pch

Numerical. Graphical parameter to select the type of point to be drawn. Default is set to 19. See pch argument in graphics::par()..

pnt.cex

Numerical. Graphical parameter to set the size of the points. Default is 0.5. See cex argument in graphics::par().

pnt.col

Graphical parameter to set the points color. Default is "grey80".

arrows

Logical, defaults to FALSE. In case the functional space is based on a PCA, should the loadings of the original traits be represented by arrows in the functional space?

arrows.length

Numerical. Graphical parameter to set the length of the arrow (see arrows). Lower values lead to shorter arrows, which can help to make arrows fit within the represented functional space. Defaults to 1.

arrows.head

Numerical. Graphical parameter to set the length of the arrow head (see arrows). Defaults to 0.08.

arrows.col

Graphical parameter to set the arrows color (see arrows). Default is "black".

arrows.label.col

Graphical parameter to set the color of the arrows labels color. Default is "black".

arrows.label.pos

Numerical. Graphical parameter to set the position of the arrow labels with respect to the arrow heads. Default is 1.1, which draws arrow labels slightly beyond the arrow heads. A value of 1 means drawing labels on top of arrow heads.

arrows.label.cex

Numerical. Graphical parameter to set the size of arrow labels. Defaults to 1.

axis.title

Logical. Default is TRUE. Should axes titles be plotted?

axis.title.x

Character. The title to be plotted in the x axis if axis.title is set to TRUE. If not specified, a default axis title is plotted.

axis.title.y

Character. The title to be plotted in the y axis if axis.title is set to TRUE. If not specified, a default axis title is plotted.

axis.title.cex

Numerical. Graphical parameter to set the size of the axes titles. Default is 1.

axis.title.line

Numerical. Graphical parameter to set the on which margin line to plot axes titles. Default is 2.

axis.cex

Numerical. Graphical parameter to set the size of the axes annotation. Default is 1.

globalContour

Logical, Default is TRUE. Should a contour line representing the global distribution be plotted when type is set to "groups". Adding a global contour lines provides a common reference for all groups and makes comparisons easier.

globalContour.quant

A vector specifying the quantiles to be plotted (in case globalContour is set to TRUE. Defaults to the threshold selected when the provided funspace object was originally created.

globalContour.lwd

Line width to be used in the global contour lines. Defaults to 3.

globalContour.lty

type of line to be used to represent the global contour lines. See lty argument in graphics::par(). Defaults to 1 (a continuous line).

globalContour.col

Graphical parameter to set the color of the global contour lines. Default is "grey50".

xlim

the x limits (x1, x2) of the plot.

ylim

the y limits (y1, y2) of the plot.

...

Other arguments

Details

Produces default plots. If the input object was generated with funspace(), the plot shows a bivariate functional trait space displaying trait probability densities (for single or multiple groups). If the input object was generated with funspaceGAM, the plot shows a heatmap depicting how a target variable is distributed within the functional trait space (for single or multiple groups).

Value

No return value. This function is called for its side effect: generating plots.

Examples

x <- princomp(GSPFF)
funtest <- funspace(x = x, PCs = c(1, 2), threshold = 0.95)
plot(funtest, type = "global", quant.plot = TRUE, quant.lwd = 2, pnt = TRUE, pnt.cex = 0.1,
   pnt.col = rgb(0.1, 0.8, 0.2, alpha = 0.2), arrows = TRUE, arrows.length = 0.7)