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:
- 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:
- 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:
meh (MacroevolEventHandler) – Instance of state-dependent rate handler class.
prob_handler (DiscreteStateDependentProbabilityHandler) – Instance of state-dependent probability handler class.
- get_meh() MacroevolEventHandler
- get_prob_handler() DiscreteStateDependentProbabilityHandler
- 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