Rewards

Rewards assign weights to states in the state space. They are used behind the scenes to calculate different coalescent tree statistics but can also be passed directly to moment() to calculate more complex statistics.

class Reward

Bases: ABC

Base class for reward generation.

prod(*rewards: Reward)

Product of this reward with other rewards.

Parameters:

rewards (Reward) – Rewards to take the product with.

Return type:

ProductReward

Returns:

Product of the rewards.

sum(*rewards: Reward)

Sum of this reward with other rewards.

Parameters:

rewards (Reward) – Rewards to take the sum with.

Return type:

SumReward

Returns:

Sum of the rewards.

supports(state_space: Type[StateSpace])

Check if the reward supports the given state space.

Parameters:

state_space (Type[StateSpace]) – state space

Return type:

bool

Returns:

True if the reward supports the state space, False otherwise

static support(state_space: Type[StateSpace], rewards: Iterable[Reward])

Check if the rewards support the given state space.

Parameters:

• state_space (Type[StateSpace]) – state space

• rewards (Iterable[Reward]) – rewards

Return type:

bool

Returns:

True if the rewards support the state space, False otherwise

class LineageCountingReward

Bases: Reward, ABC

Base class for rewards that count lineages. Such rewards are compatible with LineageCountingStateSpace.

class BlockCountingReward

Bases: Reward, ABC

Base class for rewards that count blocks. Such rewards are compatible with BlockCountingStateSpace.

class TreeHeightReward

Bases: LineageCountingReward, BlockCountingReward

Reward for tree height. Note that when using multiple loci, this will provide the height of the locus with the highest tree.

class TotalTreeHeightReward

Bases: LineageCountingReward, BlockCountingReward

Reward based on tree height. When using multiple loci, this will provide the sum of the tree heights over all loci, regardless of whether they are linked or not.

class TotalBranchLengthReward

Bases: LineageCountingReward, BlockCountingReward

Reward for total branch length. When using multiple loci, this will provide the sum of the total branch lengths over all loci, regardless of whether they are linked or not. Note that due to inherent limitation to rewards, we cannot determine the total branch length of the tree with the largest total branch length as done in TreeHeightReward.

class UnfoldedSFSReward(index: int)

Bases: SFSReward, BlockCountingReward

Reward for unfolded site frequency spectrum (SFS).

class FoldedSFSReward(index: int)

Bases: SFSReward, BlockCountingReward

Reward for folded site frequency spectrum (SFS).

class StateReward(state: int)

Bases: Reward

Reward for a specific state in the state space. This is useful for debugging or testing purposes.

__init__(state: int)

Initialize the reward.

Parameters:

state (int) – The state index to reward.

class LineageReward(n: int)

Bases: LineageCountingReward

Reward for a specific number of lineages present in across all demes and loci. This reward can be used to, for example, track the individual coalescent times.

__init__(n: int)

Initialize the reward.

Parameters:

n (int) – The number of lineages to reward. Must be at least 2.

class DemeReward(pop: str)

Bases: LineageCountingReward, BlockCountingReward

Reward fraction of lineages in a specific deme. Taking the product of this reward with another reward will result in a reward that only considers the specified deme. Use SumReward to marginalize over several demes.

__init__(pop: str)

Initialize the reward.

Parameters:

pop (str) – The population id to use.

class LocusReward(locus: int)

Bases: LineageCountingReward

Reward fraction of lineages in a specific locus. Taking the product of this reward with another reward will result in a reward that only considers the specified locus.

__init__(locus: int)

Initialize the reward.

Parameters:

locus (int) – The locus index to use.

class UnitReward

Bases: LineageCountingReward, BlockCountingReward

Reward all states with 1 (including absorbing states).

class BlockCountingUnitReward

Bases: BlockCountingReward

Reward all states with 1 (including absorbing states), and only support block-counting state spaces. This reward can be used to force usage of the block-counting state space.

class TotalBranchLengthLocusReward(locus: int)

Bases: LocusReward, LineageCountingReward

Reward for total branch length per locus. This is needed as the taking the product of TotalBranchLengthReward and LocusReward will not work as expected (see CombinedReward).

class ProductReward(rewards: List[Reward])

Bases: CompositeReward

The product of multiple rewards.

class SumReward(rewards: List[Reward])

Bases: CompositeReward

The sum of multiple rewards.

class CombinedReward(rewards: List[Reward])

Bases: ProductReward

Class extending ProductReward to allow for more intuitive combination of rewards.

combinations: Dict[Tuple[Reward, Reward], Callable[[Reward, Reward], Reward]] = {(<class 'phasegen.rewards.TotalBranchLengthReward'>, <class 'phasegen.rewards.LocusReward'>): <function CombinedReward.<lambda>>}

Dictionary of reward combinations

__init__(rewards: List[Reward])

Initialize the combined reward.

Parameters:

rewards (List[Reward]) – Rewards to combine

class CustomReward(func: ~typing.Callable[[~phasegen.state_space.StateSpace], ~numpy.ndarray], supports: ~typing.Callable[[~typing.Type[~phasegen.state_space.StateSpace]], bool] = <function CustomReward.<lambda>>)

Bases: Reward

Custom reward based on a user-defined function.

__init__(func: ~typing.Callable[[~phasegen.state_space.StateSpace], ~numpy.ndarray], supports: ~typing.Callable[[~typing.Type[~phasegen.state_space.StateSpace]], bool] = <function CustomReward.<lambda>>)

Initialize the custom reward.

Parameters:

• func (Callable[[StateSpace], ndarray]) – The function to use to calculate the reward vector.

• supports (Callable[[Type[StateSpace]], bool]) – The function to use to check if the reward supports the state space.

func: Callable[[StateSpace], ndarray]

The function to calculate the reward vector

supports(state_space: Type[StateSpace])

Check if the reward supports the given state space.

Parameters:

state_space (Type[StateSpace]) – state space

Return type:

bool

Returns:

True if the reward supports the state space, False otherwise