# BioGeography with Bayesian (and Likelihood) Evolutionary Analysis in R Scripts

## Documentation for package ‘BioGeoBEARS’ version 0.2.1

- DESCRIPTION file.
- Package NEWS.

## Help Pages

A B C D E F G I L M N O P R S T U V Y

BioGeoBEARS-package | BioGeography with Bayesian (and likelihood) Evolutionary Analysis of RangeS

## -- A --

addslash | Add a slash to a directory name if needed
add_corners | Iterate up through a plotted tree, getting the coordinates of the corners
add_to_downpass_labels | Iterate up and down a tree in C++ LAGRANGE downpass order
adf | Convert to data.frame, without factors
adf2 | Convert to data.frame, without factors
AICstats_2models | Calculate all the AIC and LRT stats between two models
AkaikeWeights_and_Ratios_pairwise_on_summary_table_compared_to_ref | Get the ratio between the pairwise Akaike Weights
AkaikeWeights_on_summary_table | Calculate Akaike Weights, and add to table
areas_list_to_states_list_new | Convert a list of areas to a list of geographic ranges (states); R version
average_tr_tips | Average the heights of (non-fossil) tips to make ultrametric-ish.
axisPhylo2 | axisPhylo with more flexibility in labeling

## -- B --

bears_2param_DIVA_fast | 2-parameter model, fixed cladogenesis model (as in LAGRANGE)
bears_2param_standard_fast | 2-parameter model, fixed cladogenesis model (as in LAGRANGE)
bears_2param_standard_fast_fixnode | 2-parameter model, fixed cladogenesis model (as in LAGRANGE)
bears_2param_standard_fast_fortest | 2-parameter model, fixed cladogenesis model (as in LAGRANGE) - older test version
bears_2param_standard_fast_symOnly | 2-parameter model, no cladogenesis model (as in BayArea or other purely continuous-time model)
bears_2param_standard_fast_symOnly_simp | 2-parameter model, no cladogenesis model (as in BayArea or other purely continuous-time model)
bears_2param_standard_slowQ_slowSP | 2-parameter model, fixed cladogenesis model - slow version
bears_3param_standard_fast | 3-parameter model, adding j (founder-event speciation)
bears_3param_standard_fast_fixnode | 3-parameter model, adding j (founder-event speciation)
bears_3param_standard_fast_noJ | 3-parameter model, adding v (vicariance proportion), but no j (founder-event speciation)
bears_4param_standard_fast | 4-parameter model, adding j (founder-event speciation) and v (vicariance proportion)
bears_5param_standard_fast | 5-parameter model, adding j (founder-event speciation), v (vicariance proportion), and maxent_constraint_01 (weighting for size of smaller-ranged descendant lineage)
bears_5param_standard_fast_diffstart | 5-parameter model, with different starting points for optimization
bears_5param_standard_fast_v | 5-parameter model, adding j (founder-event speciation), v (vicariance proportion), and maxent_constraint_01v (vicariance daughter sizes)
bears_6param_standard_fast_ys_v | 6-parameter model, adding j (founder-event speciation), v (vicariance proportion), and both maxent_constraint_01 and maxent_constraint_01v
bears_9param_standard_fast_ys_v_cb | 6-parameter model, adding j (founder-event speciation), v (vicariance proportion), and both maxent_constraint_01 and maxent_constraint_01v
bears_optim_run | Run ML search from 'BioGeoBEARS_run' object
binary_ranges_to_letter_codes | Convert binary presence/absence codes (1/0) to a list of text area names
binary_range_to_letter_code_list | Convert binary presence/absence codes (1/0) to a list of text area names
binary_range_to_letter_code_txt | Convert binary presence/absence codes (1/0) to text area names
BioGeoBEARS | BioGeography with Bayesian (and likelihood) Evolutionary Analysis of RangeS
BioGeoBEARS_model | An object of class BioGeoBEARS_model holding the model inputs
BioGeoBEARS_model_defaults | Set up a default BioGeoBEARS model object
BioGeoBEARS_model_object_to_est_params | Extract estimated parameters from a BioGeoBEARS model object
BioGeoBEARS_model_object_to_init_params | Produce initial parameters from a BioGeoBEARS model object
BioGeoBEARS_model_object_to_params_lower | Produce the lower limit on the parameters from a BioGeoBEARS model object
BioGeoBEARS_model_object_to_params_upper | Produce the upper limit on the parameters from a BioGeoBEARS model object
BioGeoBEARS_run | An object of class BioGeoBEARS_run holding the model inputs

## -- C --

calcP_n | Calculate Z (part of equation 6.4 of Harte 2011)
calcZ_part | Calculate Z (equation 6.3 of Harte 2011)
calc_AICc_column | Calculate AICc values for a list of models
calc_AICc_vals | Calculate AICc values for a list of models
calc_AIC_column | Calculate AICs to make a column in a table
calc_AIC_vals | Calculate AICs for a list of models
calc_linked_params_BioGeoBEARS_model_object | Update parameters that are deterministic functions of free parameters
calc_loglike_for_optim | Take model parameters and the data and calculate the log-likelihood
calc_loglike_for_optim_stratified | Take model parameters and the data and calculate the log-likelihood - stratified version
calc_loglike_sp | Calculate log-likelihood with a transition matrix and speciation events - byte-compiled
calc_loglike_sp_prebyte | Calculate log-likelihood with a transition matrix and speciation events - pre-byte-compiled
calc_loglike_sp_stratified | Calculate log-likelihood with a transition matrix and speciation events, and with stratification
calc_obs_like | Calculate likelihood of count data given true presence/absence and parameters
calc_post_prob_presence | Calculate posterior probability of presence, given count data and parameters
calc_prob_forward_onebranch_dense | Dense matrix exponentiation forward on a branch, with rexpokit
calc_prob_forward_onebranch_sparse | Sparse matrix exponentiation forward on a branch, with rexpokit
chainsaw2 | Saw a tree off at a particular time before present
check_BioGeoBEARS_run | Check the inputs for various problems
check_if_state_is_allowed | Check if a geographic range/state is allowed, given an areas-allowed matrix.
cls.df | Get the class for each column in a list
colors_legend | Plot a colors legend for geographic ranges
conditional_format_cell | Conditionally format a number (mostly)
conditional_format_table | Conditionally format the numbers (mostly) in a table
cornerlabels | Make labels for plotting ranges on corners
cornerpies | Make pie charts for plotting ranges on corners
corner_coords | Get the corner coordinates

## -- D --

default_states_list | Default input for a states_list
define_BioGeoBEARS_model_object | Define a BioGeoBEARS_model class and object
define_BioGeoBEARS_run | Define a maximum likelihood search, perhaps stratified
define_tipranges_object | Define a tipranges class and object
dfnums_to_numeric | Get the class for each column in a list
divide_probs_by_number_of_options_nums | Divide each type of event by its frequency, return calculated probabilities
divide_probs_by_number_of_options_txt | Divide each type of event by its frequency

## -- E --

expand.grid.alt | A faster version of expand.grid
expand.grid.jc | An even faster version of expand.grid
expokit_dgpadm_Qmat2 | A byte-compiled version of expokit_dgpadm_Qmat2_prebyte
expokit_dgpadm_Qmat2_prebyte | A version of expokit_dgpadm_Qmat to byte-compile
extend_tips_to_ultrametricize | Take a tree, extend all tips (including fossils) up to 0.0 my before present
extract_numbers | Extract just the numbers from a string, including decimal points

## -- F --

findall | Get indices of all matches to a list

## -- G --

getAIC | Calculate AIC
getAICc | Calculate AICc
getAIC_weight_for_model1 | Calculate Akaike Weight
getareas_from_tipranges_object | Get the names of the areas in a tipranges object
getname | Collapse range abbreviations to strings
getranges_from_LagrangePHYLIP | Read a LAGRANGE PHYLIP-style file containing geographic ranges into a 'tipranges' object
get_AICweight_ratio_model1_over_model2 | Calculate ratio of Akaike Weights
get_Akaike_weights_from_rel_likes | Calculate the Akaike Weights, from the relative likelihoods of the models
get_Akaike_weights_from_rel_likes_pairwise | Calculate the Akaike Weights, from the relative likelihoods of the models
get_Akaike_weight_ratio_from_Akaike_pairwise_weights | Get the ratio between the pairwise Akaike Weights
get_all_daughter_tips_of_a_node | Get all the daughter tips of a node
get_all_node_ages | Get the ages of all the nodes in the tree (above the root)
get_APE_nodenums | Get R internal node numbers
get_colors_for_numareas | Get colors for a certain number of single areas
get_daughters | Get all the direct daughters nodes of a node
get_deltaAIC | Calculate deltaAIC
get_deltaAIC_pairwise_w_ref_model | Calculate deltaAIC
get_edge_times_before_present | Get the times of the top and bottom of each edge
get_fn_prefix | Get everything BEFORE the last suffix (.nex or whatever)
get_indices_of_branches_under_tips | Get the indices of the branches (row number in edge matrix) below each tip
get_indices_of_tip_nodes | Get TRUE/FALSE for nodes being tips
get_indices_where_list1_occurs_in_list2 | Return (first!) indices in second list matching the first list
get_indices_where_list1_occurs_in_list2_noNA | Return (first!) indices in second list matching the first list, excluding NAs
get_infparams_optimx | Get the inferred parameters from an ML optimization
get_infparams_optimx_nosim | Get the inferred parameters from an ML optimization (different filenames)
get_infprobs_of_simstates | Get the probabilities of the true (simulated) states
get_inf_LgL_etc_optimx | Get the inferred parameters from a results object (utility function)
get_lagrange_nodenums | Get internal node numbers in LAGRANGE's downpass order
get_leftright_nodes_matrix_from_results | Make a table of the Right and Left nodes descending from each node
get_level | Get a node's level in the tree
get_max_height_tree | Get the maximum age of all the nodes (above the root)
get_MLsplitprobs_from_results | Extract the ML probs for the base of each branch above a split
get_ML_probs | Get the probability of the ML state for each node, from a BioGeoBEARS model results list
get_ML_states | Get ML states from a BioGeoBEARS model results list
get_ML_states_from_relprobs | Extract the ML states at each node, from a table of relative probabilities - old version
get_ML_state_indices | Extract the indices for the ML states at each node, given a row of relative probabilities
get_nodenums | Get the unique node numbers in a tree
get_nodenum_structural_root | Gets the root node
get_node_ages_of_tips | Get the ages of each tip above the root
get_parent | Get the direct parent node of a node
get_path_first | Get the text that comes before the last slash
get_path_last | Get the text that comes after the last slash
get_perEvent_probs | Get the per-event probabilities at cladogenesis
get_probvals | Calculate probability of ordered discrete states using a maxent distribution (equations 6.3-6.4 of Harte 2011)
get_pruningwise_nodenums | Get internal node numbers in pruningwise order
get_relative_prob_model1old | Calculate relative probability of model 1 (=Akaike Weight)
get_relative_prob_model2old | Calculate relative probability of model 1 (Akaike Weight)
get_rownum_ref_model | Get rownum of named model
get_simparams | Get the simulated model parameters from the row of a table
get_simstates | Load the simulation information from an underscore delimited text string.
get_sister_node | Get the node sister to two nodes
get_statesColors_table | Make a color table for each area and their combinations
get_TF_tips | Get TRUE/FALSE for nodes being tips
get_tiplabel_ranges | For each tip, get a text string of the areas in a tipranges object.
given_a_starting_state_simulate_branch_end | Given the state at the start of a branch, simulate the state at the end of the branch
given_a_starting_state_simulate_split | Given the state just below a node, simulate the states after speciation

## -- I --

infprobs_to_probs_of_each_area | Convert probabilities of each state, to the probabilities of presence in each area
infprobs_to_probs_of_each_area_from_relprobs | Convert relative probabilities matrix to the probabilities of presence in each area
is.not.na | Check for not NA

## -- L --

label_nodes_postorder_phylo3 | Add postorder node number labels to a phylo3 tree object.
letter_strings_to_tipranges_df | Convert ranges in the form of letters (A, AB, BFG, etc.) to a 'tipranges' object
letter_string_to_binary | Convert ranges in the form of letters (A, AB, BFG, etc.) to binary state number codes
LGcpp_MLstate_per_node | Get the ML states per node, from a states table
LGcpp_splits_fn_to_table | Get the ML splits per node, from C++ LAGRANGE output
LGcpp_splits_fn_to_table2 | Get the ML splits per node, from Python LAGRANGE output
LGcpp_states_fn_to_table | Get the ML states per node, from C++ LAGRANGE output
LGpy_MLsplit_per_node | Get the ML splits per node, from a splits table
LGpy_splits_fn_to_table | Get the ML splits per node, from Python LAGRANGE output
list2str | Convert a list of items to a string
lrttest | Calculate Likelihood Ratio Test (LRT)
lrttest_on_summary_table | Calculate Likelihood Ratio Test (LRT) results, and add to table

## -- M --

make_dispersal_multiplier_matrix | Make a default matrix of relative dispersal probabilities between areas
make_relprob_matrix_bi | Make a relative probability matrix for a single speciation (bifurcation) event
make_relprob_matrix_de | Make a relative dispersal probability matrix (in text form)
make_relprob_nummatrix_sp1 | Convert a observed-speciation transition matrix to an unobserved-speciation transition matrix (numeric version)
make_relprob_txtmatrix_sp1 | Convert a observed-speciation transition matrix to an unobserved-speciation transition matrix (text version)
make_spmat_row | Construct a (text) cell of the cladogenesis/speciation matrix
mapply_calc_obs_like | Mapply version of calc_obs_like()
mapply_calc_post_prob_presence | Mapply version of calc_post_prob_presence()
mapply_likelihoods | Use mapply on matrix exponentiations - post-byte-compiling
mapply_likelihoods_prebyte | Use mapply on matrix exponentiations - pre-byte-compiling
map_LGpy_MLsplits_to_tree | Take the table of ML splits and node number and map on tree (Python version)
map_LG_MLsplits_to_tree | Take the table of ML splits and node number and map on tree (C++ LAGRANGE version)
map_LG_MLsplits_to_tree_corners | Map splits to the corners on a phylogeny
map_LG_MLstates_to_tree | Map states to the nodes on a phylogeny
match_list1_in_list2 | Return TRUE for list1 items when they occur in list2
maxsize | Get the maximum rangesize for a given ancestral rangesize
merge_words_nonwords | Merge lists of words and nonwords (numbers) that may be of different length
meval | 'eval()' function for use in 'sapply'
mix_colors_for_states | Mix colors logically to produce colors for multi-area ranges
moref | print to screen the header of a file

## -- N --

nodenums_bottom_up | Assign node labels in bottom-up, left-first format (as in e.g. r8s)
normat | Utility functions to help deal with matrices Normalize a transition matrix
np | normalizePath shortcut
nullsym_to_NA | Convert a specified null range code to NA

## -- O --

order_LGnodes | Order LAGRANGE-numbered nodes so that they can be plotted in R
order_tipranges_by_tr | Order the tipranges in a tipranges object so they match the order of tips in a tree
order_tipranges_by_tree_tips | Reorder the rows in a 'tipranges' object, to correspond to tree tips

## -- P --

params_into_BioGeoBEARS_model_object | Feed modified parameters back into a BioGeoBEARS model object
parse_lagrange_output | Parse the output file from python 'LAGRANGE'
parse_lagrange_output_old | Parse the output file from python 'LAGRANGE' - older version
parse_lagrange_python_output | Parse the output file from python 'LAGRANGE'
parse_lagrange_python_output_old | Parse the output file from python 'LAGRANGE' - old version
paste_rows_without_zeros | Concatenate cells in each row of a text-based transition matrix, excluding zeros
Pdata_given_rangerow | Calculate probability of detection data given a true geographic range and a detection probability
Pdata_given_rangerow_dp | Calculate probability of detection data given a true geographic range and a detection probability
pdfit | Print a table to LaTeX format
pdftable | Print a table to LaTeX format
plot_BioGeoBEARS_model | Graphical display of your anagenetic and cladogenetic biogeography models
plot_BioGeoBEARS_results | Plot the results of a BioGeoBEARS run
plot_cladogenesis_size_probabilities | Graphical display of P(daughter rangesize) for your input or inferred speciation model
postorder_nodes_phylo4_return_table | Get a table of node numbers, including DIVA node numbers
post_prob_states | Calculate posterior probability of each states/geographic ranges, given prior probabilities and data likelihoods
post_prob_states_matrix | Calculate posterior probability of each states/geographic ranges, given prior probabilities and data likelihoods
prflag | Utility function to conditionally print intermediate results
printall | Print an entire table to screen
prob_of_states_from_prior_prob_areas | Calculate probability of detection data for each OTU at each range in a list of states/geographic ranges
process_optim | Extract 'optim' results to a row
prt | Print tree in table format
prt_tree_to_phylo4 | prt_tree_to_phylo4
prune_specimens_to_species | Take a tree and species names/geography table and produce a pruned tree and tipranges object
prune_states_list | Cut down the states list according to areas_allowed_mat

## -- R --

rangestxt_to_colors | Convert a list of ranges text (KOM, MH, KOMIH, etc.)
readfiles_BioGeoBEARS_run | Read in the extra input files, if any
read_areas_allowed_fn | Read in the area areas by time
read_area_of_areas_fn | Read in the area areas by time
read_controls | Read a file with the total number of detections in a taphonomic control
read_detections | Read a file with detection counts per area
read_dispersal_multipliers_fn | Read in the hard-coded dispersal multipliers from file
read_distances_fn | Read in the distances by time
read_PHYLIP_data | Read a PHYLIP-format file
read_times_fn | Read in the stratification time breakpoints
relative_probabilities_of_subsets | Calculate probability of different descendant rangesizes, for the smaller descendant, in subset speciation
relative_probabilities_of_vicariants | Calculate probability of different descendant rangesizes, for the smaller descendant, in vicariant speciation
rel_likes_from_deltaAICs | Calculate the relative likelihoods of the models, from the deltaAIC
rel_likes_from_deltaAICs_pairwise | Calculate the relative likelihoods of the models, from the deltaAICs, pairwise
remove_null_rowcols_from_mat | Remove rows or columns representing a null geographic range from a matrix
return_items_not_NA | Remove NAs from a vector/list

## -- S --

save_tipranges_to_LagrangePHYLIP | Save a tipranges object to a LAGRANGE PHYLIP-style file containing binary-encoded geographic ranges
section_the_tree | Section a tree for stratified analysis
sfunc | Extract the appropriate probability for a subset speciation event, given text code for rangesize of smaller descendant, and ancestor
simstates_to_probs_of_each_area | Convert simulated states to probabilities of each area
simulated_indexes_to_tipranges_file | Convert simulated Qmat 0-based indexes to a tipranges file
simulated_indexes_to_tipranges_object | Convert simulated Qmat 0-based indexes to a tipranges object
simulate_biogeog_history | Simulate a biogeographical history, given a transition matrix and cladogenesis model
size_species_matrix | Calculate the dimensions of the cladogenesis/speciation matrix
slashslash | Remove double slash (slash a slash)
sourceall | Source all .R files in a directory, except "compile" and "package" files
states_list_indexes_to_areastxt | States (ranges) lists to txt string of the areas
strsplit2 | String splitting shortcut
strsplit_whitespace | Split strings on whitespace
symbolic_cell_to_relprob_cell | Convert symbolic cell (a text equation) to relprob matrix (a numeric value).
symbolic_cell_to_relprob_cell_sp | Convert symbolic cell (a text equation) to relprob cell (a numeric value) - speciation matrix version
symbolic_to_P_matrix | Convert symbolic matrix to relprob matrix
symbolic_to_Q_matrix | Convert symbolic matrix to an instantaneous rate matrix (Q matrix)
symbolic_to_Q_matrix_exper | Experimental version of 'symbolic_to_Q_matrix_exper', including base frequencies
symbolic_to_relprob_matrix_sp | Convert symbolic matrix (with text equations) to relprob matrix (numeric values) - speciation matrix version

## -- T --

tiplikes_wDetectionModel | Calculate probability of detection data for each OTU at each range in a list of states/geographic ranges
tipranges | The tipranges class
tipranges_to_area_strings | Convert tipranges binary coding to range strings
tipranges_to_tip_condlikes_of_data_on_each_state | Convert a tipranges object to the tip likelihoods
traverse_up | Traverse the tree from node up to the tips

## -- U --

unlist_df | Unlist the columns in a data.frame
unlist_df2 | Unlist the columns in a data.frame, with more checks
unlist_df3 | Unlist the columns in a data.frame, with more checks and adf
unlist_df4 | Unlist the columns in a data.frame, with more checks, adf, and dfnums_to_numeric
unlist_dtf_cols | Unlist the columns in a data.frame

## -- V --

vfunc | Extract the appropriate probability for a vicariant speciation event, given text code for rangesize of smaller descendant, and ancestor

## -- Y --

yfunc | Extract the appropriate probability for a sympatric/range-copying speciation event, given text code for rangesize of smaller descendant, and ancestor