State Space

State Space#

State space classes and utilities. The two main state space classes are LineageCountingStateSpace and BlockCountingStateSpace.

class StateSpace(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Bases: ABC

State space.

__init__(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Create a rate matrix.

Parameters:

lineage_config (LineageConfig) – Population configuration.
locus_config (LocusConfig) – Locus configuration. One locus is used by default.
model (CoalescentModel) – Coalescent model. By default, the standard coalescent is used.
epoch (Epoch) – The epoch.

model: CoalescentModel#: Coalescent model

lineage_config: LineageConfig#: Population configuration

locus_config: LocusConfig#: Locus configuration

epoch: Epoch#: Epoch

property states: List[State]#: The states.

property lineages: ndarray#: The lineage configurations. Each configuration describes the lineages per block, deme and locus, i.e., [[[a_ijk]]] for block i, deme j and locus k.

property linked: ndarray#: The linked lineages per block, deme and locus. :return:

property unlinked: ndarray#: Unlinked lineages.

get_transitions()[source]#

Get all possible transitions from the given state.

Return type:: Tuple[Dict[Tuple[State, State], Tuple[float, str]], List[State]]
Returns:: All possible transitions from the given state.

property e: ndarray#: Vector with ones of size k.

property S: ndarray#: Intensity matrix.

property alpha: ndarray#: Initial state vector.

property k: int#: Number of states.

property transition: Transition#: Transition.

update_epoch(epoch: Epoch)[source]#

Update the epoch.

Parameters:: epoch (Epoch) – Epoch.
Returns:: State space.

drop_S()[source]#: Drop the current rate matrix.

drop_cache()[source]#: Drop the rate matrix cache and current rate matrix.

get_sparsity()[source]#

Get the sparsity of the rate matrix.

Return type:: float
Returns:: The sparsity.

plot_rates(file: str, view: bool = True, cleanup: bool = False, dpi: int = 400, ratio: float = 0.6, background_color: str = 'white', extension: str = 'png', format_state: Callable[[array], str] = None, format_transition: Callable[[Transition], str] = None)[source]#

Plot the rate matrix using graphviz. Note that graphviz must be installed which is an external dependency.

Parameters:

file (str) – File to save plot to.
view (bool) – Whether to view the plot.
cleanup (bool) – Whether to remove the source file.
dpi (int) – Dots per inch.
ratio (float) – Aspect ratio.
background_color (str) – Background color.
extension (str) – File format.
format_state (Callable[[array], str]) – Function to format state with state array as argument.
format_transition (Callable[[Transition], str]) – Function to format transition with transition as argument.

class LineageCountingStateSpace(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Bases: StateSpace

Default rate matrix where there is one state per number of lineages for each deme and locus.

property S: ndarray#: Intensity matrix.

__init__(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)#

Create a rate matrix.

Parameters:

lineage_config (LineageConfig) – Population configuration.
locus_config (LocusConfig) – Locus configuration. One locus is used by default.
model (CoalescentModel) – Coalescent model. By default, the standard coalescent is used.
epoch (Epoch) – The epoch.

property alpha: ndarray#: Initial state vector.

drop_S()#: Drop the current rate matrix.

drop_cache()#: Drop the rate matrix cache and current rate matrix.

property e: ndarray#: Vector with ones of size k.

get_sparsity()#

Get the sparsity of the rate matrix.

Return type:: float
Returns:: The sparsity.

get_transitions()#

Get all possible transitions from the given state.

Return type:: Tuple[Dict[Tuple[State, State], Tuple[float, str]], List[State]]
Returns:: All possible transitions from the given state.

property k: int#: Number of states.

property lineages: ndarray#: The lineage configurations. Each configuration describes the lineages per block, deme and locus, i.e., [[[a_ijk]]] for block i, deme j and locus k.

property linked: ndarray#: The linked lineages per block, deme and locus. :return:

Plot the rate matrix using graphviz. Note that graphviz must be installed which is an external dependency.

Parameters:

file (str) – File to save plot to.
view (bool) – Whether to view the plot.
cleanup (bool) – Whether to remove the source file.
dpi (int) – Dots per inch.
ratio (float) – Aspect ratio.
background_color (str) – Background color.
extension (str) – File format.
format_state (Callable[[array], str]) – Function to format state with state array as argument.
format_transition (Callable[[Transition], str]) – Function to format transition with transition as argument.

property states: List[State]#: The states.

property transition: Transition#: Transition.

property unlinked: ndarray#: Unlinked lineages.

update_epoch(epoch: Epoch)#

Update the epoch.

Parameters:: epoch (Epoch) – Epoch.
Returns:: State space.

model: CoalescentModel#: Coalescent model

lineage_config: LineageConfig#: Population configuration

locus_config: LocusConfig#: Locus configuration

epoch: Epoch#: Epoch

time: float | None#

class BlockCountingStateSpace(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Bases: StateSpace

Rate matrix for block-counting state space where there is one state per sample configuration:

A block-counting state is a vector of length n where each element represents the number of lineages subtending i lineages in the coalescent tree.

\[(a_1,...,a_n) \in \mathbb{Z}_+^n : \sum_{i=1}^{n} i a_i = n.\]

per deme and per locus. This state space can distinguish between different tree topologies and is thus used when computing statistics based on the SFS.

__init__(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Create a rate matrix.

Parameters:

lineage_config (LineageConfig) – Population configuration.
locus_config (LocusConfig) – Locus configuration. One locus is used by default.
model (CoalescentModel) – Coalescent model. By default, the standard coalescent is used.
epoch (Epoch) – The epoch

property S: ndarray#: Intensity matrix.

property alpha: ndarray#: Initial state vector.

drop_S()#: Drop the current rate matrix.

drop_cache()#: Drop the rate matrix cache and current rate matrix.

property e: ndarray#: Vector with ones of size k.

get_sparsity()#

Get the sparsity of the rate matrix.

Return type:: float
Returns:: The sparsity.

get_transitions()#

Get all possible transitions from the given state.

Return type:: Tuple[Dict[Tuple[State, State], Tuple[float, str]], List[State]]
Returns:: All possible transitions from the given state.

property k: int#: Number of states.

property lineages: ndarray#: The lineage configurations. Each configuration describes the lineages per block, deme and locus, i.e., [[[a_ijk]]] for block i, deme j and locus k.

property linked: ndarray#: The linked lineages per block, deme and locus. :return:

Plot the rate matrix using graphviz. Note that graphviz must be installed which is an external dependency.

Parameters:

file (str) – File to save plot to.
view (bool) – Whether to view the plot.
cleanup (bool) – Whether to remove the source file.
dpi (int) – Dots per inch.
ratio (float) – Aspect ratio.
background_color (str) – Background color.
extension (str) – File format.
format_state (Callable[[array], str]) – Function to format state with state array as argument.
format_transition (Callable[[Transition], str]) – Function to format transition with transition as argument.

property states: List[State]#: The states.

property transition: Transition#: Transition.

property unlinked: ndarray#: Unlinked lineages.

update_epoch(epoch: Epoch)#

Update the epoch.

Parameters:: epoch (Epoch) – Epoch.
Returns:: State space.

model: CoalescentModel#: Coalescent model

lineage_config: LineageConfig#: Population configuration

locus_config: LocusConfig#: Locus configuration

epoch: Epoch#: Epoch

time: float | None#

class JointBlockCountingStateSpace(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Bases: StateSpace

Rate matrix for the joint (multi-population) site-frequency spectrum.

This is a generalization of BlockCountingStateSpace. In the block-counting state space a block is a single size class i (the number of sampled lineages a lineage subtends), which discards the information of which population those descendants came from. The joint SFS bins mutations by their allele frequency in each population simultaneously, so each block must instead be the descendant vector

\[v = (v_0, \dots, v_{P-1}), \quad 0 \le v_p \le n_p, \quad 1 \le \sum_p v_p \le n,\]

i.e. the number of descendants a lineage subtends from each population p (its “deme of origin” composition). A state then counts, per locus and per current deme of residence, how many lineages carry each descendant vector.

Note

Splitting each size class by deme of origin both enlarges the block axis (n_blocks = prod(n_p + 1) - 1) and grows the number of reachable states combinatorially, much faster than the single-population block-counting space. This state space is therefore only practical for small per-population sample sizes. Only one locus is supported.

__init__(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Create a rate matrix.

Parameters:

lineage_config (LineageConfig) – Population configuration.
locus_config (LocusConfig) – Locus configuration. One locus is used by default.
model (CoalescentModel) – Coalescent model. By default, the standard coalescent is used.
epoch (Epoch) – The epoch.

property block_configs: List[Tuple[int, ...]]#: Ordered list of all descendant vectors (block types). A descendant vector (v_0,...,v_{P-1}) has 0 <= v_p <= n_p and at least one non-zero entry.

property block_index: Dict[Tuple[int, ...], int]#: Mapping from descendant vector to its block index.

property block_vectors: ndarray#: Descendant vectors as an integer array of shape (n_blocks, n_pops).

property n_blocks: int#: Number of block types (descendant vectors).

property alpha: ndarray#: Initial state vector. There is a single, origin-aware initial state (see _get_initial()), so this is its indicator vector.

property S: ndarray#: Intensity matrix.

drop_S()#: Drop the current rate matrix.

drop_cache()#: Drop the rate matrix cache and current rate matrix.

property e: ndarray#: Vector with ones of size k.

get_sparsity()#

Get the sparsity of the rate matrix.

Return type:: float
Returns:: The sparsity.

get_transitions()#

Get all possible transitions from the given state.

Return type:: Tuple[Dict[Tuple[State, State], Tuple[float, str]], List[State]]
Returns:: All possible transitions from the given state.

property k: int#: Number of states.

property lineages: ndarray#: The lineage configurations. Each configuration describes the lineages per block, deme and locus, i.e., [[[a_ijk]]] for block i, deme j and locus k.

property linked: ndarray#: The linked lineages per block, deme and locus. :return:

Plot the rate matrix using graphviz. Note that graphviz must be installed which is an external dependency.

Parameters:

file (str) – File to save plot to.
view (bool) – Whether to view the plot.
cleanup (bool) – Whether to remove the source file.
dpi (int) – Dots per inch.
ratio (float) – Aspect ratio.
background_color (str) – Background color.
extension (str) – File format.
format_state (Callable[[array], str]) – Function to format state with state array as argument.
format_transition (Callable[[Transition], str]) – Function to format transition with transition as argument.

property states: List[State]#: The states.

property transition: Transition#: Transition.

property unlinked: ndarray#: Unlinked lineages.

update_epoch(epoch: Epoch)#

Update the epoch.

Parameters:: epoch (Epoch) – Epoch.
Returns:: State space.

model: CoalescentModel#: Coalescent model

lineage_config: LineageConfig#: Population configuration

locus_config: LocusConfig#: Locus configuration

epoch: Epoch#: Epoch

time: float | None#

class TwoLocusBlockCountingStateSpace(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Bases: JointBlockCountingStateSpace

Block-counting state space for two loci separated by recombination, used to compute the two-locus SFS.

Each physical ancestral lineage is described by a vector (a_0, a_1) giving the number of sampled lineages it subtends at locus 0 and locus 1 (a_l = 0 meaning it is not ancestral at locus l). This is the same representation as the joint (multi-population) state space, with locus playing the role of population, so coalescence is again vector addition (and reuses the model-agnostic merger rates, supporting Beta/Dirac too). The new ingredient is recombination: a linked lineage (a_0, a_1) with a_0 > 0 and a_1 > 0 splits into (a_0, 0) and (0, a_1) at rate r per linked lineage. The process is absorbed once both loci have reached their MRCA.

A single population is currently supported (no migration), so the state shape collapses to (1, 1, n_blocks); linkage is encoded in the block vector itself, so the linked array is unused.

Note

n_blocks = (n + 1)^2 - 1 and the number of reachable states grows quickly, so this is only practical for small sample sizes.

__init__(lineage_config: LineageConfig, locus_config: LocusConfig = None, model: CoalescentModel = None, epoch: Epoch = None)[source]#

Create the two-locus block-counting state space.

Parameters:

lineage_config (LineageConfig) – Population configuration (a single population is currently supported).
locus_config (LocusConfig) – Locus configuration; must specify exactly two loci.
model (CoalescentModel) – Coalescent model. By default, the standard coalescent is used.
epoch (Epoch) – The epoch.

property block_configs: List[Tuple[int, ...]]#: Ordered list of all two-locus descendant vectors (a_0, a_1) with 0 <= a_l <= n and at least one non-zero entry.

property S: ndarray#: Intensity matrix.

property alpha: ndarray#: Initial state vector. There is a single, origin-aware initial state (see _get_initial()), so this is its indicator vector.

property block_index: Dict[Tuple[int, ...], int]#: Mapping from descendant vector to its block index.

property block_vectors: ndarray#: Descendant vectors as an integer array of shape (n_blocks, n_pops).

drop_S()#: Drop the current rate matrix.

drop_cache()#: Drop the rate matrix cache and current rate matrix.

property e: ndarray#: Vector with ones of size k.

get_sparsity()#

Get the sparsity of the rate matrix.

Return type:: float
Returns:: The sparsity.

get_transitions()#

Get all possible transitions from the given state.

Return type:: Tuple[Dict[Tuple[State, State], Tuple[float, str]], List[State]]
Returns:: All possible transitions from the given state.

property k: int#: Number of states.

property lineages: ndarray#: The lineage configurations. Each configuration describes the lineages per block, deme and locus, i.e., [[[a_ijk]]] for block i, deme j and locus k.

property linked: ndarray#: The linked lineages per block, deme and locus. :return:

property n_blocks: int#: Number of block types (descendant vectors).

Plot the rate matrix using graphviz. Note that graphviz must be installed which is an external dependency.

Parameters:

file (str) – File to save plot to.
view (bool) – Whether to view the plot.
cleanup (bool) – Whether to remove the source file.
dpi (int) – Dots per inch.
ratio (float) – Aspect ratio.
background_color (str) – Background color.
extension (str) – File format.
format_state (Callable[[array], str]) – Function to format state with state array as argument.
format_transition (Callable[[Transition], str]) – Function to format transition with transition as argument.

property states: List[State]#: The states.

property transition: Transition#: Transition.

property unlinked: ndarray#: Unlinked lineages.

update_epoch(epoch: Epoch)#

Update the epoch.

Parameters:: epoch (Epoch) – Epoch.
Returns:: State space.

model: CoalescentModel#: Coalescent model

lineage_config: LineageConfig#: Population configuration

locus_config: LocusConfig#: Locus configuration

epoch: Epoch#: Epoch

time: float | None#

class Transition(state_space: StateSpace)[source]#

Bases: object

Class representing a transition between two states.

__init__(state_space: StateSpace)[source]#

Initialize a transition.

Parameters:: state_space (StateSpace) – State space.

state_space: StateSpace#: State space.

transit(source: State)[source]#

Get all possible target states from the given source state.

Parameters:: source (State) – Source state.
Return type:: Dict[State, Tuple[float, str]]
Returns:: All possible target states.

static add_target(targets: Dict[State, Tuple[float, str]], target: State, rate: float, kind: str)[source]#

Add a target state to the list of targets.

Parameters:

targets (Dict[State, Tuple[float, str]]) – Dictionary of target states.
target (State) – New target state.
rate (float) – Rate of the transition.
kind (str) – Kind of the transition.

coalesce(source: State)[source]#

Get all possible coalescent transitions from the given state.

Parameters:: source (State) – Source state.
Return type:: Dict[State, Tuple[float, str]]
Returns:: All possible coalescent transitions from the given state.

migrate(source: State)[source]#

Get all possible migration transitions from the given state.

Parameters:: source (State) – Source state.
Return type:: Dict[State, Tuple[float, str]]
Returns:: All possible migration transitions from the given state.

migrate_unlinked(source: State)[source]#

Get all possible unlinked migration transitions from the given state. Note that we also consider migration to unlinked when there is only one locus.

Parameters:: source (State) – Source state.
Return type:: Dict[State, Tuple[float, str]]
Returns:: All possible migration transitions from the given state.

migrate_linked(source: State)[source]#

Get all possible linked migration transitions from the given state.

Parameters:: source (State) – Source state.
Return type:: Dict[State, Tuple[float, str]]
Returns:: All possible migration transitions from the given state.

recombine(state: State)[source]#

Get all possible recombination transitions from the given state.

Parameters:: state (State) – State.
Return type:: Dict[State, Tuple[float, str]]
Returns:: All possible recombination transitions from the given state.

class State(data: (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>))[source]#

Bases: object

State utility class.

LINKAGE = 0#: Axis for linkage.

LOCUS = 1#: Axis for loci.

DEME = 2#: Axis for demes.

BLOCK = 3#: Axis for lineage blocks.

__init__(data: (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>))[source]#

Initialize a state.

Parameters:: data ((ndarray, ndarray)) – State data.

data: Tuple[ndarray, ndarray]#: State data

copy()[source]#

Copy the state.

Return type:: State
Returns:: Copy of the state.

is_absorbing()[source]#

Whether a state is absorbing.

Return type:: bool
Returns:: Whether the state is absorbing.

property n_demes: int#

Get the number of demes.

Returns:: The number of demes.

property n_loci: int#

Get the number of loci.

Returns:: The number of loci.

property n_blocks: int#

Get the number of lineage blocks.

Returns:: The number of lineage blocks.

property lineages: ndarray#

Get the number of lineages.

Returns:: The number of lineages.

property linked: ndarray#

Get the number of linked lineages.

Returns:: The number of linked lineages.

property unlinked: ndarray#

Get the number of unlinked lineages.

Returns:: The number of unlinked lineages.

State Space

Contents

State Space#