Models (models package)

Base class Model

class gadma.models.model.Model(raise_excep=False)

Bases: object

Abstract class of model. Contains variables of class Variable.

Parameters:: raise_excep (bool) – if True then raises exception when something except Variable is added as variable.

add_variable(variable)

Adds one variable to the model.

Parameters:: variable (Variable) – variable to add.

add_variables(variables)

Adds several variables to the model.

Parameters:: variables (list) – variables to add.

fix_variable(variable, value)

static get_value_from_var2value(var2value, entity): Returns value from var2value if entity is variable or returns entity otherwise (as it means that entity is a constant)

get_variable(name)

Finds the variable of the model by its name.

Parameters:: name (str) – name of the model’s variable.
Raises:: ValueError – if there is no variable with that name.

string_repr(values)

Returns string representation of variables and values.

Parameters:: values – Values of the variables in model.

unfix_if_fixed(variable)

unfix_variable(variable)

var2value(values)

Returns dictionary {variable: value}.

Parameters:: values – List or dict {var_name: value} of values.

property variables

Combinations of variables

Base class VariablesCombination

class gadma.models.variables_combinations.VariablesCombination

Bases: Model

Base class for combination of variables.

Base class BinaryOperation

class gadma.models.variables_combinations.BinaryOperation(arg1, arg2)

Bases: Operation

Combination of two variables.

Parameters:

arg1 (gadma.Variable or value.) – First argument.
arg2 (gadma.Variable or value.) – Second argument.

Raises:

AssertError – if both arguments are not variables.

get_value(values)

Returns value of the combination from variables values.

Parameters:: values (list of dict) – Values of the variables.

is_commutative()

property name: Generates name from variables names like: self.arg1.name operation self.arg1.name

static operation(val1, val2): Returns the result of binary operation from two values.

static operation_str(): Returns string representation of binary operation.

string_repr(values)

Returns string representation of combination with defined values.

Parameters:: values (list of dict) – Values of the variables.

Classes of different binary operations

class gadma.models.variables_combinations.Addition(arg1, arg2)

Bases: BinaryOperation

The sum of two variables.

is_commutative()

static operation(val1, val2): Returns the result of binary operation from two values.

static operation_str(): Returns string representation of binary operation.

class gadma.models.variables_combinations.Division(arg1, arg2)

Bases: BinaryOperation

The division of one variable by another.

is_commutative()

static operation(val1, val2): Returns the result of binary operation from two values.

static operation_str(): Returns string representation of binary operation.

class gadma.models.variables_combinations.Multiplication(arg1, arg2)

Bases: BinaryOperation

The multiplication of two variables.

is_commutative()

static operation(val1, val2): Returns the result of binary operation from two values.

static operation_str(): Returns string representation of binary operation.

class gadma.models.variables_combinations.Subtraction(arg1, arg2)

Bases: BinaryOperation

The subtraction of two variables.

is_commutative()

static operation(val1, val2): Returns the result of binary operation from two values.

static operation_str(): Returns string representation of binary operation.

Events

class gadma.models.event.Epoch(time_arg, init_size_args, size_args, mig_args=None, dyn_args=None, sel_args=None, dom_args=None)

Bases: Event

Epoch for demographic model. All arguments could be both values and some variables. Additionally values could be combinations of the variables (see gadma.models.VariablesCombinations).

Parameters:

time_arg (float or gadma.TimeVariable) – Time of the epoch.
init_size_args (list of values and/or gadma.PopulationSizeVariable) – Sizes of populations at the beginning of the epoch.
size_args (list of values and/or gadma.PopulationSizeVariable) – Sizes of populations at the end of the epoch.
mig_args (2d list of values and/or gadma.MigrationVariable) – Migration rates between populations.
dyn_args (list of values and/or gadma.DynamicVariable) – Dynamics of population size changes during the epoch.
sel_args (list of values and/or gadma.SelectionVariable) – Selection rates for each population during the epoch.

as_custom_string(values): Returns string representation of the event.

get_vars_not_in_init_args()

class gadma.models.event.Event

Bases: Model

Base class for some event.

as_custom_string(values): Returns string representation of the event.

class gadma.models.event.Split(pop_to_div, size_args=None)

Bases: Event

Class for split demographic event.

Parameters:

pop_to_div – Population index that splits.
size_args – Sizes of populations after split.

as_custom_string(values): Returns string representation of the event.

Demographic models

Base class DemographicModel

class gadma.models.demographic_model.DemographicModel(gen_time=None, theta0=None, mutation_rate=None, recombination_rate=None, Nref=None, has_anc_size=False, linear_constrain=None)

Bases: Model

Base class for demographic model.

Parameters:

gen_time (float) – Time of one generation.
theta0 (float) – Mutation flux (4 * mu * L, where L - length of sequence).
mutation_rate (float) – Mutation rate per base per generation.
recombination_rate (float) – Recombination rate per base per generation.
Nref (float) – rescaling factor of the parameters values.
has_anc_size (bool) – If False then model does not have size of ancestral population. It is the case for dadi and moments as they have multinom mode when this size is generated automatically from the rest of the parameters.
linear_constrain (gadma.optimizers.LinearConstrain) – linear constrain on parameters.

add_variable(variable)

Overrides Model.add_variable() method. Checks that if model does not have ancestral size then no variables in physical units are added.

Parameters:: variable (Variable) – variable to add.

as_custom_string(values)

Returns string representation of the demographic model with parameters as a list with variables and their values.

Parameters:: values – Values of the demographic model.

get_Nanc_size(values=None)

Returns Nanc size as variable (if it is) or constant. If model does not has_anc_size then ValueError is raised.

Parameters:: values – Values of model variables. Could be required to understand what variable or constant is actual Nanc size.

get_number_of_parameters(values): Returns number of parameters of the model.

translate_values(units, values, Nanc=None, time_in_generations=False, rescale_back=False)

Translates values from current units to new. If some variables do not have units they are not translated.

Parameters:

units – Units to translate to. Could be “physical” or “genetic”.
values – Values of parameters.
Nanc – Size of ancestral population if it is not a parameter. E.g. has_anc_size could be False.
time_in_generations – If False then time is translated to years according to gen_time of model. Valid only if units == “physical”.
rescale_back – If True then values are rescaled back according to Nref factor of the model.

Class EpochDemographicModel

class gadma.models.demographic_model.EpochDemographicModel(gen_time=None, theta0=None, mutation_rate=None, recombination_rate=None, Nref=None, has_anc_size=None, Nanc_size=None, p_misid=None, linear_constrain=None, inbreeding_args=None)

Bases: DemographicModel

Class for demographic model of epoch type. This type is common for dadi and moments.

See gadma.models.demographic_model.DemographicModel for more information.

By default (when None value) has_anc_size is True if Nanc_size is set and False otherwise (when Nanc_size is None). If Nanc_size is not set (i.e. None) then it is taken as 1.0.

Parameters:: Nanc_size (float or gadma.utils.PopulationSizeVariable) – Constant or variable for demographic model. Usually it is some variable but for dadi and moments this parameter could be equal to 1. In that case they will use multinom inference and get best Nanc_size for the model.

property Nanc_size

add_epoch(time_arg, size_args, mig_args=None, dyn_args=None, sel_args=None, dom_args=None)

Adds new epoch to the demographic model events.

Parameters:

time_arg – time of the epoch.
size_args – population sizes at the end of the epoch.
mig_args – migrations between populations during the epoch.
dyn_args – dynamics of the populations during the epoch.
sel_args – selection coefficients of the populations during the epoch.
dom_args – dominance coefficients.

Note:

all arguments could contain variables of Variable class as well as different constants/values including gadma.models.BinaryOperation instances.

add_inbreeding(inbr_args=None)

add_p_misid(p_misid=None)

add_split(pop_to_div, size_args)

Adds new split to the demographic model events.

Parameters:

pop_to_div – population to divide.
size_args – population sizes of two subpopulations after the split.

as_custom_string(values)

Returns string representation of the demographic model with parameters.

Parameters:: values – Values of the demographic model.

classmethod create_from(model, values=None)

Create epoch model from other type of model

Parameters:

model (TreeDemographicModel) – model
values (list or dict) – Values of the parameters.

fix_dynamics(values)

Makes all dynamics in events fixed.

Parameters:: values (list or dict) – Values of parameters to take for fixation.

fix_variable(variable, value)

Fixes variable in the model to the value.

Parameters:

variable – Variable to fix.
value – Value of the variable to fix.

get_involved_for_split_time_vars(n_split)

Returns list of ints and bias. If value > 0 then this variable is involved in sum of times for split.

It will return A, b: Ax + b = time of n_split split.

get_number_of_parameters(values)

Returns number of parameters of the model. Be careful as this number could be different to the number of variables. According to the population size dynamics in values some variables could have no influence on the model and in this case they are not counted.

Parameters:: values (list or dict) – Values of the parameters. Dynamics makes the most sense.

property has_inbreeding

property has_p_misid

number_of_populations(): Returns number of populations in the model.

translate_to(ModelClass, values)

Translate model to the another type of model

Parameters:

ModelClass (type) – Class of model in which we transform our model
values (list or dict) – Values of the parameters.

unfix_dynamics(): Makes all dynamics in events unfixed.

unfix_variable(variable): Unfixes the variable of the model.

Class StructureDemographicModel

class gadma.models.structure_demographic_model.StructureDemographicModel(initial_structure, final_structure, has_migs, has_sels, has_dom, has_dyns, sym_migs, frac_split, has_p_misid, migs_mask=None, has_anc_size=False, gen_time=None, theta0=None, mutation_rate=None, recombination_rate=None, Nref=None, has_inbr=None)

Bases: EpochDemographicModel

Special class for demographic model created by structure.

Parameters:

initial_structure (list of ints) – List of ints with number of intervals in initial structure.
final_structure (list of ints) – List of ints with number of intervals in final structure.
has_migs (bool) – If True then model will have migrations.
has_sels (bool) – If True then model will have selection coefficients.
has_dom (bool) – If True then model will have dominance coefficients. It is valid only if model has selection.
has_inbr (bool) – If True then model will have inbreeding.
has_dyns (bool) – If True then model will create dynamics of size change different to Sudden change.
sym_migs (bool) – If True then migrations will be symetric.
frac_split (bool) – If True then populations split in some proportion. If False then newly formed population has size as an independent variable.
has_misid (bool) – If True then there is an additional parameter for the ancestral state misidentification error
migs_mask (list) – List of matrices of 0 and 1 for each time interval (after first split) that defines what migrations this interval has. E.g. [[[0, 1],[0, 0]], [[0, 0], [0, 0]]] for structure (*, 2) will allow migration from pop2 to pop1 in the interval right after split. Note that structure should be fixed if migs_mask is set (increase_structure() raises ValueError).
has_anc_size (bool) – If True then Nanc_size variable is created.
gen_time (float) – Time in years of one generation.
theta0 (float) – Mutation flux (4*mu*L).
mutation_rate (float) – Mutation rate per base per generation.
recombination_rate (float) – Recombination rate per base per generation.

from_structure(structure)

Creates new model from given structure. It is base constructor of the model.

Parameters:: structure (list of ints) – Structure of the model.

get_structure(): Returns current structure of the model.

increase_structure(new_structure=None, X=None)

Increase structure of the model. Raises ValueError if structure is equal or greater than final_structure.

Parameters:

new_structure – New structure for the model. Should be greater by 1 in one element. E.g. structure is (1,2), then new structure could be either (2,2) or (1,3). If None random available element is chosen to increase.
X – list of values to transform as values of new model.

Note:

Function is specific for gadma.models.StructureDemographicModel. It probably will not work for any other class.

transform_values_from_other_model(model, x)

Class CustomDemographicModel

class gadma.models.custom_demographic_model.CustomDemographicModel(function, variables, gen_time=None, theta0=None, mutation_rate=None, recombination_rate=None, fixed_anc_size=None, has_anc_size=False)

Bases: DemographicModel

Demographic model that was defined by the user in some file. Engines should be able to deal with such kind of models.

Parameters:

function – function that creates the demographic model or something like that.
variables – Variables of the function. I.e. model parameters.
gen_time – Time of one generation.
theta0 – Mutation flux. See gadma.models.DemographicModel for more information.
mutation_rate – Mutation rate. See gadma.models.DemographicModel for more information.
recombination_rate – Recombination rate.

translate_values(units, values, Nanc=None, time_in_generations=False, rescale_back=False)

Translates values from current units to new. If some variables do not have units they are not translated.

Parameters:

units – Units to translate to. Could be “physical” or “genetic”.
values – Values of parameters.
Nanc – Size of ancestral population if it is not a parameter. E.g. has_anc_size could be False.
time_in_generations – If False then time is translated to years according to gen_time of model. Valid only if units == “physical”.
rescale_back – If True then values are rescaled back according to Nref factor of the model.