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
andinner_data
attributes, and implementations ofread_data()
andevaluate()
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.
-
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
orinner_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 forMomentsEngine
.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 typedadi
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 withself.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'>]¶
-