phylojunction.calculation package

Submodules

phylojunction.calculation.discrete_sse module

class phylojunction.calculation.discrete_sse.DiscreteStateDependentParameter(val: int | float | str | List[int | float | str], name: str = '', state: int = 0, epoch_idx: int = 1)

Bases: object

Discrete state-dependent parameter.

This is the parent class for either state-dependent rates or state-dependent parameters.

Supports vectorization of values only.

Parameters:

  • value (Union[int, float, str]) – Either an integer, float or string, or a list of any of those.

  • name (str) – Name of SSE parameter.

  • state (int) – Integer representing the state this SSE parameter is associated to.

  • epoch_idx (int) – Time slice (epoch) this SSE parameter is associated to.

epoch_idx: int
name: str
state: int
value: int | float | str | List[int | float | str]
class phylojunction.calculation.discrete_sse.DiscreteStateDependentParameterManager(matrix_state_dep_params: List[List[DiscreteStateDependentParameter]], total_state_count: int, seed_age_for_time_slicing: float | None = None, list_time_slice_age_ends: List[float] | None = None, epsilon: float = 1e-12)

Bases: object

Class for checking, organizing, and storing SSE parameters.

Upon initialization, this class verifies that user provided SSE parameters (and their time slice annotation) is acceptable. Then given a seed age for anchoring ages and converting them into times, and time slice age ends, this class produces computes time slice time ends.

This class does not care about vectorization. It manipulates instances of DiscreteStateDependentParameter, which then in turn contain multiple values if vectors have been passed by user.

Currently there is no support for vectorization of seed ages nor of time slices.

Parameters:

  • matrix_state_dep_params (DiscreteStateDependentParameter) – 2D list, with first dimension being time slices, the second being SSE parameters. This is just a raw container of SSE parameters, and is not used for computations.

  • state_dep_params_dict (dict) – Dictionary with state indices (int) as keys, and a list of SSE parameters as values. This is the container that is used by MacroEvolEventHandler when calculating rates.

  • seed_age (float, optional) – Age of origin or root used to anchor time slice age ends so as to convert them into time slice time ends.

  • slice_age_ends (float) – List of time slice age ends.

  • slice_t_ends (float, optional) – List of time slice time ends. It is automatically filled upon initialization.

  • n_slices_to_ignore (int) – How many time slices are in their totality older than the whole tree (the user may have specified more time slice age ends than necessary given an origin or root time for the tree). Defaults to 0.

  • param_type (DiscreteStateDependentParameterType) – Attribute holding what type of SSE parameter this is (rate or probability).

  • epsilon (float) – Threshold for considering a difference equal to zero.

epsilon: float
matrix_state_dep_params: List[List[DiscreteStateDependentParameter]]
n_slices_to_ignore: int
param_type: DiscreteStateDependentParameterType
seed_age: float | None
slice_age_ends: List[float]
slice_t_ends: List[float] | None
state_dep_params_at_time(a_time: float, params_matrix: List[List[DiscreteStateDependentParameter]] | None = None) → List[DiscreteStateDependentParameter]

Return list of SSE parameters given a specific time.

This method finds the time slice a specific time belongs to, and retrieves the list of SSE parameters pertaining to that time slice. This list is retrieved from a user-specified matrix, or from the matrix member of the enclosing class, self.matrix_state_dep_params.

Parameters:

  • a_time (float) – A time at which we want to grab SSE parameters.

  • param_matrix (DiscreteStateDependentParameter) – A 2D list where the first dimension are time slices, and the second dimension are SSE parameters.

Returns:

a list of SSE parameters

from the appropriate time slice.

Return type:

(DiscreteStateDependentParameter)

state_dep_params_dict: Dict[int, List[List[DiscreteStateDependentParameter]]]
class phylojunction.calculation.discrete_sse.DiscreteStateDependentParameterType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

PROBABILITY = 2
RATE = 1
UNDEFINED = 0
class phylojunction.calculation.discrete_sse.DiscreteStateDependentProbability(val: int | float | str | List[int | float | str], name: str = '', state: int = 0, epoch_idx: int = 1)

Bases: DiscreteStateDependentParameter

State-dependent probability main class.

This class is derived from DiscreteStateDependentParameter. It holds a value for the probability, the name of the variable holding it, the state associated to the probability, and the time slice (epoch) that probability applies to.

Supports vectorization of values only.

Parameters:

str_representation (str) – The string that is put together upon initialization and printed when __str__() is called.

state_representation: str
class phylojunction.calculation.discrete_sse.DiscreteStateDependentProbabilityHandler(state_dep_prob_manager: DiscreteStateDependentParameterManager)

Bases: object

Class for handling state-dependent taxon sampling.

This is the sister class to MacroevolEventHandler. Note that time slices do not have to be the same as those for SSE rates.

Parameters:

  • state_dep_prob_manager (DiscreteStateDependentParameterManager) – Object that checks, organizes and stores SSE probabilities.

  • state_count (int) – Number of states characterizing the SSE process.

  • n_time_slices (int) – Number of time slices.

  • slice_age_ends (float) – List of time slice age ends.

  • slice_t_ends (float, optional) – List of time slice time ends.

  • str_representation (str) – The string that is put together upon initialization and printed when __str__() is called.

n_time_slices: int
randomly_decide_taxon_sampling_at_time_at_state(a_time, state_idx, sample_idx) → bool

Raises:

seed_age: float | None
slice_age_ends: List[float]
slice_t_ends: List[float] | None
state_count: int
state_dep_prob_manager: DiscreteStateDependentParameterManager
str_representation: str
class phylojunction.calculation.discrete_sse.DiscreteStateDependentRate(val: int | float | str | List[int | float | str], event: MacroevolEvent, name: str = '', states: List[int] = [], epoch_idx: int = 1)

Bases: DiscreteStateDependentParameter

State-dependent rate main class.

This class is derived from DiscreteStateDependentParameter. It holds a value for the rate, the type of rate, the name of variable holding it, the state associated to the rate, and the time slice (epoch) that rate applies to.

Supports vectorization of values only.

Parameters:

  • state_tuple (int) – Tuple storing all states associated to SSE parameter.

  • departing_state (int) – State event is departing from.

  • arriving_state (int) – State event is arriving at.

  • event (MacroevolEvent) – The type of macroevolutionary event (e.g., within-region speciation, extinction, etc.) this SSE parameter is associated to.

  • str_representation (str) – The string that is put together upon initialization and printed when __str__() is called.

arriving_state: int
departing_state: int
event: MacroevolEvent
state_tuple: Tuple[int]
str_representation: str
class phylojunction.calculation.discrete_sse.MacroevolEvent(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

ANAGENETIC_TRANSITION = 4
ANCESTOR_SAMPLING = 5
ASYM_SPECIATION = 2
BW_SPECIATION = 1
EXTINCTION = 3
W_SPECIATION = 0
class phylojunction.calculation.discrete_sse.MacroevolEventHandler(sse_rate_manager: DiscreteStateDependentParameterManager)

Bases: object

Class for handling state-dependent rates.

Some of the methods in this class are vector-aware (through parameter value_idx), because instances of this class will be directly called by dn_sse.simulate() method, which in turn will try to access parameter values stored in a #-simulations-sized list.

Parameters:

  • sse_rate_manager (DiscreteStateDependentParameterManager) – Object that checks, organizes and stores SSE rates.

  • state_count (int) – Number of states characterizing the SSE process.

  • n_time_slices (int) – Number of time slices.

  • slice_age_ends (float) – List of time slice age ends.

  • slice_t_ends (float, optional) – List of time slice time ends.

  • seed_age (float, optional) – Age of seed (origin or root), stored in ‘state_dep_rate_manager’.

  • str_representation (str) – The string that is put together upon initialization and printed when __str__() is called.

n_time_slices: int
sample_event_sse_rate_param(denominator: float, a_time: float, state_indices: List[int], value_idx: int = 0, a_seed: float | None = None, debug: bool | None = False)

Return one-sized list with a random SSE rate.

This method accesses the sse_rate_manager member to grab all SSE rates departing from one or more focal states. It then weighs each SSE rate by their value divided by the sum of the values of all SSE rates departing from the focal state. Given these weighed SSE rates, it randomly picks one and returns.

This method is called by DnSSE (dn_discrete_sse.py) when randomly choosing an event, after an event time and a node have already been chosen.

Parameters:

  • denominator (float) – Normalization term for computing weights of different events.

  • a_time (float) – When the event will take place.

  • state_indices (int) – Event is conditioned on departing from this state(s).

  • value_idx (int, optional) – Index specifying which parameter value (within a vector of #-of-simulations-size) we care about. Defaults to 0 (first element).

  • a_seed (int, optional) – Random seed for simulation (not working at the moment). Defaults to None.

  • debug (bool, optional) – Flag for printing debugging messages. Defaults to False.

Returns:

List with a single SSE rate.

Return type:

DiscreteStateDependentRate

seed_age: float | None
slice_age_ends: List[float]
slice_t_ends: List[float] | None
sse_rate_manager: DiscreteStateDependentParameterManager
state_count: int
str_representation: str
total_rate(a_time: float, state_representation_dict: Dict[int, Set[str]], value_idx: int = 0, departing_state: int | None = None, debug: bool | None = False) → float | Tuple[float, List[float]]

Get total rate given possible events at time slice and tree.

This method is called by DnSSE (dn_discrete_sse.py) when it is time to draw the time to the next event, which is exponentially distributed with rate equal to the total sum of rates being computed by this method (the first return in the tuple).

For the first return in the tuple, this method gets all event rates for a given time slice, and adds them up. Different rates are weighed depending on their departing states, with the weight being the number of lineages representing that state.

For the second return in the tuple, this method adds up rates by their departing states, but there is no weighing. The grouped rates are put into a list, at index = state index.

The ‘departing_state’ argument remains as legacy; this method never actually gets called with departing_state. This also means that a pure float return also never happens (only the tuple return).

Parameters:

  • a_time (float) – Forward time (not age!) we want to recover rates with.

  • state_representation_dict (dict) – Dictionary with (int) states as keys and list of (str) node labels at that state.

  • value_idx (int, optional) – Index specifying which parameter value (within a vector of #-of-simulations-size) we care about. Defaults to 0 (first element).

  • departing_state (int, optional) – State we can condition rates on. Defaults to None.

  • debug (bool, optional) – Flag for printing debugging messages. Defaults to False.

Returns:

If no departing_state is provided, returns the global

rate. Otherwise, returns a state-conditioned total rate and a list with each state total rate.

Return type:

(float)

class phylojunction.calculation.discrete_sse.SSEStash(macroevol_event_handler: MacroevolEventHandler, state_dep_prob_handler: DiscreteStateDependentProbabilityHandler | None = None)

Bases: object

Class for stashing state-dependent rate and probability handlers.

Parameters:
get_meh() → MacroevolEventHandler
get_prob_handler() → DiscreteStateDependentProbabilityHandler
meh: MacroevolEventHandler
prob_handler: DiscreteStateDependentProbabilityHandler
str_representation: str
class phylojunction.calculation.discrete_sse.StateIntoPatternConverter(n_characters: int, n_states_per_char: int)

Bases: object

Stash and machinery for checking and converting character compound-states into bit patterns, and vice-versa.

For example, if we are thinking about regions as characters, then compound-state means different ranges (e.g., “A”, “AB”), while ‘state’ is the number of different values a single character can take. In the case of 1-character-1-region, then the number of states is 2, because a species is either present or not in a region.

Parameters:

  • n_char (int) – Number of characters.

  • n_states_per_char (int) – Number of states per character.

  • n_states (int) – Total number of states.

  • str (set2int_dict (dict of) – str): Dictionary for converting a state coded as an integer into a bit set.

  • str – str): Dictionary for converting a state coded as a bit set into an integer.

int2set_dict: Dict[str, str]
n_char: int
n_states: int
n_states_per_char: int
set2int_dict: Dict[str, str]

phylojunction.calculation.math_utils module

class phylojunction.calculation.math_utils.BaseEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

class phylojunction.calculation.math_utils.MetaEnum(cls, bases, classdict, *, boundary=None, _simple=False, **kwds)

Bases: EnumType

class phylojunction.calculation.math_utils.ParametricDistribution(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, BaseEnum

EXPONENTIAL = 'expn'
GAMMA = 'gamma'
LOGNORMAL = 'lnormal'
NORMAL = 'normal'
UNIFORM = 'uniform'
phylojunction.calculation.math_utils.exp_extant_count_bd(birth_rate: float, death_rate: float, tree_age: float, n_starting_lineages: int | None = 1) → float

Return expected count of extant taxa in a birth-death tree

Parameters:

  • birth_rate (float) – Birth-rate (lambda) of birth-death process.

  • death_rate (float) – Death-rate (mu) of birth-death process.

  • tree_age (float) – Age of birth-death tree (starting from origin).

  • n_starting_lineages (int) – Number of starting lineages. Defaults to 1.

Returns:

Expected count of extant taxa.

Return type:

int

phylojunction.calculation.math_utils.exp_root_height_yule_ntaxa(birth_rate: float, n_taxa: int) → float

Return expected root height of Yule tree simulated up to a specified number of tips

Parameters:

  • birth_rate (float) – Birth-rate (lambda) of Yule process.

  • n_taxa (int) – Tree is simulated until this number of tips.

Returns:

Expected root height

Return type:

float

Module contents