tracts.demography.base_parametrized_demography.BaseParametrizedDemography#

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

Bases: ABC

Base class for parametrized demographies. A parametrized demography is a demographic model in which the migration events are defined by a set of parameters (that are optimized during inference). The class includes methods for adding migration events, checking the validity of the resulting migration matrices, and calculating the ancestry proportions resulting from the migration events. The class also allows fixing certain parameters based on known ancestry proportions of the sample populations.

name#

The name of the parametrized demography.

Type:: str

min_time#

The minimum time for time parameters in the model. This is used to set the bounds for time parameters.

Type:: int

max_time#

The maximum time for time parameters in the model. This is used to set the bounds for time parameters.

Type:: int

constraints#

A list of constraints on the parameters of the model. Constraints are of the form \(g(\theta) \geq 0\), where \(\theta\) denotes the model parameters. constraint is a dict with keys param_subset, expression, and message. param_subset is a tuple of parameter names that are involved in the constraint (\(\theta\)). expression is a lambda function representing \(g\) and message is a string that describes the constraint, which is used for logging when the constraint is violated.

Type:: list[dict]

model_base_params#

A dict mapping parameter names to Parameter objects for the free parameters of the model. Free parameters are parameters that can be optimized directly. They may become fixed during optimization if they are fixed by ancestry proportions.

Type:: dict[str, Parameter]

fixed_params#

A dict mapping parameter names to Parameter objects for the parameters that have been fixed by ancestry proportions. These parameters cannot be optimized directly and are computed from the ancestry proportions.

Type:: dict[str, Parameter]

dependent_params#

A dict mapping parameter names to DependentParameter objects for the parameters that are dependent on other parameters.

Type:: dict[str, DependentParameter]

constant_params#

A dict mapping parameter names to Parameter objects for the parameters that are fixed by the user to a certain value. These parameters cannot be optimized and are not computed from ancestry proportions.

Type:: dict[str, Parameter]

reduced_constraints#

A list of constraints that have been reduced from the original constraints after fixing parameters by ancestry proportions. These constraints are of the same form as the original constraints, but they only involve the free parameters that are being optimized after fixing parameters by ancestry proportions.

Type:: list[dict]

population_indices#

A dict mapping population names to their corresponding indices in the migration matrices.

Type:: dict[str, int]

finalized#

A boolean indicating whether the model has been finalized. The model is finalized after all parameters and populations have been added and the indices for the parameters and populations have been set. The model must be finalized before it can be used for inference.

Type:: bool

founder_events#

A dict mapping the names of founder events to their corresponding FounderEvent objects.

Type:: dict[str, FounderEvent]

events#

A dict mapping population names to a list of migration events that affect that population. Each migration event is a BaseMigrationEvent object.

Type:: dict[str, list[BaseMigrationEvent]]

parameter_handler#

A FixedParametersHandler object that handles the fixing of parameters based on ancestry proportions.

Type:: FixedParametersHandler

parametrized_populations#

A list of population names that are affected by migration events. This is used to determine which populations are included in the migration matrices and which populations’ ancestry proportions are calculated from the migration matrices.

Type:: list[str]

logger#

The logger.

Type:: logging.Logger

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

Initializes the BaseParametrizedDemography class.

Parameters:

name (str | None) – The name of the parametrized demography. If None, the name is set to an empty string.
min_time (float) – The minimum time for time parameters in the model. This is used to set the bounds for time parameters.
max_time (float) – The maximum time for time parameters in the model. This is used to set the bounds for time parameters.

add_dependent_parameter(param_name, expression, param_type=ParamType.UNTYPED, bounds=None)#

Dependent parameters cannot be optimized directly. This is used in sex-biased migration to define a sex-specific migration rate computed from an overall migration rate and sex.

Parameters:

param_name (str) – The name of the parameter to be added.
expression (Callable[[BaseParametrizedDemography, list[float]], float]) – A function that computes the value of the dependent parameter based on other parameters.
param_type (ParamType) – The type of the parameter, which is used to set the default bounds for the parameter if bounds are not provided. If ParamType.UNTYPED is used, bounds must be provided.
bounds (tuple | None) – A tuple representing the bounds for the parameter. If None, the bounds are set to the default bounds for the parameter type. If ParamType.UNTYPED is used, bounds must be provided.

add_parameter(param_name, param_type=ParamType.UNTYPED, bounds=None)#

Adds the given parameter name to the free parameters of the model. Free parameters include all parameters that can be optimized directly, and may become fixed during optimization.

Parameters:

param_name (str) – The name of the parameter to be added.
param_type (ParamType) – The type of the parameter, which is used to set the default bounds for the parameter if bounds are not provided. If ParamType.UNTYPED is used, bounds must be provided.
bounds (tuple | None) – A tuple representing the bounds for the parameter. If None, the bounds are set to the default bounds for the parameter type. If ParamType.UNTYPED is used, bounds must be provided.

add_population(population_name)#

Adds the given population name to the populations of the model.

Parameters:: population_name (str) – The name of the population to be added.

check_bounds(params)#

Checks the bounds on parameters. Bounds should be absolute restrictions on possible parameter values, whereas constraints should be restrictions on parameter values relative to each other.

Parameters:: params (list[float]) – The list of parameter values for the free parameters of the model. The order of the values corresponds to the order of the parameters in model_base_params.
Returns:: A violation score, which is negative if any of the bounds are violated and non-negative otherwise. The violation score is the largest negative value from all the bounds.
Return type:: float

check_constraints(params)#

Checks the constraints on parameters. Constraints take the form of a dict {'param_subset':tuple[str], 'expression': lambda (param_subset), 'message': str} (see constraints in BaseParametrizedDemography).

Parameters:: params (list[float]) – The list of parameter values for the free parameters of the model. The order of the values corresponds to the order of the parameters in model_base_params.
Returns:: A violation score, which is negative if any of the constraints are violated and non-negative otherwise. The violation score is the largest negative value from all the constraints.
Return type:: float

execute_migration_events(migration_matrix, params)#

finalize()#: Finalizes the model by setting the indices for the parameters and populations. This should be called after all parameters and populations have been added to the model and before the model is used for inference.

get_index(time_param_name, population_name, params)#

Returns the matrix index as a tuple from the position and time. Reduces repetitive code.

Returns:: A tuple of the form (time, population_index) representing the index in the migration matrix corresponding to the given time parameter and population name.
Return type:: tuple[float, int]

get_param_value(param_name, params)#

Gets the correct value from the name of the parameter and the list of passed params. If param_name is a number instead, uses the number directly.

Parameters:

param_name (str | float) – The name of the parameter to get the value for, or a float representing the value directly.
params (list[float]) – The list of parameter values for the free parameters of the model. The order of the values corresponds to the order of the parameters in model_base_params.

get_violation_score(params, verbose=False)#

Takes in a list of params equal to the length of model_base_params and returns a negative violation score if the resulting matrix would be or is invalid.

Parameters:

params (list[float]) – The list of parameter values for the free parameters of the model. The order of the values corresponds to the order of the parameters in model_base_params.
verbose (bool) – If True, logs the bound score, constraint score, and migration matrix violation scores when a violation is detected.

Returns:

A violation score, which is negative if the resulting migration matrix would be or is invalid and non-negative otherwise. The violation score is the largest negative value from the bound violations, constraint violations, and migration matrix violations.

Return type:

float

property has_been_fixed#

Whether any parameters have been fixed by ancestry proportions.

Returns:: True if any parameters have been fixed by ancestry proportions, False otherwise.
Return type:: bool

insert_params(params, params_from_proportions)#

Merges the parameters solved by the primary optimizer with the parameters found from the known ancestry proportions into a single list of parameters in the correct order for the model.

Parameters:

params (list[float]) – The list of parameter values for the free parameters of the model that are being optimized by the primary optimizer. The order of the values corresponds to the order of the parameters in model_base_params that are not fixed by ancestry proportions.
params_from_proportions (list[float]) – The list of parameter values for the parameters that are fixed by ancestry proportions, which are computed from the known ancestry proportions. The order of the values corresponds to the order of the parameters in params_fixed_by_ancestry.

Returns:

A list of parameter values for all the free parameters of the model, in the correct order.

Return type:

list[float]

is_time_param()#

Determines if each parameter is a time parameter.

Returns:: A list of booleans indicating whether each parameter is a time parameter. The order of the booleans corresponds to the order of the parameters in model_base_params.
Return type:: list[bool]

property parameter_bounds#

Gets the bounds for the free parameters of the model.

Returns:: A list of tuples representing the bounds for the free parameters of the model. The order of the bounds corresponds to the order of the parameters in model_base_params.
Return type:: list[tuple[float, float]]

property params_fixed_by_ancestry#

Gets the names of the parameters that are fixed by ancestry proportions.

Returns:: A dict of the names of the parameters that are fixed by ancestry proportions and their corresponding values.
Return type:: dict[str, str]

property params_fixed_by_value#

Gets the names of the parameters that are fixed by user-defined values.

Returns:: A dict of the names of the parameters that are fixed by user-defined values and their corresponding values.
Return type:: dict[str, str]

static parse_proportions(ancestor_names, proportions)#

Parses the ancestry proportions used in a founding event into a dict of parametrized source populations and a remainder population.

Parameters:

ancestor_names (list[str]) – A list of the names of the ancestor populations in the founding event. The order of the names should correspond to the order of the proportions in proportions.
proportions (list[str]) – A list of the proportions of ancestry contributed by each ancestor population in the founding event. The order of the proportions should correspond to the order of the names in ancestor_names. One of the proportions should be a string of the form “1-[the other proportions]”, which indicates that the proportion for that ancestor population is equal to 1 minus the sum of the other proportions.

Returns:

A tuple of the form (source_populations, remainder_population), where source_populations is a dict mapping the names of the ancestor populations with parametrized proportions to their corresponding proportion parameters, and remainder_population is the name of the ancestor population whose proportion is equal to 1 minus the sum of the other proportions.

Return type:

tuple[dict[str, str], str]

proportions_from_matrices(migration_matrices)#

Calculates the ancestry proportions for a set of migration matrices, each describing the migration events affecting a particular sample population.

Parameters:: migration_matrices (dict[str, ndarray]) – A dict mapping sample population names to their corresponding migration matrices.
Returns:: A dict mapping sample population names to their corresponding ancestry proportions resulting from the migration events represented by the migration matrices.
Return type:: dict[str, np.ndarray]

proportions_from_matrices_return_keys()#

This method returns the expected keys from proportions_from_matrices(). It is used by FixedParametersHandler to validate that the fixed parameter will be solvable from the given data.

Returns:: The expected keys from proportions_from_matrices(), which are the names of the sample populations that are affected by migration events.
Return type:: set[str]

static proportions_from_matrix(migration_matrix)#

Takes in a migration matrix and returns the ancestry proportions resulting from the migration events represented by the matrix.

Parameters:: migration_matrix (ndarray) – A migration matrix representing the migration events. The matrix should have dimensions \((T, P)\), where \(T\) is the number of time points and \(P\) is the number of populations. Each entry in the matrix represents the fraction of the admixed population that is replaced by migrants from a source population at a given time point.
Returns:: An array of shape \((P,)\) representing the ancestry proportions resulting from the migration events represented by the migration matrix.
Return type:: np.ndarray

set_up_fixed_parameters(params_to_fix_by_ancestry, proportions, params_to_fix_by_value=None)#

Tells the model to calculate certain rate parameters based on the known ancestry proportions of the sample populations. Proportions are given as a dict with keys corresponding to the sample populations.

Parameters:

params_to_fix_by_ancestry (list[str]) – A list of the names of the parameters to be fixed by ancestry proportions.
proportions (dict[str, list[float]]) – A dict mapping sample population names to their corresponding ancestry proportions, which are used to fix the parameters in params_to_fix_by_ancestry.
params_to_fix_by_value (dict[str, float] | None) – A dict mapping parameter names to their corresponding values, which are used to fix parameters by user-defined values. These parameters cannot be optimized and are not computed from ancestry proportions.