prof.plot: Plot profiles of posterior samples from a fitted evorates...

In bstaggmartin/backwards-BM-simulator: Evolving Rate Models of Continuous Trait Evolution

Plot profiles of posterior samples from a fitted evorates model

Description

This function plots histograms/densities ("profiles") of posterior samples for particular parameters from an evorates_fit object or param_block array.

Usage

prof.plot(
  x,
  smooth = FALSE,
  p = 0.05,
  lower.quant = NULL,
  upper.quant = NULL,
  lower.cut = NULL,
  upper.cut = NULL,
  add.lines = NULL,
  quant.lines = TRUE,
  add = FALSE,
  make.legend = TRUE,
  include.chain.legend = TRUE,
  ...,
  param.args = c("col", "border", "lines.col", "alpha", "border.alpha", "lines.alpha"),
  chain.args = c("angle", "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.
smooth	TRUEor FALSE: should profiles be plotted as histograms or "smoothed" density plots? By default, set to FALSE such that profiles are plotted as histograms. Densities are estimated via R's built-in density() function.
p	A numeric vector controlling the widths of the shaded portions of profiles for each parameter. Specifically, the shaded region is the (1-p)% credible interval (so 95% credible interval by default). The vector is recycled as necessary, NA's result in shading in the entire profile (technically the 100% credible interval), and entries below 0 or above 1 are rounded up and down to 0 and 1, respectively. Overwritten by lower.quant, upper.quant, lower.cut, and upper.cut, 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 the shaded portions of profiles 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. Overwritten by lower.cut and upper.cut, which may be used to provide finer control over the bounds of the shaded regions.
lower.cut, upper.cut	Numeric vectors specifying the boundaries of the shaded portions of profiles for each parameter (on the x-axis scale, rather than quantile-based). Notably, these can be used plot credible intervals based on the highest posterior density regions, rather than quantiles as is done by default (see examples below). Set to NULL (the default) to just use all boundaries specified by p, lower.quant, and/or upper.quant (see above). The vectors are recycled as necessary and NA's also default to boundaries specified by p, lower.quant, and/or upper.quant.
add.lines	A numeric vector specifying where to plot lines over profiles. This is not yet "vectorized", and will plot the same lines for all profiles (though I hope to change this in the future)! Can be specified via posterior quantiles if quant.lines is TRUE, or via actual positions along x-axis otherwise. NA's result in plotting lines at posterior means.
quant.lines	TRUEor FALSE: should line positions (see above) correspond to posterior quantiles or positions along the x-axis? Defaults to TRUE, meaning that add.lines corresponds to posterior quantiles; in this case entries of add.lines below 0 or above 1 are rounded up and down to 0 and 1, respectively. This does not affect NA entries of add.lines, which always result in plotting lines at posterior means.
add	TRUEor FALSE: should profiles 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 profiles? Defaults to TRUE, but automatically suppressed when only a single profile 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 profiles from only a single chain are plotted.
...	Other arguments, such as graphical parameters or arguments to pass to hist()/density() for profile construction. 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. breaks to specify the number of breaks in histograms if smooth is FALSE. bw and/or adjust to specify the width of kernels used to estimate density if smooth is TRUE. Most base R graphical parameters should work, along with a few extras: col by default specifies the color of the profiles for each parameter. Defaults to palette(). border by default specifies the color of the profile borders for each parameter. Inherits from col if not specified. alpha by default controls the transparency of profile colors for each parameter, with 0, 1, and NA corresponding to completely transparent, opaque, and no modification, respectively. Defaults to NA. lwd,lty by default specify the line width and style for all profiles (you could mess with param.args, etc. to change this–see below). angle by default controls the angle of the lines used to shade profiles for each chain if density is a positive number. Defaults to a range of angles between 0 and 180 if profiles for multiple chains are plotted. density by default controls the density of lines used to shade profiles for each chain, with NULL and NA resulting in solid shading (the default if profiles are plotted for a single chain). Defaults to 20 if profiles for multiple chains are plotted. Some arguments like col, alpha, lwd, etc. can be modified with "lines." or "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 profiles (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: trace.plot()

Examples

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

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

#some ways the plot style might be tweaked:
prof.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),
          breaks = 100,
          col = c('blue','red','green','black'), alpha = 0.1, border.alpha = 0.25,
          add.lines = c(0.25, NA, 0.75), lines.lwd = c(2, 3, 2), lines.lty = c(3, 2, 3),
          bty='n', legend.bty = 'n', legend.inset = c(0.1, 0), lwd = 2)
#may want to "smooth out" profiles!
prof.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),
          smooth = TRUE, bw = 0.1,
          col = c('blue','red','green','black'), alpha = 0.1, border.alpha = 0.25,
          add.lines = c(0.25, NA, 0.75), lines.lwd = c(2, 3, 2), lines.lty = c(3, 2, 3),
          bty='n', legend.bty = 'n', legend.inset = c(0.1, 0), lwd = 2)
#try some narrower credible intervals?
prof.plot(list(par, "R_0"), fit = cet_fit, p = 0.5,
          overwrite.param.names = expression("ln"~sigma["Meso"]^2,
                                             "ln"~sigma["Orca"]^2,
                                             "ln"~sigma["Glob"]^2,
                                             "ln"~sigma["Root"]^2),
          smooth = TRUE, bw = 0.1,
          col = c('blue','red','green','black'), alpha = 0.1, border.alpha = 0.25,
          add.lines = c(0.25, NA, 0.75), lines.lwd = c(2, 3, 2), lines.lty = c(3, 2, 3),
          bty='n', legend.bty = 'n', legend.inset = c(0.1, 0), lwd = 2)
#or intervals based on highest posterior density regions
#(have to combine chains since different cuts for the same parameters aren't yet allowed)
#(requires HDInterval package)
fit <- combine.chains(cet_fit)
combined.par <- get.bg.rate(fit = fit,
                node.groups = setNames(list('Mesoplodon','Orcinus',c('Pseudorca','Feresa')),
                                       c('Mesoplodon','Orca','Globicephalinae')),
                )
tmp <- par.c(combined.par, "R_0", fit = fit)
tmp <- apply(tmp, 2, HDInterval::hdi)
prof.plot(list(combined.par, "R_0"), fit = fit, lower.cut = tmp[1,], upper.cut = tmp[2,],
          overwrite.param.names = expression("ln"~sigma["Meso"]^2,
                                             "ln"~sigma["Orca"]^2,
                                             "ln"~sigma["Glob"]^2,
                                             "ln"~sigma["Root"]^2),
          smooth = TRUE, bw = 0.1,
          col = c('blue','red','green','black'), alpha = 0.1, border.alpha = 0.25,
          add.lines = c(0.25, NA, 0.75), lines.lwd = c(2, 3, 2), lines.lty = c(3, 2, 3),
          bty='n', legend.bty = 'n', legend.inset = c(0.1, 0), lwd = 2)

bstaggmartin/backwards-BM-simulator documentation built on June 3, 2024, 5:51 p.m.