Demography

Demographic events and demography class.

class Demography(events: List[DemographicEvent] = None, pop_sizes: Dict[str, Dict[float, float]] | Dict[str, float] | float = None, migration_rates: Dict[Tuple[str, str], Dict[float, float]] | Dict[Tuple[str, str], float] = None, warn_n_epochs: int = 20)

Bases: object

Class storing full demographic information.

pop_names: List[str]

Population names.

n_pops: int

Number of populations.

__init__(events: List[DemographicEvent] = None, pop_sizes: Dict[str, Dict[float, float]] | Dict[str, float] | float = None, migration_rates: Dict[Tuple[str, str], Dict[float, float]] | Dict[Tuple[str, str], float] = None, warn_n_epochs: int = 20)

Initialize the demography.

Parameters:

• events (List[DemographicEvent]) – List of demographic events.

• pop_sizes (Union[Dict[str, Dict[float, float]], Dict[str, float], float]) – Population sizes. Either a dictionary of the form {pop_i: {time1: size1, time2: size2}}, indexed by population name and time at which the population size changes, or a dictionary of the form {pop_i: size} if the population size is constant, or a single float if there is only one population and the population size is constant.

• migration_rates (Union[Dict[Tuple[str, str], Dict[float, float]], Dict[Tuple[str, str], float]]) – Migration rates. A dictionary of the form {(pop_i, pop_j): {time1: rate1, time2: rate2}} of migration from population pop_i to population pop_j backwards in time from time time1 etc., or alternatively a dictionary of the form {(pop_i, pop_j): rate} if the migration rate is constant over time.

• warn_n_epochs (int) – Threshold for the number of epochs considered after which a warning is issued.

warn_n_epochs: int

Threshold for the number of epochs considered after which a warning is issued.

events: List[DemographicEvent]

Array of demographic events.

to_msprime(max_epochs: int = 1000)

Convert to an Msprime demography object.

Parameters:

max_epochs (int) – Maximum number of epochs to use. Note that the number of epochs may be infinite.

Return type:

msprime.Demography

Returns:

msprime demography object.

Raises:

ImportError – If Msprime is not installed.

property epochs: Iterator[Epoch]

Get a generator for the epochs.

has_n_epochs(n: int)

Check whether the demography has at least n epochs.

Parameters:

n (int) – Number of epochs.

Return type:

bool

Returns:

Whether the demography has at least n epochs.

get_epochs(t: Iterable[float])

Get the epochs at the given times.

Parameters:

t (Iterable[float]) – Times.

Return type:

Sequence[Epoch]

Returns:

Array of epochs.

get_epoch(t: float = 0)

Get the epoch at the given time.

Parameters:

t (float) – Time.

Return type:

Epoch

Returns:

Epoch.

add_events(events: List[DemographicEvent])

Add demographic events.

Parameters:

events (List[DemographicEvent]) – List of demographic events.

add_event(event: DemographicEvent)

Add a demographic event.

Parameters:

event (DemographicEvent) – Demographic event.

plot_pop_sizes(t: ndarray = None, show: bool = True, file: str = None, title: str = 'Population size trajectory', ylabel: str = '$N_e$', ax: plt.Axes = None, kwargs: dict = None)

Plot the population size over time.

Parameters:

• t (ndarray) – Times at which to plot the population sizes. By default, we use 1000 time points between time 0 and 10.

• show (bool) – Whether to show the plot.

• file (str) – File to save the plot to.

• title (str) – Title of the plot.

• title – Title of the plot.

• ylabel (str) – Label of the y-axis.

• ax (plt.Axes) – Axes object to plot to.

• kwargs (dict) – Keyword arguments to pass to the plotting function.

Return type:

plt.Axes

Returns:

Axes object.

plot_migration(t: ndarray = None, show: bool = True, file: str = None, title: str = 'Migration rate trajectory', ylabel: str = '$m_{ij}$', ax: plt.Axes = None, kwargs: dict = None)

Plot the migration over time.

Parameters:

• t (ndarray) – Times at which to plot the migration rates. By default, we use 1000 time points between time 0 and 10.

• show (bool) – Whether to show the plot.

• file (str) – File to save the plot to.

• title (str) – Title of the plot.

• ylabel (str) – Label of the y-axis.

• ax (plt.Axes) – Axes object to plot to.

• kwargs (dict) – Keyword arguments to pass to the plotting function.

Return type:

plt.Axes

Returns:

Axes object.

plot(t: ndarray = None, show: bool = True, file: str = None, ylabel: str = '$N_e, m_{ij}$', ax: plt.Axes = None, title: str = 'Demography', kwargs: dict = None)

Plot the demographic scenario.

Parameters:

• t (ndarray) – Times at which to plot the population sizes and migration rates. By default, we use 1000 time points between time 0 and 10.

• show (bool) – Whether to show the plot.

• file (str) – File to save the plot to.

• ylabel (str) – Label of the y-axis.

• ax (plt.Axes) – Axes object to plot to.

• title (str) – Title of the plot.

• kwargs (dict) – Keyword arguments to pass to the plotting function.

Return type:

plt.Axes

Returns:

Axes object.

class Epoch(start_time: float = 0, end_time: float = inf, pop_sizes: Dict[str, float] = None, migration_rates: Dict[Tuple[str, str], float] = None)

Bases: object

Epoch of a demographic scenario with constant population sizes and migration rates.

__init__(start_time: float = 0, end_time: float = inf, pop_sizes: Dict[str, float] = None, migration_rates: Dict[Tuple[str, str], float] = None)

Initialize the epoch.

Parameters:

• start_time (float) – Start time of the epoch.

• end_time (float) – End time of the epoch.

• pop_sizes (Dict[str, float]) – Population sizes. By default, we have ``{‘pop_0’: 1}`.

• migration_rates (Dict[Tuple[str, str], float]) – Migration rates. By default, we have zero migration rates between all populations.

start_time: float

Start time of the epoch.

end_time: float

End time of the epoch.

pop_sizes: Dict[str, float]

Population sizes.

pop_names: List[str]

Population names.

n_pops: int

Number of populations.

migration_rates: Dict[Tuple[str, str], float]

Migration rates.

property tau: float

Time interval of the epoch.

to_string()

Alias for __str__().

Returns:

String representation.

class DemographicEvent

Bases: ABC

Base class for (discrete) demographic events.

start_time: float

Start time of the event.

pop_names: List[str]

Population names.

class DiscreteDemographicEvent

Bases: DemographicEvent, ABC

Base class for discrete demographic events.

times: ndarray

Time at which the events occur in ascending order.

start_time: float

Start time of the event.

pop_names: List[str]

Population names.

class DiscreteRateChanges(pop_sizes: Dict[str, Dict[float, float]] = None, migration_rates: Dict[Tuple[str, str], Dict[float, float]] = None)

Bases: DiscreteDemographicEvent

Demographic event for discrete changes in population sizes and migration rates.

__init__(pop_sizes: Dict[str, Dict[float, float]] = None, migration_rates: Dict[Tuple[str, str], Dict[float, float]] = None)

Initialize the population size change.

Parameters:

• pop_sizes (Dict[str, Dict[float, float]]) – Population sizes. Either a dictionary of the form {pop_i: {time1: size1, time2: size2}}, indexed by population name, or a list of dictionaries of the form {time1: size1, time2: size2} ordered by population index, or a single dictionary of the form {time1: size1, time2: size2} for a single population.

• migration_rates (Dict[Tuple[str, str], Dict[float, float]]) – Migration rates. A dictionary of the form {(pop_i, pop_j): {time1: rate1, time2: rate2}} of migration from population pop_i to population pop_j at time time1 etc.

pop_names: List[str]

Population names.

n_pops: int

Number of populations / demes.

times: ndarray

Times at which the population size changes occur.

pop_sizes: Dict[float, Dict[str, float]]

Population sizes.

migration_rates: Dict[float, Dict[Tuple[str, str], float]]

Migration rates at each time.

start_time: float

Start time of the event.

class PopSizeChanges(pop_sizes: Dict[str, Dict[float, float]])

Bases: DiscreteRateChanges

Demographic event for changes in population size.

__init__(pop_sizes: Dict[str, Dict[float, float]])

Initialize the population size change.

Parameters:

pop_sizes (Dict[str, Dict[float, float]]) – Population sizes. A dictionary of the form {pop_i: {time1: size1, time2: size2}}.

pop_names: List[str]

Population names.

n_pops: int

Number of populations / demes.

times: ndarray

Times at which the population size changes occur.

pop_sizes: Dict[float, Dict[str, float]]

Population sizes.

migration_rates: Dict[float, Dict[Tuple[str, str], float]]

Migration rates at each time.

start_time: float

Start time of the event.

class PopSizeChange(pop: str, time: float, size: float)

Bases: PopSizeChanges

Demographic event for a single change in population size.

__init__(pop: str, time: float, size: float)

Initialize the population size change.

Parameters:

• pop (str) – Population name.

• time (float) – Time at which the population size changes.

• size (float) – Population size.

pop_names: List[str]

Population names.

n_pops: int

Number of populations / demes.

times: ndarray

Times at which the population size changes occur.

pop_sizes: Dict[float, Dict[str, float]]

Population sizes.

migration_rates: Dict[float, Dict[Tuple[str, str], float]]

Migration rates at each time.

start_time: float

Start time of the event.

class MigrationRateChanges(rates: Dict[Tuple[str, str], Dict[float, float]])

Bases: DiscreteRateChanges

Demographic event for changes in migration rates.

__init__(rates: Dict[Tuple[str, str], Dict[float, float]])

Initialize the (backwards-time) migration rate change.

Parameters:

rates (Dict[Tuple[str, str], Dict[float, float]]) – Migration rates. A dictionary of the form {(pop_i, pop_j): {time1: rate1, time2: rate2}} of migration from population pop_i to population pop_j backwards in time with rate1 from time time1 etc.

pop_names: List[str]

Population names.

n_pops: int

Number of populations / demes.

times: ndarray

Times at which the population size changes occur.

pop_sizes: Dict[float, Dict[str, float]]

Population sizes.

migration_rates: Dict[float, Dict[Tuple[str, str], float]]

Migration rates at each time.

start_time: float

Start time of the event.

class MigrationRateChange(source: str, dest: str, time: float, rate: float)

Bases: MigrationRateChanges

Demographic event for a single change in migration rate.

__init__(source: str, dest: str, time: float, rate: float)

Initialize the (backwards-time) migration rate change.

Parameters:

• source (str) – Source population name.

• dest (str) – Destination population name.

• time (float) – Time at which the migration rate changes.

• rate (float) – Migration rate from the source to the destination population backwards in time.

pop_names: List[str]

Population names.

n_pops: int

Number of populations / demes.

times: ndarray

Times at which the population size changes occur.

pop_sizes: Dict[float, Dict[str, float]]

Population sizes.

migration_rates: Dict[float, Dict[Tuple[str, str], float]]

Migration rates at each time.

start_time: float

Start time of the event.

class SymmetricMigrationRateChanges(pops: Iterable[str], rate: Dict[float, float] | float)

Bases: MigrationRateChanges

Demographic event for changes in symmetric migration rates.

__init__(pops: Iterable[str], rate: Dict[float, float] | float)

Initialize the (backwards-time) migration rate change.

Parameters:

• pops (Iterable[str]) – Population names across which the migration rates change uniformly.

• rate (Union[Dict[float, float], float]) – Migration rates. A dictionary of the form {time1: rate1, time2: rate2} of migration from population pop_i to population pop_j at time time1 etc. or alternatively a single float if the migration rate is constant over time.

pop_names: List[str]

Population names.

n_pops: int

Number of populations / demes.

times: ndarray

Times at which the population size changes occur.

pop_sizes: Dict[float, Dict[str, float]]

Population sizes.

migration_rates: Dict[float, Dict[Tuple[str, str], float]]

Migration rates at each time.

start_time: float

Start time of the event.

class PopulationSplit(time: float, derived: str | List[str], ancestral: str, multiplier: float = 100)

Bases: DiscreteDemographicEvent

Demographic event for a population split (forward in time). This corresponds to population merger backwards in time. Since phasegen does not support deterministic lineage movement due to its inherent structure, we can model a population split by specifying a large unidirectional migration rate from the derived to the ancestral population.

__init__(time: float, derived: str | List[str], ancestral: str, multiplier: float = 100)

Initialize the population split.

Parameters:

• time (float) – Time of the split.

• derived (Union[str, List[str]]) – Derived populations from which all lineages move to the ancestral population.

• ancestral (str) – Ancestral population to which all lineages move.

• multiplier (float) – Migration rate multiplier. The migration rate from the derived to the ancestral population is set to the population size of the derived population times this multiplier. This value should be chosen large enough to ensure that the lineages move to the ancestral population fast enough.

start_time: float

Time of the split.

times: ndarray

Times at which the event occurs.

pop_names: List[str]

Population names.

derived: List[str]

Derived populations.

ancestral: str

Ancestral population.

multiplier: float

Migration rate multiplier.

class DiscretizedDemographicEvent

Bases: DemographicEvent, ABC

Base class for discretized demographic events.

start_time: float

Start time of the event.

pop_names: List[str]

Population names.

class DiscretizedRateChange(trajectory: Callable[[float], float], start_time: float, end_time: float = inf, pop: str | None = None, source: str | None = None, dest: str | None = None, step_size: float = 0.1)

Bases: DiscretizedDemographicEvent

Demographic event for discretized rate changes of a single population or migration rate.

__init__(trajectory: Callable[[float], float], start_time: float, end_time: float = inf, pop: str | None = None, source: str | None = None, dest: str | None = None, step_size: float = 0.1)

Initialize the population size change.

Parameters:

• trajectory (Callable[[float], float]) – Trajectory function taking the time as argument and returning the rate.

• start_time (float) – Start time of the event.

• end_time (float) – End time of the event.

• pop (str | None) – Population name or None if no population size changes.

• source (str | None) – Source population name or None if no migration rate changes.

• dest (str | None) – Destination population name or None if no migration rate changes.

• step_size (float) – Step size used for the discretization.

pop: str | None

Population name.

pop_names: List[str]

Population names.

start_time: float

Start time of the event.

end_time: float

End time of the event.

trajectory: Callable[[float], float]

Trajectory function.

step_size: float

Step size used for the discretization.

source_pop: str | None

Source population name.

dest_pop: str | None

Destination population name.

class DiscretizedRateChanges(trajectory: Dict[Any, Callable[[float], float]], start_time: Dict[Any, float] | float, end_time: Dict[Any, float] | float = inf, step_size: float = 0.1)

Bases: DiscretizedDemographicEvent

Demographic event for discretized rate changes of multiple populations or migration rates.

__init__(trajectory: Dict[Any, Callable[[float], float]], start_time: Dict[Any, float] | float, end_time: Dict[Any, float] | float = inf, step_size: float = 0.1)

Initialize the population size change.

Parameters:

• trajectory (Dict[Any, Callable[[float], float]]) – Trajectory functions taking the time as argument and returning the rate.

• start_time (Union[Dict[Any, float], float]) – Start times of the events. A single value or a dictionary mapping keys to values.

• end_time (Union[Dict[Any, float], float]) – End times of the events.

• step_size (float) – Step size used for the discretization.

events

Discretized rate change events.

pop_names: List[str]

Population names.

start_time: float

Start time of the event.

end_time: float

End time of the event.

class ExponentialRateChanges(initial_rate: Dict[Any, float], growth_rate: Dict[Any, float] | float, start_time: Dict[Any, float] | float, end_time: Dict[Any, float] | float = inf, step_size: float = 0.1)

Bases: DiscretizedRateChanges

Demographic event for exponential rate changes of multiple populations or migration rates.

pop_names: List[str]

Population names.

start_time: float

Start time of the event.

end_time: float

End time of the event.

events

Discretized rate change events.

__init__(initial_rate: Dict[Any, float], growth_rate: Dict[Any, float] | float, start_time: Dict[Any, float] | float, end_time: Dict[Any, float] | float = inf, step_size: float = 0.1)

Initialize the exponential growth.

Parameters:

• initial_rate (Dict[Any, float]) – Initial rates. A dictionary mapping keys to values. Keys are either population names or tuples of population names for population sizes and migration rates, respectively.

• growth_rate (Union[Dict[Any, float], float]) – Exponential growth rates. A single value or a dictionary mapping keys to values.

• start_time (Union[Dict[Any, float], float]) – Start times of the growth. A single value or a dictionary mapping keys to values.

• end_time (Union[Dict[Any, float], float]) – End times of the growth.

• step_size (float) – Step size used for the discretization.

class ExponentialPopSizeChanges(initial_size: Dict[str, float], growth_rate: Dict[str, float] | float, start_time: Dict[str, float] | float, end_time: Dict[str, float] | float = inf, step_size: float = 0.1)

Bases: ExponentialRateChanges

Demographic event for exponential population size changes of multiple populations.

pop_names: List[str]

Population names.

start_time: float

Start time of the event.

end_time: float

End time of the event.

events

Discretized rate change events.

__init__(initial_size: Dict[str, float], growth_rate: Dict[str, float] | float, start_time: Dict[str, float] | float, end_time: Dict[str, float] | float = inf, step_size: float = 0.1)

Initialize the exponential growth.

Parameters:

• initial_size (Dict[str, float]) – Initial population sizes. A dictionary mapping population names to sizes.

• growth_rate (Union[Dict[str, float], float]) – Exponential growth rates. A single value or a dictionary mapping keys to values.

• start_time (Union[Dict[str, float], float]) – Start times of the growth. A single value or a dictionary mapping keys to values.

• end_time (Union[Dict[str, float], float]) – End times of the growth.

• step_size (float) – Step size used for the discretization.