BioGeoBEARS (version 0.2.1)

define_BioGeoBEARS_run: Define a maximum likelihood search, perhaps stratified

Description

Set up the inputs object for an ML search. See parameter descriptions for defaults.

Usage

define_BioGeoBEARS_run(abbr = "default", description = "defaults", BioGeoBEARS_model_object = define_BioGeoBEARS_model_object(), trfn = "Psychotria_5.2.newick", geogfn = "Psychotria_geog.data", timesfn = NA, distsfn = NA, dispersal_multipliers_fn = NA, area_of_areas_fn = NA, areas_allowed_fn = NA, detects_fn = NA, controls_fn = NA, max_range_size = NA, states_list = NULL, force_sparse = FALSE, use_detection_model = FALSE, print_optim = TRUE, num_cores_to_use = NA, cluster_already_open = FALSE, use_optimx = TRUE, return_condlikes_table = FALSE, calc_TTL_loglike_from_condlikes_table = TRUE, calc_ancprobs = TRUE, fixnode = NULL, fixlikes = NULL, speedup = TRUE, tmpwd = getwd())

Arguments

abbr

Text abbreviation of run, e.g. "default"

description

Text description of run, e.g. "defaults"

BioGeoBEARS_model_object

Default is define_BioGeoBEARS_model_object()

trfn

The filename of the phylogenetic tree, in NEWICK format (http://evolution.genetics.washington.edu/phylip/newicktree.html). Tipnames should match the names in geogfn. See read.tree in APE for reading in phylogenetic trees. Default "Psychotria_5.2.newick"

geogfn

A PHYLIP-style file with geographic range data (see getranges_from_LagrangePHYLIP) for each tipname. This is the same format used by C++ LAGRANGE (SmithRee2010_CPPversion). Default "Psychotria_geog.data"

timesfn

Filename for the stratified times.

distsfn

Filename for the changing distances.

dispersal_multipliers_fn

Filename for the changing hard-coded dispersal multipliers

area_of_areas_fn

Filename for the area of each area

areas_allowed_fn

Filename for the allowed connections between areas for single-species ranges.

detects_fn

Filename for the counts of detections of OTUs of interest. See calc_obs_like.

controls_fn

Filename for the counts of taphonomic controls (which INCLUDE the OTUs of interest). See calc_obs_like.

max_range_size

The maximum rangesize, in number of areas. Having a smaller maximum range size means that you can have more areas (the size of the state space is greatly reduced; see numstates_from_numareas.

states_list

A list of the possible states/geographic ranges, in 0-based index form.

force_sparse

Should sparse matrix exponentiation be used? Default FALSE, which means dense matrix exponentiation is always used. If NA, the program will use sparse matrix exponentiation for transition matrices above rank 128 (size 128x128). NOTE: Sparse matrix exponentiation seems to give correlated, but not exact, results, and these errors may accumulate. Presumably the problems become less with larger matrices, but I have not explored this in detail.

use_detection_model

If TRUE, use the detection model (with parameters mf, dp, and fdp) and counts of detections and counts of taphonomic controls to calculate the tip_condlikes_of_data_on_each_state.

print_optim

If TRUE (default), print the optimization steps as ML estimation progresses.

tmpwd

The working directory in which the input and output files will be placed. Default is getwd. This is stored mostly for future reference; users are responsible for manually navigating to the appropriate directory ahead of time, using setwd.

num_cores_to_use

If >1, parallel processing will be attempted. Note: parallel processing via library (parallel) will work in Mac command-line R, but not in Mac GUI R.app.

cluster_already_open

If the user wants to distribute the matrix exponentiation calculations from all the branches across a number of processors/nodes on a cluster, specify the cluster here. E.g. cluster_already_open = makeCluster(rep("localhost",num_cores_to_use), type = "SOCK"). Note: this will work on most platforms, including Macs running R from command line, but will NOT work on Macs running the R GUI R.app, because parallel processing functions like MakeCluster from e.g. library(parallel) for some reason crash R.app. The program runs a check for R.app and will just run on 1 node if found.

use_optimx

If TRUE, use optimx rather that optim.

return_condlikes_table

If TRUE, return the table of ALL conditional likelihood results, including at branch subsections (only some should be used in calculating the final log-likelihood of the geography range data on the tree!)

calc_TTL_loglike_from_condlikes_table

If TRUE, force making of the condlikes table, and use it to calculate the log-likelihood (default=TRUE; matches LAGRANGE).

calc_ancprobs

If TRUE (default), calculate and return the necessary pieces (uppass and downpass probs) for ancestral states.

fixnode

If the state at a particular node is going to be fixed (e.g. for ML marginal ancestral states), give the node number.

fixlikes

The state likelihoods to be used at the fixed node. I.e. 1 for the fixed state, and 0 for the others.

speedup

If TRUE (default), set the maximum number of iterations to itnmax=50*(number of free parameters), instead of the optimx default, 250. Also set optimx reltol parameter to 0.001 (instead of the default, ~1e-8).

Value

inputs Inputs for ML search.

References

http://phylo.wikidot.com/matzke-2013-international-biogeography-society-poster

Matzke_2012_IBS

See Also

readfiles_BioGeoBEARS_run, define_BioGeoBEARS_model_object, setwd, getwd

Examples

test=1