plot_BioGeoBEARS_results: Plot the results of a BioGeoBEARS run
In BioGeoBEARS: BioGeography with Bayesian (and Likelihood) Evolutionary Analysis in R Scripts

Description Usage Arguments Details Note Author(s) References See Also Examples

This function plots on a tree the highest-probability ancestral states (ranges), splits if desired (these are the ranges/states just after cladogenesis, and are plotted on the corners of a tree), and/or pie charts at nodes. A legend tying the relationship between colors and states/ranges is also optionally plotted.

  plot_BioGeoBEARS_results(results_object,
    analysis_titletxt = NULL, addl_params = list(),
    plotwhat = "text", label.offset = NULL, tipcex = 0.8,
    statecex = 0.7, splitcex = 0.6, titlecex = 0.8,
    plotsplits = TRUE, plotlegend = FALSE,
    legend_ncol = NULL, legend_cex = 1,
    cornercoords_loc = "manual", include_null_range = TRUE,
    tr = NULL, tipranges = NULL)

`results_object`	The results object from `bears_optim_run` (with ancestral states on).
`analysis_titletxt`	The main title of the plot. If NULL, `results_object$inputs$description` is checked.
`addl_params`	The function will plot the log-likelihood (LnL) and the ML values of the free parameters. If you want additional parameters plotted, list them here.
`plotwhat`	To plot the ML discrete states, "text". To plot a piechart of the relative probability of all the states, "pie".
`label.offset`	Offset for the tree tip labels. If `NULL`, program chooses 0.05 x tree height.
`tipcex`	`cex` value for the tiplabels (scaling factor, i.e. 0.5 is half size)
`statecex`	`cex` value for the states (scaling factor, i.e. 0.5 is half size). Used on piecharts if plotwhat="pie".
`splitcex`	`cex` value for the splits (scaling factor, i.e. 0.5 is half size). Used on piecharts if plotwhat="pie".
`titlecex`	`cex` value for the title (scaling factor, i.e. 0.5 is half size).
`plotsplits`	If `TRUE`, plot states on the corners – text or pie charts, depending on `plotwhat`.
`plotlegend`	If `TRUE`, make a (separate) plot with a legend giving the colors for each state/range, using `colors_legend`.
`legend_ncol`	The number of columns in the legend. If `NULL` (default), the function calculates `floor(sqrt(length(possible_ranges_list_txt) / 2))` when the number of states is <=64, and `sqrt(ceiling(length(possible_ranges_list_txt)))` when > 64. Note that when you have hundreds of states, there is probably no good way to have a readable legend, and it is easier to just rely upon printing the character codes for the ML states in the plots, with the colors, and users can then see and trace the common colors/states by eye.
`legend_cex`	The cex (character expansion size) for the legend. Defaults to 1, which means the `legend` function determines the size. The value 2.5 works well for 15 or 16 states/ranges.
`cornercoords_loc`	The directory location containing the R script `plot_phylo3_nodecoords.R`. This function, modified from the APE function `plot.phylo`, cannot be included directly in the R package as it contains C code that does not pass CRAN's R CMD check. The default, cornercoords_loc="manual", will not allow split states to be plot. The R script `plot_phylo3_nodecoords.R` is located in the BioGeoBEARS extension data directory, `extdata/a_scripts`. You should be able to get the full path with `list.files(system.file("extdata/a_scripts", package="BioGeoBEARS"), full.names=TRUE)`.
`include_null_range`	If `TRUE` (default), the null range is included in calculation of colors. (Safest for now.)
`tr`	Tree to plot on. Default `NULL`, which means the tree will be read from the file at `results_object$inputs$trfn`.
`tipranges`	Tip geography data. Default `NULL`, which means the tree will be read from the file at `results_object$inputs$geogfn`.

The legend is plotted on a separate plot, as it is very difficult to predict whether or not there will be space on any given tree plot. The utility of the legend is also debatable, as plot_BioGeoBEARS_results plots the colors and state/range names directly onto the plot. Any legend will get unwieldy above perhaps 32 states, which is just 5 areas with no constraints (see numstates_from_numareas, or type numstates_from_numareas(numareas5, maxareas5, include_null_range=TRUE).

Note that this assumes that the ancestral states were calculated under the global optimum model (rather than the local optimum, with the model re-optimized for each possible state at each possible node, as done in e.g. LAGRANGE), and that these are marginal probabilities, i.e. this is not a joint reconstruction, instead it gives the probabilities of states at each node. This will not always be readable as a joint reconstruction (it could depict split scenarios that are not possible, for instance.)

Go BEARS!

Nicholas J. Matzke matzke@berkeley.edu

https://code.google.com/p/lagrange/

Matzke_2012_IBS

ReeSmith2008

get_leftright_nodes_matrix_from_results, corner_coords, plot.phylo, plot.phylo, tiplabels, legend, floor, ceiling, floor, numstates_from_numareas, system.file, list.files

test=1

Loading required package: rexpokit
Loading required package: SparseM

Attaching package: 'SparseM'

The following object is masked from 'package:base':

    backsolve

Loading required package: Rcpp
Loading required package: cladoRcpp
Loading required package: ape
Loading required package: phylobase

Attaching package: 'phylobase'

The following object is masked from 'package:ape':

    edges