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 inheritted 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
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)

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.

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

Reads data from data_holder.filename in inner type.

Parameters

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

Returns

readed data

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 setted before; or if data_holder is None and any was not setted 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 = []
gadma.engines.engine.all_engines()

Returns an iterator over all registered engines of the demographic inference.

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: gadma.engines.engine.Engine

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

base_module = None
draw_sfs_plots(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)
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
classmethod read_data(data_holder)

Reads SFS data from data_holder.

Could read two types of data:

  • dadi SFS data type

  • dadi SNP data type

Check dadi manual for additional information.

Parameters

data_holder (SFSDataHolder) – holder of the data.

supported_data = [<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'>]
gadma.engines.dadi_moments_common.read_dadi_data(module, data_holder)

Read file in one of dadi’s formats.

Parameters
  • module – dadi or moments module (or analogue)

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

Returns

(‘sfs’/’snp’, data)

Return type

(str, dadi.Spectrum)

Dadi engine

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

Bases: gadma.engines.dadi_moments_common.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

base_module = <module 'dadi' from '/home/katenos/.local/lib/python3.6/site-packages/dadi/__init__.py'>
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 with MomentsEngine (!). 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_type (float) – Time of one generation.

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

evaluate(values, pts)

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

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'
inner_data_type

alias of dadi.Spectrum_mod.Spectrum

simulate(values, ns, 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.

supported_data = [<class 'gadma.data.data.SFSDataHolder'>]

Moments engine

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

Bases: gadma.engines.dadi_moments_common.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.

base_module = <module 'moments' from '/usr/local/lib/python3.6/dist-packages/moments-1.0.6-py3.6-linux-x86_64.egg/moments/__init__.py'>
default_dt_fac = 0.01
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_type (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_theta(values, dt_fac=0.01)
id = 'moments'
inner_data_type

alias of moments.Spectrum_mod.Spectrum

simulate(values, ns, dt_fac=0.01)

Returns simulated expected SFS for demographic_model with values as parameters.

Parameters
  • values – Values of demographic model parameters.

  • ns – sample sizes of the simulated SFS.

supported_data = [<class 'gadma.data.data.SFSDataHolder'>]