plot.contsimmap: Plot continuous stochastic character maps

In bstaggmartin/contsimmap: Stochastic Character Maps of Continuous Trait Data on Phylogenies

Plot continuous stochastic character maps

Description

This function runs the default plotting method for continuous stochastic character maps (class "contsimmap").

Usage

## S3 method for class 'contsimmap'
plot(
  contsimmap,
  traits = 1,
  sims = sample(dim(contsimmap)[3], min(20, dim(contsimmap)[3])),
  edges = NULL,
  Col.by = c("simulation", "state", "edge", "time", dimnames(contsimmap)[[2]]),
  Layer.by = NULL,
  Alpha.by = NULL,
  Mix.by = NULL,
  Wgt.by = NULL,
  Lty.by = NULL,
  Lwd.by = NULL,
  add = FALSE,
  reverse.layers = FALSE,
  polarize = FALSE,
  ang.min = 0,
  ang.max = 2 * pi,
  curviness = 1,
  ...
)

Arguments

contsimmap	An object of class "contsimmap".
traits	A character/numeric vector specifying which traits within contsimmap to plot. Specifying a single trait results in a "phenogram"-style plot with the x-axis corresponding to time; specifying multiple traits results in a "phylomorphospace"-style plot with the first two traits corresponding to the x and y-axes, respectively. Additional traits are ignored for now, though a pairs() or 3D plotting method may implemented in the future. Also, NA traits are not yet supported and could break the function spectacularly. Alternatively, phylogenies may be plotted in more traditional styles akin to the plot.phylo() function in ape by setting trait = "phylogram" or trait = "cladogram". In conjunction with the Col.by, Mix.by, etc. arguments, this allows one to annotate phylogenies with colors according to mapped continuous and/or discrete states, much like the contMap() or plotSimmap() functions from phytools. Fan-style phylogenies may also be plotted by setting the polarize argument to TRUE.
sims	A character/numeric vector specifying which simulations within contsimmap to plot. Set to NULL to plot all simulations. NA simulations are not yet supported and could break the function spectacularly.
edges	A character/numeric vector specifying which edges within contsimmap to plot. Set to NULL to plot all edges. NA simulations are not yet supported and could break the function spectacularly.
Col.by, Layer.by, Alpha.by, Mix.by, Wgt.by, Lty.by, Lwd.by	Any unambiguous abbreviation of "simulation", "state", "edge", "time", or trait names within contsimmap. These arguments specify how their respective graphical arguments are allocated across the plot. For example, setting Col.by = "simulation" results in plotting each simulation in a different color, while setting it to "edge" or "time" instead causes edges or time slices to be colored differently. Layer.by controls how parts of the plot are layered on top of one another; for example, setting Layer.by = "time" results in plotting younger parts of the phylogeny last. Alpha.by, Mix.by, and Wgt.by control modifications of the base colors using alter.cols(); for example, setting Col.by = "simulation" and Alpha.by = "time" would result in plotting each simulation in a different color but adjusting the transparency of these colors according to time slice. Setting any of these to NULL or NA results in defaults: "simulation" for Col.by, "simulation" for Layer.by if producing a "phenogram"-style plot and "time" otherwise, whatever Col.by is for Alpha.by/Mix.by/Lty.by, whatever Mix.by is for Wgt.by, and whatever Lty.by is for Lwd.by.
add	TRUE or FALSE: should the plot be added to the existing plot window or initiate a new plotting window?
reverse.layers	TRUE or FALSE: should the layering order specified by Layer.by (and the optional layer argument passed to ...) be reversed? For example, if Layer.by = "time" and reverse.layering = TRUE, the older, rather than younger, parts of the phylogeny will be plotted last.
polarize	TRUE or FALSE: should the x and y coordinates be transformed to polar coordinates r and \theta, respectively? This is mainly for plotting phylogenies in conventional fan style by specifying traits = "phylogram" and polarize = TRUE, though maybe you want to "polarize" a phenogram/phylomorphospace for some reason? Seems kinda like a neat idea, and I don't judge!
ang.min	If polarize = TRUE: specifies the angle (in radians) that the minimum y coordinate gets converted to.
ang.max	If polarize = TRUE: specifies the angle (in radians) that the maximum y coordinate gets converted to.
curviness	If traits = "cladogram": a positive number specifying the degree to which edge lines are "biased" towards the y coordinate of ancestral nodes (if <1) versus descendant nodes (if >1). The default is 1, resulting in perfectly straight lines that don't curve.
...	Just about any base R graphical argument you can think of–it should theoretically all work! Notably, entries of col, lty, and lwd are recycled according to their respective <xxx>.by arguments: If "simulation", entries are assigned to simulations in the same order as given by sims. Entries may also be named to assign them to specific simulations. If "state", entries are assigned to discrete states in the multiSimmap object contsimmap is based on, in alphanumeric order. Entries may also be named to assign them to specific states. If "edge", entries are assigned to edges available in contsimmap in order of their numeric indices. Entries may also be named to assign them to specific edges. If "time" or a trait name, entries are interpolated to create a continuous gradient (as best as R can manage). As a result, any NA entries are generally ignored. You can use <xxx>.breaks arguments to control how this gradient is constructed (see below). There are also a few additional and potentially important arguments: layer, which is used to alter the layering order by specifying "high priority" elements. For example, setting layer = "tree1_sim1" ensures that simulation "tree1_sim1" is plotted last, assuming that Layer.by = "simulation". layer can also be a numeric or logical vector. If Layer.by is set to "time" or a trait name, one can even use this argument to specify particular time slices or trait values that should be plotted last. Note that that this instead specifies "low priority" elements that are plotted first if reverse.layering = TRUE. alpha, mix, and wgt, which are recycled as described above and correspond to the same arguments in alter.cols(). <xxx>.breaks (where <xxx> is either "time" or a trait name), which controls how continuous gradients are constructed. This is similar to the breaks argument in the image() function, and basically ends up getting passed to the vec argument in a call to findInterval(). Essentially, you provide thresholds where corresponding graphical arguments change. This can also be set to an integer, in which case <xxx>.breaks + 2 equally-spaced intervals are constructed across an appropriate range. If not specified, these arguments are set to 100L by default.

Value

Invisibly assigns plot information to "last_plot.phylo" in .PlotPhyloEnv environment, just like the plot.phylo() function from ape. Most importantly, this allows the use of the ape functions nodelabels(), tiplabels(), and edgelabels() for further plot annotation. Note that tip/node coordinates are averaged if multiple simulations are plotted at once.

bstaggmartin/contsimmap documentation built on Aug. 12, 2024, 5:16 a.m.