From c6b23a872fe5ba37f72d52803732e533b937ec86 Mon Sep 17 00:00:00 2001 From: Arnaud Becheler <8360330+Becheler@users.noreply.github.com> Date: Wed, 3 Jan 2024 17:16:50 +0000 Subject: [PATCH] fix: gaussian naming convention and doc link --- docs/4-tutorials.md | 16 ++++++++++++---- example/dispersal_kernel.cpp | 8 ++++---- .../quetzal/demography/dispersal_kernel.hpp | 16 ++++++++-------- 3 files changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/4-tutorials.md b/docs/4-tutorials.md index e00c48cb..d7355a8e 100644 --- a/docs/4-tutorials.md +++ b/docs/4-tutorials.md @@ -27,7 +27,7 @@ - @subpage demographic_histories_in_quetzal - Examples - - @subpage dispersal-kernels + - @subpage dispersal_kernels - @subpage Growth Expressions - @subpage Memory Management @@ -814,10 +814,18 @@ There a different modeling approaches to look at these demographic histories, pr [//]: # (----------------------------------------------------------------------) @page dispersal_kernels Dispersal Kernels +@tableofcontents + +# Background + +# Neighborhood-based Dispersal + +# Distance-based Dispersal + +# Resistance-based Dispersal @note -The objective of this section is to parametrize a Dispersal Location Kernel (in the sense of Nathan et al. 2012) -and to compute useful quantities, such as the distance between two locations, the probability to disperse from one to the other, and the mean dispersal distance expected under the distribution. +Simulating a demographic process on a spatial graph first requires to account for the modality of dispersal between the vertices (locations) of the graph. A relatively simple way to do so is to link the geographic distance between two locations to the probability to disperse between them. The objective of this section is to highlight this model choice by parametrizing a simple Dispersal Location Kernel (in the sense of Nathan et al. 2012) and to compute useful quantities, such as the distance between two coordinates, the probability to disperse from one to the other, and the mean dispersal distance expected under the distribution. ## Background @@ -827,7 +835,7 @@ The dispersal location kernel represents the statistical pattern of dispersal di For a source \f$(x_0,y_0)\f$, the dispersal location kernel denoted as \f$k_L(r)\f$ provides the density of the probability of the dispersal end point in the 2D space. In this case, \f$k_L(r)dA\f$ is the probability of a dispersal end point to be within a small 2D area \f$dA\f$ around the location \f$(x,y)\f$. Since a probability is unitless and \f$dA\f$ is an area, \f$k_L(r)\f$ is expressed in per unit area in a 2D space. -Quetzal automate dimensional analysis and conversion thanks to the `mp-units` library. +Quetzal implements several types of kernel available in the `quetzal::demography::dispersal_kernel` namespace, and automates compile-time dimensional analysis and units conversion thanks to the `mp-units` library. **Input** diff --git a/example/dispersal_kernel.cpp b/example/dispersal_kernel.cpp index d7c011b2..01fad25f 100644 --- a/example/dispersal_kernel.cpp +++ b/example/dispersal_kernel.cpp @@ -8,7 +8,7 @@ int main() { // Shorten notation using namespace mp_units::si::unit_symbols; // SI system: km, m, s - using quetzal::demography::dispersal_kernel::Gaussian; + using quetzal::demography::dispersal_kernel::gaussian; using quetzal::geography::lonlat; // Dispersal kernels operate on distances between geographic coordinates @@ -17,11 +17,11 @@ int main() constexpr auto distance = source.great_circle_distance_to(target) * km; // Used to parametrize the kernel - constexpr auto param = Gaussian<>::param_type {.a=1000.*m}; + constexpr auto param = gaussian<>::param_type {.a=1000.*m}; // Compute quantities - auto p = Gaussian<>::pdf(distance, param); - auto d = Gaussian<>::mean_dispersal_distance(param); + auto p = gaussian<>::pdf(distance, param); + auto d = gaussian<>::mean_dispersal_distance(param); std::cout << "Dispersal from " << source << " to " << target << " :\n" << "distance is " << distance << "\n" diff --git a/src/include/quetzal/demography/dispersal_kernel.hpp b/src/include/quetzal/demography/dispersal_kernel.hpp index 74d4b792..dc7747db 100644 --- a/src/include/quetzal/demography/dispersal_kernel.hpp +++ b/src/include/quetzal/demography/dispersal_kernel.hpp @@ -31,7 +31,7 @@ namespace quetzal /// @details To be used as a reference against leptokurtic kernels. /// Suitable for diffusion-based dispersal or complete random-walk during a constant time. template Distance = mp_units::quantity> - struct Gaussian + struct gaussian { /// @brief Dispersal location kernel parameter @@ -65,7 +65,7 @@ namespace quetzal /// @brief Logistic dispersal location kernel (fat-tailed, power-law tail) /// @ingroup demography /// @details Suitable for frequent long-distance dispersal events and weak effect of distance close to the source. - template Distance> + template Distance = mp_units::quantity> struct logistic { @@ -113,7 +113,7 @@ namespace quetzal /// @details To be used as reference against more fat-tailed kernels. /// Suitable for representing a travel at constant speed in a random direction with a constant /// stopping rate, or a correlated random walk with settlement. - template Distance> + template Distance = mp_units::quantity> struct negative_exponential { /// @brief Dispersal location kernel parameter @@ -149,7 +149,7 @@ namespace quetzal /// @brief Exponential Power dispersal location kernel (\f$b > 1\f$ : thin-tailed, \f$b < 1\f$ : fat-tailed. Always thinner than power laws.) /// @ingroup demography /// @details Suitable for pollen dispersal. Gaussian and Exponential are special cases, making it suitable for shape comparisons. - template Distance> + template Distance = mp_units::quantity> struct exponential_power { /// @brief Dispersal location kernel parameter @@ -194,7 +194,7 @@ namespace quetzal /// @ingroup demography /// @details Suitable for seed dispersal. Obtained as a continuous mixture of Gaussian kernels with variance /// parameters distributed as the inverse of a Gamma distribution. - template Distance> + template Distance = mp_units::quantity> struct two_dt { /// @brief Dispersal location kernel parameter @@ -242,7 +242,7 @@ namespace quetzal /// @brief Inverse Power Law dispersal location kernel (fat-tailed, power-law tail) /// @ingroup demography /// @details Suitable for very fat tails. - template Distance> + template Distance = mp_units::quantity> struct inverse_power_law { /// @brief Dispersal location kernel parameter @@ -288,7 +288,7 @@ namespace quetzal /// @brief Lognormal dispersal location kernel (fat-tailed) /// @ingroup demography /// @details Suitable for seed dispersal, particularly when the peak of the distribution is not at zero distance from the source. - template Distance> + template Distance = mp_units::quantity> struct lognormal { /// @brief Dispersal location kernel parameter @@ -329,7 +329,7 @@ namespace quetzal /// @brief Gaussian Mixture dispersal location kernel (leptokurtic, never fat-tailed) /// @ingroup demography /// @details Used in theoretical studies. - template Distance> + template Distance = mp_units::quantity> struct gaussian_mixture { /// @brief Dispersal location kernel parameter