BioGeoBEARS (version 0.2.1)

make_relprob_matrix_de: Make a relative dispersal probability matrix (in text form)

Description

This function takes a list of states/geographic ranges, and makes a relative probability matrix describing the probability of transition between each state. These probabilities are described in terms of d, "dispersal" (actually range expansion) and "extinction" (actually local extirpation, or range contraction), as done in the program LAGRANGE (Ree et al. (2008), Smith et al. (2010)).

Usage

make_relprob_matrix_de(states_list = default_states_list(), split_ABC = FALSE, split = "", remove_simultaneous_events = TRUE, add_multiple_Ds = TRUE, dispersal_multiplier_matrix = make_dispersal_multiplier_matrix(states_list))

Arguments

states_list

A list of states, where each state consists of a list of areas. A default example list is provided.

split_ABC

TRUE or FALSE If TRUE then each state/range in the input geographic ranges (states_list) will be split on the argument contained in split.

split

The character to split on.

remove_simultaneous_events

If TRUE (default, as in LAGRANGE and almost all phylogenetic Markov models), then it is assumed that all changes in geographic range along branches must happen one event at a time. If FALSE, simultaneous events are not excluded; this is not recommended. However, notably, a commonly-used biogeographic model (treating biogeography as a multistate discrete character in an ML framework, where every species/lineage inhabits one and only one area at any point in time) effectively is invoking a simultaneous event: e.g., A->B is a simultaneous range gain and range loss, from the perspective of the dispersal-extinction framework.

add_multiple_Ds

If TRUE (default, as in LAGRANGE), the probabilities of dispersal from each possible source area are added together.

dispersal_multiplier_matrix

A user-provided dispersal multiplier matrix; the default is a matrix of 1s from make_dispersal_multiplier_matrix(states_list=states_list).

Value

dedf The output data.frame, termed dedf (dedf=dispersal-extinction data.frame), contains the actual text of the formulas by which the transition probability matrix would be calculated.

Details

The output data.frame, termed dedf (dedf=dispersal-extinction data.frame), contains the actual text of the formulas by which the transition probability matrix would be calculated. E.g., the example calculates the matrix corresponding to Equation 1 on p. 6 of Ree & Smith (2008).

Note that the geographic range-change process described here is a continuous-time process, where the probability of change is a function of branch length, and all transitions occur because of dispersal and extinction. LAGRANGE also implements a cladogenesis model (thus DEC -- dispersal-extinction-cladogenesis) which describes an "instantaneous" process of geographic range change at speciation/lineage-splitting events. BioGeoBEARS allows users to turn on, turn off, or otherwise customize both the continuous-time model and the cladogenesis model.

References

http://phylo.wikidot.com/matzke-2013-international-biogeography-society-poster https://code.google.com/p/lagrange/

ReeSmith2008

SmithRee2010_CPPversion

Matzke_2012_IBS

FosterIdiots

See Also

make_dispersal_multiplier_matrix

Examples

testval=1

states_list = list("_", c("A"), c("B"), c("C"), c
("A","B"), c("B","C"), c("A","C"), c("A","B","C"))

states_list = areas_list_to_states_list_new(
areas=c("A","B","C"), include_null_range=TRUE, split_ABC=TRUE)
states_list

dedf = make_relprob_matrix_de(states_list=states_list,
split_ABC=FALSE, split="", remove_simultaneous_events=TRUE,
add_multiple_Ds=TRUE,
dispersal_multiplier_matrix=make_dispersal_multiplier_matrix(states_list=states_list))

dedf