dendropy.model.protractedspeciation: The Protracted Speciation (Birth-Death) Model

Models, modeling and model-fitting of the protracted speciation, as described in:

Etienne, R.S., Morlon, H., and Lambert, A. 2014. Estimating the
duration of speciation from phylogenies. Evolution 2014: 2430-2440.
doi:10.1111/evo.12433
dendropy.model.protractedspeciation.expected_duration_of_speciation(speciation_initiation_rate, speciation_completion_rate, incipient_species_extinction_rate, D=None)[source]

Returns mean duration of speciation, following Eqs. 4 in Etienne et al. (2014):

The duration of speciation differs from the speciation-completion time in that the latter is the waiting time until a single incipient lineage completes the speciation process if extinction was zero, whereas the former is the time needed for an incipient species or one of its descendants to complete speciation, condi- tional on the fact that speciation completes, that is, this is the time taken by any species that succeeded in speciating completely.
Parameters:
  • speciation_initiation_rate (float) – The birth rate, b (the incipient species birth rate and the “good” species birth rate are assumed to be equal): the rate at which new (incipient) species are produced from either incipient or “good” species lineages.
  • speciation_completion_rate (float) – The rate at which incipient species get converted to good species, $lambda_1$.
  • incipient_species_extinction_rate (float) – The incipient species exctinction rate, $mu_1$: the rate at which incipient species go extinct.
  • D (float) – Value of D (as given in Eq. 5 in Etienne et al. 2014). Will be calculated if not specified.
Returns:

t (float) – The duration of speciation.

dendropy.model.protractedspeciation.log_probability_of_duration_of_speciation(tau, speciation_initiation_rate, speciation_completion_rate, incipient_species_extinction_rate, D=None, phi=None)[source]

Returns probability of duration of speciation, tau, following Eqs. 6 in Etienne et al.

Parameters:
  • tau (float) – The duration of speciation.
  • speciation_initiation_rate (float) – The birth rate, b (the incipient species birth rate and the “good” species birth rate are assumed to be equal): the rate at which new (incipient) species are produced from either incipient or “good” species lineages.
  • speciation_completion_rate (float) – The rate at which incipient species get converted to good species, $lambda_1$.
  • incipient_species_extinction_rate (float) – The incipient species exctinction rate, $mu_1$: the rate at which incipient species go extinct.
  • D (float) – Value of D (as given in Eq. 5 in Etienne et al. 2014). Will be calculated if not specified.
  • phi (float) – Value of phi (as given in Eq. 7 in Etienne et al. 2014). Will be calculated if not specified.
Returns:

p (float) – The probability of the duration of speciation, tau.

dendropy.model.protractedspeciation.maximum_probability_duration_of_speciation(speciation_initiation_rate, speciation_completion_rate, incipient_species_extinction_rate, D=None, phi=None)[source]

Returns duration of speciation that maximizes probability under given process parameters, following eq. 8 of Etienne et al (2014).

Parameters:
  • speciation_initiation_rate (float) – The birth rate, b (the incipient species birth rate and the “good” species birth rate are assumed to be equal): the rate at which new (incipient) species are produced from either incipient or “good” species lineages.
  • speciation_completion_rate (float) – The rate at which incipient species get converted to good species, $lambda_1$.
  • incipient_species_extinction_rate (float) – The incipient species exctinction rate, $mu_1$: the rate at which incipient species go extinct.
  • D (float) – Value of D (as given in Eq. 5 in Etienne et al. 2014). Will be calculated if not specified.
  • phi (float) – Value of phi (as given in Eq. 7 in Etienne et al. 2014). Will be calculated if not specified.
Returns:

t (float) – The duration of speciation with the maximum probability under the given process parameters.

dendropy.model.protractedspeciation.probability_of_duration_of_speciation(tau, speciation_initiation_rate, speciation_completion_rate, incipient_species_extinction_rate, D=None, phi=None)[source]

Returns probability of duration of speciation, tau, following Eqs. 6 in Etienne et al.

Parameters:
  • tau (float) – The duration of speciation.
  • speciation_initiation_rate (float) – The birth rate, b (the incipient species birth rate and the “good” species birth rate are assumed to be equal): the rate at which new (incipient) species are produced from either incipient or “good” species lineages.
  • speciation_completion_rate (float) – The rate at which incipient species get converted to good species, $lambda_1$.
  • incipient_species_extinction_rate (float) – The incipient species exctinction rate, $mu_1$: the rate at which incipient species go extinct.
  • D (float) – Value of D (as given in Eq. 5 in Etienne et al. 2014). Will be calculated if not specified.
  • phi (float) – Value of phi (as given in Eq. 7 in Etienne et al. 2014). Will be calculated if not specified.
Returns:

p (float) – The probability of the duration of speciation, tau.

The ProtractedSpeciationProcess Class

class dendropy.model.protractedspeciation.ProtractedSpeciationProcess(speciation_initiation_from_orthospecies_rate, speciation_initiation_from_incipient_species_rate, speciation_completion_rate, orthospecies_extinction_rate, incipient_species_extinction_rate, rng=None)[source]
generate_sample(**kwargs)[source]

Samples from the Protracted Speciation Model process, returning a tuple:

  • the lineage tree: this tree has all nodes/lineages, i.e. both “good” species as well as incipient species.
  • the (ortho- or confirmed- or “good”-)species tree: the tree only has “good” species, i.e. with all incipient species pruned out.

Each node on the protracted speciation tree as will as the “good” species tree will have an attribute, protracted_speciation_model_lineage, which is a reference to a ProtractedSpeciationProcessLineage instance which represents the lineage associated with this node. Note that each node can only be associated with a single lineage, but a lineage might span several nodes.

If is_correlate_lineage_and_species_trees is True, then additional attributes will be added. See dendropy.model.protractedspeciation.ProtractedSpeciationProcess.correlate_lineage_and_species_trees for details.

Parameters:
  • max_time (float or None) – Terminate and return results when this time is reached. If None, then do not terminated based on run time.
  • max_extant_orthospecies (int or None) – Terminate and return results when this number of tips are found in the confirmed-species tree (i.e., the pruned tree consisting of only “good” species). If None, then do not terminate based on the number of tipes on the confirmed-species tree.
  • max_extant_lineages (int or None) – Terminate and return results when this number of tips are found in the lineage tree (i.e. the tree with both incipient and good species). If None, then do not terminate based on the number of tipes on the incipient species tree.
  • is_initial_lineage_orthospecies (bool) – Whether the first lineage that initialies the process is a “good” species or not. Defaults to True: first species on the tree is a “good” species.
  • is_retry_on_total_extinction (bool) – If False, then a TreeSimTotalExtinctionException will be raised if all lineages go extinct before the termination conditions are met. Defaults to True: if all lineages go extinct before the termination conditions are met, then the simulation is rerun, up to a maximum of max_retries.
  • max_retries (int) – Maximum number of runs to execute in the event of prematurely-terminated simulations due to all lineages going extinct. Once this number or re-runs is exceed, then TreeSimTotalExtinctionException is raised. Defaults to 1000. Set to None to never quit trying.
  • is_correlate_lineage_and_species_trees (bool) – [NOT USED] If True then additional attributes will be added to the resulting trees to relate them. See dendropy.model.protractedspeciation.ProtractedSpeciationProcess.correlate_lineage_and_species_trees for details.
Returns:

  • lineage_tree (|Tree| instance) – A tree from the protracted speciation process, with all lineages (good species as well as incipient species).
  • orthospecies_tree (|Tree| instance) – A tree from the protracted speciation process with only “good” species.