trace.plot: Plot traces of posterior samples from a fitted evorates model

In bstaggmartin/evorates: Evolving Rate Models of Continuous Trait Evolution

Plot traces of posterior samples from a fitted evorates model

Description

This function plots posterior samples as a function of iterations ("traces") for particular parameters from an evorates_fit object or param_block array.

Usage

trace.plot(
  x,
  ribbon = TRUE,
  ribbon.first = FALSE,
  n.windows = 50,
  window.size = NULL,
  p = 0.05,
  lower.quant = NULL,
  upper.quant = NULL,
  add.lines = NULL,
  add = FALSE,
  make.legend = TRUE,
  include.chain.legend = TRUE,
  ...,
  param.args = c("col", "lines.col", "alpha", "lines.alpha", "ribbon.col",
    "ribbon.border", "ribbon.alpha", "ribbon.border.alpha"),
  chain.args = c("ribbon.angle", "ribbon.density"),
  inpar.args = c("lines.lty", "lines.lwd")
)

Arguments

x	The parameters to be plotted. Typically, this is a param_block array extracted from an evorates_fit object, though it can also be a character or numeric vector specifying parameters to extract from an evorates_fit object passed to the fit argument (see ...). For details on how parameters are extracted, see grapes-chains-grapes. Multiple param_block arrays and character/numeric selections can be combined as lists.
ribbon	TRUEor FALSE: should ribbons of "rolling" posterior quantiles be plotted? Here, rolling means that multiple quantiles per trace are calculated within sliding windows of posterior samples (the number of windows and their size can be tweaked via the arguments n.windows and window.size; see below). The ribbons help give a sense of how "stationary" the posterior samples are and thus provide insight into he convergence/mixing of chains. Set to TRUE by default.
ribbon.first	TRUEor FALSE: should ribbons be plotted first, "underneath" their main trace lines, or vice versa? Defaults to TRUE, such that ribbons are plotted second, "on top of" their main trace lines.
n.windows	The number of windows used to calculate "rolling" quantiles for ribbons. Windows are centered such that chains are broken into approximately equal intervals (i.e., specfying 10 windows for 1000 iterations will result in windows centered at iterations 1, 112, 223, 334, ..., 1000). Also specifies number of windows used for lines defined by add.lines (see below).
window.size	The size of windows used to calculate "rolling" quantiles for ribbons. If NULL (the default), window sizes are set to about 10 times the interval between window centers. Larger window sizes result in smoother-looking ribbons. Also specifies the window size used for lines defined by add.lines (see below).
p	A numeric vector controlling the width of ribbons for each parameter. Specifically, the shaded region is the "rolling" (1-p)% credible interval (so 95% credible interval by default). The vector is recycled as necessary, NA's suppress ribbon plotting, and entries below 0 or above 1 are rounded up and down to 0 and 1, respectively. Overwritten by lower.quant and upper.quant, which may be used to provide finer control over the bounds of the shaded regions.
lower.quant, upper.quant	Numeric vectors specifying the boundaries of ribbons for each parameter based on posterior quantiles. Set to NULL (the default) to just use all boundaries specified by p (see above). The vectors are recycled as necessary, NA's also default to boundaries specified by p, and entries below 0 or above 1 are rounded up and down to 0 and 1, respectively.
add.lines	A numeric vector specifying additional "rolling" quantiles to plot over traces. This is not yet "vectorized", and will plot the same lines for all traces (though I hope to change this in the future)! NA's result in plotting rolling means.
add	TRUE or FALSE: should traces be plotted in an open plotting window, or should a new plot window be opened? Defaults to FALSE, meaning that a new plot window is started.
make.legend	TRUEor FALSE: should a legend be automatically generated for the plotted traces? Defaults to TRUE, but automatically suppressed when only a single trace is plotted.
include.chain.legend	TRUE or FALSE: should the automatically-generated legend include a legend for the different chains? TRUE by default, but automatically suppressed when traces from only a single chain are plotted. Particularly helpful here since chains are indistinguishable by default when ribbon is FALSE (you could mess with param.args, etc. to change this–see below).
...	Other arguments, such as graphical parameters. Here are the some commonly-used ones: fit to specify an evorates_fit object from which to extract parameters (if x includes character or numeric selections). overwrite.param.names to specify alternate names for parameters in the automatically generated x-axis title and legend. This is helpful if you want to include otherwise forbidden characters in parameter names, like greek symbols. Most base R graphical parameters should work, along with a few extras: col by default specifies the color of main trace line for each parameter. Defaults to palette(). alpha by default controls the transparency of main trace line colors for each parameter, with 0, 1, and NA corresponding to completely transparent, opaque, and no modification, respectively. Defaults to NA. ribbon.col by default specifies the color of the ribbon fill for each parameter. Inherits from col if not specified. ribbon.border/border by default specifies the color of the ribbon borders for each parameter. Inherits from ribbon.col if not specified. ribbon.angle/angle by default controls the angle of the lines used to fill ribbons for each chain if ribbon.density/density is a positive number. Defaults to a range of angles between 0 and 180 if profiles for multiple chains are plotted. ribbon.density/density by default controls the density of lines used to shade ribbons for each chain, with NULL and NA resulting in solid shading (the default if traces are plotted for a single chain). Defaults to 20 if traces for multiple chains are plotted. lwd,lty by default specify the line width and style for all main trace lines (you could mess with param.args, etc. to change this–see below). Some arguments like col, alpha, lwd, etc. can be modified with "lines.", "ribbon.", or "ribbon.border." at the beginning to make them only affect certain elements of the plot. Perhaps most importantly, "legend." can be used to make arguments affect the automatically generated legend if make.legend is TRUE.
param.args, chain.args, inpar.args	Generally, these should not be altered, but are exposed here for the curious to play around with. These are vectors of argument names for graphical parameters that control whether the graphical parameters vary by the parameter the profile corresponds to (param.args), the chain the profile corresponds to (chain.args), or within traces (inpar.args). Notably, default graphical parameters are tailored to the defaults for these arguments, and messing with these will often result in ugly plots without a lot of extra customization!

Value

Nothing as of now–this function just makes a plot!

See Also

Other evorates plotting functions: prof.plot()

Examples

#get whale/dolphin evorates fit
data("cet_fit")

#plot some parameters
trace.plot(cet_fit %chains% c("R_sig2", "R_mu"))
#the above is equivalent to:
trace.plot(c("R_sig2", "R_mu"), fit = cet_fit)
#could also do something like this:
par <- get.bg.rate(fit = cet_fit,
                   node.groups = setNames(list('Mesoplodon','Orcinus',c('Pseudorca','Feresa')),
                                          c('Mesoplodon','Orca','Globicephalinae')),
)
trace.plot(par)
#or even:
trace.plot(list(par, "R_0"), fit = cet_fit)

#some ways the plot style might be tweaked:
trace.plot(list(par, "R_0"), fit = cet_fit,
           overwrite.param.names = expression("ln"~sigma["Meso"]^2,
                                              "ln"~sigma["Orca"]^2,
                                              "ln"~sigma["Glob"]^2,
                                              "ln"~sigma["Root"]^2),
           col = c('blue','red','green','black'), alpha = 0.2, lty=1,
           ribbon = FALSE,
           add.lines = c(0.025, 0.25, NA, 0.75, 0.975),
           lines.alpha = 0.3, lines.lwd = c(1, 2, 3, 2, 1), lines.lty = c(3, 2, 1, 2, 3),
           bty='n', legend.bty = 'n', legend.x = "topleft", legend.horiz = TRUE, include.chain.legend = FALSE)
#may want rougher, more finely-grained rolling quantiles?
trace.plot(list(par, "R_0"), fit = cet_fit,
           overwrite.param.names = expression("ln"~sigma["Meso"]^2,
                                              "ln"~sigma["Orca"]^2,
                                              "ln"~sigma["Glob"]^2,
                                              "ln"~sigma["Root"]^2),
           col = c('blue','red','green','black'), alpha = 0.2, lty=1,
           ribbon = FALSE, n.windows = 100, window.size = 50,
           add.lines = c(0.025, 0.25, NA, 0.75, 0.975),
           lines.alpha = 0.3, lines.lwd = c(1, 2, 3, 2, 1), lines.lty = c(3, 2, 1, 2, 3),
           bty='n', legend.bty = 'n', legend.x = "topleft", legend.horiz = TRUE, include.chain.legend = FALSE)

bstaggmartin/evorates documentation built on May 31, 2024, 5:56 a.m.