diff --git a/doc/misc/changelog.md b/doc/misc/changelog.md index 83050ea54..dca6a675e 100644 --- a/doc/misc/changelog.md +++ b/doc/misc/changelog.md @@ -1236,7 +1236,7 @@ etc., that are collected under the 0.8.0 milestone on `Github`. `API`/`UI` changes: -This release brings Python classes that have been reimplemented using [attrs](). These changes have a lot of benefits: +This release brings Python classes that have been reimplemented using [attrs](https://www.attrs.org). These changes have a lot of benefits: * A lot of C++ code got removed (yay!) because we can use `attrs` for the pickling machinery, `__repr__`, etc.. @@ -1274,14 +1274,14 @@ Improved behavior: Changes to implementation of Python classes * {class}`fwdpy11.ModelParams` has been reimplemented - using [attrs](). {pr}`484`, {pr}`486`, {pr}`487`. -* Demographic model types are now implemented using [attrs]() and + using [attrs](https://www.attrs.org). {pr}`484`, {pr}`486`, {pr}`487`. +* Demographic model types are now implemented using [attrs](https://www.attrs.org) and inherit from the C++ back-end class. {pr}`492` -* Region types are now implemented using [attrs]() and +* Region types are now implemented using [attrs](https://www.attrs.org) and inherit from the C++ back-end class. {pr}`497` -* Genetic value types are now implemented using [attrs]() and +* Genetic value types are now implemented using [attrs](https://www.attrs.org>) and inherit from the C++ back-end class. {pr}`504` -* Genetic map unit types are now implemented using [attrs]() and +* Genetic map unit types are now implemented using [attrs](https://www.attrs.org) and inherit from the C++ back-end class. {pr}`506` C++ back end changes: @@ -1608,7 +1608,7 @@ This is a major refactoring: * Many Python class names are changed to reflect that there is only one population type now. * The manual has been rewritten. -The details for this release are best tracked via the cards in [Project 9]() on GitHub. +The details for this release are best tracked via the cards in [Project 9](https://github.com/molpopgen/fwdpy11/projects/9) on GitHub. ## 0.3.1 @@ -1724,7 +1724,7 @@ This version breaks pickle format compatibility with files generated with versio * Fixed bug in `fwdpy11.util.sort_gamete_keys`. The function was working on a copy, meaning data were not being modified. PR {pr}`93` -* Fix a bug in updating a population's mutation lookup table. This bug was upstream in fwdpp ([fwdpp issue 130]()). While definitely a bug, I could never find a case where simulation outputs were adversely affected. In other words, simulation output remained the same after the fix, due to the rarity of the bug. PR {pr}`98` +* Fix a bug in updating a population's mutation lookup table. This bug was upstream in fwdpp ([fwdpp issue 130](https://github.com/molpopgen/fwdpp/issues/130)). While definitely a bug, I could never find a case where simulation outputs were adversely affected. In other words, simulation output remained the same after the fix, due to the rarity of the bug. PR {pr}`98` ### API changes/new features: @@ -1756,7 +1756,7 @@ This version breaks pickle format compatibility with files generated with versio * PR {pr}`108` changes the back-end for representing diploids and for calculating genetic values. * PR {pr}`98` changes the definition of the populaton lookup table, using - the same model as [fwdpp PR #132]() + the same model as [fwdpp PR #132](https://github.com/molpopgen/fwdpp/pull/132) * Refactored class hierarchy for populations. :pr`85` * Updated to the fwdpp 0.6.x API and cleanup various messes that resulted. PR {pr}`76`, PR {pr}`84`, PR {pr}`90`, PR {pr}`109`, PR {pr}`110` * The position of extinct variants is set to the max value of a C++ double. PR {pr}`105` diff --git a/doc/pages/advancedtopics.md b/doc/pages/advancedtopics.md index af3187239..950785f99 100644 --- a/doc/pages/advancedtopics.md +++ b/doc/pages/advancedtopics.md @@ -334,36 +334,38 @@ type. `fwdpy11` provides the following helper functions to improve efficiency: -```{py:function} fwdpy11.strict_additive_effects +```{eval-rst} +.. py:function:: fwdpy11.strict_additive_effects -This function computes the sum of effect sizes in a -diploid genome, ignoring dominance. The return value -is an offset from zero, so add 1.0 to convert to a -fitness if needed. + This function computes the sum of effect sizes in a + diploid genome, ignoring dominance. The return value + is an offset from zero, so add 1.0 to convert to a + fitness if needed. -:param pop: The population -:type pop: fwdpy11.DiploidPopulation -:param metadata: The offspring metadata -:type metadata: fwdpy11.DiploidMetadata -:returns: Sum of effect sizes -:rtype: float + :param pop: The population + :type pop: fwdpy11.DiploidPopulation + :param metadata: The offspring metadata + :type metadata: fwdpy11.DiploidMetadata + :returns: Sum of effect sizes + :rtype: float ``` -```{py:function} fwdpy11.additive_effects +```{eval-rst} +.. py:function:: fwdpy11.additive_effects -This function computes the sum of effect sizes in a -diploid genome, accounting for dominance. The return value -is an offset from zero, so add 1.0 to convert to a -fitness if needed. + This function computes the sum of effect sizes in a + diploid genome, accounting for dominance. The return value + is an offset from zero, so add 1.0 to convert to a + fitness if needed. -:param pop: The population -:type pop: fwdpy11.DiploidPopulation -:param metadata: The offspring metadata -:type metadata: fwdpy11.DiploidMetadata -:type scaling: float -:returns: Sum of effect sizes (accounting for heterozygous effects) -:rtype: float + :param pop: The population + :type pop: fwdpy11.DiploidPopulation + :param metadata: The offspring metadata + :type metadata: fwdpy11.DiploidMetadata + :type scaling: float + :returns: Sum of effect sizes (accounting for heterozygous effects) + :rtype: float ``` @@ -438,13 +440,13 @@ guaranteed. To quote the `pybind11` documentation: > things will fall apart due to differences between Python’s MRO and C++’s mechanisms. > The source of this quote is the `pybind11` manual section on -[Classes](). +[Classes](https://pybind11.readthedocs.io/en/stable/advanced/classes.html#). The examples that follow take their advice. #### `attrs` -The [attrs]() package provides a library +The [attrs](https://www.attrs.org) package provides a library of convenient class decorators that significantly reduce the amount of "boiler plate" code needed to write Python classes. Some of the examples below will use this library. You must @@ -461,53 +463,56 @@ Speaking of decorators, we provide several that make writing genetic value types a bit easier. You will see concrete examples using them later. -```{py:decorator} fwdpy11.custom_genetic_value_decorators.genetic_value_is_trait_default_clone(ndim=1) +```{eval-rst} +.. py:decorator:: fwdpy11.custom_genetic_value_decorators.genetic_value_is_trait_default_clone(ndim=1) -This decorator is a *class* that adds the ability -for custom types to be passed to classes derived from -:class:`fwdpy11.DiploidGeneticValue`. + This decorator is a *class* that adds the ability + for custom types to be passed to classes derived from + :class:`fwdpy11.DiploidGeneticValue`. -Because this decorator is a class, you need the ``()`` -to apply it. + Because this decorator is a class, you need the ``()`` + to apply it. -This decorator is required because of the very different -object models of C++ and Python. -See `here `_ -for some of the gory details. + This decorator is required because of the very different + object models of C++ and Python. + See [here](https://github.com/pybind/pybind11/issues/1049) + for some of the gory details. -.. py:method:: __init__ + .. py:method:: __init__ - :param ndim: The dimensionality of the model - :type ndim: int + :param ndim: The dimensionality of the model + :type ndim: int - The default is ``ndim=1``. + The default is ``ndim=1``. ``` -```{py:decorator} fwdpy11.custom_genetic_value_decorators.genetic_value_noise_default_clone +```{eval-rst} +.. py:decorator:: fwdpy11.custom_genetic_value_decorators.genetic_value_noise_default_clone -This is the analog to -:attr:`fwdpy11.custom_genetic_value_decorators.genetic_value_is_trait_default_clone` -for noise objects inheriting from :class:`fwdpy11.GeneticValueNoise`. + This is the analog to + :attr:`fwdpy11.custom_genetic_value_decorators.genetic_value_is_trait_default_clone` + for noise objects inheriting from :class:`fwdpy11.GeneticValueNoise`. -Unlike its analog, this decorator is a *function* and not a class. + Unlike its analog, this decorator is a *function* and not a class. ``` -```{py:decorator} fwdpy11.custom_genetic_value_decorators.default_update +```{eval-rst} +.. py:decorator:: fwdpy11.custom_genetic_value_decorators.default_update -This decorator adds the following function to ``cls``, -which is a no-op function: + This decorator adds the following function to ``cls``, + which is a no-op function: -.. code-block:: python + .. code-block:: python - def update(pop: fwdpy11.DiploidPopulation): - pass + def update(pop: fwdpy11.DiploidPopulation): + pass -.. note:: + .. note:: - In the future, we will experiment with adding a C++ - implementation of this no-op. + In the future, we will experiment with adding a C++ + implementation of this no-op. ``` @@ -575,37 +580,38 @@ so that results are reproducible.) The type passed into the `__call__` function is: -```{py:class} fwdpy11.DiploidGeneticValueToFitnessData +```{eval-rst} +.. py:class:: fwdpy11.DiploidGeneticValueToFitnessData -.. versionadded:: 0.9.0 + .. versionadded:: 0.9.0 -This class supports the buffer protocol, which exposes the -genetic values array. The most efficient access will -be via a :class:`memoryview`. + This class supports the buffer protocol, which exposes the + genetic values array. The most efficient access will + be via a :class:`memoryview`. -Instances of this class have the following attributes: + Instances of this class have the following attributes: -.. py:attribute:: offspring_metadata + .. py:attribute:: offspring_metadata - An instance of :class:`fwdpy11.DiploidMetadata`, giving you - access to those fields that have been assigned to the offspring. - (This is a *copy* of the metadata from the C++ side.) + An instance of :class:`fwdpy11.DiploidMetadata`, giving you + access to those fields that have been assigned to the offspring. + (This is a *copy* of the metadata from the C++ side.) -.. py:attribute:: offspring_metadata_index + .. py:attribute:: offspring_metadata_index - A 64 bit integer that gives the location (index) of - ``offspring_metadata`` in :attr:`fwdpy11.DiploidPopulation.diploid_metadata`. - This index is useful in the event of mass migrations via copies, - which can cause a mismatch between :attr:`fwdpy11.DiploidMetadata.label` - and this value. + A 64 bit integer that gives the location (index) of + ``offspring_metadata`` in :attr:`fwdpy11.DiploidPopulation.diploid_metadata`. + This index is useful in the event of mass migrations via copies, + which can cause a mismatch between :attr:`fwdpy11.DiploidMetadata.label` + and this value. -.. py:attribute:: parent1_metadata + .. py:attribute:: parent1_metadata - The first parent's metadata (:class:`fwdpy11.DiploidMetadata`). + The first parent's metadata (:class:`fwdpy11.DiploidMetadata`). -.. py:attribute:: parent2_metadata + .. py:attribute:: parent2_metadata - The second parent's metadata (:class:`fwdpy11.DiploidMetadata`). + The second parent's metadata (:class:`fwdpy11.DiploidMetadata`). ``` @@ -642,38 +648,39 @@ See {func}`fwdpy11.gsl_ran_gaussian_ziggurat` for details on that function. #### The data type -```{py:class} fwdpy11.DiploidGeneticValueNoiseData +```{eval-rst} +.. py:class:: fwdpy11.DiploidGeneticValueNoiseData -.. versionadded:: 0.9.0 + .. versionadded:: 0.9.0 -Instances of this class have the following attributes: + Instances of this class have the following attributes: -.. py:attribute:: rng + .. py:attribute:: rng - The simulation's random number generation, an - instance of :class:`fwdpy11.GSLrng` + The simulation's random number generation, an + instance of :class:`fwdpy11.GSLrng` -.. py:attribute:: offspring_metadata + .. py:attribute:: offspring_metadata - An instance of :class:`fwdpy11.DiploidMetadata`, giving you - access to those fields that have been assigned to the offspring. - (This is a *copy* of the metadata from the C++ side.) + An instance of :class:`fwdpy11.DiploidMetadata`, giving you + access to those fields that have been assigned to the offspring. + (This is a *copy* of the metadata from the C++ side.) -.. py:attribute:: offspring_metadata_index + .. py:attribute:: offspring_metadata_index - A 64 bit integer that gives the location (index) of - ``offspring_metadata`` in :attr:`fwdpy11.DiploidPopulation.diploid_metadata`. - This index is useful in the event of mass migrations via copies, - which can cause a mismatch between :attr:`fwdpy11.DiploidMetadata.label` - and this value. + A 64 bit integer that gives the location (index) of + ``offspring_metadata`` in :attr:`fwdpy11.DiploidPopulation.diploid_metadata`. + This index is useful in the event of mass migrations via copies, + which can cause a mismatch between :attr:`fwdpy11.DiploidMetadata.label` + and this value. -.. py:attribute:: parent1_metadata + .. py:attribute:: parent1_metadata - The first parent's metadata (:class:`fwdpy11.DiploidMetadata`). + The first parent's metadata (:class:`fwdpy11.DiploidMetadata`). -.. py:attribute:: parent2_metadata + .. py:attribute:: parent2_metadata - The first parent's metadata (:class:`fwdpy11.DiploidMetadata`). + The first parent's metadata (:class:`fwdpy11.DiploidMetadata`). ``` @@ -683,60 +690,61 @@ Instances of this class have the following attributes: The ABC type is {class}`fwdpy11.PyDiploidGeneticValue`: -```{py:class} fwdpy11.PyDiploidGeneticValue +```{eval-rst} +.. py:class:: fwdpy11.PyDiploidGeneticValue -.. py:method:: __init__() + .. py:method:: __init__() - :param ndim: - :type ndim: int - :param genetic_value_to_fitness: - :type genetic_value_to_fitness: fwdpy11.GeneticValueIsTrait or None - :param noise: - :type noise: fwdpy11.GeneticValueNoise or None + :param ndim: + :type ndim: int + :param genetic_value_to_fitness: + :type genetic_value_to_fitness: fwdpy11.GeneticValueIsTrait or None + :param noise: + :type noise: fwdpy11.GeneticValueNoise or None -.. py:method:: calculate_gvalue - :abstractmethod: + .. py:method:: calculate_gvalue + :abstractmethod: - :param data: Input data - :type data: fwdpy11.PyDiploidGeneticValueData - :returns: The value to be stored in the offspring's - :attr:`fwdpy11.DiploidMetadata.g` - :rtype: float + :param data: Input data + :type data: fwdpy11.PyDiploidGeneticValueData + :returns: The value to be stored in the offspring's + :attr:`fwdpy11.DiploidMetadata.g` + :rtype: float -.. py:method:: genetic_value_to_fitness + .. py:method:: genetic_value_to_fitness - :param data: Input data - :type data: fwdpy11.DiploidGeneticValueToFitnessData + :param data: Input data + :type data: fwdpy11.DiploidGeneticValueToFitnessData - :returns: fitness - :rtype: float + :returns: fitness + :rtype: float - .. note:: + .. note:: - This function does not need to be defined - by derived classes most of the time. - The default behavior is to apply - the instance of :class:`fwdpy11.GeneticValueToFitnessMap` - stored by the instance of :class:`fwdpy11.DiploidGeneticValue` - (or :class:`fwdpy11.PyDiploidGeneticValue`). Defining - this function in a derived class skips calling held instance - in favor of the derived class implementation. - In general, one only needs to derive this class for models - where either individual genetic values depend on genotypes of the - rest of the population. See :ref:`here `. + This function does not need to be defined + by derived classes most of the time. + The default behavior is to apply + the instance of :class:`fwdpy11.GeneticValueToFitnessMap` + stored by the instance of :class:`fwdpy11.DiploidGeneticValue` + (or :class:`fwdpy11.PyDiploidGeneticValue`). Defining + this function in a derived class skips calling held instance + in favor of the derived class implementation. + In general, one only needs to derive this class for models + where either individual genetic values depend on genotypes of the + rest of the population. See :ref:`here `. -.. py:method:: update + .. py:method:: update - :param pop: The population being simulated - :type pop: fwdpy11.DiploidPopulation - :rtype: None + :param pop: The population being simulated + :type pop: fwdpy11.DiploidPopulation + :rtype: None - .. note:: + .. note:: - A default implementation can be defined using - the decorator - :attr:`fwdpy11.custom_genetic_value_decorators.genetic_value_noise_default_clone`. + A default implementation can be defined using + the decorator + :attr:`fwdpy11.custom_genetic_value_decorators.genetic_value_noise_default_clone`. ``` diff --git a/doc/pages/gslrandom.md b/doc/pages/gslrandom.md index 06df677b9..6220407f9 100644 --- a/doc/pages/gslrandom.md +++ b/doc/pages/gslrandom.md @@ -6,59 +6,64 @@ The following functions map directly to C functions from the GNU Scientific Library. All functions take positional arguments without names. -```{py:function} fwdpy11.gsl_ran_gaussian_ziggurat +```{eval-rst} +.. py:function:: fwdpy11.gsl_ran_gaussian_ziggurat -:param rng: Random number generator -:type rng: fwdpy11.GSLrng -:param sd: The standard deviation -:type sd: float -:returns: A gaussian deviate with mean zero and standard - deviation ``sd`` -:rtype: float + :param rng: Random number generator + :type rng: fwdpy11.GSLrng + :param sd: The standard deviation + :type sd: float + :returns: A gaussian deviate with mean zero and standard + deviation ``sd`` + :rtype: float ``` -```{py:function} fwdpy11.gsl_rng_uniform +```{eval-rst} +.. py:function:: fwdpy11.gsl_rng_uniform -:param rng: Random number generator -:type rng: fwdpy11.GSLrng -:returns: Uniform deviate from the range ``[0, 1)`` -:rtype: float + :param rng: Random number generator + :type rng: fwdpy11.GSLrng + :returns: Uniform deviate from the range ``[0, 1)`` + :rtype: float ``` -```{py:function} fwdpy11.gsl_ran_flat +```{eval-rst} +.. py:function:: fwdpy11.gsl_ran_flat -:param rng: Random number generator -:type rng: fwdpy11.GSLrng -:param a: Lower bound of range, inclusive. -:type a: float -:param b: Upper bound of range, exclusive. -:type b: float -:returns: Uniform deviate from the range ``[a, b)``. -:rtype: float + :param rng: Random number generator + :type rng: fwdpy11.GSLrng + :param a: Lower bound of range, inclusive. + :type a: float + :param b: Upper bound of range, exclusive. + :type b: float + :returns: Uniform deviate from the range ``[a, b)``. + :rtype: float ``` -```{py:function} fwdpy11.gsl_ran_poisson +```{eval-rst} +.. py:function:: fwdpy11.gsl_ran_poisson -:param rng: Random number generator -:type rng: fwdpy11.GSLrng -:param mean: The mean of the distribution -:type mean: float -:returns: The number of successes -:rtype: int + :param rng: Random number generator + :type rng: fwdpy11.GSLrng + :param mean: The mean of the distribution + :type mean: float + :returns: The number of successes + :rtype: int ``` -```{py:function} fwdpy11.gsl_ran_geometric +```{eval-rst} +.. py:function:: fwdpy11.gsl_ran_geometric -:param rng: Random number generator -:type rng: fwdpy11.GSLrng -:param p: The probability of success -:type p: float -:returns: The waiting time until the next success -:rtype: int + :param rng: Random number generator + :type rng: fwdpy11.GSLrng + :param p: The probability of success + :type p: float + :returns: The waiting time until the next success + :rtype: int ``` diff --git a/doc/short_vignettes/demography_vignettes_intro.md b/doc/short_vignettes/demography_vignettes_intro.md index 037250096..3a154f627 100644 --- a/doc/short_vignettes/demography_vignettes_intro.md +++ b/doc/short_vignettes/demography_vignettes_intro.md @@ -4,7 +4,8 @@ ## Discrete demes and Wright-Fisher life cycles -Demographic models of discrete demes are declared according to the `demes specification `. +Demographic models of discrete demes are declared according to the +[demes specification](https://popsim-consortium.github.io/demes-spec-docs/main/tutorial.html). See {class}`fwdpy11.ForwardDemesGraph` and {func}`fwdpy11.discrete_demography.from_demes` for details. Please cite the `demes` paper {cite}`Gower2022-xx` when using `fwdpy11`.