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)

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)

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)

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)

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, lineage_label_format_template=None, species_label_format_template=None, rng=None, **kwargs)
generate_sample(**kwargs)

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 tip node on the lineage tree will have an attribute, species_tree_node, which is a reference to the species tree tip to which the lineage tip corresponds.

Each tip node on the species tree will have an attribute, lineage_tree_nodes, which is a reference to an iterable of tip nodes on the lineage tree that are associated with this species tree node.

Parameters:
  • max_time (float or None) – Terminate and return results if this time is exceeded. If None, then do not terminate based on run time.
  • min_extant_orthospecies (int or None) – Terminate and return results when at least this number of tips are found in the confirmed-species tree (i.e., the pruned tree consisting of only “good” species) and other specified conditions are met.
  • max_extant_orthospecies (int or None) – Terminate and return results when at least this number of tips are found in the confirmed-species tree (i.e., the pruned tree consisting of only “good” species).
  • num_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_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.
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.