Easy-to-use C++ library for the live tracking of lineage and coalescence trees in individual-based forward-in-time simulations.

   

Content

• Aim
• What is puutools
• Contributing
• Installation instructions
• CMake find module
• First usage with a walk-through example
• A complex scenario where puutools has been useful
• Copyright
• License

Aim

^{Helmi Biese - View from Pyynikki Ridge, 1900.}

Individual-based forward-in-time evolutionary simulations are more and more common, and have proven useful in many fields (ecology and evolution, conservation biology, systems and computational cell biology, etc).

Recovering the evolutionary and mutational events is one major interest of evolutionary simulations. It requires tools which efficiently track the lineages of in silico populations, hopefully providing exhaustive access to the simulation events that led to the final state of a population.

One solution consists in producing full backups at regular intervals during a simulation, and recovering lineage information in post-processing. However, this approach usually requires gigabytes of storage, as it saves more information than strictly necessary, and then limits the opportunity to produce light and portable simulation software.

Another solution consists in dynamically tracking the lineage and/or coalescence trees during a simulation, to only keep the pertinent information in live memory. Such an approach provides live access to ancestor relationships (including tracing back evolutionary events) at any time during a simulation. While this approach comes at slightly higher computational and live memory costs (it is necessary to maintain in memory and regularly update the trees), it is much lighter and efficient than the back-up/post-treatment approach.

This functionality is usually re-implemented from scratch in different simulation software, at the cost of re-investing time to optimize the algorithms. The aim of puutools is to help developers by offering an easy-to-use and light framework to manage lineage and coalescence information on the fly during an evolutionary simulation.

What is puutools

puutools is a C++ library which allows to dynamically create, track and manage lineage and/or coalescence trees during individual-based forward-in-time simulations of evolution.

With puutools, it is possible to update the lineage and/or the coalescence tree of a population at each generation during a simulation, and to track and recover evolutionary events at any time. puutools is easy to deploy and versatile, providing the user with a small set of integrated functions.

puutools is an all-in-one library. It does not depend on third-party packages, and its code is kept simple and light. puutools comes as and header-only library, so specific compilation is not needed.

puutools has primarily been implemented and optimized during the European project EvoEvo (FP7-ICT-610427), as part of the Evo²Sim software (see Rocabert et al. 2017). The code has then been deployed in σFGM framework (see Rocabert et al. 2020). To date, puutools is distributed as a static library for C++ developers. We plan to provide a Python-binding in a future version.

Contributing

If you wish to contribute, do not hesitate to reach the developer.

Installation instructions

Supported platforms

puutools library has been primarily developed for Unix/Linux and macOS systems.

Required dependencies

• A C++11 compiler (GCC, LLVM, ...);
• CMake >= 3.19 (command line version);

Additional dependencies for the example code:

• Gnu Scientific Library (GSL);
• CBLAS;
• R >= 4.0.0;
• Rpackage ape;

Installation

Download the latest release of puutools, and save it into a directory of your choice. Open a terminal and use the cd command to navigate to this directory. To install puutools, simply call the script install.sh on the command line:

sh install.sh

The script requires sudo access to install the library in the appropriate folder. puutools comes as a single C++ header file, and will be usually installed in an include directory (usually /usr/local/include).

⚠️ If you cannot or do not want to use a sudo access, simply download the source code file puutools.h and include it directly to your project.

CMake find module

In case your project is compiled through CMake, the following module can be used to detect whether puutools is available during compilation. It has also the advantage to automatically detect the paths in the CMakeLists.txt file.

You can download the module here: CMake Find Module

Then add the piece of code below in your CMakeLists.txt file:

find_package(PUUTOOLS REQUIRED)
if(PUUTOOLS_FOUND)
  include_directories(${PUUTOOLS_INCLUDE_DIR})
endif(PUUTOOLS_FOUND)

First usage with a walk-through example

You will find a complete walk-through example to get used with the current functionalities of puutools.

A complex scenario where puutools has been useful

The original code of puutools has been implemented for research purpose as part of the bacterial evolution simulator Evo²Sim. The software has for example been used to study bacterial diversification events in batch culture setups (see Rocabert et al. 2017). Tracking lineages and coalescence trees was an essential step in this scientific work. An example of simulation output is available here: https://charlesrocabert.github.io/doc/evo2sim_simulation_example/viewer/viewer.html.

Copyright

Copyright © 2022-2024 Charles Rocabert. All rights reserved.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.