Table of Contents
-
+
Introduction
Coalescence Binary Trees classes provide a way to guarantee that each vertex \(v\) has exactly
- 0 successor (the vertex is a leaf)
@@ -161,7 +161,7 @@
The graph structure is bidirectional and allows to model a forest of disconnected trees. That is, if a vertex has no predecessor, then it's either a root (if it has 2 successors) or an isolated vertex (if it has no successor).
Users will encounter this type of tree when returning from coalescence binary mergers, or if they simply want to build and manipulate graphs while enforcing a binary tree structure.
-
+
Implementations
Coalescence Binary Trees can store an additional arbitrary type of information (called a Property Class) along their vertices or edges: if the user decides to do so, the tree class interface adapts to offer ways to manipulate this information.
There are logically 4 different classes (equivalently interfaces) resulting from this:
diff --git a/coalescence_k_ary_tree.html b/coalescence_k_ary_tree.html
index 5e8bda35..5612420d 100644
--- a/coalescence_k_ary_tree.html
+++ b/coalescence_k_ary_tree.html
@@ -149,11 +149,11 @@
Table of Contents
-
-
+
Introduction
Coalescence k-ary Trees classes are similar to Binary Trees, but provide an interface guaranteeing that each vertex \(v\) has exactly
- \(0\) successor (the vertex is a leaf)
@@ -161,7 +161,7 @@
The graph structure is bidirectional and allows to model a forest of disconnected trees. That is, if a vertex has no predecessor, then it's either a root (if it has 2 or more successors) or an isolated vertex (if it has no successor).
Users will encounter this type of tree when returning from coalescence multiple mergers, or if they simply want to build and manipulate graphs that do not make strong assumptions on the tree structure.
-
+
Implementations
Coalescence K-ary Trees can store an additional arbitrary type of information (called a Property Class) along their vertices or edges: if the user decides to do so, the tree class interface adapts to offer ways to manipulate this information.
There are logically 4 different classes (equivalently interfaces) resulting from this:
diff --git a/demographic_histories_in_quetzal.html b/demographic_histories_in_quetzal.html
index 116b1807..096f8f13 100644
--- a/demographic_histories_in_quetzal.html
+++ b/demographic_histories_in_quetzal.html
@@ -148,7 +148,7 @@
Demographic Histories in Quetzal
-
+
Background
In population genetics, demographic history refers to the historical changes in population size, structure, and distribution of individuals within a species over time. It encompasses various events and processes that have shaped the genetic diversity and characteristics of a population. Some key aspects of demographic history include:
@@ -158,16 +158,16 @@
- Admixture: Admixture occurs when genetically distinct populations interbreed, leading to the mixing of their genetic material. Admixture can result from migration or colonization events and has a significant influence on genetic diversity.
- Population Isolation: Isolated populations may experience unique evolutionary trajectories due to reduced gene flow and increased genetic drift. This can lead to the development of distinct genetic traits and adaptations.
-
+
Graphs structure
There a different modeling approaches to look at these demographic histories, primarily based on the level of intricacy one intends to incorporate into the framework:
-
+
Phylogenetic Trees
Typically represent a bifurcating pattern of evolution, where each node (or branching point) represents a speciation event. This gives population histories the semantic of a tree graph (called a population tree or species tree), where ancestral populations split into sub-populations, sometimes loosely connected by migration. Gene trees coalesce into these species tree. Genetic inference under this kind of model aims at estimating the tree topology and/or the timing and parameters of events, such as ancestral population size changes and migration rates. It is important to note that in this framework geography is implicit and events such as population size changes and admixture events are explicitely modeled and estimated.
-
+
Phylogenetic Networks
While a phylogenetic tree typically represents a bifurcating pattern of evolution, real-world evolutionary processes can be more intricate. Phylogenetic networks are employed when evolutionary events like horizontal gene transfer, hybridization, recombination, and other reticulate processes are involved. These events can lead to interconnected patterns that cannot be accurately illustrated by a simple tree. Networks with Hybridization are specifically designed to capture the evolutionary relationships of organisms that have undergone hybridization events, where two distinct species interbreed to produce hybrid offspring.
-
+
Spatial Graphs
Another category of models puts an emphasis on the geographic structure of these populations and embed GIS information into the model. Here the demographic history receives the semantic of a dense spatial graph where geolocalized nodes represent demes and local processes whereas edges represent distances and dispersal processes. In this kind of models estimating the individual properties of so many demes is not judicious and genetic inference rather aims at estimating species-wide parameters that link local deme conditions (such as rainfall) to populational processes (like growth rate). It's crucial to understand that within this geospatial framework, events like population changes and admixture events are emergent properties of the model: they are generally not explicitly outlined in the model nor subjected to direct estimation.
diff --git a/dispersal_kernels.html b/dispersal_kernels.html
index 3b579099..9068da69 100644
--- a/dispersal_kernels.html
+++ b/dispersal_kernels.html
@@ -7,7 +7,7 @@
- Quetzal-CoaTL: Spatial Interactions
+ Quetzal-CoaTL: Distance-based dispersal Kernels
@@ -145,23 +145,17 @@
-Spatial Interactions
+Distance-based dispersal Kernels
Table of Contents
-
-
-Distance-Based Kernels
+
+Distance-based kernel
A straightforward approach to determine the dispersal mode across a complete spatial graph involves correlating the geographic distance between two locations with the likelihood of dispersal 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). Additionally, we will calculate essential metrics, such as the distance between two coordinates, the dispersal probability between them, and the average dispersal distance anticipated under this distribution.
-
-Basics
The dispersal location kernel represents the statistical pattern of dispersal distances within a population. In this context, it essentially serves as the probability density function (pdf) that outlines the distribution of locations after dispersal in relation to the original location. The expressions have been adjusted to incorporate a scale parameter, \(a\), which is consistent with a distance unit, and a shape parameter, \(b\), that dictates the curvature of the distribution curve, emphasizing the influence of long-distance events.
For a source \((x_0,y_0)\), the dispersal location kernel denoted as \(k_L(r)\) provides the density of the probability of the dispersal end point in the 2D space. In this case, \(k_L(r)dA\) is the probability of a dispersal end point to be within a small 2D area \(dA\) around the location \((x,y)\). Since a probability is unitless and \(dA\) is an area, \(k_L(r)\) is expressed in per unit area in a 2D space.
Quetzal incorporates various kernel types available in the quetzal::demography::dispersal_kernel namespace, and streamlines compile-time dimensional analysis and units conversion using the mp-units library.
@@ -205,78 +199,13 @@
-
-Using Kernels with Spatial Graphs
-Users can create a spatial graph from landscape data, customizing assumptions about connectivity and topology. By defining a dispersal kernel and calculating dispersal probabilities for each edge based on distance metrics, users can uncover insights into potential dispersal patterns within the spatial graph. This approach offers a powerful means for exploring and understanding spatial dynamics and connectivity, facilitating deeper analysis of ecological or geographic phenomena.
-Input
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 28 auto graph = geo::from_grid(land, vertex_info(), edge_info(), geo::connect_fully(), geo::isotropy(),
-
-
-
-
-
-
-
-
-
-
-
-
-
- 42 | std::views::transform( [&](auto const& e){ return sphere_distance( graph.source( e ), graph.target( e ) );} )
- 43 | std::views::transform( [&](auto distance){ return kernel::pdf( distance, { .a=200.*km , .b=5.5 } ) ;} );
-
-
-
-
-
-Discrete spatio-temporal variations of a set of environmental variables.Definition: landscape.hpp:42
-Individuals can not escape the landscape's borders.Definition: bound_policy.hpp:20
-
-boost::no_property no_propertyRepresents no information carried by vertices or edges of a graph.Definition: concepts.hpp:57
-graph()Default constructor. Initializes a graph with 0 vertices.Definition: graph.hpp:322
-auto from_grid(SpatialGrid const &grid, VertexProperty const &v, EdgeProperty const &e, Vicinity const &vicinity, Directionality dir, Policy const &bounding_policy)Spatial graph construction method.Definition: from_grid.hpp:30
-boost::undirectedS isotropyProperty of a process independent of the direction of movement.Definition: directionality.hpp:18
-Definition: newick_parser_2.cpp:12
-Exponential Power dispersal location kernel ( : thin-tailed, : fat-tailed. Always thinner than powe...Definition: dispersal_kernel.hpp:158
-Definition: vicinity.hpp:53
-Definition: coalescence_binary_tree_2.cpp:5
-Output
-
-@include{lineno} geography_dispersal_kernel_2.txt
-
+
+
- Generated by
1.9.1
diff --git a/expressive_friction.html b/expressive_friction.html
new file mode 100644
index 00000000..f740e6fb
--- /dev/null
+++ b/expressive_friction.html
@@ -0,0 +1,238 @@
+
+
+
+
+
+
+
+
+ Quetzal-CoaTL: Defining a friction model for trans-oceanic dispersal events
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Defining a friction model for trans-oceanic dispersal events
+
+
+- Note
- The objective of this section is to load both a suitability map and a Digital Elevation Model (DEM) with
quetzal::geography::landscape and prepare their integration into the simulation framework with quetzal::expressive and account for trans-oceanic dispersal events by dynamically defining the friction and the carrying capacity of a cell as functions of the suitability and elevation value.
+Drafting events, in the context of biological dispersal, refer to a phenomenon where organisms are carried across large distances by clinging to or being transported by other organisms, objects, or air currents. This can be thought of as a form of passive dispersal where an organism takes advantage of external forces to move beyond its usual range.
+The term "drafting" is borrowed from concepts in physics. In biology, this concept is applied to scenarios where organisms, often small and lightweight, catch a ride on other organisms (like birds, insects, or larger animals), objects (like debris), or wind currents. Drafting events can play a significant role in the dispersal of organisms, especially those with limited mobility.
+These drafting events provide an opportunity for organisms to reach new areas that they might not be able to access through their own locomotion. It's an interesting ecological phenomenon that highlights the intricate ways in which different species interact and influence each other's distribution and survival.
+The general idea is to define lambda expressions that embed stochastic aspects of the model, while preserving the callable interface (space, time) -> double.
+Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 32 auto suit = expressive::use([s_view](location_type x, time_type t) { return s_view(x, t).value_or(0.0); });
+ 33 auto elev = expressive::use([s_view](location_type x, time_type t) { return s_view(x, t).value_or(0.0); });
+
+
+
+
+
+
+
+ 41 return static_cast<double>(d(gen)) * 2; // will (rarely) allow 2 individuals to survive in the ocean cell
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 57 // expressions can be passed to a simulator core and later invoked with a location_type and a time_type argument
+
+
+
+ 61 std::cout << "Friction f( x = " << x << ", t = " << t << " ) = " << rafting_friction(x, t) << std::endl;
+ 62 std::cout << "Carrying capacity K( x = " << x << ", t = " << t << " ) = " << rafting_capacity(x, t) << std::endl;
+
+Discrete spatio-temporal variations of a set of environmental variables.Definition: landscape.hpp:42
+constexpr auto use(F f)Transforms functions into operator friendly classes.Definition: expressive.hpp:205
+
+Output
+
+
+
+
+
+
+
+
+ - Generated by 1.9.1
+
+
+
+
diff --git a/expressive_suitability_DEM_landscape.html b/expressive_suitability_DEM_landscape.html
new file mode 100644
index 00000000..94ce9228
--- /dev/null
+++ b/expressive_suitability_DEM_landscape.html
@@ -0,0 +1,240 @@
+
+
+
+
+
+
+
+
+ Quetzal-CoaTL: Adjusting a suitability map using a Digital Elevation Model
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Adjusting a suitability map using a Digital Elevation Model
+
+
+- Note
- The objective of this section is to load both a suitability map and a Digital Elevation Model (DEM) with
quetzal::geography::landscape and prepare their integration into the simulation framework with quetzal::expressive by dynamically modulating the suitability value as a function of the local elevation.
+
+Why separating Elevation from Suitability ?
+It is a common approach to pack a wealth of information into a sole raster file. For instance, this can involve using a single friction file and designating ocean cells with NA values, and obstacles for dispersal with values of 1. Another way is to try to inject elevational data into the suitability map during the Ecological Niche Modeling step.
+While these approaches are feasible and occasionally advantageous, they do not consistently represent the optimal or most adaptable solution.
+In a broader sense, it's advisable to consider each Geographic Information System (GIS) input file as a means of representing a distinct attribute of the landscape such as suitability, friction, or elevation, utilizing quetzal::geography::landscape to read and align these input files then utilizing quetzal::expressive to adjust or combine these quantities according to the user's modeling intentions.
+As an illustration we will show in this example how to adjust the stochasticity of a suitability-driven process as a function of the elevation model. This case and its variations can be applicable in various contexts:
+
+- Conveniently enforcing a threshold value beyond which the suitability undergoes a significant change (e.g., becoming 0). This approach is valuable for examining sky-island systems or for easily estimating an isoline by dynamically adjusting the cutoff parameter value at runtime, as opposed to altering input files for every simulation run.
+- Depicting the likelihood of a propagule reaching a nunatak, that is a small-scale suitable shelter protruding from the snow sheet (or ice cap). Typically nunataks are the only places where plants can survive in these environments.
+
+Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 32 auto suit = expressive::use([s_view](location_type x, time_type t) { return s_view(x, t).value_or(0.0); });
+ 33 auto elev = expressive::use([e_view](location_type x, time_type t) { return e_view(x, t).value_or(0.0); });
+
+
+
+
+ 38 // 1) hostile environment above an isoline: particularly useful if 123.0 is a randomly sampled parameter to be
+
+
+
+
+
+ 44 // 2) small-scale suitable ice-free shelters randomly popping above the snow cover at high-altitude
+
+
+
+
+
+
+ 51 // expressions can be passed to a simulator core and later invoked with a location_type and a time_type argument
+
+
+
+ 55 std::cout << "Suitability w/ isoline ( x = " << x << ", t = " << t << " ) = " << isoline_suitability(x, t)
+
+ 57 std::cout << "Suitability w/ shelter ( x = " << x << ", t = " << t << " ) = " << nunatak_suitability(x, t)
+
+
+Discrete spatio-temporal variations of a set of environmental variables.Definition: landscape.hpp:42
+constexpr auto use(F f)Transforms functions into operator friendly classes.Definition: expressive.hpp:205
+
+Output
+
+
+
+
+
+
+
+
+ - Generated by 1.9.1
+
+
+
+
diff --git a/expressive_suitability_raster.html b/expressive_suitability_raster.html
new file mode 100644
index 00000000..ef1c794c
--- /dev/null
+++ b/expressive_suitability_raster.html
@@ -0,0 +1,218 @@
+
+
+
+
+
+
+
+
+ Quetzal-CoaTL: Preparing a suitability landscape for the simulation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Preparing a suitability landscape for the simulation
+
+
+- Note
- The objective of this section is to load a suitability map with
quetzal::geography::raster and prepare its integration into the simulation framework with quetzal::expressive.
+In the context of ecological niche modeling (ENM), suitability refers to the degree of appropriateness or favorability of a particular environmental condition for a species to thrive and persist. ENM is a technique used in ecology to predict the distribution of species across landscapes based on their known occurrences and environmental variables.
+Suitability can be thought of as a spectrum, ranging from conditions that are highly suitable for a species' survival and reproduction to conditions that are unsuitable or even detrimental. ENM attempts to map this spectrum across geographical space by analyzing the relationships between species occurrences and various environmental factors, such as temperature, precipitation, elevation, soil type, and vegetation cover.
+It's important to note that suitability does not solely depend on a single environmental variable. Instead, it's a complex interplay of multiple factors that determine whether a species can survive, reproduce, and establish a viable population in a given area. Suitability GIS maps derived from previous analysis steps (see e.g. the niche models in Quetzal-crumbs python package) can then be integrated into the coalescence simulation framework.
+The following example code
+- loads a suitability map using
quetzal::geography::raster
+- prepares its integration into the simulation framework using
quetzal::expressive
+- it gives to the suitability the semantic of a function of space and time
f(x,t)
+- it gives it access to mathematical operators with
quetzal::expressive::use
+- then it builds upon it to define an (arbitrary) expression of e.g. the growth rate (but it could be friction, or carrying capacity...)
+
+Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Discrete spatio-temporal variations of an environmental variable.Definition: raster.hpp:38
+constexpr auto use(F f)Transforms functions into operator friendly classes.Definition: expressive.hpp:205
+
+Transforms literals into operator friendly classes.Definition: expressive.hpp:263
+Output
+
+
+
+
+
+
+
+
+ - Generated by 1.9.1
+
+
+
+
diff --git a/from__grid_8hpp_source.html b/from__grid_8hpp_source.html
index e1b55caf..8ad1201f 100644
--- a/from__grid_8hpp_source.html
+++ b/from__grid_8hpp_source.html
@@ -166,25 +166,14 @@
33 using graph_type = quetzal::geography::graph<VertexProperty, EdgeProperty, typename Vicinity::connectedness, Directionality>;
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ 34 // using graph_type = typename Vicinity::graph_type<Directionality, VertexProperty, EdgeProperty>;
+
+
+
+
+
+
+
Definition: graph.hpp:262
graph()Default constructor. Initializes a graph with 0 vertices.Definition: graph.hpp:322
diff --git a/geotiff_parser.html b/geotiff_parser.html
index f6baea4f..e91c44fa 100644
--- a/geotiff_parser.html
+++ b/geotiff_parser.html
@@ -149,17 +149,17 @@
Introduction
Coalescence Binary Trees classes provide a way to guarantee that each vertex \(v\) has exactly
- 0 successor (the vertex is a leaf) @@ -161,7 +161,7 @@
The graph structure is bidirectional and allows to model a forest of disconnected trees. That is, if a vertex has no predecessor, then it's either a root (if it has 2 successors) or an isolated vertex (if it has no successor).
Users will encounter this type of tree when returning from coalescence binary mergers, or if they simply want to build and manipulate graphs while enforcing a binary tree structure.
-
+
Implementations
Coalescence Binary Trees can store an additional arbitrary type of information (called a Property Class) along their vertices or edges: if the user decides to do so, the tree class interface adapts to offer ways to manipulate this information.
There are logically 4 different classes (equivalently interfaces) resulting from this:
-
diff --git a/coalescence_k_ary_tree.html b/coalescence_k_ary_tree.html
index 5e8bda35..5612420d 100644
--- a/coalescence_k_ary_tree.html
+++ b/coalescence_k_ary_tree.html
@@ -149,11 +149,11 @@
Table of Contents
-
+
Introduction
Coalescence k-ary Trees classes are similar to Binary Trees, but provide an interface guaranteeing that each vertex \(v\) has exactly
- \(0\) successor (the vertex is a leaf)
@@ -161,7 +161,7 @@
The graph structure is bidirectional and allows to model a forest of disconnected trees. That is, if a vertex has no predecessor, then it's either a root (if it has 2 or more successors) or an isolated vertex (if it has no successor).
Users will encounter this type of tree when returning from coalescence multiple mergers, or if they simply want to build and manipulate graphs that do not make strong assumptions on the tree structure.
-
+
Implementations
Coalescence K-ary Trees can store an additional arbitrary type of information (called a Property Class) along their vertices or edges: if the user decides to do so, the tree class interface adapts to offer ways to manipulate this information.
There are logically 4 different classes (equivalently interfaces) resulting from this:
diff --git a/demographic_histories_in_quetzal.html b/demographic_histories_in_quetzal.html
index 116b1807..096f8f13 100644
--- a/demographic_histories_in_quetzal.html
+++ b/demographic_histories_in_quetzal.html
@@ -148,7 +148,7 @@
Demographic Histories in Quetzal
Introduction
Coalescence k-ary Trees classes are similar to Binary Trees, but provide an interface guaranteeing that each vertex \(v\) has exactly
- \(0\) successor (the vertex is a leaf) @@ -161,7 +161,7 @@
The graph structure is bidirectional and allows to model a forest of disconnected trees. That is, if a vertex has no predecessor, then it's either a root (if it has 2 or more successors) or an isolated vertex (if it has no successor).
Users will encounter this type of tree when returning from coalescence multiple mergers, or if they simply want to build and manipulate graphs that do not make strong assumptions on the tree structure.
-
+
Implementations
Coalescence K-ary Trees can store an additional arbitrary type of information (called a Property Class) along their vertices or edges: if the user decides to do so, the tree class interface adapts to offer ways to manipulate this information.
There are logically 4 different classes (equivalently interfaces) resulting from this:
-
diff --git a/demographic_histories_in_quetzal.html b/demographic_histories_in_quetzal.html
index 116b1807..096f8f13 100644
--- a/demographic_histories_in_quetzal.html
+++ b/demographic_histories_in_quetzal.html
@@ -148,7 +148,7 @@
Demographic Histories in Quetzal
-
+
+
Background
In population genetics, demographic history refers to the historical changes in population size, structure, and distribution of individuals within a species over time. It encompasses various events and processes that have shaped the genetic diversity and characteristics of a population. Some key aspects of demographic history include:
@@ -158,16 +158,16 @@
- Admixture: Admixture occurs when genetically distinct populations interbreed, leading to the mixing of their genetic material. Admixture can result from migration or colonization events and has a significant influence on genetic diversity.
- Population Isolation: Isolated populations may experience unique evolutionary trajectories due to reduced gene flow and increased genetic drift. This can lead to the development of distinct genetic traits and adaptations.
-
+
Graphs structure
There a different modeling approaches to look at these demographic histories, primarily based on the level of intricacy one intends to incorporate into the framework:
-
+
Phylogenetic Trees
Typically represent a bifurcating pattern of evolution, where each node (or branching point) represents a speciation event. This gives population histories the semantic of a tree graph (called a population tree or species tree), where ancestral populations split into sub-populations, sometimes loosely connected by migration. Gene trees coalesce into these species tree. Genetic inference under this kind of model aims at estimating the tree topology and/or the timing and parameters of events, such as ancestral population size changes and migration rates. It is important to note that in this framework geography is implicit and events such as population size changes and admixture events are explicitely modeled and estimated.
-
+
Phylogenetic Networks
While a phylogenetic tree typically represents a bifurcating pattern of evolution, real-world evolutionary processes can be more intricate. Phylogenetic networks are employed when evolutionary events like horizontal gene transfer, hybridization, recombination, and other reticulate processes are involved. These events can lead to interconnected patterns that cannot be accurately illustrated by a simple tree. Networks with Hybridization are specifically designed to capture the evolutionary relationships of organisms that have undergone hybridization events, where two distinct species interbreed to produce hybrid offspring.
-
+
Spatial Graphs
Another category of models puts an emphasis on the geographic structure of these populations and embed GIS information into the model. Here the demographic history receives the semantic of a dense spatial graph where geolocalized nodes represent demes and local processes whereas edges represent distances and dispersal processes. In this kind of models estimating the individual properties of so many demes is not judicious and genetic inference rather aims at estimating species-wide parameters that link local deme conditions (such as rainfall) to populational processes (like growth rate). It's crucial to understand that within this geospatial framework, events like population changes and admixture events are emergent properties of the model: they are generally not explicitly outlined in the model nor subjected to direct estimation.
diff --git a/dispersal_kernels.html b/dispersal_kernels.html
index 3b579099..9068da69 100644
--- a/dispersal_kernels.html
+++ b/dispersal_kernels.html
@@ -7,7 +7,7 @@
- Quetzal-CoaTL: Spatial Interactions
+ Quetzal-CoaTL: Distance-based dispersal Kernels
@@ -145,23 +145,17 @@
-Spatial Interactions
+Distance-based dispersal Kernels
Table of Contents
-
-
-Distance-Based Kernels
+
+Distance-based kernel
A straightforward approach to determine the dispersal mode across a complete spatial graph involves correlating the geographic distance between two locations with the likelihood of dispersal 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). Additionally, we will calculate essential metrics, such as the distance between two coordinates, the dispersal probability between them, and the average dispersal distance anticipated under this distribution.
-
-Basics
The dispersal location kernel represents the statistical pattern of dispersal distances within a population. In this context, it essentially serves as the probability density function (pdf) that outlines the distribution of locations after dispersal in relation to the original location. The expressions have been adjusted to incorporate a scale parameter, \(a\), which is consistent with a distance unit, and a shape parameter, \(b\), that dictates the curvature of the distribution curve, emphasizing the influence of long-distance events.
For a source \((x_0,y_0)\), the dispersal location kernel denoted as \(k_L(r)\) provides the density of the probability of the dispersal end point in the 2D space. In this case, \(k_L(r)dA\) is the probability of a dispersal end point to be within a small 2D area \(dA\) around the location \((x,y)\). Since a probability is unitless and \(dA\) is an area, \(k_L(r)\) is expressed in per unit area in a 2D space.
Quetzal incorporates various kernel types available in the quetzal::demography::dispersal_kernel namespace, and streamlines compile-time dimensional analysis and units conversion using the mp-units library.
@@ -205,78 +199,13 @@
-
-Using Kernels with Spatial Graphs
-Users can create a spatial graph from landscape data, customizing assumptions about connectivity and topology. By defining a dispersal kernel and calculating dispersal probabilities for each edge based on distance metrics, users can uncover insights into potential dispersal patterns within the spatial graph. This approach offers a powerful means for exploring and understanding spatial dynamics and connectivity, facilitating deeper analysis of ecological or geographic phenomena.
-Input
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 28 auto graph = geo::from_grid(land, vertex_info(), edge_info(), geo::connect_fully(), geo::isotropy(),
-
-
-
-
-
-
-
-
-
-
-
-
-
- 42 | std::views::transform( [&](auto const& e){ return sphere_distance( graph.source( e ), graph.target( e ) );} )
- 43 | std::views::transform( [&](auto distance){ return kernel::pdf( distance, { .a=200.*km , .b=5.5 } ) ;} );
-
-
-
-
-
-Discrete spatio-temporal variations of a set of environmental variables.Definition: landscape.hpp:42
-Individuals can not escape the landscape's borders.Definition: bound_policy.hpp:20
-
-boost::no_property no_propertyRepresents no information carried by vertices or edges of a graph.Definition: concepts.hpp:57
-graph()Default constructor. Initializes a graph with 0 vertices.Definition: graph.hpp:322
-auto from_grid(SpatialGrid const &grid, VertexProperty const &v, EdgeProperty const &e, Vicinity const &vicinity, Directionality dir, Policy const &bounding_policy)Spatial graph construction method.Definition: from_grid.hpp:30
-boost::undirectedS isotropyProperty of a process independent of the direction of movement.Definition: directionality.hpp:18
-Definition: newick_parser_2.cpp:12
-Exponential Power dispersal location kernel ( : thin-tailed, : fat-tailed. Always thinner than powe...Definition: dispersal_kernel.hpp:158
-Definition: vicinity.hpp:53
-Definition: coalescence_binary_tree_2.cpp:5
-Output
-
-@include{lineno} geography_dispersal_kernel_2.txt
-
+
Background
In population genetics, demographic history refers to the historical changes in population size, structure, and distribution of individuals within a species over time. It encompasses various events and processes that have shaped the genetic diversity and characteristics of a population. Some key aspects of demographic history include:
-
@@ -158,16 +158,16 @@
- Admixture: Admixture occurs when genetically distinct populations interbreed, leading to the mixing of their genetic material. Admixture can result from migration or colonization events and has a significant influence on genetic diversity.
- Population Isolation: Isolated populations may experience unique evolutionary trajectories due to reduced gene flow and increased genetic drift. This can lead to the development of distinct genetic traits and adaptations.
+
Graphs structure
There a different modeling approaches to look at these demographic histories, primarily based on the level of intricacy one intends to incorporate into the framework:
-
+
Phylogenetic Trees
Typically represent a bifurcating pattern of evolution, where each node (or branching point) represents a speciation event. This gives population histories the semantic of a tree graph (called a population tree or species tree), where ancestral populations split into sub-populations, sometimes loosely connected by migration. Gene trees coalesce into these species tree. Genetic inference under this kind of model aims at estimating the tree topology and/or the timing and parameters of events, such as ancestral population size changes and migration rates. It is important to note that in this framework geography is implicit and events such as population size changes and admixture events are explicitely modeled and estimated.
-
+
Phylogenetic Networks
While a phylogenetic tree typically represents a bifurcating pattern of evolution, real-world evolutionary processes can be more intricate. Phylogenetic networks are employed when evolutionary events like horizontal gene transfer, hybridization, recombination, and other reticulate processes are involved. These events can lead to interconnected patterns that cannot be accurately illustrated by a simple tree. Networks with Hybridization are specifically designed to capture the evolutionary relationships of organisms that have undergone hybridization events, where two distinct species interbreed to produce hybrid offspring.
-
+
Spatial Graphs
Another category of models puts an emphasis on the geographic structure of these populations and embed GIS information into the model. Here the demographic history receives the semantic of a dense spatial graph where geolocalized nodes represent demes and local processes whereas edges represent distances and dispersal processes. In this kind of models estimating the individual properties of so many demes is not judicious and genetic inference rather aims at estimating species-wide parameters that link local deme conditions (such as rainfall) to populational processes (like growth rate). It's crucial to understand that within this geospatial framework, events like population changes and admixture events are emergent properties of the model: they are generally not explicitly outlined in the model nor subjected to direct estimation.
diff --git a/dispersal_kernels.html b/dispersal_kernels.html index 3b579099..9068da69 100644 --- a/dispersal_kernels.html +++ b/dispersal_kernels.html @@ -7,7 +7,7 @@ -
-
+Spatial Interactions
Distance-based dispersal Kernels
Table of Contents
--Distance-Based Kernels
++Distance-based kernel
A straightforward approach to determine the dispersal mode across a complete spatial graph involves correlating the geographic distance between two locations with the likelihood of dispersal 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). Additionally, we will calculate essential metrics, such as the distance between two coordinates, the dispersal probability between them, and the average dispersal distance anticipated under this distribution.
--Basics
The dispersal location kernel represents the statistical pattern of dispersal distances within a population. In this context, it essentially serves as the probability density function (pdf) that outlines the distribution of locations after dispersal in relation to the original location. The expressions have been adjusted to incorporate a scale parameter, \(a\), which is consistent with a distance unit, and a shape parameter, \(b\), that dictates the curvature of the distribution curve, emphasizing the influence of long-distance events.
For a source \((x_0,y_0)\), the dispersal location kernel denoted as \(k_L(r)\) provides the density of the probability of the dispersal end point in the 2D space. In this case, \(k_L(r)dA\) is the probability of a dispersal end point to be within a small 2D area \(dA\) around the location \((x,y)\). Since a probability is unitless and \(dA\) is an area, \(k_L(r)\) is expressed in per unit area in a 2D space.
Quetzal incorporates various kernel types available in the quetzal::demography::dispersal_kernel namespace, and streamlines compile-time dimensional analysis and units conversion using the mp-units library.
-
-Using Kernels with Spatial Graphs
-Users can create a spatial graph from landscape data, customizing assumptions about connectivity and topology. By defining a dispersal kernel and calculating dispersal probabilities for each edge based on distance metrics, users can uncover insights into potential dispersal patterns within the spatial graph. This approach offers a powerful means for exploring and understanding spatial dynamics and connectivity, facilitating deeper analysis of ecological or geographic phenomena.
-Input
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
28 auto graph = geo::from_grid(land, vertex_info(), edge_info(), geo::connect_fully(), geo::isotropy(),
-
-
-
-
-
-
-
-
-
-
-
-
-
- 42 | std::views::transform( [&](auto const& e){ return sphere_distance( graph.source( e ), graph.target( e ) );} )
- 43 | std::views::transform( [&](auto distance){ return kernel::pdf( distance, { .a=200.*km , .b=5.5 } ) ;} );
-
-
-
-
-
-Discrete spatio-temporal variations of a set of environmental variables.
Definition: landscape.hpp:42
Individuals can not escape the landscape's borders.
Definition: bound_policy.hpp:20
boost::no_property no_property
Represents no information carried by vertices or edges of a graph.
Definition: concepts.hpp:57
graph()
Default constructor. Initializes a graph with 0 vertices.
Definition: graph.hpp:322
auto from_grid(SpatialGrid const &grid, VertexProperty const &v, EdgeProperty const &e, Vicinity const &vicinity, Directionality dir, Policy const &bounding_policy)
Spatial graph construction method.
Definition: from_grid.hpp:30
boost::undirectedS isotropy
Property of a process independent of the direction of movement.
Definition: directionality.hpp:18
Definition: newick_parser_2.cpp:12
Exponential Power dispersal location kernel ( : thin-tailed, : fat-tailed. Always thinner than powe...
Definition: dispersal_kernel.hpp:158
Definition: vicinity.hpp:53
Definition: coalescence_binary_tree_2.cpp:5
Output
--@include{lineno} geography_dispersal_kernel_2.txt
--
+
- Generated by 1.9.1
+
+
+
+
+
+
+
+
+
+
+ |
+
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+Defining a friction model for trans-oceanic dispersal events
+
+
+- Note
- The objective of this section is to load both a suitability map and a Digital Elevation Model (DEM) with
quetzal::geography::landscapeand prepare their integration into the simulation framework withquetzal::expressiveand account for trans-oceanic dispersal events by dynamically defining the friction and the carrying capacity of a cell as functions of the suitability and elevation value.
Drafting events, in the context of biological dispersal, refer to a phenomenon where organisms are carried across large distances by clinging to or being transported by other organisms, objects, or air currents. This can be thought of as a form of passive dispersal where an organism takes advantage of external forces to move beyond its usual range.
+The term "drafting" is borrowed from concepts in physics. In biology, this concept is applied to scenarios where organisms, often small and lightweight, catch a ride on other organisms (like birds, insects, or larger animals), objects (like debris), or wind currents. Drafting events can play a significant role in the dispersal of organisms, especially those with limited mobility.
+These drafting events provide an opportunity for organisms to reach new areas that they might not be able to access through their own locomotion. It's an interesting ecological phenomenon that highlights the intricate ways in which different species interact and influence each other's distribution and survival.
+The general idea is to define lambda expressions that embed stochastic aspects of the model, while preserving the callable interface (space, time) -> double.
Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
32 auto suit = expressive::use([s_view](location_type x, time_type t) { return s_view(x, t).value_or(0.0); });
+ 33 auto elev = expressive::use([s_view](location_type x, time_type t) { return s_view(x, t).value_or(0.0); });
+
+
+
+
+
+
+
+ 41 return static_cast<double>(d(gen)) * 2; // will (rarely) allow 2 individuals to survive in the ocean cell
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 57 // expressions can be passed to a simulator core and later invoked with a location_type and a time_type argument
+
+
+
+ 61 std::cout << "Friction f( x = " << x << ", t = " << t << " ) = " << rafting_friction(x, t) << std::endl;
+ 62 std::cout << "Carrying capacity K( x = " << x << ", t = " << t << " ) = " << rafting_capacity(x, t) << std::endl;
+
+Discrete spatio-temporal variations of a set of environmental variables.
Definition: landscape.hpp:42
constexpr auto use(F f)
Transforms functions into operator friendly classes.
Definition: expressive.hpp:205
Output
++
-
+
+
- Generated by 1.9.1
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+Adjusting a suitability map using a Digital Elevation Model
+
+
+- Note
- The objective of this section is to load both a suitability map and a Digital Elevation Model (DEM) with
quetzal::geography::landscapeand prepare their integration into the simulation framework withquetzal::expressiveby dynamically modulating the suitability value as a function of the local elevation.
+Why separating Elevation from Suitability ?
+It is a common approach to pack a wealth of information into a sole raster file. For instance, this can involve using a single friction file and designating ocean cells with NA values, and obstacles for dispersal with values of 1. Another way is to try to inject elevational data into the suitability map during the Ecological Niche Modeling step.
+While these approaches are feasible and occasionally advantageous, they do not consistently represent the optimal or most adaptable solution.
+In a broader sense, it's advisable to consider each Geographic Information System (GIS) input file as a means of representing a distinct attribute of the landscape such as suitability, friction, or elevation, utilizing quetzal::geography::landscape to read and align these input files then utilizing quetzal::expressive to adjust or combine these quantities according to the user's modeling intentions.
As an illustration we will show in this example how to adjust the stochasticity of a suitability-driven process as a function of the elevation model. This case and its variations can be applicable in various contexts:
+-
+
- Conveniently enforcing a threshold value beyond which the suitability undergoes a significant change (e.g., becoming 0). This approach is valuable for examining sky-island systems or for easily estimating an isoline by dynamically adjusting the cutoff parameter value at runtime, as opposed to altering input files for every simulation run. +
- Depicting the likelihood of a propagule reaching a nunatak, that is a small-scale suitable shelter protruding from the snow sheet (or ice cap). Typically nunataks are the only places where plants can survive in these environments. +
Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
32 auto suit = expressive::use([s_view](location_type x, time_type t) { return s_view(x, t).value_or(0.0); });
+ 33 auto elev = expressive::use([e_view](location_type x, time_type t) { return e_view(x, t).value_or(0.0); });
+
+
+
+
+ 38 // 1) hostile environment above an isoline: particularly useful if 123.0 is a randomly sampled parameter to be
+
+
+
+
+
+ 44 // 2) small-scale suitable ice-free shelters randomly popping above the snow cover at high-altitude
+
+
+
+
+
+
+ 51 // expressions can be passed to a simulator core and later invoked with a location_type and a time_type argument
+
+
+
+ 55 std::cout << "Suitability w/ isoline ( x = " << x << ", t = " << t << " ) = " << isoline_suitability(x, t)
+
+ 57 std::cout << "Suitability w/ shelter ( x = " << x << ", t = " << t << " ) = " << nunatak_suitability(x, t)
+
+
+Discrete spatio-temporal variations of a set of environmental variables.
Definition: landscape.hpp:42
constexpr auto use(F f)
Transforms functions into operator friendly classes.
Definition: expressive.hpp:205
Output
++
-
+
+
- Generated by 1.9.1
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+Preparing a suitability landscape for the simulation
+
+
+- Note
- The objective of this section is to load a suitability map with
quetzal::geography::rasterand prepare its integration into the simulation framework withquetzal::expressive.
In the context of ecological niche modeling (ENM), suitability refers to the degree of appropriateness or favorability of a particular environmental condition for a species to thrive and persist. ENM is a technique used in ecology to predict the distribution of species across landscapes based on their known occurrences and environmental variables.
+Suitability can be thought of as a spectrum, ranging from conditions that are highly suitable for a species' survival and reproduction to conditions that are unsuitable or even detrimental. ENM attempts to map this spectrum across geographical space by analyzing the relationships between species occurrences and various environmental factors, such as temperature, precipitation, elevation, soil type, and vegetation cover.
+It's important to note that suitability does not solely depend on a single environmental variable. Instead, it's a complex interplay of multiple factors that determine whether a species can survive, reproduce, and establish a viable population in a given area. Suitability GIS maps derived from previous analysis steps (see e.g. the niche models in Quetzal-crumbs python package) can then be integrated into the coalescence simulation framework.
+The following example code
-
+
- loads a suitability map using
quetzal::geography::raster
+ - prepares its integration into the simulation framework using
quetzal::expressive
+ - it gives to the suitability the semantic of a function of space and time
f(x,t)
+ - it gives it access to mathematical operators with
quetzal::expressive::use
+ - then it builds upon it to define an (arbitrary) expression of e.g. the growth rate (but it could be friction, or carrying capacity...) +
Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Discrete spatio-temporal variations of an environmental variable.
Definition: raster.hpp:38
constexpr auto use(F f)
Transforms functions into operator friendly classes.
Definition: expressive.hpp:205
Transforms literals into operator friendly classes.
Definition: expressive.hpp:263
Output
++
-
+
+
- Generated by 1.9.1
+
Definition: graph.hpp:262
graph()
Default constructor. Initializes a graph with 0 vertices.
Definition: graph.hpp:322
Table of Contents
-
+
Reading a single variable
Landscapes, along with their spatial and temporal heterogeneity, play a significant role in shaping the dynamics of populations and lineages. In computational models, these landscapes are often represented as geospatial grids or rasters.
In most analyses, it is common for users to establish connections between local growth processes and a habitability raster obtained from Ecological Niche Models. Additionally, they may associate dispersal or connectivity with a Digital Elevation Model.
@@ -313,7 +313,7 @@
-
+
Reading multiple variables
Reading a single variable
Landscapes, along with their spatial and temporal heterogeneity, play a significant role in shaping the dynamics of populations and lineages. In computational models, these landscapes are often represented as geospatial grids or rasters.
In most analyses, it is common for users to establish connections between local growth processes and a habitability raster obtained from Ecological Niche Models. Additionally, they may associate dispersal or connectivity with a Digital Elevation Model.
@@ -313,7 +313,7 @@Reading multiple variables
Aligning rasters refers to a spatial data representation technique used in Geographic Information Systems (GIS). In this context, raster data layers are aligned and registered to a common coordinate system and grid structure. This ensures that the cells or pixels in the raster layers are spatially aligned and correspond to the same geographic locations.
Alignment is achieved in quetzal::geography::raster objects by defining a consistent grid structure, such as a uniform cell size and orientation, for all raster layers.
-
+
Next steps
Geospatial datasets play a crucial role in coalescence by providing valuable information about the demographic process. Once a raster is successfully parsed, users typically have three primary objectives they may want to pursue:
-
+
Demes on a regular spatial grid
The rasters grid structure can be employed to construct a spatial graph of demes that is fully connected and utilized for simulating the demographic process. This is pertinent when looking at very larged continuous land masses. In this context:
-
@@ -393,12 +393,12 @@
- Edges represent the distances between demes, and their connectivity can be modified using dispersal kernels.
-
+
Demes on a variable spatial graph
In archipelagos or clusters of loosely connected islands, the fluctuations in sea levels have a notable impact on the dynamics of species. These variations cause the intermittent connection and separation of land masses and their corresponding populations. Similarly, climatic shifts in sky-island complexes can have similar effects. As a result, the assumption of a completely interconnected graph representing population units (demes) is no longer applicable in these situations.
To address this, Digital Elevation Models (DEMs) can be utilized to establish a relationship between the dynamics of sea levels and species. In these cases, the connectivity of the graph at any given time is determined by the current elevation, and changes in elevation directly impact the level of connectivity between different areas.
-
+
Inform local processes
Ecological Niche Models (ENMs) play a crucial role in predicting how populations might respond to changes in climate, both in the past and the future.
Typically, these models produce raster outputs that represent estimates of suitability. These suitability values are then utilized to determine growth rates and carrying capacity.
diff --git a/graphs_in_quetzal.html b/graphs_in_quetzal.html index 933daeb4..0921743d 100644 --- a/graphs_in_quetzal.html +++ b/graphs_in_quetzal.html @@ -149,35 +149,35 @@Table of Contents
-Although graphs are ubiquitous in phylogeography and coalescence frameworks, they can represent quite different objects depending on the exact context. Consequently Quetzal had to make a number of design choices in their implementation.
-
+
Invariants Guarantee
As geneticists, we expect from a simple Kingman coalescent tree to exhibit certain characteristics (for example the guarantee of having either 0 or 2 children but never only 1) that we don't expect from a phylogenetic network (that would in contrast exhibit cycles and hybrid nodes).
In programming jargon, these expectations are called class invariants.
Rather than exposing a 1-fit-all type of graph and be prone to programming mistakes, Quetzal comes with more specialized classes that maintain their invariants.
-
+
Edge and Vertices descriptors
A point common to all class of graphs is that vertices and edges have unique identifiers.
This identifier is implementation-dependent and not always of type int. It is instead referred by a type nested in each graph class: vertex_descriptor and edge_descriptor.
Methods of a class that receive or return specific edges/vertices will manipulate objects of this type.
-
+
Edge and Vertices Information (Property Classes)
The quality of information attached to the vertices and edges of a graph also varies depending on the user problem.
For example, a spatial coalescent tree may need a way to store the geographic location of the visited locations, whereas a Kingman coalescent tree does not need to allocated storage for this. Similarly, Phylogenetic Networks will surely embed completely different types of information, like \(\gamma\), the inheritance probability.
To reflect this variability in the type of information, graphs can embed arbitrary information along edges and vertices through small user-defined classes called property classes.
The type of information a graph class embeds is referred by a nested type: vertex_property and edge_property.
+
Depth First Search (DFS) Algorithms
DFS is a form of graph traversal referering to the process of visiting (e.g. retrieving, updating, or deleting) each node in a tree data structure, exactly once.
-
+
DFS on trees
When the graph has the structure of a tree, there are only three operations that are worth worrying about:
pre-order,
diff --git a/md_99_developers_notes.html b/md_99_developers_notes.html
index 40647369..f673008c 100644
--- a/md_99_developers_notes.html
+++ b/md_99_developers_notes.html
@@ -148,7 +148,7 @@
Developer's notes
-
+
+
+
+
diff --git a/namespaceboost.js b/namespaceboost.js
index 6e6fdc8f..23b3a05f 100644
--- a/namespaceboost.js
+++ b/namespaceboost.js
@@ -1,5 +1,53 @@
var namespaceboost =
[
+ [ "Objectives", "newick_generator.html#autotoc_md53", null ],
+ [ "From a Quetzal binary tree", "newick_generator.html#autotoc_md55", [
+ [ "No property", "newick_generator.html#autotoc_md57", null ],
+ [ "Custom properties", "newick_generator.html#autotoc_md59", null ]
+ ] ],
+ [ "From a Quetzal k-ary tree", "newick_generator.html#autotoc_md61", [
+ [ "No property", "newick_generator.html#autotoc_md63", null ],
+ [ "Custom properties", "newick_generator.html#autotoc_md65", null ]
+ ] ],
+ [ "Interfacing legacy code", "newick_generator.html#autotoc_md67", [
+ [ "No property", "newick_generator.html#autotoc_md69", null ],
+ [ "Custom properties", "newick_generator.html#autotoc_md71", null ]
+ ] ],
+ [ "Reading a single variable", "geotiff_parser.html#autotoc_md81", null ],
+ [ "Reading multiple variables", "geotiff_parser.html#autotoc_md83", null ],
+ [ "Next steps", "geotiff_parser.html#autotoc_md85", [
+ [ "Demes on a regular spatial grid", "geotiff_parser.html#autotoc_md87", null ],
+ [ "Demes on a variable spatial graph", "geotiff_parser.html#autotoc_md89", null ],
+ [ "Inform local processes", "geotiff_parser.html#autotoc_md91", null ]
+ ] ],
+ [ "Why separating Elevation from Suitability ?", "expressive_suitability_DEM_landscape.html#autotoc_md97", null ],
+ [ "Background", "demographic_histories_in_quetzal.html#autotoc_md100", null ],
+ [ "Graphs structure", "demographic_histories_in_quetzal.html#autotoc_md101", [
+ [ "Phylogenetic Trees", "demographic_histories_in_quetzal.html#autotoc_md102", null ],
+ [ "Phylogenetic Networks", "demographic_histories_in_quetzal.html#autotoc_md103", null ],
+ [ "Spatial Graphs", "demographic_histories_in_quetzal.html#autotoc_md104", null ]
+ ] ],
+ [ "Background", "spatial_graphs.html#autotoc_md106", null ],
+ [ "Assumptions", "spatial_graphs.html#autotoc_md107", [
+ [ "Vicinity", "spatial_graphs.html#autotoc_md108", null ],
+ [ "Bounding policy", "spatial_graphs.html#autotoc_md109", null ],
+ [ "Directionality", "spatial_graphs.html#autotoc_md110", null ]
+ ] ],
+ [ "Example", "spatial_graphs.html#autotoc_md111", null ],
+ [ "Background", "spatial_graph_construction.html#autotoc_md113", null ],
+ [ "Graph from raster", "spatial_graph_construction.html#autotoc_md114", null ],
+ [ "Graph from landscape", "spatial_graph_construction.html#autotoc_md115", null ],
+ [ "Graph from abstract grid", "spatial_graph_construction.html#autotoc_md116", null ],
+ [ "From scratch", "spatial_graph_construction.html#autotoc_md117", [
+ [ "Sparse Graph", "spatial_graph_construction.html#autotoc_md118", null ],
+ [ "Dense Graph", "spatial_graph_construction.html#autotoc_md119", null ]
+ ] ],
+ [ "Distance-based kernel", "dispersal_kernels.html#autotoc_md122", null ],
+ [ "Invariants Guarantee", "graphs_in_quetzal.html#autotoc_md72", null ],
+ [ "Edge and Vertices descriptors", "graphs_in_quetzal.html#autotoc_md73", null ],
+ [ "Edge and Vertices Information (Property Classes)", "graphs_in_quetzal.html#autotoc_md74", null ],
+ [ "Depth First Search (DFS) Algorithms", "graphs_in_quetzal.html#autotoc_md75", null ],
+ [ "DFS on trees", "graphs_in_quetzal.html#autotoc_md76", null ],
[ "accumulators", null, [
[ "extract", null, [
[ "tajima", "accumulator_8hpp.html#a546c9fcb7963ce0b708bb38573235d15", null ]
diff --git a/namespacequetzal_1_1geography.html b/namespacequetzal_1_1geography.html
index 23c393a0..971fff1a 100644
--- a/namespacequetzal_1_1geography.html
+++ b/namespacequetzal_1_1geography.html
@@ -462,7 +462,7 @@ v
-
+
-
+
-
+
-
+
+
Conventions
Like the C++ Standard Library and Boost and numerous other libraries, Quetzal follows thede guidelines:
@@ -157,7 +157,7 @@
- All other names use snake case:
unordered_map.
- Private data have a
_ prefix to distinguish it from public data.
-
+
Build process
conan install conanfile.py --install-folder=build -pr:b=conan/profiles/macos-armv8-appleclang13 -pr:h=conan/profiles/macos-armv8-appleclang13
cd build
@@ -165,12 +165,12 @@
cmake --build .
ctest
make docs
-
+
Packaging
conan remote add becheler-conan https://arnaudbecheler.jfrog.io/artifactory/api/conan/becheler-conan
conan create . test/demo -pr:b=conan/profiles/clang_13 -pr:h=conan/profiles/clang_13
conan upload quetzal-CoaTL/0.1@demo/testing --all -r=becheler-conan
-
+
Conventions
Like the C++ Standard Library and Boost and numerous other libraries, Quetzal follows thede guidelines:
-
@@ -157,7 +157,7 @@
- All other names use snake case:
unordered_map. - Private data have a
_prefix to distinguish it from public data.
+
Build process
conan install conanfile.py --install-folder=build -pr:b=conan/profiles/macos-armv8-appleclang13 -pr:h=conan/profiles/macos-armv8-appleclang13
cd build
@@ -165,12 +165,12 @@
cmake --build .
ctest
make docs
-
+
conan install conanfile.py --install-folder=build -pr:b=conan/profiles/macos-armv8-appleclang13 -pr:h=conan/profiles/macos-armv8-appleclang13
cd build
@@ -165,12 +165,12 @@
cmake --build .
ctest
make docs
-
conan remote add becheler-conan https://arnaudbecheler.jfrog.io/artifactory/api/conan/becheler-conan
conan create . test/demo -pr:b=conan/profiles/clang_13 -pr:h=conan/profiles/clang_13
conan upload quetzal-CoaTL/0.1@demo/testing --all -r=becheler-conan
-Documentation
If you refresh the doxygen-awesome package, make sure to add this snippet in the header.html before closing </head>:
<a href="https://github.com/Quetzal-framework/quetzal-CoaTL" class="github-corner" aria-label="View source on GitHub">
<svg width="80" height="80" viewBox="0 0 250 250" style="fill:#70B7FD; color:#151513; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true">
diff --git a/md_drafts_2_abstract.html b/md_drafts_2_abstract.html
index 0d2a0836..4e2ff2d0 100644
--- a/md_drafts_2_abstract.html
+++ b/md_drafts_2_abstract.html
@@ -150,7 +150,7 @@
This page gives an overview of the features available in the library.
Please refer to the Tutorials section for more detals on how to use them. If proper documentation does not exist yet, or lacks of clarity, please open an issue.
-
+
Input/Output
Quetzal-CoaTL provides a set of functions and classes that facilitate the reading of data structures (using parsers) and the writing of data structures (using generators) that are crucial for addressing coalescence problems.
-
+
Algorithms
The Quetzal-CoaTL algorithms consist of a core set of algorithm patterns (implemented as generic algorithms) and graph algorithms:
- Mergers:
By themselves, these algorithm patterns do not compute or update any meaningful quantities over lineages; they are merely building blocks for instantiating coalescence algorithms.
-+
Graphs
Since algorithms are decoupled from data-structures, these need to
-+
Compile-time units system
A part of the Quetzal-CoaTL uses mp-units to enable compile-time dimensional analysis and unit/quantity manipulation. The rational of compile-time support for Physical Units in C++ libraries can be found here.
In fewer words, instead of having
@@ -227,7 +227,7 @@doubleandintall across the code base with comments similar to// !!! THIS IS IN km !!!, Quetzal actually implements them as distinct types so that the compiler can check before runtime that you are not trying to add for example a branch length in unit of coalescence with a branch length in units of generations.
+
Data Structures
[1] M. H. Austern. Generic Programming and the STL. Professional computing series. Addison-Wesley, 1999.
vAn example of information to be stored on vertices
e An example of information to be stored on edges vicinity A policy class giving the connectivity method to be applied directionality A policy class giving the directionality (isotropy or anisotropy) directionality A policy class giving the directionality (isotropy or anistropy) bound A BoundPolicy
Table of Contents
-
+
Objectives
In this tutorial section you will learn how to:
- Use the
quetzal::format::newick::generate_from function to generate a Newick string
@@ -177,10 +177,10 @@
- Customize the behavior of the generator based on the type of information (properties) you wish to format.
-
+
From a Quetzal binary tree
-
+
No property
When a Newick string is generated from a tree that has no vertex nor edge information/properties attached to it, it is then assumed the only interest is the tree topology: as there is no clear way to populate the labels or branch length data fields in the Newick string, those are left empty.
Input
@@ -217,11 +217,11 @@
Set a root node branch length to zero. Remove all nested comments.Definition: from_network.hpp:180
Objectives
In this tutorial section you will learn how to:
- Use the
quetzal::format::newick::generate_fromfunction to generate a Newick string-
@@ -177,10 +177,10 @@
- Customize the behavior of the generator based on the type of information (properties) you wish to format.
-+
From a Quetzal binary tree
-+
No property
When a Newick string is generated from a tree that has no vertex nor edge information/properties attached to it, it is then assumed the only interest is the tree topology: as there is no clear way to populate the labels or branch length data fields in the Newick string, those are left empty.
Input
@@ -217,11 +217,11 @@Set a root node branch length to zero. Remove all nested comments.Definition: from_network.hpp:180
Since there are no comments stored in the labels of the generated random tree, the output of the different flavors are here quite similar:
Output
-
-
-
+
-
+
-
+
Custom properties
When a Newick string is generated from a tree that has some information attached to its vertices and edges through a property class, the formatter can acccess this information as long as the property class defined a std::string label() const method.
Input
@@ -280,13 +280,13 @@
Definition: newick_parser_2.cpp:12
Definition: coalescence_binary_tree_2.cpp:5
Definition: newick_parser_2.cpp:12
Definition: coalescence_binary_tree_2.cpp:5
Output
-
+
-
+
-
+
-
+
From a Quetzal k-ary tree
Extending the string generation to a k-ary tree is straightforward: instead of passing a quetzal::coalescence::binary_tree object, just pass a quetzal::coalescence::k_ary_tree to the quetzal::format::newick::generate_from function.
-
+
No property
No vertex nor edge properties are embedded: the vertices labels and branch length data fields of the Newick string are left empty.
Input
@@ -324,7 +324,7 @@-
+
Custom properties
The Newick string is generated from a tree that embeds some information attached to its vertices and edges through a property class, the formatter can acccess this information as long as the property class defined a std::string label() const method.
Input
@@ -385,9 +385,9 @@- +
-
+
Interfacing legacy code
If your existing code heavily dependson your own class to describe a tree graph, then refactoring your whole project to switch to Quetzal trees may be too costly.
In this case, you can connect the quetzal::format::newick::generator class to your own legacy code.
-
+
No property
No property
Quetzal implements a quetzal::format::newick::generator that consumes a tree graph and produces a newick string.
This generator is not aware of your class. Instead, it requires you to defined 4 functors that embed all the information there is to know about a vertex \(v\):
Output
-
+
Custom properties
Once you understand the previous example with no property, then generating a Newick string from one of your legacy tree class object with added vertices and/or edge labels is pretty straightforward.
You only need to modify three things:
-
diff --git a/newick_parser.html b/newick_parser.html
index d837d6ad..f4655ae5 100644
--- a/newick_parser.html
+++ b/newick_parser.html
@@ -149,29 +149,29 @@
Table of Contents
-
+
Introduction
-
+
Background
Newick tree format is a way of representing graph-theoretical trees with edge lengths using parentheses and commas.
Yet not very efficient, Newick is a simple and popular format for representing trees, and provides a rather useful abstraction in coalescence theory for representing the shared history of populations (species trees, population trees) or gene genealogies that coalesce into these trees.
Quetzal provides some utilities to parse, generate and manipulate such format.
-
+
Grammar
Whitespace here refer to any of the following: spaces, tabs, carriage returns, and linefeeds.
-
+
Objectives
In this tutorial section you will learn how to:
- Parse a Newick string to a Quetzal k-ary tree class,
@@ -189,10 +189,10 @@
- Parse a Newick string to your own legacy tree class
-
+
To a Quetzal k-ary tree
-
+
Default properties
In this example we will use the default (and simplistic) properties of the graph synthetized by the parsing. By properties we mean the type the data structures used to store arbitrary information along the vertices and edges of a graph.
For general graphs it could be anything, but since we are parsing Newick formats, we can reasonably expect ad minima:
-
+
Custom properties
Introduction
-
+
Background
Newick tree format is a way of representing graph-theoretical trees with edge lengths using parentheses and commas.
Yet not very efficient, Newick is a simple and popular format for representing trees, and provides a rather useful abstraction in coalescence theory for representing the shared history of populations (species trees, population trees) or gene genealogies that coalesce into these trees.
Quetzal provides some utilities to parse, generate and manipulate such format.
-
+
Grammar
Whitespace here refer to any of the following: spaces, tabs, carriage returns, and linefeeds.
-
+
Objectives
In this tutorial section you will learn how to:
- Parse a Newick string to a Quetzal k-ary tree class, @@ -189,10 +189,10 @@
- Parse a Newick string to your own legacy tree class
-
+
To a Quetzal k-ary tree
-
+
Default properties
Default properties
In this example we will use the default (and simplistic) properties of the graph synthetized by the parsing. By properties we mean the type the data structures used to store arbitrary information along the vertices and edges of a graph.
For general graphs it could be anything, but since we are parsing Newick formats, we can reasonably expect ad minima:
Custom properties
In the previous example we used default types to represent the properties of a vertex and an edge. These defaults are useful, but not always sufficient. For example, you may want to visit your tree graph and trigger specific events when specific nodes or edges are visited.
In this case, you would need to define your own small structures to represent the graph properties you want:
-
+
Interfacing legacy code
If you have been coding for a while, you may already depend heavily on your own class to describe a tree graph, and not feel very excited about refactoring your whole project to switch to Quetzal trees. Fair enough.
This section shows how to use Quetzal parser to populate your own legacy class and then forget about Quetzal.
diff --git a/niche_in_quetzal.html b/niche_in_quetzal.html new file mode 100644 index 00000000..b3905335 --- /dev/null +++ b/niche_in_quetzal.html @@ -0,0 +1,224 @@ + + + + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ |
+
+ Quetzal-CoaTL
+
+ The Coalescence Template Library
+ |
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Niche models in Quetzal
+
+
+
+Table of Contents
+ ++Niche models as mathematical expressions
+In the field of ecology, the niche refers to the compatibility between a species and a specific environmental condition. It explains how an organism or a population adapts to the availability of resources and competition.
+For instance, when resources are plentiful and the presence of predators, parasites, and pathogens is low, the organism or population tends to grow. In locations and times of resources scarcity and high predation, the populations tend to shrink.
+The composition and significance of environmental variables that constitute the dimensions of a niche can vary among species, and the importance of specific environmental factors for a species may change depending on geographical and ecological contexts.
+- Note
- In the broader context of this library, the niche model lacks a specific definition as it relies on the preferences and requirements of individual users. What we can understand is that it involves some combination of spatial and temporal factors that are closely intertwined with the demographic process. This justifies the need for a highly adaptable approach for representing the concept of niche, as it is bound to vary depending on the specific species, population, or geographic area under study.
Given this understanding, the primary goal of Quetzal is to provide users with quetzal::expressive, a user-friendly means to effectively combine geospatial and temporal elements. This enables users to establish meaningful mathematical connections between a diverse and heterogeneous landscape and the underlying demographic processes, based on their own perspectives and preferences. Generally speaking, users will want to use quetzal::expressive to mathematically compose spatio-temporal expressions with a signature double (location_type, time_type) until they reach a satisfying definition of the local demographic parameter of interest.
+Mathematical composition in C++
+Mathematical composition in C++ is not trivial as unlike languages, C++ does not understand mathematical expressions and their composition. In this strongly-typed language, you can not simply multiply the integer 42 and the function \( f(x,y) = x^y \) and expect it to work. Indeed, if you try to rescale a lambda function, e.g.:
int a = 42;
+auto f = [](auto x, auto y){return std::pow(x,y); };
+my_expression = a * f; // error
+ it will not compile. As the compiler does not know natively what the rules are to multiply a number with whatever type f is, it will (verbosely) insult you saying the operator*() is not defined for the type int and an anonymous type (the lambda function).
+Mathematical composition with quetzal::expressive
+You need a library to tell the compiler what to do. This is where quetzal::expressive comes handy: it allows you to add, substract, multiply, or compose mathematical expressions by giving them a uniform interface.
In the context of demographic models, my_expression in the example below could represent for example r(x,t) the growth rate at location x at time t. Being able to compose several smaller expressions into bigger expressions gives much freedom to users who can for example define r in one part on the program and compose it at a later time with a different expression e.g. k(x,t) the carrying capacity at location x at time t. By treating these local demographic parameters as independent expressions that can be mixed and matched, quetzal::expressive allows great freedom in the implementation details of a spatio-temporal process.
Input
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
constexpr auto use(F f)
Transforms functions into operator friendly classes.
Definition: expressive.hpp:205
Transforms literals into operator friendly classes.
Definition: expressive.hpp:263
Output
++
+
+
+
diff --git a/pages.html b/pages.html
index 54a79544..7b809b5a 100644
--- a/pages.html
+++ b/pages.html
@@ -161,18 +161,20 @@
-
+
+
- Generated by 1.9.1
+