treats (version 1.0)

plot.treats: Plot treats objects

Description

Plotting treats objects (either a simulated tree and trait(s) or a process for traits objects)

Usage

# S3 method for treats
plot(
  x,
  col,
  ...,
  trait = 1,
  edges = "grey",
  tips.nodes = NULL,
  use.3D = FALSE,
  simulations = 50,
  cent.tend = mean,
  quantiles = c(95, 50),
  legend = FALSE
)

Value

No return value, plot x's content.

Arguments

x

treats data.

col

Optional, a vector of colours that can be named (see details).

...

Any additional options to be passed to plot functions (from graphics or rgl if use.3D = TRUE).

trait

which trait to plot (default is 1; see details).

edges

either a colour name to attribute to the edges or NULL to not display the edges (default is "grey").

tips.nodes

optional, a colour to circle tips and nodes (only used if use.3D = FALSE). By default tips.nodes = NULL.

use.3D

logical, whether to use a 3D plot or not (default is FALSE; see details).

simulations

if the input is a treats traits or bd.params object, how many replicates to run (default is 50).

cent.tend

if the input is a treats traits, which central tendency to plot (default is mean).

quantiles

if the input is a treats traits, which quantiles to plot (default are c(95, 50))).

legend

logical, whether to display the legend in 2D plots (TRUE) or not (FALSE; default)

Author

Thomas Guillerme

Details

The col option can be either:

• a vector of colours to be applied to "treats" "traits" objects (for respectively the median, 50

• a vector of colours to be applied to "treats" objects for the colours of different elements of the plot. This vector cycles through different elements of the the tree depending on the length of the vector: if one colour is given, it is applied to all elements; if two colours are given, the first one is applied to the nodes and the second to the tips; if three colours are given, they are applied to the nodes, fossils and living elements respectively. If more colours are given, they are applied in a gradient way to all elements depending on their age (see the function usage below). Note that you can always name the vector elements for avoiding ambiguities: e.g. col = c("nodes" = "orange", "fossils" = "lightblue", "livings" = "blue") (the default - you can use the name "tips" to designate both livings and fossils).

• a function from which to sample the colours to match the time gradient for each element.

The trait option can intake from 1 to 3 traits (if use.3D = TRUE). If two traits are given (e.g. c(1, 2)), the default plots a correlation plot between both traits (same for 3 traits if use.3D = TRUE).

The use.3D option uses the rgl library to create a 3D plot. The plot displays either a time on the Z axis with two traits on the X and Y axis (if two traits are requested via trait) or three traits on the X Y and Z (if three traits a requested via trait).

See Also

treats

Examples

## Specifying a trait process
my_trait <- make.traits()
## Plotting a trait process
plot(my_trait, main = "A Brownian Motion")

## Simulating a tree with ten taxa
my_tree <- treats(stop.rule = list(max.taxa = 10))
## Plotting a simple birth death tree (using ape::plot.phylo)
plot(my_tree, main = "A pure birth tree")

## Simulating a tree with traits
my_data <- treats(stop.rule = list(max.taxa = 10),
                traits    = my_trait)
## Plotting the tree and traits
plot(my_data)

## Specifying a 3D trait process
my_3D_trait <- make.traits(n = 3)
## Simulating a birth death tree with that trait
my_data <- treats(bd.params = list(extinction = 0.2),
                stop.rule = list(max.living = 50),
                traits    = my_3D_trait)

## Plotting the second trait and the tree (default)
## The colours are purple for nodes and blue for tips
## with a black circle for highlighting the tips
plot(my_data, trait = 2, col = c("purple", "blue"),
     edges = "pink", tips.nodes = "black")

## Plotting the first and third trait correlation
## The colours are a heat map based on the elements age
plot(my_data, trait = c(1,3), col = terrain.colors,
     edges = "grey", tips.nodes = "black")

## Plotting the first and third trait correlation in 3D
plot(my_data, trait = c(1,3), col = rainbow,
     edges = "grey", tips.nodes = "black", use.3D = TRUE)
#rglwidget() # to display the plot with non-default OpenRGL

## Plotting all traits in 3D (without branch lengths)
plot(my_data, trait = c(1:3), col = heat.colors,
     edges = NULL, tips.nodes = "black", use.3D = TRUE)
#rglwidget() # to display the plot with non-default OpenRGL