tracts.demography.parametrized_demography.ParametrizedDemography#

class ParametrizedDemography(name=None, min_time=1, max_time=inf)#

Bases: BaseParametrizedDemography

A class representing a demographic history for multiple populations of interest, with parametrized migrations from other populations.

name#

The name of the demographic model.

Type:

str

min_time#

The minimum time for the demographic model, in generations. Default is 1 generation ago.

Type:

float

max_time#

The maximum time for the demographic model, in generations. Default is infinity.

Type:

float

logger#

The logger.

Type:

logging.Logger

__init__(name=None, min_time=1, max_time=inf)#

Initializes a ParametrizedDemography object.

Parameters:

  • name (str | None) – The name of the demographic model. Default is None, which will be set to an empty string.

  • min_time (float) – The minimum time for the demographic model, in generations. Default is 1 generation ago.

  • max_time (float) – The maximum time for the demographic model, in generations. Default is infinity.

add_continuous_migration(dest_population, source_population, rate_param, start_param, end_param=None)#

Adds a continuous migration from a source population, parametrized by start_time, end_time, and magnitude.

add_founder_event(dest_population, source_populations, remainder_population, found_time, end_time=None, pulse_pops=[])#

Adds a founder event. A parametrized demography must have exactly one founder event.

Parameters:

  • dest_population (str) – The name of the destination population for the founder event.

  • source_populations (dict[str, str]) – A dictionary where each key is a source population and each value is the name of the parameter defining the migration ratio of each population.

  • remainder_population (str) – The name of the source population for the remaining migrants, such that the total migration ratio adds up to 1.

  • found_time (str) – The name of the parameter defining the time of the founder event.

  • end_time (str) – The name of the parameter defining the end time of the founder event, for continuous founding. If None, the founder event is a pulse founding. Default is None.

Return type:

None

add_pulse_migration(dest_population, source_population, rate_param, time_param)#

Adds a pulse migration from a source population, parametrized by time and rate.

Parameters:

  • dest_population (str) – The name of the destination population for the pulse migration.

  • source_population (str) – The name of the source population for the pulse migration.

  • rate_param (str) – The name of the parameter defining the rate of the pulse migration.

  • time_param (str) – The name of the parameter defining the time of the pulse migration.

execute_migration_events(migration_matrices, params)#

Adds the migration events to the migration matrices.

Parameters:

  • migration_matrices (dict[str, ndarray]) – A dictionary mapping population names to their corresponding migration matrices.

  • params (list[float]) – The list of parameter values.

get_founding_time(population)#

Gets the name of the parameter defining the founding time of a population.

Parameters:

population (str) – The name of the population for which to get the founding time.

Returns:

The name of the parameter defining the founding time of the population.

Return type:

str

get_migration_matrices(params)#

Takes in a list of params equal to the length of model_base_params and returns a \(P \times G\) migration matrix for each population of interest where P is the number of incoming populations and G is the number of generations. If one of the parameters (time or migration) is incorrect, returns an empty matrix.

Parameters:

params (list[float]) – A list of parameter values, where the order of the values corresponds to the order of the parameters in model_base_params.

Returns:

A dictionary mapping population names to their corresponding migration matrices.

Return type:

dict[str, ndarray]

get_random_parameters()#
static load_from_YAML(source, implicit_population=None)#

Creates an instance of ParametrizedDemography from a YAML file.

Parameters:

  • source (str | Path) – The path to the YAML file containing the demographic model. See online documentations for details on how to specify demographic models in YAML files.

  • implicit_population (str | None) – The name of the population to use as the implicit population in the discrete founder event (if any), whose proportion is set to one minus the sum of the proportions contributed by the other source populations. The rate and sex-bias parameter of the implicit population is not explicitely optimized and its optimal value is derived from the optimal values of the other source populations. If None, defaults to the first source population specified in the founder event.

Returns:

An instance of ParametrizedDemography representing the demographic model specified in the YAML file.

Return type:

ParametrizedDemography