The demography debugger

class fwdpy11.DemographyDebugger(initial_deme_sizes, events, simlen=None, deme_labels=None)

Efficiently debug demographic events.

The class executes a mock simulation of demographic events in order to quickly detect errors. It also generates a “report” of the model details for double-checking.

If model errors are found, a ValueError exception is raised. The goal is to catch the types of errors that would result in an exception during a simulation.

The class is initialized with the following arguments, which may be either positional or keyword:

Parameters

New in version 0.6.0.

Changed in version 0.8.1: Initialization now done with attr. A list of initial deme sizes is now accepted.

__init__(initial_deme_sizes, events, simlen=None, deme_labels=None)None

Initialize self. See help(type(self)) for accurate signature.

property report

Obtain the details of the demographic model as a nicely-formatting string.

Pre-computed demographic models

class fwdpy11.demographic_models.DemographicModelDetails(*, model: object, name: str, source: Dict, parameters: object, citation: Optional[Dict], metadata: Optional[object] = None)

Stores rich information about a demographic model. Instances of this class get returned by functions generating pre-calculated models.

This class has the following attributes, whose names are also kwargs for intitialization. The attribute names also determine the order of positional arguments:

Parameters

New in version 0.8.0.

class fwdpy11.demographic_models.DemographicModelCitation(*, DOI: object, full_citation: object, metadata: object)

Citation information for a demographic model

This class has the following attributes, whose names are also kwargs for intitialization. The attribute names also determine the order of positional arguments:

Parameters
  • DOI – The Digital Object Identifier

  • full_citation – Something string-like giving the full citation.

  • metadata – Any additional information that may be needed.

New in version 0.8.0.

fwdpy11.demographic_models.IM

This module provides functions to generate demographic events for “isolation-with-migration”, or IM, models.

fwdpy11.demographic_models.IM.two_deme_IM(Nanc, T, psplit, Ns, migrates, burnin=10.0)

Isolation-with-migration (IM) model for two demes.

An ancestral population splits into two daughter demes. At the time of the split, psplit of the ancestral population moves into deme 1. The two daughter populations begin exponential growth until the present time and migration may occur between them.

Parameters
  • Nanc (int) – The ancestral population size.

  • T (float) – The time of the split, in units of Nanc generations into the past.

  • psplit (float) – The proportion of the ancestral population that splits off to found deme 1

  • Ns (tuple) – The final sizes of demes 0 and 1, relative to Nanc

  • migrates (float) – The migration rates from 0 to 1 and from 1 to 0, respectively. Migration rates are the fraction of the destination deme replaced by the source deme.

  • burnin (float) – Time to simulate before the split, in units of Nanc

Returns

The model events, instances of fwdpy11.demographic_models.IM.TwoDemeIMParameters and fwdpy11.demographic_models.IM.TwoDemeIMMetaData.

Return type

fwdpy11.demographic_models.DemographicModelDetails

Note

The events returned by this model assume/require that you will construct a population with intitial size Nanc.

New in version 0.6.0.

Changed in version 0.8.0: Returns instance of fwdpy11.demographic_models.DemographicModelDetails

class fwdpy11.demographic_models.IM.TwoDemeIMParameters(Nanc: int, T: float, psplit: float, Ns: tuple, migrates: list, burnin: float)

Holds the parameters to fwdpy11.demographic_models.IM.two_deme_IM().

Instances of this class are held as the parameters attribute of fwdpy11.demographic_models.DemographicModelDetails.

Attribute names are the same as the kwargs to fwdpy11.demographic_models.IM.two_deme_IM():

Parameters
  • Nanc

  • T

  • psplit

  • Ns

  • migrates

  • burnin

New in version 0.8.0.

class fwdpy11.demographic_models.IM.TwoDemeIMMetaData(split_time: int, gens_post_split: int, simlen: int)

Holds metadata returned by fwdpy11.demographic_models.IM.two_deme_IM().

Instances of this class are held as the metadata attribute of fwdpy11.demographic_models.DemographicModelDetails.

Parameters
  • split_time – The time until the two demes split

  • gens_post_split – The time from the split until the end of the simulation

  • simlensplit_time + gens_post_split

New in version 0.8.0.

Human demographic models

This module provides the following models:

This module provided pre-calculated demographic models for human populations.

class fwdpy11.demographic_models.human.TennessenModel(value)

Enumeration type declaring alternative implementations of the Tennessen et al. (2012) model. See fwdpy11.demographic_models.human.tennessen() for details.

V0 = 0

Default version of the model

V1 = 1

Alternate version of the model

fwdpy11.demographic_models.human.jouganous_three_deme(burnin: int = 20)

Generate parameters for the demographic model described in Table 2 of:

Jouganous, Julien, Will Long, Aaron P. Ragsdale, and Simon Gravel. 2017. “Inferring the Joint Demographic History of Multiple Populations: Beyond the Diffusion Approximation.” Genetics 206 (3): 1549–67.

Parameters

burnin – Burn-in time, as a multiplier of the ancestral population size. Defaults to 20.

Returns

The demographic model

Return type

fwdpy11.demographic_models.DemographicModelDetails

The metadata field of the return value contains information about the simulation length, ancestral population size (Nref), etc., and the mapping of integer values to deme names.

New in version 0.8.1.

fwdpy11.demographic_models.human.tennessen(burnin: int = 20, model_version: fwdpy11.demographic_models.human.TennessenModel = <TennessenModel.V0: 0>)

Generate parameters for the demographic model described in:

Tennessen, Jacob A., Abigail W. Bigham, Timothy D. O’Connor, Wenqing Fu, Eimear E. Kenny, Simon Gravel, Sean McGee, et al. 2012. “Evolution and Functional Impact of Rare Coding Variation from Deep Sequencing of Human Exomes.” Science 337 (6090): 64–69.

Parameters
Returns

The demographic model

Return type

fwdpy11.demographic_models.DemographicModelDetails

The metadata field of the return value contains information about the simulation length, ancestral population size (Nref), etc., and the mapping of integer values to deme names.

When this model is run, deme 0 corresponds to African and deme 1 corresponds to Eurasian.

Due to uncertainty in the literature over the details of this model, we provide two slightly different implementations. The first implementation is the default, and is specified by fwdpy11.demographic_models.human.TennessenModel.V0. For this model, the final deme sizes are those shown in Figure 3 of the Tennessen et al. (2012) paper. If fwdpy11.demographic_models.human.TennessenModel.V1 is used instead, then the final sizes are obtained by calculating them forwards in time using a combination of the information from Tennessen et al. (2012) and Fu et al. 2013. However, due to having to convert from continuous to discrete time, etc., other definitions of this model are also possible. Here, all deme sizes and times are obtained using numpy.rint().

Note

This implementation is based on code provided by Aaron Ragsdale.

New in version 0.8.0.