Engines (engines package)

GADMA supports several engines of demographic inference. Additional engine could be implemented by creating new subclass of class Engine and register it with function register_engine().

Base class Engine

class gadma.engines.engine.Engine(data=None, model=None)

Bases: object

Abstract class representing an engine of the demographic inference.

New engine should be inherited from this class. Engine must have at least the id, supported_models, supported_data and inner_data attributes, and implementations of read_data() and evaluate() functions of this abstract class.

Variables:

  • Engine.id (str) – the unique identifier of the engine.

  • Engine.supported_models – list of supported Model classes.

  • Engine.supported_data – list of supported DataHolder classes.

  • Engine.inner_data_type – class of inner data that is used by engine.

can_draw_comp = False
can_draw_model = False
can_evaluate = False
can_simulate = False
property data
evaluate(values, **options)

Evaluation of the objective function of the engine.

Parameters:

values – values of variables of setted demographic model.

generate_code(values, filename=None, nanc=None, gen_time=None, gen_time_units='years')

Prints nice formatted code in the format of engine to file or returns it as string if no file is set.

Parameters:

  • values – values for the engine’s model.

  • filename – file to print code. If None then the string will be returned.

get_N_ancestral(values)

Returns size of ancestral population. Is implemented for models with ancestral size as parameter. For dadi and moments it is not always True.

static get_value_from_var2value(var2value, entity)
id = ''
inner_data_type = None
property model
classmethod read_data(data_holder)

Reads data from data_holder.filename in inner type.

Parameters:

data_holder (gadma.DataHolder) – Holder of data to read.

Returns:

data which was read

Return type:

Engine.inner_data_type

set_and_evaluate(values, model, data, options={})

Sets model and data for the engine instance and evaluates the objective function via calling evaluate().

Parameters:

  • values – values of variables of the demographic model.

  • model (class from :attr:supported_models) – model.

  • data (gadma.DataHolder or :attr:inner_data) – holder of the data or raw data for the engine.

Raises:

ValueError – if model is None and any was not set before; or if data_holder is None and any was not set before.

set_data(data)

Sets new data for the engine.

Parameters:

data (DataHolder or inner_data_type.) – new data.

Raises:

ValueError – when data is not supported by the engine.

set_model(model)

Sets new model for the engine.

Parameters:

model (Model) – new model.

Raises:

ValueError – when model is not supported by engine.

supported_data = []
supported_models = []
update_data_holder_with_inner_data()
gadma.engines.engine.all_engines()

Returns an iterator over all registered engines of the demographic inference that can evaluate log-likelihood.

gadma.engines.engine.get_engine(id)

Returns the engine of the demographic inference with the specified id.

Raises:

ValueError – if engine with such id was not registered.

gadma.engines.engine.register_engine(engine)

Registers the specified engine of the demographic inference.

Raises:

ValueError – if engine with the same id was already registered.

Class DadiOrMomentsEngine

class gadma.engines.dadi_moments_common.DadiOrMomentsEngine(data=None, model=None)

Bases: Engine

Base engine class for dadi and moments engines. It has all common methods of both engines.

base_module = None
can_draw_comp = True
can_draw_model = False
can_evaluate = True
can_simulate = True
draw_data_comp_plot(values, grid_sizes, save_file=None, vmin=None)

Draws plots of SFS data for observed data and simulated by model data.

Parameters:

  • values (list or dict) – Values of the model parameters, it could be list of values or dictionary {variable name: value}.

  • grid_sizes – special parameter for numerical solutions. It is pts for DadiEngine and dt_fac for MomentsEngine.

  • save_file (str) – File to save picture. If None then picture will be displayed to the screen.

  • vmin (float) – Values in sfs below vmin are masked in plot. Should be positive.

evaluate(values, grid_sizes)

Simulates SFS from values and evaluate log likelihood between simulated SFS and observed SFS.

generate_code(values, filename, grid_sizes, nanc=None, gen_time=None, gen_time_units='years')

Prints nice formated code in the format of engine to file or returns it as string if no file is set.

Parameters:

  • values – values for the engine’s model.

  • filename – file to print code. If None then the string will be returned.

get_N_ancestral(values, grid_sizes)

Returns size of ancestral population. Is implemented for models with ancestral size as parameter. For dadi and moments it is not always True.

get_N_ancestral_from_theta(theta)
get_claic_component(x0, all_boots, grid_sizes, eps)
get_theta(values, grid_sizes)
id = 'dadi_or_moments'
inner_data_type = None
property multinom
supported_data = [<class 'gadma.data.data.VCFDataHolder'>, <class 'gadma.data.data.SFSDataHolder'>]
supported_models = [<class 'gadma.models.demographic_model.DemographicModel'>, <class 'gadma.models.structure_demographic_model.StructureDemographicModel'>, <class 'gadma.models.custom_demographic_model.CustomDemographicModel'>]
update_data_holder_with_inner_data()
gadma.engines.dadi_moments_common.read_sfs_data(module, data_holder)

Reads file in one of dadi’s or fastsimcoal2 formats.

Parameters:

  • module – dadi or moments module (or analogue)

  • data_holder (gadma.data.DataHolder) – object holding the data.

Returns:

data

Return type:

(str, dadi.Spectrum)

gadma.engines.dadi_moments_common.read_vcf_data(module, data_holder)

Reads file in vcf format and returns dadi’s Spectrum object.

Parameters:

  • module – dadi or moments module (or analogue)

  • data_holder (gadma.data.VCFDataHolder) – object holding the data.

Returns:

data

Return type:

(str, dadi.Spectrum)

Dadi engine

class gadma.engines.dadi_engine.DadiEngine(data=None, model=None)

Bases: DadiOrMomentsEngine

Engine for using dadi for demographic inference.

Citation of dadi:

Gutenkunst RN, Hernandez RD, Williamson SH, Bustamante CD (2009) Inferring the Joint Demographic History of Multiple Populations from Multidimensional SNP Frequency Data. PLoS Genet 5(10): e1000695. https://doi.org/10.1371/journal.pgen.1000695

draw_data_comp_plot(values, pts, save_file=None, vmin=None)

Draws plots of SFS data for observed data and simulated by model data.

Parameters:

  • values (list or dict) – Values of the model parameters, it could be list of values or dictionary {variable name: value}.

  • grid_sizes – special parameter for numerical solutions. It is pts for DadiEngine and dt_fac for MomentsEngine.

  • save_file (str) – File to save picture. If None then picture will be displayed to the screen.

  • vmin (float) – Values in sfs below vmin are masked in plot. Should be positive.

evaluate(values, pts)

Simulates SFS from values and evaluate log likelihood between simulated SFS and observed SFS.

extrapolation = 'make_extrap_log_func'
generate_code(values, filename, pts, nanc=None, gen_time=None, gen_time_units=None)

Prints nice formated code in the format of engine to file or returns it as string if no file is set.

Parameters:

  • values – values for the engine’s model.

  • filename – file to print code. If None then the string will be returned.

get_theta(values, pts)
id = 'dadi'
simulate(values, ns, sequence_length, population_labels, pts)

Returns simulated expected SFS for demographic_model with values as parameters. Simulation is performed with self.pts as grid points for numerical solutions.

Parameters:

  • values – values of demographic model parameters.

  • ns – sample sizes of the simulated SFS.

Moments engine

class gadma.engines.moments_engine.MomentsEngine(data=None, model=None)

Bases: DadiOrMomentsEngine

Engine for using moments for demographic inference.

Citation of moments:

Jouganous, J., Long, W., Ragsdale, A. P., & Gravel, S. (2017). Inferring the joint demographic history of multiple populations: beyond the diffusion approximation. Genetics, 206(3), 1549-1567.

can_draw_model = True
default_dt_fac = 0.01
draw_data_comp_plot(values, dt_fac=0.01, save_file=None, vmin=None)

Draws plots of SFS data for observed data and simulated by model data.

Parameters:

  • values (list or dict) – Values of the model parameters, it could be list of values or dictionary {variable name: value}.

  • grid_sizes – special parameter for numerical solutions. It is pts for DadiEngine and dt_fac for MomentsEngine.

  • save_file (str) – File to save picture. If None then picture will be displayed to the screen.

  • vmin (float) – Values in sfs below vmin are masked in plot. Should be positive.

draw_schematic_model_plot(values, save_file=None, fig_title='Demographic Model from GADMA', nref=None, gen_time=1, gen_time_units='Generations')

Draws schematic plot of the model with values. See moments manual for more information.

Parameters:

  • values (list or dict) – Values of the model parameters, it could be list of values or dictionary {variable name: value}.

  • save_file (str) – File to save picture. If None then picture will be displayed to the screen.

  • fig_title (str) – Title of the figure.

  • nref (int) – An ancestral population size. If None then parameters will be drawn in genetic units.

  • gen_time (float) – Time of one generation. Should be in units of gen_time_units.

  • gen_time_units – Units of gen_type. For example, it could be Years, Generations, Thousand Years and so on.

evaluate(values, dt_fac=0.01)

Simulates SFS from values and evaluate log likelihood between simulated SFS and observed SFS.

generate_code(values, filename=None, dt_fac=0.01, nanc=None, gen_time=None, gen_time_units=None)

Prints nice formated code in the format of engine to file or returns it as string if no file is set.

Parameters:

  • values – values for the engine’s model.

  • filename – file to print code. If None then the string will be returned.

get_N_ancestral(values, dt_fac=0.01)

Returns size of ancestral population. Is implemented for models with ancestral size as parameter. For dadi and moments it is not always True.

get_theta(values, dt_fac=0.01)
id = 'moments'
simulate(values, ns, sequence_length, population_labels, dt_fac=0.01)

Returns simulated expected SFS for demographic_model with values as parameters. :param values: Values of demographic model parameters. :param ns: sample sizes of the simulated SFS.