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 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#