Merge branch 'develop'

Quetzal-framework · Nov 8, 2017 · ab4a9c0 · ab4a9c0
2 parents 01145ef + 39fd064
commit ab4a9c0
Show file tree

Hide file tree

Showing 37 changed files with 1,064 additions and 335 deletions.
diff --git a/documentation/examples/example1/bio1.tif b/documentation/examples/example1/bio1.tif
diff --git a/documentation/examples/example1/bio12.tif b/documentation/examples/example1/bio12.tif
diff --git a/documentation/examples/example1/example b/documentation/examples/example1/example
diff --git a/documentation/examples/example1/example1.cpp b/documentation/examples/example1/example1.cpp
diff --git a/documentation/examples/example1/microsat_test.csv b/documentation/examples/example1/microsat_test.csv
diff --git a/documentation/mainpage.dox b/documentation/mainpage.dox
@@ -5,7 +5,7 @@
  *
  * # Introduction
  *
- * QuetzalCoaTL (COALescence Template Library), or Quetzal for shorter use, is a
+ * QuetzalCoaTL (Coalescence Template Library), or Quetzal for shorter use, is a
  * C++ template library for simulating coalescence processes in spatially explicit
  * landscapes with complex demography.
  *
@@ -14,6 +14,8 @@
  * this library can offer you some useful tools for building programs based on complex generative
  * models of genetic data.
  *
+ * [Check the founder article introducing the library.](https://www.biorxiv.org/content/early/2017/11/06/214767)
+ *
  * - Because of ABC is computationally intensive, we wanted Quetzal to be
  *   <B>fast</B> enough to run millions of simulations in a minimal amount of time.
  *
@@ -46,6 +48,8 @@
  *
  * **Maintainer:** [Arnaud Becheler](https://becheler.github.io/)
  *
+ * **How to cite:** [see the founder article](https://www.biorxiv.org/content/early/2017/11/06/214767)
+ *
  * **Community:** IRC channel \#quetzal on [Freenode](https://webchat.freenode.net/)
  *
  * **Supported platform:** Linux

diff --git a/documentation/modules.dox b/documentation/modules.dox
@@ -51,7 +51,7 @@
   * setting up mathematical models linking environmental and demographic quantities
   * together. Obviously, the details of the functions used depend on the biological context and the
   * modeler intuition, so there is __no do-it-all function__ that could be implemented
-  * once an only once and used in all possible contexts.
+  * once and used in all possible contexts.
   *
   * Inevitably, later or sooner the user would have to build its own modeling functions:
   * all we can do is to propose __concise way to express them.__
@@ -194,14 +194,55 @@
   * @}
   *
   * \defgroup abc abc
-  * \brief Template classes for embedding simulation model objects into an ABC framework.
+  * \brief Template classes for embedding simulation model objects into an Approximate Bayesian Computation framework.
   *
-  * Defines template classes to embed simulation code into an ABC framework. It
-  * relies heavily on the C++ concept of GenerativeModel, which defines the set
-  * of constraints that a simulation model object must have to interact with the
-  * ABC module. For now, only basics are implemented (Rubin rejection sample,
+  * Defines template classes to embed simulation code into an Approximate Bayesian Computation framework framework.
+  * For now, only basics are implemented (Rubin rejection sample,
   * Pritchard rejection sampler, generation of the reference table). Nevertheless,
   * this allows to perform an open-ended number of important inference tasks,
-  * as the user can inject almost any kind of distance or summary statistics
+  * as the user can for example inject almost any kind of distance or summary statistics
   * in the analysis of the reference table.
+  *
+  * ## C++ concept : GenerativeModel
+  *
+  * The abc module relies heavily on the C++ concept of GenerativeModel, which defines the set
+  * of constraints that a simulation model object must have to interact with the
+  * abc module.
+  *
+  * The type `D` satisfies GenerativeModel if
+  *
+  * * `D` satisfies [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+  * * `D` satisfies [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable)
+  *
+  * Given
+  *
+  * * `T`, the type named by `M::return_type`
+  * * `P`, the type named by `M::param_type`, which:
+  *   * satisfies [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+  *   * satisfies [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable)
+  *   * satisfies [EqualityComparable](http://en.cppreference.com/w/cpp/concept/EqualityComparable)
+  *   * has a constructor taking identical arguments as each of the constructors of
+  *    `D` that take arguments corresponding to the model parameters.
+  *   * has a member function with the identical name, type, and semantics,
+  *    as every member function of `D` that returns a parameter of the model
+  *   * declares a member typedef `using distribution_type = D`;
+  * * `d`, a value of type `D`
+  * * `x`, a (possibly `const`) value of type `D`
+  * * `p`, a (possibly `const`) value of type `P`
+  * * `g`,  a lvalue of a type satisfying the STL [UniformRandomBitGenerator](http://en.cppreference.com/w/cpp/concept/UniformRandomBitGenerator) concept
+  *
+  * The following expressions must be valid and have their specified effects :
+  *
+  * Expression          | Type | Notes
+  * --------------------|------|-------------------------------------|
+  * `D::result_type`    | `T`    | the type of the simulated data      |
+  * `D::param_type`     | `T`    |                                     |
+  * `D()`               |      | creates a distribution indistinguishable from any other default-constructed `D` |
+  * `D(p)`              |      | creates a distribution indistinguishable from `D` constructed directly from the values used to construct `p` |
+  * `x.param()`         | `P`    | Returns `p` such that `D(p).param() == p`   |
+  * `d.param(p)`        | `void` | Postcondition: `d.param() == p`             |
+  * `d(g)`              | `T`    | The sequence of data returned by successive invocations of this call with the same `g` are randomly distributed according to the distribution parametrized by `d.param()` |
+  * `d(g,p)`            | `T`    | The sequence of data returned by successive invocations of this call with the same `g` are randomly distributed according to the distribution parametrized by `p` |
+  *
+  * \remark All types satisfying the requirements of the STL [RandomNumberDistribution](http://en.cppreference.com/w/cpp/concept/RandomNumberDistribution) satisfy quetzal GenerativeModel concept.
   */
diff --git a/modules/abc/ReferenceTable.h b/modules/abc/ReferenceTable.h
@@ -12,7 +12,46 @@
 #include <vector>
 #include <algorithm>
 
-//! \remark Represents a set of couples {param, summary statistics}
+/*!
+ * \brief Reference table produced by ABC sampling procedures in the prior predictive distribution.
+ *
+ * In some ABC procedures, a parameter \f$\theta\f$ is generated from the prior \f$\pi(\theta)\f$,
+ * a data \f$z\f$ is simulated from the likelyhood and a dimension reduction function \f$\eta\f$
+ * is computed on \f$z\f$. The set of simulated statistics is called the
+ * reference table.
+ *
+ * \tparam ParamType the parameter type.
+ * \tparam DataType the type of the data generated.
+ * \tparam Cont the type wrapping the couple parameter and the data value.
+ *
+ * The template parameter Cont must meet the following requirements:
+ *
+ * * `Cont` satisfies [CopyConstructible](http://en.cppreference.com/w/cpp/concept/CopyConstructible)
+ * * `Cont` satisfies [CopyAssignable](http://en.cppreference.com/w/cpp/concept/CopyAssignable)
+ *
+ * Given
+ *
+ * * `T`, the type named by `Cont::data_type`
+ * * `P`, the type named by `Cont::param_type`, which:
+ * * `s`, a value of type `Cont`
+ * * `x`, a value of type `T`
+ * * `p`, a value of type `P`
+ *
+ * The following expressions must be valid and have their specified effects :
+ *
+ * Expression          | Type | Notes
+ * --------------------|------|-------------------------------------|
+ * `Cont::data_type`   | `T`    | the type of the simulated data    |
+ * `Cont::param_type`  | `P`    | the type of the parameter         |
+ * `s.data()`          | `T`    | Returns the simulated data        |
+ * `s.param()`         | `P`    | Returns the parameter used for simulating the data |
+ *
+ * \ingroup abc
+ * \section Example
+ * \snippet abc/test/test.cpp Example
+ * \section Output
+ * \include abc/test/test.output
+ */
 template<template <class,class> class Cont, class ParamType, class DataType>
 class ReferenceTable{
 
@@ -47,8 +86,8 @@ class ReferenceTable{
 
   template<typename UnaryOperation>
   auto compute_summary_statistics(UnaryOperation const& eta) const {
-    using Ret = typename quetzal::expressive::return_type<UnaryOperation>;
-    ReferenceTable<Cont, ParamType, Ret> s;
+    using sumstat_type = typename std::result_of_t<UnaryOperation(const DataType &)>;
+    ReferenceTable<Cont, ParamType, sumstat_type> s;
     for(auto const& it : m_table){
       s.emplace_back(it.param(), eta(it.data()));
     }

diff --git a/modules/abc/UTest_abc.sh b/modules/abc/UTest_abc.sh
@@ -2,10 +2,8 @@
 
 echo -e "UTest_abc\n|"
 
-echo -e "|--\t abc_test..................................."
-g++ -o abc_test -Wall -std=c++14 abc_test.cpp
-./abc_test
-rm abc_test
-echo -e "|--\t DONE \n|"
+cd test
+
+./UTest.sh
 
 echo -e "DONE\n"