Welcome to pycoalescence

.

pycoalescence is a Python package for running and analysing spatially-explicit neutral ecology simulations efficiently and easily. Input your maps and output a simulated landscape of individuals.

There are two parts to this project. Models are run in necsim, built in c++, using coalescence methods. Most users will not need to use this tool directly. pycoalescence is an API for necsim that aids setting up, running and analysing models.

pycoalescence

.

|PyPiLinux|_

Introduction

pycoalescence is a Python module for the spatially explicit coalescence neutral simulator, necsim, described here. pycoalescence provides a pythonic interface to the C++ simulator for swift simulation set-up, initiation and analysis. It is intended to be used be ecologists studying neutral dynamics in spatially explicit systems.

Features

A large number of performance-enhancing features have been implemented, as well as support for a wide number of scenarios. The features include:

• Coalescence methods written in C++ for excellent performance.
• Full output of community structure, with species IDs generated for every individual.
• Full spatial modelling, using a dispersal kernel to simulate spatial dynamics.
• Multiple sampling points, both spatially and temporally.
• Simulations of a region much larger than the sample area.
• Calculation of many biodiversity metrics, including species richness, species abundances, beta-diversity and locations of lineages.
• Usage of protracted speciation to restrict the time period that speciation events can occur in.
• Generate and apply a metacommunity to a simulation without requiring a new simulation to be performed.
• Scalability - support for simulations of tens or hundreds of millions of individuals in a single simulation.

Getting started

Installation

Two methods of installation are recommended: using conda to handle package management, including installation of all dependencies, or using pip into Python virtual environments (see here for good advice).

The other methods of installing listed here are provided as references to the install process itself, and to provide finer control over installation methods if difficulties are encountered. Note that pip and conda both internally call setuptools, which in turn runs installer.py.

Important

Mac OS X and Linux are supported through pip. Mac OS, Linux and Windows are supported through conda. For manual installation it should be possible to install pycoalescence on any system, but may require some tinkering.

Note

See here for solutions to some common installation issues.

Note

Whichever installation option you use, it is important to ensure that the package is compiled in the same environment as you intend to run simulations.

Installing via conda

Conda is a package manager that handles sourcing of all dependencies in a relatively straight-forward, cross-platform manner. pycoalescence is provided on conda-forge, so please be aware of the conda forge gotchas, especially regarding mixing the conda-forge and default channels. Installation of the package and all dependencies including boost, gdal, cmake and the relevant C++ compiler, simply requires conda install -c conda-forge pycoalescence, although we recommend installing directly to a clean virtual environment using conda install --name MyEnv1 -c conda-forge pycoalescence. Note that conda installs the dependencies into its own environment and may ignore system installs.

conda on Linux

C++14 compilers are currently unsupported on Linux on conda-forge, meaning that installation through this channel is not possible at this time. The solution is to build the package recipe on your local machine using the following steps (requires git and conda are installed locally).

• Change directory to a temporary directory and source the base conda environment

  • cd temp
  • source /path/anaconda3/bin/activate

• Download the recipe from conda-forge using git and modify the recipe to include linux

  • git clone https://github.com/conda-forge/pycoalescence-feedstock.git
  • Delete “or linux” from line 18 in pycoalescence-feedstock/recipes/meta.yaml. This will allow the build on linux systems.

• Build the package (make sure conda-build package has been installed) and install the package to your desired environment.

  • conda-build . (this step takes some time)
  • conda install --use-local pycoalescence --name MyEnv

Note

When the C++ compilers are updated on conda-forge, this method for installing on Linux will no longer be necessary.

Installing via pip

|PyPiLinux|_

Note

See here for solutions to some common installation issues.

Installation via pip requires that the non-pythonic dependencies are installed manually first. Importantly, make sure that gdal is fully functional. On some systems this appears to need compilation directly from source. Also ensure that you have a C++14 compliant compiler, cmake, sqlite and boost installed. Finally make sure your Python 3 is >= 3.6.1 or Python 2 >= 2.7.9.

With all requirements installed, it is recommended that you use a virtual environment (or pipenv) to control your Python packages (see here).

Finally, installation of pycoalescence, including Python dependencies, should just require pip install pycoalescence. The package should be downloaded and built.

Installing manually - setuptools

This method is not recommended unless you experience problems with conda or pip. To install using setuptools, download the source code manually and run python setup.py install from the terminal. Running this command will install pycoalescence to the current Python environment.

Installing manually - installer.py

Calling python installer.py [opts] from the pycoalescence directory within the source code allows for finer control over installation options. Importantly, two different make environments can be used, either ./configure and make, or cmake. A list of options is given below, and can also be displayed by running python installer.py -h. Running python installer.py will generate the package in-place, meaning that it will not be added to the Python environment. This can be desirable for HPC systems where package installation is not permitted.

Option	Description	Default
–cmake	Build the C++ library (necsim) required for pycoalescence.	True
–autotools	Use the autotools build process (./configure and make)	False
–compiler-args	Additional arguments to pass to the autotools compiler	None
–cmake-args	Additional arguments to pass to the cmake compiler during configuration	None
–cmake-build-args	Additional arguments to pass to the cmake compiler at build time	None
–debug	Compile using DEBUG defines	False
-c -C –compile	Compile only, do not re-configure necsim	False

HPC installation

On systems where package installation is not possible, use python installer.py to build the package in-place. Alternatively, python hpc_setup.py provides a custom installation with a few options switched on for HPC systems, including usage of the intel compiler by default and optimisation flags for HPC. Note that this option uses the autotools process (./configure and make) instead of cmake for compilation.

Installation issues

Consider using conda to manage package dependencies if you experience issues and please report any problems you have. On Mac OS X, installation via pip requires that the dependencies have already been provided.

Gdal issues

First, make sure the gdal C++ library has been installed on your system. On macOS run brew install gdal and for linux distributions run apt-get install gdal-devel or equivalent.

The most common issue for installing pycoalescence is gdal dependencies not being found (including errors relating to cpl_error.h, gdal.h, gdal_priv.h or cpl_conv.h). This is usually the result of gdal installing in a non-standard location, or the header files not being included with the gdal install. One option to test that gdal is installed properly on your system is to run from osgeo.gdal_array import _gdal_array from a python interpreter. If this gives an error, one possible fix on Unix systems is to uninstall the gdal python package and reinstall using pip install gdal==$(gdal-config --version) --global-option=build_ext --global-option=$(gdal-config --cflags) to make sure that the gdal links to your system’s version.

If this still doesn’t fix your problems, try compiling the C++ library on your system from source first. Then download the Python package from here that matches your local C++ version, and run python setup.py build from the gdal directory. If this is successful, run python setup.py install to install gdal to your Python environment.

Note

The development versions of boost, sqlite3 and gdal are required, which looks something like gdal-devel for Linux distributions.

Note

Install scipy and matplotlib to remove warnings when importing pycoalescence (pip install scipy matplotlib).

Boost issues

If you are on macOS, use brew install

For issues related to missing boost headers, make sure that your system has boost properly installed through your package manager. Development versions of boost are required on linux. Ensure that the paths to the boost headers are visible to pycoalescence.

Note

boost 1.68.0 is currently unsupported on conda due to changes in compiler link options.

Performing simulations

Check out the full simulation examples in this jupyter notebook.

Setting up simulations

The process of setting up a Simulation object is outlined below.

1. Instantiate our Simulation object using sim = Simulation(logging_level=20) where the logging level corresponds to the amount of information that is displayed using Python’s logging module (20 corresponds to “info”, the second highest display level, after “debug”).

2. Specify simulation parameters

   • Use set_simulation_parameters() to set the job number, task number, output directory and other key simulation variables.

   • Set the map variables by one of the following:

     1. set_map_parameters() to input file paths and dimensions
     2. set_map_files() to set the map file paths. This calls detect_map_dimensions() to automatically detect file offsets and dimensions.

     Tip

     Check Limitations of simulation variables for important information on restrictions on simulation inputs.

     Note

     detect_map_dimensions() requires that the files are in .tif formats so that file dimensions can be read. If input files are csv format, method a) should be used.

     Note

     One can specify either “null” or “none” map types; “null” creates a map at the specified size, whereas “none” creates hard boundaries without any in-memory map object created at all. However, the dimensions of these files must be manually supplied.

   • Optionally, also run set_speciation_rates() to set a list of speciation rates to apply at the end of the simulation.

3. Run the simulation This is split into 3 parts, which can be called individually if necessary:

   1. Finalise setup

      • Run finalise_setup() to check that simulations are setup and set up the maps and data structures in memory necsim.

   2. Run simulations

      • Start the simulation using run_coalescence()
      • Returns True if the simulations complete successfully and False if the simulations run out of time and pause

   3. Apply speciation rates and output database

      • Generate a coalescence tree for each speciation rate using apply_speciation_rates()
      • This function also writes the output to the simulation file.

Important

The last three steps can be combined using run(), which also performs checks for if the simulation has run out of time and paused, rather than completing.

See the examples for the full simulation process.

Note

See Glossary for definitions of sample map, fine map and coarse map.

Key Features

Some key simulation features are:

• Set differing landscape types using fine and coarse density maps, both current and historical (see set_map_files() and add_historical_map()).
• Specify a sampling mask, as a binary sampling mask defining areas to sample from (the sample map). Alternatively, for varying sampling effort across space choose uses_spatial_sampling=True in set_simulation_parameters().
• Multiple sampling points in time using add_sample_time().
• Protracted speciation simulations using protracted=True in set_simulation_parameters().
• Non-spatial simulations using spatial=False in set_simulation_parameters().
• Spatial simulations using a variety of dispersal kernels. This is the default, using a normally-distributed dispersal kernel. For other kernels see here.
• Varying reproductive rates across space using a map of relative reproductive rates. See here.
• Varying death rates across space using a map of relative death rates. See here.
• Varying landscape types including infinite landscapes, infinitely tiled landscapes of the coarse or fine density map and closed landscapes with hard boundaries. See here.

Examples

Some basic examples are given below. For more complicated scenarios, including examples of fetching data from completed simulations, please see this jupyter notebook.

A simple simulation

from pycoalescence import Simulation
# set logging level to "info" (from logging module)
c = Simulation(logging_level=20)
# set the main simulation parameters - use default values for other keyword arguments
c.set_simulation_parameters(seed=1, task=1, output_directory="output", min_speciation_rate=0.1,
                            sigma=4, deme=10, sample_size=0.1, max_time=1)
# optionally add a set of speciation rates to apply at the end of the simulation
c.set_speciation_rates([0.1, 0.2, 0.3])
# set the map parameters - null means the map will be generated with 100% cover everywhere (no file input).
c.set_map_parameters(sample_file = "null", sample_x = 100, sample_y=100,
                     fine_file = "null", fine_x = 200, fine_y = 200, fine_x_offset = 50, fine_y_offset = 50,
                     coarse_file = "null", coarse_x = 1000, coarse_y = 1000,
                     coarse_x_offset = 100, coarse_y_offset = 100, coarse_scale = 10,
                     historical_fine_map = "null", historical_coarse_map = "null")
# run checks, complete the simulation and output the database
c.run()

A more complex example using multiple temporal sampling points and detection of map dimensions from the inputted map files.

from pycoalescence import Simulation
c = Simulation()
# set the main simulation parameters
c.set_simulation_parameters(seed=1, task=1, output_directory="output", min_speciation_rate=0.1,
                            sigma=4, tau=4, deme=1, sample_size=0.1
                            max_time=100, dispersal_method="fat-tailed", m_prob=0.0, cutoff=0,
                            dispersal_relative_cost=1, min_num_species=1, habitat_change_rate=0.2,
                            gen_since_historical=200, time_config_file="null", restrict_self=False,
                            landscape_type=False)
# add a set of speciation rates to be applied at the end of the simulation
c.set_speciation_rates([0.2, 0.3, 0.4])
# set the map files - note that dimensions and offsets are detected automatically from the files
c.set_map_files(sample_file="null", fine_file="path/to/fine.tif", coarse_file="path/to/coarse.tif")
# add sample times
c.add_sample_time(0.0)
c.add_sample_time(1.0)
# add historical maps
c.add_historical_map(fine_map="path/to/historicalfine1.tif", coarse_map="path/to/historicalcoarse1.tif", time=1,
 rate=0.5)
# run checks, complete the simulation and output the database
c.run()

Note

necsim can also be run directly using command line arguments (see Introduction to necsim), but this is not recommended.

Dispersal Kernels

Three different dispersal functions are currently supported, which take some combination of the sigma (\(\sigma\)) , tau (\(\tau\) ), m_prob (\(m\) ) and cutoff (\(c\) ) dispersal parameters. You only need to provide the required parameters for each dispersal method; any additional parameters provided will be ignored.

• Normal distribution (the default)

  This requires \(\sigma\) only (the standard deviation). The outputted dispersal kernel in two dimensions will follow a Rayleigh distribution for dispersal distance, \(N(r)\)

• Fat-tailed distribution

  This requires both \(\sigma\) and \(\tau\). Importantly, for our fat-tailed dispersal kernel, \(F(r)\), \(\lim{\tau \to \inf} = N(r)\). Within this dispersal kernel, there is an increased chance of long-distance dispersal (but lower than the normal-uniform dispersal kernel). The fat-tailed distribution, as a function of the radius of dispersal, is given as \(k_R(r) = \frac{r}{\sigma^2}(1+\frac{r^2}{\tau \sigma ^2})^{-\frac{\tau+2}{2}}\).

• Normal-uniform distribution

  This requires \(\sigma\), \(m\) and \(c\) . Here, we pick with probability \(1-m\) from a normal distribution with standard deviation \(\sigma\), and probability \(m\) from a uniform distribution. This uniform distribution picks a random distance uniformly between 0 and \(c\), the maximal dispersal distance. For very large \(c\), extremely long distance dispersal is possible.

It is also possible to provide a dispersal probability map, which sets the probability of dispersing from one cell to another. The dispersal map should be dimensions xy by xy where x and y are the dimensions of the fine map. A dispersal map can be set by using set_map_files(dispersal_map="/path/to/dispersal.tif").

pycoalescence has the ability to simulate a dispersal kernel on a landscape. For more information about that process, see here.

Important

In this scenario, it is not possible to use a coarse map, which should be “none”.

Differing demographic rates

Simulations can use varying reproductive and/or death rates across the landscape, by using set_map_files(reproduction_map="/path/to/rep.tif", death_map="/path/to/death.tif"). In this scenario, all species have different per-capita reproduction and death rates across the landscape.

Note

Density is already taken into account during simulations for reproduction rates, so the reproduction map should be solely for the per-capita differences in reproductive rate.

Note

In a neutral model, each death event is followed by a birth event. The death map therefore represents both the relative number of deaths, and the relative number of maturations in each cell. The reproduction map instead indicates the relative number of propagules generated by each cell which may end up dispersing and maturing at other locations.

Important

The reproduction and death maps can only be used with a fine map, and coarse map should be set to “none”.

Limitations of simulation variables

Important

This section contains key information about the simulation inputs. Please read carefully to minimise any unnecessary bugs.

Certain simulation variables have limitations, depending on the method of setting up the simulation.

• Map variables set up using set_map_parameters()

  • Sample map dimensions must be smaller than fine map dimensions.
  • Fine map dimensions must be smaller than coarse map dimensions (supplied at the resolution of the fine map files).
  • Dimensions of historical fine and coarse maps must match their respective current map dimensions.
  • All offsets must maintain the smaller map within the larger map
  • If any files are supplied as ‘null’, map sizes must still be provided. This is important for sample map size, but should be corrected in a future update for coarse map files.

• Map files (and variables) set using set_map_files()

  • In addition to the above conditions being true, the files must all be georeferenced, so that coarse and fine map dimensions will be read correctly.

  Hint

  Use a GIS program (such as ArcGIS or QGIS) for manipulation of map files to ensure georeferencing is preserved.

  • If the samplemask map is “null”, the program will read the dimensions from the fine map and choose that as the area to sample entirely over. Supplying “null” will therefore sample the entirety of the fine map.

  Hint

  Scalings and offsets between maps should also work correctly, but if problems are encountered, try manually specifying offsets and dimensions to identify any problems.

  • The reproduction map, death map and dispersal map (if provided) must match the dimensions of the fine map. No coarse map should be provided in these scenarios.

An example of how the map files are related is shown below. Black arrows indicate the offsets for the fine map (in the x and y dimensions) and purple arrows indicate the offsets for the coarse map.

Infinite Landscapes

Simulations can also be run on infinite landscapes. Set landscape_types=opt in set_simulation_parameters() where opt is one of the following:

• “closed” (default)

  Run without infinite landscapes, with closed boundaries to the coarse map.

• “infinite”

  Run with a historical infinite landscape outside of the coarse map boundaries.

• “tiled_coarse”

  Tile the coarse map infinitely in all dimensions. A coarse map must be provided.

• “tiled_fine”

  Tile the fine map infinitely in all dimensions. No coarse map should be provided.

Optimising Simulations

Note

As of version 1.2.6rc35 dynamic resizing of internal objects is implemented. Whilst this does reduce RAM usage in all scenarios, it also means the optimisation process outlined below only relevant when the major constraint is the size of the density maps.

The optimisation process below can reduce RAM usage in systems where the major limitation is that the size of the density maps is much larger than the number of individuals being simulated. This process has a minor to major impact on performance, depending on the number of individuals. It will not fix issues with simulations not finishing, only reduce the RAM requirements.

optimise_ram() exists for reducing the RAM requirements of a simulation. Running the function with a specific RAM limit, in GB, should choose a sample map size and offsets to minimise the in-memory object sizes. This may have a minor impact on simulation speed, but this is likely negligible. After the function is run, the Simulation class should have re-defined the grid x and y dimensions to be the largest size possible to simulate for the required memory. The sample map offsets from the grid are then also stored, such that the grid encompasses the area with the highest number of individuals.

optimise_ram() may take some time to run. However, for a single set of simulations with the same RAM limit, this function should only need to be completed once. Getting and setting the optimised solution is therefore possible with get_optimised_solution() and set_optimised_solution(). The whole procedure is outlined below.

# Detect the RAM-optimised solution
>> sim1.optimise_ram()
# Get the optimised solution for Simulation object sim1
>> sim1.get_optimised_solution()
{'grid_file_name': 'set',
'grid_x_size': 5134,
'grid_y_size': 5134,
'sample_x_offset': 8208,
'sample_y_offset': 14877}
# Now set the optimised solution for Simulation object sim2
>> sim2.set_optimised_solution({'grid_file_name': 'set',
                              'grid_x_size': 5134,
                              'grid_y_size': 5134,
                              'sample_x_offset': 8208,
                              'sample_y_offset': 14877})

Generating Configuration Files

The default process is to not generate any actual config files - these are instead kept in memory to be passed to C++. However, the configs can be written to a file using write_config(), which may be useful for storing simulation parameters outside of the simulation database.

Example configuration file

[main]
seed = 1
task = 2
output_directory = output/
min_spec_rate = 1e-05
sigma = 0.5
tau = 2
deme = 10
sample_size = 0.1
max_time = 2000
dispersal_relative_cost = 1
min_species = 1

[sample_grid]
path = /Data/Maps/maskmap.tif
x = 486
y = 517
mask = /Data/Maps/maskmap.tif

[fine_map]
path = /Data/Maps/finemap.tif
x = 34000
y = 28000
x_off = 17155
y_off = 11178

[coarse_map]
path = /Data/Maps/coarsemap.tif
x = 24000
y = 20000
x_off = 10320
y_off = 7200
scale = 10.0

[historical_fine0]
path = none
number = 0
time = 200
rate = 0

[historical_coarse0]
path = none
number = 0
time = 200
rate = 0

[historical_fine1]
path = none
number = 1
time = 200
rate = 0

[historical_coarse1]
path = none
number = 1
time = 200
rate = 0

[dispersal]
method = norm-uniform
m_probability = 1e-10
cutoff = 0
restrict_self = 0
landscape_type = 0

Post-simulation analysis

Once simulations are complete, necsim’s applying speciation rates functionality can be used to apply additional speciation rates to the coalescence tree. A simple way of applying additional simulation rates is provided within the CoalescenceTree class.

The two functions for this routine are

• set_speciation_parameters() which primarily takes a list of speciation rates to apply with other options for generating the community.
• apply() performs the analysis and writes to the output file. This can be extremely RAM and time-intensive for simulations of a large number of individuals. The calculations will be stored in extra tables within the same SQL file as originally specified.

Instead of speciation events always contributing a new species, they can instead draw from a metacommunity, simulating immigration events. There are three methods of providing a metacommunity:

• simulate a non-spatial community using a metacommunity size and metacommunity speciation rate parameter to generate the species abundances from which to draw individuals.
• analytically generate the community using an approximation of the above simulation. The same two parameters (metacommunity size and metacommunity speciation rate) are required.
• Supply a database containing a SPECIES_ABUNDANCES table and an external community reference number referring to a particular generated community within the database.

All methods use the same function, set_speciation_parameters() with option set as one of “simulated”, “analytical” or a path to the external database, respectively for the above three methods.

Examples

A basic application procedure is

from pycoalescence import CoalescenceTree
t = CoalescenceTree()
speciation_rates = [0.1, 0.2 ,0.3]
t.set_database("output/data_1_1.db")
t.set_speciation_parameters(speciation_rates)
t.apply()

The CoalescenceTree class object can also be set up from a Simulation class object as:

from pycoalescence import Simulation, CoalescenceTree
sim = Simulation()
# ... set up simulation here, then run
# Now import our completed simulation without needing to run t.set_database("filepath")
t = CoalescenceTree(sim)

Example application with more complicated parameters, including using a csv file defining each “fragment” within the landscape (record_fragments), for which species abundances and species richness values are calculated separately. There is also a parameter defining which locations to sample from (the sample_file).

from pycoalescence import Simulation, CoalescenceTree
sim = Simulation()
# ... set up simulation here, then run
# Now import our completed simulation without needing to run t.set_database("filepath")
speciation_rates = [0.1, 0.2, 0.3]
times = [0.0, 1.0, 2.0]
t = CoalescenceTree(sim)
t.set_speciation_parameters(speciation_rates=speciation_rates, record_spatial=True,
record_fragments="path/to/fragments.csv", sample_file="path/to/sample/file.tif",
times=times)
t.apply()

Note

The record_fragments variable can either be boolean (to automatically detect contiguous fragments from the data), or a path to a csv file. The csv file should contain the fragment name, x min, y min, x max, y max and area (a weighting parameter usually equal to the number of variables). The x and y minima and maxima define the extremes of the fragment.

A few biodiversity metrics can then be obtained directly from the database using built-in functions, relieving the user of having to generate these manually. These include

• species richness, using get_species_richness()
• species abundances, using get_species_abundances()
• species octave (2^n) classes for generating species abundance distributions, using get_octaves()

Check out other full examples in this jupyter notebook.

Note

The above functions for acquiring biodiversity metrics require supplying a speciation rate and time, otherwise will output data for all speciation rates and times.

Tip

Equivalent functions also exist for obtaining individual fragment biodiversity metrics.

Tip

The entire coalescence tree can be outputted using get_species_list. This may be useful for scenarios where it is desirable to calculate custom biodiversity metrics.

Extended analysis

The coalescence_tree module can be used for more extensive simulation analysis, such as comparing simulated landscapes to real data and calculating goodness of fits.

The general procedure for using this module involves a few functions, all contained in the CoalescenceTree class.

• set_database() generates the link to the SQL database, which should be an output from a necsim simulation (run using the Simulation class).
• import_comparison_data() reads an SQL database which contains real data to compare to the simulation output. The comparison data should contain the following tables:
  • BIODIVERSITY_ METRICS, containing only “metric”, “fragment”, “value” and “number_of_individuals” columns. The metric can be “fragment_richness” or any other metric created by your own functions which exists also in the simulated data.
  • SPECIES_ABUNDANCES containing at least “SpeciesID”, “Abund”.

Additionally, one can provide the following if comparisons between fragments are required:

• FRAGMENT_ABUNDANCES containing at least “Plot”, “Mnemonic” and “Abund”.
• FRAGMENT_OCTAVES containing at least “fragment”, “octave”, “num_species”. This can also be calculated from FRAGMENT_ABUNDANCES using calculate_comparison_octaves()

Additional Package Features

These features are not required for spatially explicit coalescence models, as they are utilised internally by the package. However, there are some features that could be of great convenience to users, especially for generating and manipulating landscapes using tif files.

• Read tif files and perform a number of operations taking into account georeferencing of the data. Functionality is contained within the Map class (see here).
• Generate fragmented landscapes (see here). This may be useful for generating example landscapes of a particular size with desired characteristics.
• Simulate a dispersal kernel on a landscape to obtain characteristics of the effective dispersal kernel. Currently only a single map is supported with “closed”, “infinite” or “tiled” landscape types (see here).
• Simulations can be merged into a single output, with each simulation occupying a separate guild (see here). Analyses can then be performed on the combined data.

Testing install

The system install can be tested by running test_install.py from the command line (python test_install.py) which requires that python setup.py has been successfully run previously or the package otherwise successfully installed.

Prerequisites

Essential

Note that conda should detect and install all prerequisites automatically. Pip will detect and install Python prerequisites (such as numpy), although on some systems will fail to install gdal.

• Python version 2 >= 2.7.9 or 3 >= 3.6.1. Other versions may work, but are not supported.
• C++ compiler (such as GNU g++) with C++14 support.
• Cmake >= 3.6 for installing via pip or conda.
• The SQLite library for both C++ and Python installations. Comes as standard with Python.
• The gdal library for both Python and C++ (available here). It allows reading parameter information from .tif files (using detect_map_dimensions()). Both the Python package and C++ binaries are required; installation differs between systems, so view the gdal documentation for more help installing gdal properly.
• The Boost library for C++ available here.
• Numerical Python (numpy) package (pip install numpy).

Recommended

• Scipy package for generating fragmented landscapes (pip install scipy).
• Matplotlib package for plotting fragmented landscapes (pip install matplotlib).

Optional

• For work involving large csv files, the fast-cpp-csv-parser by Ben Strasser, available here can be used. This provides much faster csv read and write capabilities and is probably essential for larger-scale simulations, but not necessary if your simulations are small or you are intending to use .tif files (the recommended method). The folder fast-cpp-csv-parser/ should be in the same directory as your necsim C++ header files (the lib/necsim directory) and requires manual installation.

Note

fast-cpp-csv-parser is no longer tested with updated versions of that package, but should still be functional.

Glossary

grid

Used to refer to the simulation area that is stored in memory as a matrix, for quick referencing. If no RAM optimisations have been performed, this will be the same size as the sample map. If also no sample map is used, this will be the same as the fine map.

sample map

The map file containing the points to be sampled from. This is the most zoomed in level of the simulation, and should encompass all starting locations of lineages.

fine map

The map file at a higher resolution (the same as the sample grid) which covers the area lineages are most likely to move to, or where a higher spatial resolution is considered important.

coarse map

The map file at a lower resolution (specified by the scale) which covers a larger area than the fine map. This is to allow lineages to move far from their starting positions if required.

historical map

A historic map containing population densities at those times. Both fine and coarse historical maps can be declared and multiple sets of pristine maps can be declared at unique times.

Version

Version 1.2.7.post13

Contacts

Author: Samuel Thompson

Contact: samuel.thompson14@imperial.ac.uk - thompsonsed@gmail.com

Institution: Imperial College London and National University of Singapore

This project is released under MIT See file LICENSE.txt or go to here for full license details.

necsim

A Neutral Ecology Coalescence Simulator

Introduction

necsim is a generic spatial coalescence simulator for neutral systems. It is intended to simulate an ecological community under individual-based neutral dynamics. It applies the model to maps for the supplied parameters and outputs information for each individual to a SQL database.

Functionality is also provided for applying varying speciation rates to outputs of necsim for analysis after simulations are complete. This enables the main simulation to be run with the minimum speciation rate required and afterwards analysis can be completed using different speciation rates. The same functionality is also provided within necsim for application of speciation rates immediately after simulations are complete.

Important

The recommended method of installing the program and running simulations is to use the pycoalescence module.

A Note on the Neutral Theory of Ecology

Neutral theory in ecology refers to the idea that individuals can be modelled as ecologically identical entities, undergoing dispersal, drift and speciation without niche effects or other competitive elements.

Whilst obviously not realistic, the patterns produced by such models can often give a surprisingly accurate portrayal of real-world systems. For more information on the topic, please see Hubbell (2001).

Instructions

Compiling the program

For compilation, there are several provided options:

• Compilation can be handled within pycoalescence by running python setup.py. This is the recommended option.

• Alternatively, compilation can be completed with additional options using make. The steps are outlined below

  • You might need to first run autoconf from within the necsim directory to generate the configure executable.
  • Run ./configure (located within the necsim directory). Provide additional compilation flags if necessary (detailed below).
  • Run make all to create the executable.
  • [Optional] Move the executable (called necsim) to the build/Default directory in pycoalescence.

• If you require compilation outside of the pycoalescence module, make use of the the file Makefile located in Makefiles/SimpleCompile. This can be modified and run using make to generate the executable.

Note

If you want to also compile the module for integrating with Python, provide the Python library (PYTHON_LIB) and Python include directories (PYTHON_INCLUDE) as command line flags to ./configure. You must then run make all. This is not recommended, and it is advised you use the install proceedure outlined here.

Warning

Compilation on high-performance clusters will likely require an icc compiler and custom linking to the required libraries.

See the Requirements section for a full list of the necessary prerequisites.

Requirements

• The SQLite library available here.
• The Boost library available here.
• C++ compiler (such as GNU g++) with C++14 support.
• Access to the relevant folders for Default simulations (see FAQS).

Recommended, but not essential:

• gdal library available here: provides reading of tif files.
• The fast-cpp-csv-parser by Ben Strasser, available here: provides much faster csv read and write capabilities. This is only really necessary if you have extremely large csv files as your map objects. If that is the case, I would highly recommend moving to using tif files, as they provide much more error-checking support within necsim, as well as much more advanced tools for dealing with spatial data.

Note

To use the fast-cpp-csv-parser, copy the whole folder (with csv.h in) to the necsim directory. Then reconfigure and recompile your code, making sure that you see ‘fast-cpp-csv-parser = enabled’ in the configuration output.

Compiler Options

Recognised compiler options include:

Option	Description
–with-debug	Adds additional debugging information to a log file in /logs
–with-gdal=DIR	Define a gdal library at DIR
–with-hpc	Compile ready for HPC, using intel’s icpc compilation and a variety of optimisation flags.
–with-boost=DIR	Define a boost library at DIR

Additional c++ compilation flags can be specified by CPPFLAGS=opts for additional library paths or compilation options as required.

Note that gdal and fast-cpp-csv-parser availability will be automatically detected and included in the compilation if possible.

Running simulations

As of version 3.1 and above, the routine relies on supplying command line arguments (see below) for all the major simulation variables. Alternatively, supplying a config .txt file and using the command line arguments ./necsim -c /path/to/config.txt can be used for parsing command line arguments from the text file.

Command Line Arguments

Deprecated since version This: method of supplying simulation parameters is not recommended and is provided for backwards-compatibility only. Support will be dropped completely in a future release.

The following command line arguments are required. This list can be accessed by running “./necsim -h” or ./necsim -help

As of version 3.6 and above, the command line options to be specified are:

1. the seed for the simulation.
2. the simulation task (for file reference).
3. the map config file.
4. the output directory.
5. the minimum speciation rate.
6. the dispersal z_fat value.
7. the dispersal L value.
8. the deme size.
9. the deme sample size.
10. the maximum simulation time (in seconds).
11. the lambda value for moving through non-habitat.
12. the temporal sampling file containing generation values for sampling points in time (null for only sampling the present)
13. the minimum number of species known to exist. (Currently has no effect).
14. (and onwards) speciation rates to apply after simulation.

In this format, the map config file and temporal sampling file are as described in Config Files.

Alternatively, by specifying the -f flag, (full mode) as the first argument, the program can read in pre-3.6 command line arguments, which are as followed.

1. the task_iter used for setting the seed.
2. the sample grid x dimension
3. the sample grid y dimension
4. the fine map file relative path.
5. the fine map x dimension
6. the fine map y dimension
7. the fine map x offset
8. the fine map y offset
9. the coarse map file relative path.
10. the coarse map x dimension
11. the coarse map y dimension
12. the coarse map x offset
13. the coarse map y offset
14. the scale of the coarse map compared to the fine (10 means resolution of coarse map = 10 x resolution of fine map)
15. the output directory
16. the speciation rate.
17. the dispersal sigma value.
18. the deme size
19. the deme sample size (as a proportion of deme size)
20. the time to run the simulation (in seconds).
21. lambda - the relative cost of moving through non-forest
22. the_task - for referencing the specific task later on.
23. the minimum number of species the system is known to contain.
24. the historical fine map file to use
25. the historical coarse map file to use
26. the rate of forest change from historical
27. the time (in generations) since the historical forest was seen.
28. the dispersal tau value (the width of the fat-tailed kernel).
29. the sample mask, with binary 1:0 values for areas that we want to sample from. If this is not provided then this will default to mapping the whole area.
30. the link to the file containing every generation that the list should be expanded. This should be in the format of a list.
31. (and onwards) - speciation rates to apply after the simulation is complete.

Warning

This method of running simulations is provided for legacy purposes only, and is no longer recommended. For increase functionality, use the condensed command-line format, or switch to using config files.

Config Files

A configuration file can be used for setting simulation parameters.

• main simulation config file

  • Contains the main simulation parameters, including dispersal parameters, speciation rates, sampling information and file referencing information. It also includes the paths to the other config files, which must be specified if the main simulation config is used.
  • Contains the map parameters, including paths to the relevant map files, map dimensions, offsets and scaling. This option cannot be null (map dimensions at least must be specified).
  • Contains the temporal sampling points, in generations. If this is ‘null’, sampling will automatically occur only at the present (generation time=0)

When running the simulation using config files, the path to the main simulation config file should be specified, e.g ./necsim -c /path/to/main/config.txt.

Main Config File

The configuration containing the majority of the simulation set up, outside of map dimensions. An example file is shown below. This file can be automatically generated by create_config() in pycoalescence. An example of this configuration is given below:

[main]
seed = 6
task = 6
output_directory = output
min_spec_rate = 0.5
sigma = 4
tau = 4
deme = 1
sample_size = 0.1
max_time = 1
lambda = 1
min_species = 1

[spec_rates]
spec_rate1  = 0.6
spec_rate2  = 0.8

Map Config Options

The map options contain the information for setting up all maps required by the simulation. This involves maps at all times and at all scales. An example is given below.

[sample_grid]
path = null
x = 13
y = 13
mask = null

[fine_map]
path = sample/SA_sample_fine.tif
x = 13
y = 13
x_off = 0
y_off = 0

[coarse_map]
path = sample/SA_sample_coarse.tif
x = 35
y = 41
x_off = 11
y_off = 14
scale = 1.0

[historical_fine0]
path = sample/SA_sample_fine_historical1.tif
number = 0
time = 1
rate = 0.5

[historical_coarse0]
path = sample/SA_sample_coarse_historical1.tif
number = 0
time = 1
rate = 0.5

[historical_fine1]
path = sample/SA_sample_fine_historical2.tif
number = 1
time = 4
rate = 0.7

[historical_coarse1]
path = sample/SA_sample_coarse_historical2.tif
number = 1
time = 4
rate = 0.7

Note

The rates and times between the pairs of historical fine maps and historical coarse maps must match up. Without matching values here, there could be undetermined errors, or coarse map values being ignored.

Note

Pristine maps assume the same dimensions as their respective present-day equivalents.

Note

In older versions of this program these options were contained in a separate file. However, as of 1.2.4 all simulation options are contained in the same file.

Time Config Options

The temporal sampling options are specified as follows.

[main]
time0 = 0.0
time1 = 1.0

Note

For each speciation rate, all biodiversity measures (such as species’ abundances and species’ richness) will be calculated for each time supplied separately.

Default parameters

To run the program with the default parameters for testing purposes, run with the command line arguments -d or -dl (for the larger default run). Note that this will require access to the Default/ folder relative to the path of the program for storing the outputs to the default runs:

Outputs

Upon successful completion of a simulation, the outputs and parameters are stored in an SQLite database.

• an SQLite database file in the output directory. This database contains all important simulation data over several tables, which can be accessed using a program like DB Browser for SQLite or Microsoft Access. Alternatively, most programming languages have an SQLite interface (RSQlite, Python sqlite3)

The tables in the SQLite database are

• SIMULATION_PARAMETERS

  contains the parameters the simulation was performed with for referencing later.

• SPECIES_LIST

  contains the locations of every coalescence event. This is used by SpeciationCounter to reconstruct the coalescence tree for application of speciation rates after simulations are complete.

• SPECIES_ABUNDANCES

  contains the species abundance distributions for each speciation rate and time point that has been specified.

• SPECIES_LOCATIONS [optional]

  contains the x, y coordinates of every individual at each time point and for every specified speciation rate, along with species ID numbers.

• FRAGMENT_ABUNDANCES [optional]

  contains the species abundance distributions for each habitat fragment, either specified by the fragment csv file, or detected from squares across the map.

Additional information can be found in SpeciationCounter regarding the optional database tables.

SpeciationCounter

SpeciationCounter provides a method for applying additional speciation rates to outputs from necsim, without having to re-run the entire simulation. SpeciationCounter works by reconstructing the coalescence tree, checking at each point if an additional speciation rate has occured. As such, SpeciationCounter can only apply speciation rates higher than the initial speciation rate the program was run with.

Applying Speciation Rates

The command-line interface for applying speciation rates post-simulation has been removed - instead use CoalescenceTree in pycoalescence module.

Debugging

Most errors will return an error code in the form “ERROR_NAME_XXX: Description” a list of which can be found in ERROR_REF.txt.

Brief Class Descriptions

A brief description of the important classes is given below.

• The Tree class

  • The most important class!
  • Contains the main setup, run and data output routines.
  • setup() imports the data files from csv (if necessary) and creates the in-memory objects for the storing of the coalescence tree and the spatial grid of active lineages. Setup time mostly depends on the size of the csv file being imported.
  • runSimulation() continually loops over successive coalesence, move or speciation events until all individuals have speciated or coalesced. This is where the majority of the simulation time will be, and is mostly dependent on the number of individuals, speciation rate and size of the spatial grid.
  • At the end of the simulation, the applyMultipleRates() routine will generate the in-memory SQLite database for storing the coalescent tree. It can run multiple times if multiple speciation rates are required. outputData() is called internally to output the SQLite database to file.

• The TreeNode class

  • Contains a single record of a node on the phylogenetic tree, to be used in reassembling the tree structure at the end of the simulation.

• The DataPoint class

  • Contains a single record of the location of a lineage.

• The NRrand class

  • Contains the random number generator, as written by James Rosindell (j.rosindell@imperial.ac.uk).

• The Landscape class

  • Contains the routines for importing and calling values from the Map objects.
  • The getVal() and runDispersal() functions can be modified to produce altered dispersal behaviour.

• The DispersalCoordinator class

  • Used to generate dispersal distances from a particular dispersal kernel. The dispersal kernel can also take the form of a dispersal map, which defines probabilites of dispersal between every cell on the landscape.

• The Matrix and Row classes

  • Based on code written by James Rosindell (j.rosindell@imperial.ac.uk).
  • Handles indexing of the 2D object plus importing values from a csv or tif file

• The Map class

  • Derived from Matrix with extra functionality for handling tif file parameter reads and calculation of spatial data.

• The DataMask and Samplematrix classes

  • Special maps that define the location of sampling across a landscape. Contain extra functionality for defining “null” maps (sampling everywhere).

• The SpeciesList class

  • Contains the list of individuals, for application in a matrix, to essentially create a 3D array.
  • Handles the positioning of individuals in space within a grid cell.

• The ConfigOption class

  • Contains basic functions for importing command line arguments from a config file, providing an alternative way of setting up simulations.

• The Community class

  • Provides the routines for applying different speciation rates to a phylogenetic tree, to be used either immediately after simulation within necsim, or at a later time using SpeciationCounter
  • Use to generate a community of individuals for a particular set of parameters, providing options for generating species identities, species abundance distributions and species locations.

Known Bugs

• Simulations run until completion, rather than aiming for a desired number of species. This is an intentional change. Functions related to this functionality remain but are deprecated.
• In SpeciationCounter, only continuous rectangular fragments are properly calculated. Other shapes must be calculated by post-processing.
• In SpeciationCounter, 3 fragments instead of 2 will be calculated for certain adjacent rectangular patches.

FAQS (WIP)

• Why doesn’t the default simulation output anything?
  • Check that the program has access to the folders relative to the program at Default/
• Why can’t I compile the program?
  • This could be due to a number of reasons, most likely that you haven’t compiled with access to the lsqlite3 or boost packages. Installation and compilation differs across different systems; for most UNIX systems, compiling with the linker arguments -lsqlite3 -lboost_filesystem and -lboost_system will solve problems with the compiler not finding the sqlite or boost header file.
  • Another option could be the potential lack of access to the fast-cpp-csv-parser by Ben Strasser, available here. If use_csv has been defined at the head of the file, try without use_csv or download the csv parser and locate the folder within your working directory at compilation.
• Every time the program runs I get error code XXX.
  • Check the ERROR_REF.txt file for descriptions of the files. Try compiling with the DEBUG precursor to gain more information on the problem. It is most likely a problem with the set up of the map data (error checking is not yet properly implemented here).

Version

Version 1.2.7.post13

Contacts

Author: Samuel Thompson

Contact: samuelthompson14@imperial.ac.uk - thompsonsed@gmail.com

Institution: Imperial College London and National University of Singapore

Based heavily on code by James Rosindell

Contact: j.rosindell@imperial.ac.uk

Institution: Imperial College London

Licence

This project is released under MIT See file LICENSE.txt or go to here for full license details.

You are free to modify and distribute the code for any non-commercial purpose.

Class Hierarchy

• • Namespace necsim
    • Struct CommunitiesArray
    • Struct CommunityParameters
    • Struct ConfigException
    • Struct FatalException
    • Struct Fragment
    • Struct HistoricalMapParameters
    • Struct MapLocation
    • Struct MetacommunitiesArray
    • Struct MetacommunityParameters
    • Struct ProtractedSpeciationParameters
    • Struct SectionOption
    • Struct SimParameters
    • Struct SQLStatement
    • Class ActivityMap
    • Class AnalyticalSpeciesAbundancesHandler
    • Class Cell
    • Class Community
    • Class ConfigParser
    • Class DataMask
    • Class DataPoint
    • Class DispersalCoordinator
    • Class GillespieHeapNode
    • Class GillespieProbability
    • Class Landscape
    • Class LogFile
    • Class Logger
    • Template Class Map
    • Template Class Matrix
    • Class Metacommunity
    • Class ProtractedSpatialTree
    • Class ProtractedTree
    • Class PyLogger
    • Class Samplematrix
    • Class SimulateDispersal
    • Class SimulatedSpeciesAbundancesHandler
    • Class SpatialTree
    • Class SpeciationCommands
    • Class SpeciesAbundancesHandler
    • Class SpeciesList
    • Class SpecSimParameters
    • Class SQLiteHandler
    • Class Step
    • Class Tree
    • Class TreeNode
    • Enum CellEventType
    • Enum EventType
  • Namespace random_numbers
    • Class RNGController
    • Class SplitMix64
    • Class Xoroshiro256plus
  • Struct module_state
  • Class LandscapeMetricsCalculator
  • Class ProtractedTree
  • Template Class PyCommunityTemplate
  • Class PyLMC
  • Class PySimulateDispersal
  • Template Class PyTemplate

File Hierarchy

• • Directory necsim
    • Directory eastl
      • File heap.h
    • File ActivityMap.cpp
    • File ActivityMap.h
    • File AnalyticalSpeciesAbundancesHandler.cpp
    • File AnalyticalSpeciesAbundancesHandler.h
    • File Cell.cpp
    • File Cell.h
    • File Community.cpp
    • File Community.h
    • File ConfigParser.cpp
    • File ConfigParser.h
    • File cpl_custom_handler.cpp
    • File cpl_custom_handler.h
    • File custom_exceptions.h
    • File DataMask.cpp
    • File DataMask.h
    • File DataPoint.cpp
    • File DataPoint.h
    • File DispersalCoordinator.cpp
    • File DispersalCoordinator.h
    • File double_comparison.cpp
    • File double_comparison.h
    • File file_system.cpp
    • File file_system.h
    • File GillespieCalculator.cpp
    • File GillespieCalculator.h
    • File Landscape.cpp
    • File Landscape.h
    • File LicenseHeader.h
    • File LogFile.cpp
    • File LogFile.h
    • File Logger.cpp
    • File Logger.h
    • File Logging.cpp
    • File Logging.h
    • File main.cpp
    • File Map.h
    • File MapLocation.cpp
    • File MapLocation.h
    • File Matrix.h
    • File Metacommunity.cpp
    • File Metacommunity.h
    • File neutral_analytical.cpp
    • File neutral_analytical.h
    • File parameters.cpp
    • File parameters.h
    • File ProtractedSpatialTree.h
    • File ProtractedTree.cpp
    • File ProtractedTree.h
    • File README.md
    • File RNGController.h
    • File setup.cpp
    • File setup.h
    • File SimParameters.h
    • File SimulateDispersal.cpp
    • File SimulateDispersal.h
    • File SimulatedSpeciesAbundancesHandler.cpp
    • File SimulatedSpeciesAbundancesHandler.h
    • File SimulationTemplates.h
    • File SpatialTree.cpp
    • File SpatialTree.h
    • File SpeciationCommands.cpp
    • File SpeciationCommands.h
    • File SpeciesAbundancesHandler.cpp
    • File SpeciesAbundancesHandler.h
    • File SpeciesList.cpp
    • File SpeciesList.h
    • File SpecSimParameters.h
    • File SQLiteHandler.cpp
    • File SQLiteHandler.h
    • File Step.h
    • File Tree.cpp
    • File Tree.h
    • File TreeNode.cpp
    • File TreeNode.h
    • File Xoroshiro256plus.h
  • File CCommunity.h
  • File CLandscapeMetricsCalculator.h
  • File CSimulateDispersal.h
  • File CSimulation.h
  • File LandscapeMetricsCalculator.cpp
  • File LandscapeMetricsCalculator.h
  • File necsim.cpp
  • File necsim.h
  • File PyImports.cpp
  • File PyImports.h
  • File PyLogger.cpp
  • File PyLogger.h
  • File PyLogging.cpp
  • File PyLogging.h
  • File PyTemplates.h

Full API

Namespace eastl

Functions

• Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, const T&, Compare)
• Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, T&&, Compare)
• Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, const T&)
• Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, T&&)
• Template Function eastl::adjust_heap_impl(RandomAccessIterator, Distance, Distance, Distance, T)
• Template Function eastl::adjust_heap_impl(RandomAccessIterator, Distance, Distance, Distance, T, Compare)
• Template Function eastl::change_heap(RandomAccessIterator, Distance, Distance)
• Template Function eastl::change_heap(RandomAccessIterator, Distance, Distance, Compare)
• Template Function eastl::is_heap(RandomAccessIterator, RandomAccessIterator)
• Template Function eastl::is_heap(RandomAccessIterator, RandomAccessIterator, Compare)
• Template Function eastl::is_heap_until(RandomAccessIterator, RandomAccessIterator)
• Template Function eastl::is_heap_until(RandomAccessIterator, RandomAccessIterator, Compare)
• Template Function eastl::make_heap(RandomAccessIterator, RandomAccessIterator)
• Template Function eastl::make_heap(RandomAccessIterator, RandomAccessIterator, Compare)
• Template Function eastl::pop_heap(RandomAccessIterator, RandomAccessIterator)
• Template Function eastl::pop_heap(RandomAccessIterator, RandomAccessIterator, Compare)
• Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, const T&)
• Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, T&&)
• Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, const T&, Compare)
• Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, T&&, Compare)
• Template Function eastl::promote_heap_impl(RandomAccessIterator, Distance, Distance, T)
• Template Function eastl::promote_heap_impl(RandomAccessIterator, Distance, Distance, T, Compare)
• Template Function eastl::push_heap(RandomAccessIterator, RandomAccessIterator)
• Template Function eastl::push_heap(RandomAccessIterator, RandomAccessIterator, Compare)
• Template Function eastl::remove_heap(RandomAccessIterator, Distance, Distance)
• Template Function eastl::remove_heap(RandomAccessIterator, Distance, Distance, Compare)
• Template Function eastl::sort_heap(RandomAccessIterator, RandomAccessIterator)
• Template Function eastl::sort_heap(RandomAccessIterator, RandomAccessIterator, Compare)

Namespace necsim

Classes

• Struct CommunitiesArray
• Struct CommunityParameters
• Struct ConfigException
• Struct FatalException
• Struct Fragment
• Struct HistoricalMapParameters
• Struct MapLocation
• Struct MetacommunitiesArray
• Struct MetacommunityParameters
• Struct ProtractedSpeciationParameters
• Struct SectionOption
• Struct SimParameters
• Struct SQLStatement
• Class ActivityMap
• Class AnalyticalSpeciesAbundancesHandler
• Class Cell
• Class Community
• Class ConfigParser
• Class DataMask
• Class DataPoint
• Class DispersalCoordinator
• Class GillespieHeapNode
• Class GillespieProbability
• Class Landscape
• Class LogFile
• Class Logger
• Template Class Map
• Template Class Matrix
• Class Metacommunity
• Class ProtractedSpatialTree
• Class ProtractedTree
• Class PyLogger
• Class Samplematrix
• Class SimulateDispersal
• Class SimulatedSpeciesAbundancesHandler
• Class SpatialTree
• Class SpeciationCommands
• Class SpeciesAbundancesHandler
• Class SpeciesList
• Class SpecSimParameters
• Class SQLiteHandler
• Class Step
• Class Tree
• Class TreeNode

Enums

• Enum CellEventType
• Enum EventType

Functions

• Function necsim::archimedesSpiralX
• Function necsim::archimedesSpiralY
• Function necsim::calculateDistance
• Function necsim::cantorPairing
• Function necsim::checkSpeciation
• Function necsim::cplNecsimCustomErrorHandler
• Function necsim::createParent
• Function necsim::distanceBetweenCells
• Function necsim::doesExist
• Function necsim::doesExistNull
• Function necsim::doubleCompare(double, double, double)
• Function necsim::doubleCompare(long double, long double, long double)
• Function necsim::doubleCompare(long double, long double, double)
• Function necsim::elegantPairing
• Template Function necsim::findMinCols
• Template Function necsim::findMinRows
• Function necsim::getConfigFileFromCmdArgs
• Function necsim::getCsvLineAndSplitIntoTokens
• Function necsim::getDefaultLogFile
• Function necsim::getGlobalLogger
• Function necsim::getTime
• Function necsim::getUniqueFileName
• Function necsim::importArgs
• Function necsim::importToMapAndRound
• Function necsim::inverseSpeciation
• Function necsim::loggerIsSetup
• Function necsim::main
• Function necsim::openSQLiteDatabase
• Function necsim::operator<<(std::ostream&, const MapLocation&)
• Function necsim::operator<<(ostream&, const SpeciesList&)
• Function necsim::operator<<(ostream&, const TreeNode&)
• Function necsim::operator<<(ostream&, ActivityMap&)
• Function necsim::operator<<(ostream&, const SectionOption&)
• Function necsim::operator<<(ostream&, const ConfigParser&)
• Function necsim::operator<<(ostream&, const DataPoint&)
• Template Function necsim::operator<<(ostream&, const vector<T>&)
• Function necsim::operator<<(ostream&, const GillespieProbability&)
• Function necsim::operator>>(std::istream&, MapLocation&)
• Function necsim::operator>>(istream&, SpeciesList&)
• Function necsim::operator>>(istream&, TreeNode&)
• Function necsim::operator>>(istream&, ActivityMap&)
• Function necsim::operator>>(istream&, SectionOption&)
• Function necsim::operator>>(istream&, ConfigParser&)
• Function necsim::operator>>(istream&, DataPoint&)
• Template Function necsim::operator>>(istream&, vector<T>&)
• Function necsim::operator>>(std::istream&, GillespieProbability&)
• Function necsim::removeComOption
• Function necsim::removeGlobalLogger
• Function necsim::runAsDefault
• Function necsim::runLarge
• Template Function necsim::runMain
• Function necsim::runXL
• Function necsim::writeCritical
• Function necsim::writeError
• Function necsim::writeInfo
• Function necsim::writeWarning

Variables

• Variable necsim::gdal_data_sizes
• Variable necsim::log_name
• Variable necsim::logger
• Variable necsim::pyLogger
• Variable necsim::saved_stdout

Namespace neutral_analytical

Functions

• Function neutral_analytical::calcFundamentalBiodiversityNumber
• Function neutral_analytical::calcSpeciationRate
• Function neutral_analytical::siMetacommunitySpeciesWithAbundance
• Function neutral_analytical::siSpeciesAbundanceCumulativeDistribution
• Function neutral_analytical::siSpeciesRichness
• Function neutral_analytical::siSpeciesRichnessDeprecated

Namespace random_numbers

Classes

• Class RNGController
• Class SplitMix64
• Class Xoroshiro256plus

Functions

• Function random_numbers::intToDouble
• Function random_numbers::rotl

Variables

• Variable random_numbers::ktab
• Variable random_numbers::wtab
• Variable random_numbers::ytab

Namespace std

STL namespace.

Struct module_state

• Defined in File necsim.h

Struct Documentation

struct module_state

Public Members

PyObject *error

Struct CommunitiesArray

• Defined in File parameters.h

Struct Documentation

struct CommunitiesArray

A structure for containing an array of previous calculation information, including which fragments have been already calculated for.

Public Functions

CommunitiesArray()

Default constructor.

~CommunitiesArray()

Trivial destructor.

void pushBack(unsigned long reference, long double speciation_rate, long double time, bool fragment, unsigned long metacommunity_reference, const ProtractedSpeciationParameters &protracted_params)

Adds an extra CommunityParameters object to the calc_array vector with the supplied variables.

Parameters

• reference: the reference for this set of community parameters
• speciation_rate: the speciation rate of the past calculation
• time: the time of the past calculation
• fragment: bool of whether fragments were used in the past calculation
• metacommunity_reference: reference for the metacommunity parameters, or 0 if no metacommunity
• protracted_params: protracted speciation parameters to add

void pushBack(shared_ptr<CommunityParameters> tmp_param)

Adds the provided CommunityParameters object to the calc_array vector.

Parameters

• tmp_param: the set of community parameters to add

shared_ptr<CommunityParameters> addNew(long double speciation_rate, long double time, bool fragment, unsigned long metacommunity_reference, const ProtractedSpeciationParameters &protracted_params)

Adds a new communities calculation paremeters reference, with a new unique reference.

Return

reference to the new CommunityParameters object added

Parameters

• speciation_rate: the speciation rate of the new calculation
• time: the time used in the new calculation
• fragment: true if fragments were used in the new calculation
• metacommunity_reference: the reference to the set of metacommunity parameters (0 for none)
• protracted_params: protracted speciation parameters to add

bool hasPair(long double speciation_rate, double time, bool fragment, unsigned long metacommunity_reference, const ProtractedSpeciationParameters &protracted_params)

Checks whether the calculation with the supplied variables has already been performed.

Note

Return

true if the reference exists in past community parameters

Parameters

• speciation_rate: the speciation rate to check for
• time: the time to check for
• fragment: bool for checking if fragments were used
• metacommunity_reference: the reference to the set of metacommunity parameters (0 for none)
• protracted_params: protracted speciation parameters to add

Public Members

vector<shared_ptr<CommunityParameters>> comm_parameters

The array of CommunityParameters which have been stored.

Struct CommunityParameters

• Defined in File parameters.h

Struct Documentation

struct CommunityParameters

A struct for containing pairs of previous calculations to make sure that aren’t repeated.

Public Functions

CommunityParameters()

Default constructor.

~CommunityParameters()

Trivial destructor.

CommunityParameters(unsigned long reference_in, long double speciation_rate_in, long double time_in, bool fragment_in, unsigned long metacommunity_reference_in, const ProtractedSpeciationParameters &protracted_params)

Constructor for CommunityParameters, for storing a pairs of previous calculations, requiring a speciation rate and a time. Overloaded version with setup routines.

Parameters

• reference_in: the reference to set for this CommunityParameters set
• speciation_rate_in: the speciation rate of the previous calculation
• time_in: the time of the previous calculation
• fragment_in: bool of whether fragments were used in the previous calculation
• metacommunity_reference_in: the metacommunity reference, or 0 for no metacommunity
• protracted_params: protracted speciation parameters to add

void setup(unsigned long reference_in, long double speciation_rate_in, long double time_in, bool fragment_in, unsigned long metacommunity_reference_in, const ProtractedSpeciationParameters &protracted_params)

Sets up the CommunityParameters object.

Parameters

• reference_in: the reference to set for this CommunityParameters set
• speciation_rate_in: the speciation rate of the previous calculation
• time_in: the time of the previous calculation
• fragment_in: bool of whether fragments were used in the previous calculation
• metacommunity_reference_in: the metacommunity reference, or 0 for no metacommunity
• protracted_params: protracted speciation parameters to add

bool compare(long double speciation_rate_in, long double time_in, bool fragment_in, unsigned long metacommunity_reference_in, const ProtractedSpeciationParameters &protracted_params)

Compare these set of parameters with the input set. If they match, return true, otherwise return false.

Return

Parameters

• speciation_rate_in: speciation rate to compare with stored community parameter
• time_in: time to compare with stored community parameter
• fragment_in: if fragments are being used on this database
• metacommunity_reference_in: metacommunity reference to compare with stored community parameter
• protracted_params: the minimum number of generations required for existance before speciation
• protracted_params: protracted speciation parameters to add

bool compare(long double speciation_rate_in, long double time_in, unsigned long metacommunity_reference_in, const ProtractedSpeciationParameters &protracted_params)

Compare these set of parameters with the input set. If they match, return true, otherwise return false Overloaded version ignoring the fragments parameter.

Return

Parameters

• speciation_rate_in: speciation rate to compare with stored community parameter
• time_in: time to compare with stored community parameter
• metacommunity_reference_in: metacommunity reference to compare with stored community parameter
• protracted_params: protracted speciation parameters to add

bool compare(unsigned long reference_in)

Checks if the supplied reference is the same in the community parameter.

Return

Parameters

• reference_in:

Public Members

unsigned long reference

long double speciation_rate

long double time

bool fragment

unsigned long metacommunity_reference

ProtractedSpeciationParameters protracted_parameters

The protracted speciation parameters for this object.

bool updated

Struct ConfigException

• Defined in File custom_exceptions.h

Inheritance Relationships

Base Type

• public necsim::FatalException (Struct FatalException)

Struct Documentation

struct ConfigException : public necsim::FatalException

A structure for all exceptions thrown within config processes.

Public Functions

ConfigException()

ConfigException(string msg)

Generates a FatalException with the specified error message.

Parameters

• msg: the message to pass to FatalException

Struct FatalException

• Defined in File custom_exceptions.h

Inheritance Relationships

Base Type

• public std::runtime_error

Derived Type

• public necsim::ConfigException (Struct ConfigException)

Struct Documentation

struct FatalException : public std::runtime_error

This is called any time a fatal exception is called and the program is unwound and ended.

Subclassed by necsim::ConfigException

Public Functions

FatalException()

FatalException(string msg)

Writes the message out to the logger if debug mode is enabled, otherwise just throws a runtime_error.

Parameters

• msg: the message to write out and pass to runtime_error

Struct Fragment

• Defined in File Community.h

Struct Documentation

struct Fragment

Contains the information needed for defining a fragment.

Public Members

string name

long x_east

long x_west

long y_north

long y_south

unsigned long num

double area

Struct HistoricalMapParameters

• Defined in File SimParameters.h

Struct Documentation

struct HistoricalMapParameters

Public Functions

HistoricalMapParameters()

HistoricalMapParameters(string f, string c, const double &h, const double &g)

bool operator<(const HistoricalMapParameters &mp) const

bool operator>(const HistoricalMapParameters &mp) const

Public Members

string fine_map_file

string coarse_map_file

double habitat_change_rate

double generation

Struct MapLocation

• Defined in File MapLocation.h

Inheritance Relationships

Derived Types

• public necsim::DataPoint (Class DataPoint)
• public necsim::Step (Class Step)

Struct Documentation

struct MapLocation

Subclassed by necsim::DataPoint, necsim::Step

Public Functions

MapLocation()

MapLocation(long x, long y, long xwrap, long ywrap)

bool isOnGrid() const

Checks if the location is directly on the grid without wrapping (i.e. xwrap and ywrap are 0).

Return

true if on the grid

bool operator==(MapLocation const &m) const

Equality operator for MapLocation.

Return

true if the x, y, xwrap and ywrap are identical

Parameters

• m: the MapLocation object to compare against

bool operator!=(MapLocation const &m) const

Inequality operator for MapLocation.

Return

true if locations are not identical

Parameters

• m: the MapLocation object to compare against

Public Members

long x

long y

long xwrap

long ywrap

Friends

std::ostream &operator<<(std::ostream &os, const MapLocation &m)

Output operator for MapLocation.

Return

the output stream

Parameters

• os: the output stream to write to
• m: the object to write out

std::istream &operator>>(std::istream &is, MapLocation &m)

Input operator for MapLocation.

Return

the input stream

Parameters

• is: the input stream to read from
• m: the object to read to

Struct MetacommunitiesArray

• Defined in File parameters.h

Struct Documentation

struct MetacommunitiesArray

Contains an array of MetacommunityParameters that have been applied to the coalescence tree.

Public Functions

MetacommunitiesArray()

Default constructor.

~MetacommunitiesArray()

Trivial destructor.

vector<shared_ptr<MetacommunityParameters>>::iterator begin()

Support for range-based for loop iteration over metacomm_parameters.

Return

the start of the parameters vector

vector<shared_ptr<MetacommunityParameters>>::iterator end()

Support for range-based for loop iteration over metacomm_parameters.

Return

the end of the parameters vector

vector<shared_ptr<MetacommunityParameters>>::const_iterator begin() const

Support for range-based for loop iteration over metacomm_parameters.

Return

the start of the parameters vector

vector<shared_ptr<MetacommunityParameters>>::const_iterator end() const

Support for range-based for loop iteration over metacomm_parameters.

Return

the end of the parameters vector

void pushBack(const unsigned long &reference, const unsigned long &metacommunity_size, const long double &speciation_rate, const string &option, const unsigned long &external_reference)

Adds an extra CommunityParameters object to the calc_array vector with the supplied variables.

Parameters

• reference: the reference for this set of metacommunity parameters
• speciation_rate: the speciation rate used in generation of the metacommunity
• metacommunity_size: the size of the metacommunity used
• option: the metacommunity option (“simulated”, “analytical” or a path to a database)
• external_reference: the reference for the external database

void pushBack(shared_ptr<MetacommunityParameters> tmp_param)

Adds the provided PastMetacommunityParameters object to the calc_array vector.

Parameters

• tmp_param: the set of metacommunity parameters to add

void clear()

Wipes the internal vector.

unsigned long size()

Gets the size of the array.

Return

the number of metacommunity parameters that have been added

bool empty()

Check if the array is empty.

Return

true if the array has no elements in

unsigned long addNew(const unsigned long &metacommunity_size, const long double &speciation_rate, const string &option, const unsigned long &external_reference)

Adds a new metacommunities calculation paremeters reference, with a new unique reference.

Return

the new reference number, which should be unique

Parameters

• speciation_rate: the speciation rate of the new calculation
• metacommunity_size: the size of the metacommunity in the new calculation
• option: the metacommunity option (“simulated”, “analytical” or a path to a database)
• external_reference: the reference for the external database

unsigned long addNew(const MetacommunityParameters &metacomm_in)

Adds a new set of metacommunity parameters to the array.

Return

the new reference number, which should be unique

Parameters

• metacomm_in: the new metacommunity parameters to add

bool hasOption(const unsigned long &metacommunity_size, const long double &speciation_rate, const string &option, const unsigned long &external_reference)

Checks whether the calculation with the supplied variables has already been performed.

Return

true if the reference exists in past metacommunity parameters

Parameters

• speciation_rate: the speciation rate to check for
• metacommunity_size: the size of metacommunity to check for
• option: the metacommunity option (“simulated”, “analytical” or a path to a database)
• external_reference: the reference for the external database

bool hasOption(unsigned long reference)

Checks whether the calculation with the supplied reference has already been performed. Overloaded version for checking references.

Return

true if the reference exists in past metacommunity parameters

Parameters

• reference: the reference to check for in past metacommunity parameters

bool hasOption(const MetacommunityParameters &metacomm_in)

Checks whether the calculation with the supplied reference has already been performed.

Return

true if the metacommunity already exists in past metacommunity parameters

Parameters

• metacomm_in: the metacommunity parameters to check for

unsigned long getReference(const unsigned long &metacommunity_size, const long double &speciation_rate, const string &option, const unsigned long &external_reference)

Gets the metacommunity reference for the provided parameters, or returns 0 if it doesn’t exist.

Return

the metacommunity reference number, or 0 if it doesn’t exist

Parameters

• speciation_rate: the metacommunity speciation rate to obtain for
• metacommunity_size: the metacommunity size to apply for
• fragment: bool for checking if fragments were used
• option: the metacommunity option (“simulated”, “analytical” or a path to a database)
• external_reference: the reference for the external database

unsigned long getReference(const MetacommunityParameters &metacomm_parameters)

Gets the metacommunity reference for the provided parameters, or returns 0 if it doesn’t exist.

Return

the metacommunity reference number, or 0 if it doesn’t exist

Parameters

• metacomm_parameters: the parameters to check for

void addNull()

Adds an empty metacommunity parameters option.

bool hasMetacommunityOption()

Determines if the array has any Metacommunity options (other than a null option).

Return

Public Members

vector<shared_ptr<MetacommunityParameters>> metacomm_parameters

Struct MetacommunityParameters

• Defined in File parameters.h

Struct Documentation

struct MetacommunityParameters

Contains a set of metacommunity parameters that have been applied, or are to be applied, to the coalescence tree.

Public Functions

MetacommunityParameters()

Default constructor.

~MetacommunityParameters()

Trivial destructor.

MetacommunityParameters(const unsigned long &reference_in, const unsigned long &metacommunity_size_in, const long double &speciation_rate_in, const string &option_in, const unsigned long &external_reference_in)

Constructor for MetacommunityParameters, storing a previously applied metacommunity.

Parameters

• reference_in: the metacommunity reference number
• metacommunity_size_in: the speciation rate used for metacommunity generation
• speciation_rate_in: size of the tested metacommunity
• option: the metacommunity option (“simulated”, “analytical” or a path to a database)
• external_reference: the reference for the external database

bool compare(unsigned long metacommunity_size_in, long double speciation_rate_in, const string &option_in, const unsigned long &ext_reference_in)

Compare these set of parameters with the input set. If they match, return true, otherwise return false.

Return

true if the two parameter sets are identical

Parameters

• speciation_rate_in: speciation rate to compare with stored community parameter
• metacommunity_size_in: size of the tested metacommunity
• option_in: the metacommunity option (“simulated”, “analytical” or a path to a database)
• external_reference_in: the reference for the external database

bool compare(const MetacommunityParameters &metacomm_in)

Compare these set of parameters with the input set. If they match, return true, otherwise return false.

Return

true if the two parameter sets are identical

Parameters

• metacomm_in:

bool compare(unsigned long reference_in)

Checks if the supplied reference is the same in the metacommunity reference.

Return

Parameters

• reference_in: the reference to check against

bool isMetacommunityOption() const

Checks if this combination of metacommunity parameters is not a null option.

Return

true if the combination is valid (i.e. not null)

void clear()

Wipes the metacommunity parameters.

MetacommunityParameters &operator=(const MetacommunityParameters &parameters)

bool operator==(const MetacommunityParameters &parameters)

bool operator!=(const MetacommunityParameters &parameters)

Public Members

unsigned long reference = {}

unsigned long metacommunity_size = {}

long double speciation_rate = {}

string option

unsigned long external_reference = {}

Struct ProtractedSpeciationParameters

• Defined in File parameters.h

Struct Documentation

struct ProtractedSpeciationParameters

Public Functions

ProtractedSpeciationParameters()

bool operator==(const ProtractedSpeciationParameters &p1) const

Public Members

double min_speciation_gen

double max_speciation_gen

Struct SectionOption

• Defined in File ConfigParser.h

Struct Documentation

struct SectionOption

A simple container for importing options from a config file.

Public Functions

SectionOption()

Default constructor for SectionOption.

string getOption(string refval)

Returns the value for the provided reference from within the key.

Return

the requested value as a string. Returns string “null” if no reference is found.

Parameters

• refval: the reference to obtain the value of

Public Members

string section

vector<string> val

vector<string> refs

Friends

ostream &operator<<(ostream &os, const SectionOption &k)

Overloading the << operator for outputting to the output stream.

Return

os the output stream.

Parameters

• os: the output stream.
• k: the KeyOption object.

istream &operator>>(istream &is, SectionOption &k)

Overloading the >> operator for inputting from an input stream.

Return

is the input stream

Parameters

• is: the input stream
• k: the KeyOption object

Struct SimParameters

• Defined in File SimParameters.h

Struct Documentation

struct SimParameters

Stores and imports the variables required by the Map object. Used to setting the Map variables in a more elegant way.

Public Functions

SimParameters()

Default constructor.

void importParameters(ConfigParser configOption)

Links to the provided ConfigOption. Assumes that the parameters have already been parsed from the config file.

Parameters

• configOption: the parsed ConfigOption object

void importParameters(const string &conf_in)

Imports the spatial variables from a path to the config file..

Parameters

• config_in: string of the path to the config file

void importParameters()

Main import of parameters from the config file option.

void setKeyParameters(const long long &job_type, const long long &seed, const string &output_directory, const unsigned long &max_time, unsigned long desired_specnum, const string &times_file)

Sets the main simulation parameters.

Parameters

• job_type: the job type reference number, used for file referencing
• seed: the seed to set random number generation
• output_directory: the output directory
• max_time: the maximum time to simulate for
• desired_specnum: the desired number of species to aim towards (currently not functional)
• times_file: the file containing a list of temporal sampling points

void setSpeciationParameters(const long double &spec_in, bool is_protracted_in, const double &min_speciation_gen_in, const double &max_speciation_gen_in)

Sets the speciation parameters for the simulation.

Parameters

• spec_in: the speciation rate to use
• is_protracted_in: if true, simulates as a protracted simulation
• min_speciation_gen_in: the minimum speciation generation for protracted simulations
• max_speciation_gen_in: the maximum speciation generation for protracted simulations

void setDispersalParameters(const string &dispersal_method_in, const double &sigma_in, const double &tau_in, const double &m_prob_in, const double &cutoff_in, const double &dispersal_relative_cost_in, bool restrict_self_in, const string &landscape_type_in, const string &dispersal_file_in, const string &reproduction_file_in)

Sets the dispersal parameters for the simulation.

Parameters

• dispersal_method_in: the method of individuals dispersing (normal, fat-tailed or norm-uniform)
• sigma_in: the sigma value for a normal distribution
• tau_in: the tau value for the fat-tailed distribution
• m_prob_in: the probability of uniform dispersal for the norm-uniform distribution
• cutoff_in: the maximum dispersal distance for the uniform distribution
• dispersal_relative_cost_in: the relative cost of dispersing through non-forest
• restrict_self_in: if true, prevents dispersal from the same cell
• landscape_type_in: the landscape type (infinite, tiled or closed)
• dispersal_file_in: a map of dispersal probabilities
• reproduction_file_in: a map of reproduction probabilities

void setHistoricalMapParameters(const string &historical_fine_file_map_in, const string &historical_coarse_map_file_in, const double &gen_since_historical_in, const double &habitat_change_rate_in)

Sets the historical map parameters for the simulation.

Parameters

• historical_fine_file_map_in: the fine resolution historical file
• historical_coarse_map_file_in: the coarse resolution historical file
• gen_since_historical_in: the number of generations since the historical state was achieved
• habitat_change_rate_in: the rate of habitat change towards the historical state

void setHistoricalMapParameters(vector<string> path_fine, vector<unsigned long> number_fine, vector<double> rate_fine, vector<double> time_fine, vector<string> path_coarse, vector<unsigned long> number_coarse, vector<double> rate_coarse, vector<double> time_coarse)

void setMapParameters(const string &fine_map_file_in, const string &coarse_map_file_in, const string &sample_mask_file_in, const unsigned long &grid_x_size_in, const unsigned long &grid_y_size_in, const unsigned long &sample_x_size_in, const unsigned long &sample_y_size_in, const unsigned long &sample_x_offset_in, const unsigned long &sample_y_offset_in, const unsigned long &fine_map_x_size_in, const unsigned long &fine_map_y_size_in, const unsigned long &fine_map_x_offset_in, const unsigned long &fine_map_y_offset_in, const unsigned long &coarse_map_x_size_in, const unsigned long &coarse_map_y_size_in, const unsigned long &coarse_map_x_offset_in, const unsigned long &coarse_map_y_offset_in, const unsigned long &coarse_map_scale_in, const double &deme_in, const double &deme_sample_in, bool uses_spatial_sampling_in)

Sets the map parameters for the simulation.

Parameters

• fine_map_file_in: the fine resolution density map
• coarse_map_file_in: the coarse resolution density map
• sample_mask_file_in: the spatial sampling mask
• grid_x_size_in: the x dimension of the grid
• grid_y_size_in: the y dimension of the grid
• sample_x_size_in: the x dimension of the sample mask
• sample_y_size_in: the y dimension of the sample mask
• sample_x_offset_in: the x offset of the sample mask from the grid
• sample_y_offset_in: the y offset of the sample mask from the grid
• fine_map_x_size_in: the x dimension of the fine map
• fine_map_y_size_in: the y dimension of the fine map
• fine_map_x_offset_in: the x offset of the fine map from the sample mask
• fine_map_y_offset_in: the y offset of the fine map from the sample mask
• coarse_map_x_size_in: the x dimension of the coarse map
• coarse_map_y_size_in: the y dimension of the coarse map
• coarse_map_x_offset_in: the x offset of the coarse map from the fine map
• coarse_map_y_offset_in: the y offset of the coarse map from the fine map
• coarse_map_scale_in: the scale of the coarse map compared to the fine map
• deme_in: the number of individuals per cell
• deme_sample_in: the proportion of individuals to sample from each cell
• uses_spatial_sampling_in: if the sample mask denotes differing spatial sampling proportions

bool setHistorical(const double &generation)

Updates the historical map parameters to the next item in the deque.

Return

bool true if we need to re-import the maps (i.e. the historical maps have changed between updates)

bool checkNeedsUpdate(const double &g)

Checks if there will be another update to be performed on the map.

Return

true if another map update exists

bool hasAnotherUpdate()

void parseHistorical()

Parses the historical map data and creates the queue of historical maps.

void setInitialHistoricalParameters()

void printVars()

Prints selected important variables to the terminal.

void printSpatialVars()

Prints the spatial variables.

void setMetacommunityParameters(const unsigned long &metacommunity_size, const long double &speciation_rate, const unsigned long &seed, const unsigned long &job_type)

Sets the metacommunity parameters.

Parameters

• metacommunity_size: the number of individuals in the community
• speciation_rate: the speciation rate for the metacommunity
• seed: the seed for the simulation
• job_type: the job referencing number

SimParameters &operator=(const SimParameters &other)

Public Members

string fine_map_file

string coarse_map_file

string output_directory

string historical_fine_map_file

string historical_coarse_map_file

string sample_mask_file

long long job_type = {}

long long seed = {}

unsigned long grid_x_size = {}

unsigned long grid_y_size = {}

unsigned long sample_x_size = {}

unsigned long sample_y_size = {}

unsigned long sample_x_offset = {}

unsigned long sample_y_offset = {}

unsigned long fine_map_x_size = {}

unsigned long fine_map_y_size = {}

unsigned long fine_map_x_offset = {}

unsigned long fine_map_y_offset = {}

unsigned long coarse_map_x_size = {}

unsigned long coarse_map_y_size = {}

unsigned long coarse_map_x_offset = {}

unsigned long coarse_map_y_offset = {}

unsigned long coarse_map_scale = {}

unsigned long desired_specnum = {}

double dispersal_relative_cost = {}

double deme = {}

double deme_sample = {}

long double spec = {0.0}

double sigma = {}

unsigned long max_time = {}

double gen_since_historical = {}

double habitat_change_rate = {}

double tau = {}

string dispersal_method

double m_prob = {}

double cutoff = {}

bool restrict_self = {}

string times_file

vector<double> times

ConfigParser configs

bool is_historical = {}

bool uses_spatial_sampling = {}

string landscape_type

bool is_protracted = {}

double min_speciation_gen = {}

double max_speciation_gen = {}

string dispersal_file

string death_file

string reproduction_file

std::queue<HistoricalMapParameters> all_historical_map_parameters

bool has_parsed_historical

Friends

ostream &operator<<(ostream &os, const SimParameters &m)

Overloading the << operator for outputting to the output stream.

Return

os the output stream.

Parameters

• os: the output stream.
• m: the SimParameters object.

istream &operator>>(istream &is, SimParameters &m)

Overloading the >> operator for inputting from an input stream.

Return

is the input stream

Parameters

• is: the input stream
• m: the mapvars object

Struct SQLStatement

• Defined in File SQLiteHandler.h

Struct Documentation

struct SQLStatement

Wrapper for sqlite3_stmt which stores the last command issued and the pointer to the statement object.

Public Functions

SQLStatement()

Default constructor.

int step()

Steps the transaction forwards one step.

Note

Waits 10 seconds for locks to be released before raising an error if there are problems.

Return

the result code of the transaction step

void clearAndReset()

Destroys the previous bindings and resets the statement.

Public Members

std::string last_command

sqlite3_stmt *stmt

Class LandscapeMetricsCalculator

• Defined in File LandscapeMetricsCalculator.h

Inheritance Relationships

Base Type

• public necsim::Map< double > (Template Class Map)

Class Documentation

class LandscapeMetricsCalculator : public necsim::Map<double>

Calculates a variety of landscape metrics from an imported tif file.

Public Functions

LandscapeMetricsCalculator()

virtual ~LandscapeMetricsCalculator()

double calculateMNN()

Calculates the mean distance between nearest neighbours on a Map.

Return

the mean distance between every cell and its nearest neighbour

void checkMinDistance(Cell &home_cell, const long &x, const long &y, double &min_distance)

Checks if the minimum distance between cells is a new minimum.

Parameters

• home_cell: the cell to check the distance from
• x: the x coordinate of the new location
• y: the y coordinate of the new location
• min_distance: the previous minimum distance

double findNearestNeighbourDistance(const long &row, const long &col)

Determines the distance to the nearest neighbour of a cell.

Return

Parameters

• row:
• col:

void createCellList()

Creates a list containing all habitat cells in the landscape. List is stored in all_cells.

double calculateClumpiness()

Calculates the clumpiness metric, which measures the degree to which the focal habitat is aggregated or clumped given its total area.

Return

the clumpiness metric

unsigned long calculateNoAdjacencies()

Calculates the number of adjacencies in the landscape.

Adjacencies are habitat cells that are directly next to each other. Note that this uses the “double=count” method.

Return

the number of adjacent cells in the landscape.

double calculateMinPerimeter()

Calculates the minimum bounding perimeter for square cells on a landscape.

Return

the minimum bounding perimeter for cells on a landscape

void setCPLErrorHandler()

void removeCPLErrorHandler()

void open(const string &filename_in)

Opens the provided filename to the poDataset object.

Parameters

• filename: file to open in read-only mode.

void open()

Overloaded open for using the preset file name.

bool isOpen()

Checks if the connection to the map file has already been opened.

All this does is check if poDataset is a null pointer.

Return

true if poDataset is a null pointer.

void close()

Destroys the connection to the dataset.

void getRasterBand()

Sets the raster band to the first raster.

void getBlockSizes()

Obtains the x and y dimensions from the tif file for reading in blocks.

void getMetaData()

Sets the no data, data type and data type name values from the tif file.

double getUpperLeftX() const

Gets the upper left x (longitude) coordinate.

Return

upper left x of the map

double getUpperLeftY() const

Gets the upper left y (latitude) coordinate.

Return

upper left y of the map

string getFileName() const

Gets the name of the file that has been imported from.

Return

the file name

void import(const string &filename)

Imports the matrix from a csv file.

Exceptions

• runtime_error: if type detection for the filename fails.

Parameters

• filename: the file to import.

bool importTif(const string &filename)

Imports the matrix from a tif file using the gdal library functions.

Note

Opens a connection to the file object, which should be closed.

Parameters

• filename: the path to the file to import.

bool openOffsetMap(Map &offset_map)

Opens the offset map and fetches the metadata.

Return

true if the offset map is opened within this function

Parameters

• offset_map: the offset map to open (should be the larger map).

void closeOffsetMap(Map &offset_map, const bool &opened_here)

void calculateOffset(Map &offset_map, long &offset_x, long &offset_y)

Calculates the offset between the two maps.

The offset_map should be larger and contain this map, otherwise returned values will be negative

Note

Opens a connection to the tif file (if it has not already been opened), which is then closed. If the connection is already open, then it will not be closed and it is assumed logic elsewhere achieves this.

Note

Offsets are returned as rounded integers at the resolution of the smaller map.

Parameters

• offset_map: the offset map to read from
• offset_x: the x offset variable to fill
• offset_y: the y offset variable to fill

unsigned long roundedScale(Map &offset_map)

Calculates the relative scale of this map compared to the offset map.

The offset map should be larger and contain this map.

Note

Only the x resolution is checked, it is assumed the x and y resolutions of both maps is the same (i.e. each cell on the map is a square.

Return

the relative scale of the offset map

Parameters

• offset_map: the offset map object to read from

void internalImport()

Default importer when we rely on the default gdal method of converting between values. Note that importing doubles to ints results in the values being rounded down.

Return

true if a tif file exists and can be imported, false otherwise.

void internalImport()

Overloaded imported for handling conversion of types to boolean. This function should only be once elsewhere, so inlining is fine, allowing this file to remain header only.

void internalImport()

Overloaded functions for importing from tifs and matching between gdal and C types.

void internalImport()

void internalImport()

void internalImport()

void internalImport()

void internalImport()

void internalImport()

void internalImport()

void defaultImport()

Default import routine for any type. Provided as a separate function so implementation can be called from any template class type.

void importFromDoubleAndMakeBool()

Imports from the supplied filename into the GeoTiff object, converting doubles to booleans. The threshold for conversion is x>0.5 -> true, false otherwise.

void importUsingBuffer(GDALDataType dt_buff)

Imports from the supplied filename into the GeoTiff object, converting doubles to booleans. The threshold for conversion is x>0.5 -> true, false otherwise.

Parameters

• dt_buff: the buffer type for the data

Template Parameters

• T2: the template type for data reading.

void printNumberComplete(const uint32_t &j, unsigned int &number_printed)

Print the percentage complete during import.

Parameters

• j: the reference for the counter
• number_printed: the number of previously printed lines

void checkTifImportFailure()

Checks the error code of the CPLErr object and formats the error.

void setSize(unsigned long rows, unsigned long cols)

Sets the matrix size. Similar concept to that for Rows.

Parameters

• rows: the number of rows.
• cols: the number of columns.

unsigned long getCols() const

Getter for the number of columns.

Return

the number of columns.

unsigned long getRows() const

Getter for the number of rows.

Return

the number of rows.

void fill(double val)

Fills the matrix with the given value.

Parameters

• val: the value to fill

unsigned long index(const unsigned long &row, const unsigned long &col) const

Gets the index of a particular row and column in the matrix.

Return

the index of row and column within the matrix

Parameters

• row: the row number to index
• col: the column number to index

double &get(const unsigned long &row, const unsigned long &col)

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

const double &get(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

double getCopy(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

vector<double>::iterator begin()

Returns iterators for range-based for loops.

Return

iterator to the start of the vector

vector<double>::const_iterator begin() const

Returns iterators for range-based for loops.

Return

iterator to the start of the vector

vector<double>::iterator end()

Returns end iterators for range-based for loops.

Return

iterator to the end of the vector

vector<double>::const_iterator end() const

Returns end iterators for range-based for loops.

Return

iterator to the end of the vector

double getMean() const

Gets the arithmetic mean of the Matrix.

Return

the mean value in the matrix

double sum() const

Matrix operator+(const Matrix &m) const

Overloading the + operator.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the matrix object which is the sum of the two matrices.

Parameters

• m: the matrix to add to this matrix.

Matrix operator-(const Matrix &m) const

Overloading the - operator.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the matrix object which is the subtraction of the two matrices.

Parameters

• m: the matrix to subtract from this matrix.

Matrix &operator+=(const Matrix &m)

Overloading the += operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator-=(const Matrix &m)

Overloading the -= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to subtract from this matrix.

Matrix operator*(const double s) const

Overloading the * operator for scaling.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the scaled matrix.

Parameters

• s: the constant to scale the matrix by.

Matrix operator*(Matrix &m) const

Overloading the * operator for matrix multiplication.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension. Multiplies each value in the matrix with its corresponding value in the other matrix.

Return

the product of each ith,jth value of the matrix.

Parameters

• m: the matrix to multiply with

Matrix &operator*=(const double s)

Overloading the *= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator*=(const Matrix &m)

Overloading the *= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix operator/(const double s) const

Overloading the / operator for scaling.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the scaled matrix.

Parameters

• s: the constant to scale the matrix by.

Matrix &operator/=(const double s)

Overloading the /= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator/=(const Matrix &m)

Overloading the /= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

void setValue(const unsigned long &row, const unsigned long &col, const char *value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters

• row: the row index.
• col: the column index.
• value: the value to set

void setValue(const unsigned long &row, const unsigned long &col, const double &value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters

• row: the row index.
• col: the column index.
• value: the value to set

bool importCsv(const string &filename)

Imports the matrix from a csv file using the fast-csv-parser method.

Return

true if the csv can be imported.

Parameters

• filename: the path to the file to import.Imports the matrix from a csv file using the standard, slower method.

Parameters

• filename: the path to the file to import.

Protected Attributes

shared_ptr<GDALDataset *> po_dataset

shared_ptr<GDALRasterBand *> po_band

unsigned long block_x_size

unsigned long block_y_size

double no_data_value

string file_name

GDALDataType gdal_data_type

CPLErr cpl_error

double upper_left_x

double upper_left_y

double x_res

double y_res

bool cpl_error_set

unsigned long num_cols

unsigned long num_rows

vector<double> matrix

Class ActivityMap

• Defined in File ActivityMap.h

Class Documentation

class ActivityMap

Contains the routines for importing activity maps and getting a cell value from the map.

Activity maps can be reproduction probability maps or death maps.

Public Functions

ActivityMap()

bool isNull()

Gets if the map is a null reproduction map, with no matrix storage in memory necessary.

Return

true if the map is “null” or “none”

void import(string file_name, unsigned long size_x, unsigned long size_y, shared_ptr<RNGController> random_in)

Imports the map file from the given path Requires the dimensions to be identical as the fine map file dimensions.

Parameters

• file_name: the path to the reproduction map to import
• size_x: the x dimensions of the map file
• size_y: the y dimensions of the map file

void setActivityFunction()

Correctly sets the reproduction function to either rejectionSampleNull or rejectionSample depending on if a reproduction map is used or not.

void setOffsets(const unsigned long &x_offset, const unsigned long &y_offset, const unsigned long &xdim, const unsigned long &ydim)

Sets the offsets for the reproduction map from the sample grid.

Parameters

• x_offset: the x offset from the sample grid
• y_offset: the y offset from the sample grid
• xdim: the x dimension of the sample grid
• ydim: the y dimension of the sample grid

bool rejectionSampleNull(const unsigned long &x, const unsigned long &y, const long &xwrap, const long &ywrap)

Returns true for all cell values Function to be pointed to in cases where there is no reproduction map.

Return

true always

Parameters

• random_number: random number object to pass forward
• x: x coordinate of the lineage on the sample grid
• y: y coordinate of the lineage on the sample grid
• xwrap: x wrapping of the lineage
• ywrap: y wrapping of the lineage

bool rejectionSample(const unsigned long &x, const unsigned long &y, const long &xwrap, const long &ywrap)

Returns true for all cell values Function to be pointed to in cases where there is no reproduction map.

Return

true always

Parameters

• random_number: random number object to pass forward
• x: x coordinate of the lineage on the sample grid
• y: y coordinate of the lineage on the sample grid
• xwrap: x wrapping of the lineage
• ywrap: y wrapping of the lineage

double getVal(const unsigned long &x, const unsigned long &y, const long &xwrap, const long &ywrap)

Gets the value of the reproduction map at that location.

Return

value of the reproduction map at the required location

Parameters

• x: x coordinate of the lineage on the sample grid
• y: y coordinate of the lineage on the sample grid
• xwrap: x wrapping of the lineage
• ywrap: y wrapping of the lineage

bool actionOccurs(const unsigned long &x, const unsigned long &y, const long &xwrap, const long &ywrap)

Tests if the random action occurs.

Return

value of the reproduction map at the required location

Parameters

• x: x coordinate of the lineage on the sample grid
• y: y coordinate of the lineage on the sample grid
• xwrap: x wrapping of the lineage
• ywrap: y wrapping of the lineage

void standardiseValues()

Standardises probability values from 0-1.

double get(const unsigned long &rows, const unsigned long &cols)

Get the value at the specified index.

Return

the value at the specified row and column

Parameters

• rows: the row index to obtain
• cols: the column index to obtain

double getMean() const

Gets the arithmetic mean of the Map object.

Return

the mean value

ActivityMap &operator=(const ActivityMap &rm)

Equality operator.

Return

the self ActivityMap object

Parameters

• rm: the ActivityMap object to copy from

Protected Types

typedef bool (ActivityMap::*rep_ptr)(const unsigned long &x, const unsigned long &y, const long &xwrap, const long &ywrap)

Protected Attributes

Map<double> activity_map

string map_file

double max_val

bool null_map

unsigned long offset_x

unsigned long offset_y

unsigned long x_dim

unsigned long y_dim

shared_ptr<RNGController> random

rep_ptr activity_map_checker_fptr

Friends

ostream &operator<<(ostream &os, ActivityMap &r)

Operator for outputting to an ostream.

Return

the os object

Parameters

• os: the ostream to output to
• r: the ActivityMap to read from

istream &operator>>(istream &is, ActivityMap &r)

Operator for inputting from an istream.

Return

the is object

Parameters

• is: the istream to input from
• r: the ActivityMap to input to

Class AnalyticalSpeciesAbundancesHandler

• Defined in File AnalyticalSpeciesAbundancesHandler.h

Inheritance Relationships

Base Type

• public necsim::SpeciesAbundancesHandler (Class SpeciesAbundancesHandler)

Class Documentation

class AnalyticalSpeciesAbundancesHandler : public virtual necsim::SpeciesAbundancesHandler

Public Functions

AnalyticalSpeciesAbundancesHandler()

Default constructor.

~AnalyticalSpeciesAbundancesHandler()

Default destructor.

void setup(shared_ptr<RNGController> random, const unsigned long &metacommunity_size, const long double &speciation_rate, const unsigned long &local_community_size)

Creates the SpeciesAbundancesHandler object.

Parameters

• random: the random number generator
• metacommunity_size: the number of individuals in the metacommunity
• speciation_rate: the speciation rate of the metacommunity
• local_community_size: the number of individuals in the local community

void generateSpeciesAbundances()

Generates the species abundances using the analytical approximation.

unsigned long getRandomSpeciesID()

Gets a randomly generated species identity.

Return

the species identity

unsigned long pickPreviousIndividual(const unsigned long &individual_id)

Picks out a random individual from previously-seen individuals.

Return

species id of the individual

Parameters

• individual_id: the individual id number to pick

void addNewSpecies()

Picks out a new individual/species id with a random species abundance.

Return

the species id of the new individual

unsigned long getRandomAbundanceOfSpecies()

Gets a random species abundance by sampling from the logarithmic distribution.

Note

this produces the abundance of any given species, not the abundance of any given individual

Return

the randomly generated abundance of a species

void setAbundanceList(const shared_ptr<map<unsigned long, unsigned long>> &abundance_list_in)

Sets the abundance list.

Parameters

• abundance_list_in: list of abundances for each species

void setAbundanceList(shared_ptr<vector<unsigned long>> abundance_list_in)

Sets the abundance list.

Parameters

• abundance_list_in: list of abundances for each species

Protected Attributes

unsigned long seen_no_individuals

map<unsigned long, unsigned long> ind_to_species

shared_ptr<RNGController> random

unsigned long max_species_id

unsigned long metacommunity_size

unsigned long local_community_size

long double speciation_rate

Class Cell

• Defined in File Cell.h

Class Documentation

class Cell

Simple structure containing the x and y positions of a cell.

Public Functions

Cell()

Default contructor for Cell.

Sets x and y to 0.

Cell(long x, long y)

Constructor for Cell, taking the x and y position.

Parameters

• x: the x location
• y: the y location

Cell &operator=(Cell const &c)

Overloading equality operator.

Return

the cell with the new values

Parameters

• c: the Cell containing the values to overload

bool operator==(Cell const &c)

Equality operator for Cell.

Return

true if the x and y locations are identical

Parameters

• c: the Cell object to compare against

bool operator!=(Cell const &c)

Inequality operator for Cell.

Return

true if the x and y locations are not identical

Parameters

• c: the Cell object to compare against

Public Members

long x

long y

Class Community

• Defined in File Community.h

Inheritance Relationships

Derived Type

• public necsim::Metacommunity (Class Metacommunity)

Class Documentation

class Community

A class to contain the tree object lineages and reconstructing the coalescence tree. Contains functions for calculating the number of species for a given speciation rate, outputting spatial data and generating species abundance distributions. Requires a link to the SQLite database from simulation output, and produces results within the same database file.

Subclassed by necsim::Metacommunity

Public Functions

Community(shared_ptr<vector<TreeNode>> r)

Contructor for the community linking to Treenode list.

Parameters

• r: Row of TreeNode objects to link to.

Community()

Default constructor.

virtual ~Community()

Default destructor.

void setList(shared_ptr<vector<TreeNode>> l)

Set the nodes object to the input Row of Treenode objects.

Parameters

• l: the Row of Treenode objects to link to.

ProtractedSpeciationParameters setupInternal(shared_ptr<SimParameters> sim_parameters, shared_ptr<SQLiteHandler> database)

Sets up the community from a set of simulation parameters and the sqlite3 database connection.

Return

Parameters

• sim_parameters: parameters to use for setting up the community
• database: points to the database object to open

void setDatabase(shared_ptr<SQLiteHandler> dbin)

Sets the database object for the sqlite functions.

Parameters

• dbin: the sqlite3 input database.

bool hasImportedData()

Get the boolean of whether the data has been imported yet.

Return

true if database has been imported.

long double getMinimumSpeciation()

Get the minimum speciation rate the simulation was originally run with. This value is read in from the SIMULATION_PARAMETERS table in the database file.

Return

the minimum speciation rate.

void importSamplemask(string sSamplemask)

Imports the samplemask if it hasn’t already been imported.

Parameters

• sSamplemask: the path to the samplemask file.

unsigned long countSpecies()

Counts the number of species that have speciated currently on the tree.

Return

the number of species

unsigned long calculateCoalescenceTree()

Calculate the number of species in the list for the parameters in the current_community_parameters object. This is the main function which reconstructs the coalescence tree. Each Treenode object will end having its existence value set correctly after a call to this function.

Return

the number of species present.

void addSpecies(unsigned long &species_count, TreeNode *treenode, set<unsigned long> &species_list)

Speciates TreeNode and updates the species count.

For systems which are not using a metacommunity, this function will just perform basic speciation.

Note

species_list is not updated in unless the function is overridden for metacommunity application.

Parameters

• species_count: the total number of species currently in the community
• treenode: pointer to the TreeNode object for this lineage
• species_list: the set of all species ids.

void calcSpeciesAbundance()

Calculates the species abundance of the dataset. The species abundances will be with rOut after a call do this function. If a samplemask has been applied, only lineages which originally existed in the samplemask will be counted.

void resetTree()

Resets the entire tree. Sets existance to false, speciation to false and removes any species ID.

void openSqlConnection(string input_file)

Opens the connection to the sql database file Note that this imports the database to memory, so functionality should be changed for extremely large database files.

Parameters

• input_file: the sql database output from a necsim simulation.

void closeSqlConnection()

Safely destroys the SQL connection.

void setInternalDatabase()

Opens a connection to an in-memory database. This will eventually be written to the output file.

void internalOption()

Internally sets the file referencing, data import and sql connection flags to true, for allowing checks to pass from internal object creation (so no external files are needed)

void importData(string inputfile)

Imports the data from the desired SQL database object into the array.

Note

Opens the sql connection if it has not already been opened.

Note

If nodes is not of length 0, this function does nothing. This is so that any in-memory data is not overwritten.

Parameters

• inputfile: the path to the input SQLite database.

void setSimParameters(shared_ptr<SimParameters> sim_parameters)

Sets the simulation parameters from a SimParameters object.

Parameters

• sim_parameters: pointer to the SimParameters object to set from

void setSpecSimParameters(shared_ptr<SpecSimParameters> spec_sim_parameters)

Sets the speciation parameters from a SpecSimParameters object.

Note

Be careful of the difference between this function and setSimParameters (which sets the main simulation parameters).

Parameters

• spec_sim_parameters: pointer to the SpecSimParameters object containing community speciation parameters

void importSimParameters(string file)

Imports the simulation parameters by reading the SIMULATION_PARAMETERS table in the provided file. This imports the grid_x_size, grid_y_size (which should also be the sample map dimensions) and the minimum speciation rate.

Note

Opens the sql connection if it has not already been opened.

Note

If bDataImport has already been set, no operation is performed.

Parameters

• file: the sqlite database simulation output which will be used for coalescence tree generation.

void forceSimCompleteParameter()

Forces the sim_complete parameter to be true in SIMULATION_PARAMETERS. Used when speciating all remaining lineages to force a simulation to completion.

bool isSetDatabase()

Gets if the database has been set yet.

Return

true if the database is already set

void getMaxSpeciesAbundancesID()

Gets the maximum species abundance ID from the database and stores it in the max_species_id variable.

Note

Does not check for SPECIES_ABUNDANCES existence and will throw an error if it cannot access it

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Changes the rOut object so that values represent cummulative species abundances.

Allows binary sort on rOut (much faster) and the previous rOut value can be obtained by value = rOut[i] - rOut[i-1]

Return

pointer to sorted Row of species abundances

shared_ptr<vector<unsigned long>> getRowOut()

Returns the row_out object, which should contain species abundances or cumulative abundances.

Note

Does not recalculate species abundances, so if getCumulativeAbundances has been called, will return the cumulative species abundances instead.

Note

Returns a copy, so could cause problems for extremely large simulations with immense numbers of species.

Return

row_out, the species abundances, or the cumulative abundances if getCumulativeAbundances has been called

unsigned long getSpeciesNumber()

Gets the number of species in the most recent calculation.

Return

the number of species in the most recent calculation

void getMaxFragmentAbundancesID()

Gets the maximum fragment abundance ID from the database and stores it in the max_fragment_id variable.

Note

Does not check for FRAGMENT_ABUNDANCES existence and will throw an error if it cannot access it

void getMaxSpeciesLocationsID()

Gets the maximum species locations ID from the database and stores it in the max_locations_id variable.

Note

Does not check for SPECIES_LOCATIONS existence and will throw an error if it cannot access it

void setProtractedParameters(const ProtractedSpeciationParameters &protracted_params)

Sets the protracted parameters for application of protracted speciation.

This overloaded version is for setting protracted parameters before a full simulation has been outputted (i.e. immediately after completion of the simulation).

Parameters

• protracted_params: protracted speciation parameters to add

void overrideProtractedParameters(const ProtractedSpeciationParameters &protracted_params)

Overrides the protracted parameters for the Community object.

Parameters

• protracted_params: the protracted parameters to override with

void setProtracted(bool protracted_in)

Sets the protracted boolean to the input.

Parameters

• protracted_in: the protracted boolean to set

void createDatabase()

Creates a new table in the database file and outputs the database object to the same file as the input file. Calculates the community structure for the set of community parameters in current_community_parameters.

The new SPECIES_ABUNDANCES table contains the species abundance distribution for the whole samplemask. A similar tabe FRAGMENT_ABUNDANCES is generated by createFragmentDatabase() if specified via the command line parameters.

void generateBiodiversity()

Calculates the coalescence tree and generates species abundances.

void outputSpeciesAbundances()

Outputs the species abundances into the database.

bool checkCalculationsPerformed(const long double &speciation_rate, const double &time, const bool &fragments, const MetacommunityParameters &metacomm_parameters, const ProtractedSpeciationParameters &proc_parameters)

Checks if calculations with the given set of parameters has already been performed.

Return

Parameters

• speciation_rate: the speciation rate to check for
• time: the time to check for
• fragments: if true, checks fragments have been used
• metacommunity_size: the metacommunity size to check for
• metacommunity_speciation_rate: the metacommunity speciation rate to check for
• proc_parameters: protracted speciation parameters to add

void addCalculationPerformed(const long double &speciation_rate, const double &time, const bool &fragments, const MetacommunityParameters &metacomm_parameters, const ProtractedSpeciationParameters &protracted_parameters)

Adds a performed calculation to the lists of calculations. Also sets the current_community_parameters pointer to the set of parameters to be applied.

Parameters

• speciation_rate: the speciation rate of the performed calculation
• time: the time of the performed calculation
• fragments: if true, fragments were used
• metacommunity_size: the metacommunity size of the performed calculation
• metacommunity_speciation_rate: the metacommunity speciation rate of the performed calculation
• protracted_parameters: protracted speciation parameters to add

void createFragmentDatabase(const Fragment &f)

Creates a new table in the database file and outputs the database object to the same file as the input file. Essentially creates a species abundance distribution (as in createDatabase()), but for the specified fragment within the samplemask.

Parameters

• f: the Fragment to sample from.

void exportDatabase()

Output the database from memory to the database file. Most of the time, it is desirable for the outputfile to be the same path as the input file and will write to the same object.

bool checkSpeciesLocationsReference()

Checks for the current CommunityParameters reference in the SPECIES_LOCATIONS table.

Return

true if the reference exists in the SPECIES_LOCATIONS table

bool checkSpeciesAbundancesReference()

Checks for the current CommunityParameters reference in the SPECIES_ABUNDANCES table.

Return

return true if the reference exists in the SPECIES_LOCATIONS table

void recordSpatial()

Record the full spatial data. Creates a new table, SPECIES_LOCATIONS containing every species and their parameters. This allows for more in-depth analysis to be performed if necessary.

void calcFragments(string fragment_file)

Calculates the limits of each fragment in the sample map and adds it to the vector of fragments. If the fragment_file is null, then the program will attempt to calculate fragments from the map.

Parameters

• fragment_file: the fragment file to read from.

void applyFragments()

Calculate species abundances for each fragment, and call createFragmentDatabase() for each Fragment.

void getPreviousCalcs()

Gets the previous calculations that have already been performed.

vector<unsigned long> getUniqueCommunityRefs()

Gets the unique community references from the SQL database.

Return

a vector containing the unique references

vector<unsigned long> getUniqueMetacommunityRefs()

Gets the unique metacommunity reference from the SQL database.

Return

a vector containing the unique references

void writeNewCommunityParameters()

Write all performed calculations to the output database.

void writeNewMetacommunityParameters()

Write all performed calculations to the output database.

void createSpeciesList()

Creates a new table, SPECIES_LIST in the output database.

void deleteSpeciesList()

Drops the SPECIES_LIST table from the database.

void writeSpeciesList(const unsigned long &enddata)

Writes the coalescence tree to a table called SPECIES_LIST.

void updateCommunityParameters()

Updates the fragments tag on those simulations which now have had fragments added.

void writeSpeciationRates()

Prints speciation rates to terminal.

void calculateTree()

Calculates the coalescence tree for each set of parameters in speciation_parameters;.

void output()

Outputs the data to the SQL database.

void printEndTimes(time_t tStart, time_t tEnd)

Prints the application times.

Parameters

• tStart: the start time
• tEnd: the end time

void apply(shared_ptr<SpecSimParameters> sp)

Apply the given speciation parameters to the coalescence tree. Overridden for metacommunity application.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void applyNoOutput(shared_ptr<SpecSimParameters> sp)

Applies the given speciation parameters to the coalescence tree, but does not write the output.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void applyNoOutput(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> tree_data)

Applies the given speciation parameters to the coalescence tree, but does not write the output.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
• tree_data: the coalescence tree containing simulation data

void setupApplication(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Sets up the community application by reading parameters and data.

Parameters

• sp: the speciation parameters to use for generating the community
• data: the list of all nodes on the coalescence tree

void doApplication(shared_ptr<SpecSimParameters> sp)

Creates the coalescence tree for the given speciation parameters.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void doApplication(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Creates the coalescence tree for the given speciation parameters.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
• data: the Row of TreeNodes that contains the coalescence tree.

void doApplicationInternal(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Creates the coalescence tree for the given speciation parameters, using internal file referencing to avoid any actual file creation.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
• data: the Row of TreeNodes that contains the coalescence tree.

void speciateRemainingLineages(const string &filename)

Speciates the remaining lineages in an incomplete simulation to force it to appear complete.

unsigned long getSpeciesRichness(const unsigned long &community_reference)

Gets the species richness for the community reference from the database.

Return

the number of species

Parameters

• community_reference: the community reference to obtain the species richness for

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances of the community.

Return

a map of species ids to species abundances

Parameters

• community_reference: the reference of the desired community

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundance from the species_abundances internal object.

Return

the species abundances

bool isDatabaseNullPtr()

Check if the database is a null pointer.

Return

true if the database is a null pointer.

Protected Attributes

bool in_mem

bool database_set

shared_ptr<SQLiteHandler> database

bool bSqlConnection

shared_ptr<vector<TreeNode>> nodes

shared_ptr<vector<unsigned long>> species_abundances

unsigned long iSpecies

bool has_imported_samplemask

bool has_imported_data

Samplematrix samplemask

vector<Fragment> fragments

shared_ptr<CommunityParameters> current_community_parameters

shared_ptr<MetacommunityParameters> current_metacommunity_parameters

long double min_spec_rate

unsigned long grid_x_size

unsigned long grid_y_size

unsigned long samplemask_x_size

unsigned long samplemask_y_size

unsigned long samplemask_x_offset

unsigned long samplemask_y_offset

CommunitiesArray past_communities

MetacommunitiesArray past_metacommunities

bool protracted

ProtractedSpeciationParameters minimum_protracted_parameters

ProtractedSpeciationParameters applied_protracted_parameters

unsigned long max_species_id

unsigned long max_fragment_id

unsigned long max_locations_id

shared_ptr<SpecSimParameters> spec_sim_parameters

Class ConfigParser

• Defined in File ConfigParser.h

Class Documentation

class ConfigParser

Stores and parses configuration options from the command line and config files.

Public Functions

ConfigParser()

default construtor for ConfigOption

void setConfig(const string &file, bool main, bool full_parse = false)

Sets the config file the specified string. A boolean is also provided, set equal to true if this is the main command line import. This causes the deletion of the first few command line options after import.

Parameters

• file: the target config file (in .txt format).
• main: boolean of if this is the main command line import.
• full_parse: sets bFullParse to provided value

void parseConfig()

Reads a config file of a specific configuration. Each section begins with ‘[section_name]’. Each variable is defined as ‘key=value’, and must be one per line Each key’s variable will be read as a string into a KeyOption structure.

void parseConfig(istream &istream1)

Reads a config stream of a specific configuration. Each section begins with ‘[section_name]’. Each variable is defined as ‘key=value’, and must be one per line Each key’s variable will be read as a string into a KeyOption structure.

vector<SectionOption> getSectionOptions()

Returns the vector of key options imported from the file.

Return

vector of key options

void setSectionOption(string section, string reference, string value)

Sets the section option with the provided section, key and value.

Parameters

• section: the section name
• reference: the reference key for the parameter
• value: the value of the key

SectionOption operator[](unsigned long index)

Gets the SectionOption at the provided index.

Return

the section option at the index

Parameters

• index: the index of the SectionOption to obtain, must be less than configs.size()

unsigned long getSectionOptionsSize()

Gets the size of the key options vector.

Return

the size of the configuration vector.

vector<string> getSections()

Gets the sections contained in the SectionOptions object.

Return

A vector of the section names.

bool hasSection(const string &sec)

Checks whether the config option has the specified section.

Return

true if the section has been found

Parameters

• sec: the section name to check for

vector<string> getSectionValues(string sec)

Gets all values within a section.

Throws a Config_Exception if the section is not found.

Return

a vector of the section’s values.

Parameters

• sec: the section to find values for

string getSectionOptions(string section, string ref)

Returns a specific value for a particular key options and reference.

Return

the string at the correct place in KeyOptions.val

Parameters

• section: the section to match
• ref: the reference to match

string getSectionOptions(string section, string ref, string def)

Returns a specific value for a particular key options and reference. This overloaded version of the function returns the default value def when no match is found.

Return

the string at the correct place in KeyOptions.val

Parameters

• section: the section to match
• ref: the reference to match
• def: the default value to return if no match is found

int importConfig(vector<string> &comargs)

Imports the parameters from the config file and returns an integer of the number of arguments.

Return

a count of the number of arguments (should also be the size of comargs).

Parameters

• comargs: a vector of command line arguments to import to from file.

Friends

ostream &operator<<(ostream &os, const ConfigParser &c)

Overloading the << operator for outputting to the output stream.

Return

os the output stream.

Parameters

• os: the output stream.
• c: the ConfigOption object.

istream &operator>>(istream &is, ConfigParser &c)

Overloading the >> operator for inputting from an input stream. Note that the config file must still exist for re-inport and parsing.

Return

is the input stream

Parameters

• is: the input stream
• c: the ConfigOption object

Class DataMask

• Defined in File DataMask.h

Inheritance Relationships

Derived Type

• public necsim::Samplematrix (Class Samplematrix)

Class Documentation

class DataMask

Contains the DataMask object, a Matrix of booleans describing the spatial sampling pattern.

Subclassed by necsim::Samplematrix

Public Functions

DataMask()

The DataMask constructor.

~DataMask()

bool isNull()

Returns if the simulation is using the a null samplemask, and therefore does not need to store the full sample grid in memory.

Return

true if using a null samplemask

void setup(shared_ptr<SimParameters> sim_parameters)

Sets the parameters for the datamask, including the dimensions of the map, the offsets from the grid and the dimensions of the grid itself for recalculating coordinates.

Parameters

• sim_parameters: Simulation parameter to set the data mask from

bool checkCanUseDefault(shared_ptr<SimParameters> sim_parameters)

void importBooleanMask(unsigned long xdim, unsigned long ydim, unsigned long mask_xdim, unsigned long mask_ydim, unsigned long xoffset, unsigned long yoffset, string inputfile_in)

Imports the sample mask as a boolean mask and sets the relevant sample mask dimensions. Should only be called if the import is actually required (i.e. the map is not null or none).

Parameters

• xdim: the x dimension of the grid area
• ydim: the y dimension of the grid area
• mask_xdim: the x dimension of the sample map file
• mask_ydim: the y dimension of the sample map file
• xoffset: the x offset of the grid area from the sample map file
• yoffset: the y offset of the grid area from the sample map file
• inputfile_in: the path to the sample map file

void doImport()

Imports the boolean map object.

void completeBoolImport()

Sets the map dimensions and the getVal function pointer.

void setupNull(shared_ptr<SimParameters> mapvarin)

Sets up the null sampling map.

void importSampleMask(shared_ptr<SimParameters> mapvarin)

Imports the specified file for the sampling percentage within each cell.

The map should consist of floating points representing the relative sampling rates in each cell. Note that the actual sampling proportion is equal to the cell value multiplied by global deme sampling proportion.

Parameters

• mapvarin: the SimParameters object containing the samplemask file location and dimensions

bool getVal(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Calculates the matrix value at the provided x, y location. If everywhere is sampled, simply returns true, as no sample_mask will be stored in memory. This is to save RAM where possible.

Return

the sample_mask value at x,y (or true if the file was “null”)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps
• ywrap: the number of y wraps

double getNullProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Separate return function for always returning 1.0 as density value.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getBoolProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, for calculating the proportion of individuals to be sampled in each cell.

Note

this function assumes that the file is not “null” and the exact sampling mask has been imported. No error checks on these conditions are performed except in debugging mode.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getSampleProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, for calculating the proportion of individuals to be sampled in each cell.

Note

this function assumes that the file is not “null” and the exact sampling mask has been imported. No error checks on these conditions are performed except in debugging mode.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getExactValue(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, as returned by the pointer function.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

void convertBoolean(shared_ptr<Landscape> map1, const double &deme_sampling, const double &generation)

Converts the spatial map into the boolean grid required for continued simulation. This is done so that the faster boolean accesses are possible.

Parameters

• map1: the map object to obtain density values from
• deme_sampling: the proportion of individuals to sample
• generation: the generation individuals are added at

void clearSpatialMask()

Removes the spatial mask from memory. This should be performed if no more map expansions are required.

void recalculateCoordinates(long &x, long &y, long &x_wrap, long &y_wrap)

Converts the coordinates back into the grid format. Changes the values in the provided variables to be correct.

Parameters

• x: the x value to convert
• y: the y value to convert
• x_wrap: the xwrap variable to place the value into
• y_wrap: the ywrap variable to place the value into

Public Members

Map<bool> sample_mask

A binary grid telling whether or not the cell should be sampled.

Map<double> sample_mask_exact

Exact grid for determining sampling proportion.

Protected Types

typedef double (DataMask::*fptr)(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Protected Attributes

string inputfile

bool isNullSample

bool isGridOffset

unsigned long x_offset

unsigned long y_offset

unsigned long x_dim

unsigned long y_dim

unsigned long mask_x_dim

unsigned long mask_y_dim

fptr getProportionfptr

Class DataPoint

• Defined in File DataPoint.h

Inheritance Relationships

Base Type

• public necsim::MapLocation (Struct MapLocation)

Class Documentation

class DataPoint : public virtual necsim::MapLocation

A data object used in coalescence simulations for calculating the output. Data from this object is outputted to an SQLite database after simulations are complete.

Public Functions

DataPoint()

Standard constructor.

~DataPoint()

Standard destructor.

void setup(unsigned long x, unsigned long y, long xwrap_in, long ywrap_in, unsigned long reference_in, unsigned long list_position_in, double min_max_in)

Setup of lineage data with any information that’s wanted. Note that nwrap is set to 0 in this routine.

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap_in: the number of wraps of the location on the grid in the x direction
• ywrap_in: the number of wraps of the location on the grid in the y direction
• reference_in: the position in the TreeNode reference object
• list_position_in: the position within the SpeciesList object at the relevant x,y position
• min_max_in: the input maximum minimum speciation rate required for speciation to have occured

void setup(unsigned long reference_in, unsigned long list_position_in, double min_max_in)

Setup of lineage data with any information that’s wanted.

Parameters

• reference_in: the reference point for the TreeNode reference object
• list_position_in: the list position of this lineage in SpeciesList object
• min_max_in: the input maximum minimum speciation rate required for speciation to have occured

void setup(const DataPoint &datin)

Copy constructor from another Datapoint object.

Parameters

• datin: a Datapoint object to copy the data from.

void setReference(unsigned long z)

Sets the mpos (the position within the Row of TreeNode objects.).

Parameters

• z: the desired mpos.

void setNext(unsigned long x)

Set the next link in the linked list.

Parameters

• x: the next Datapoint object.

void setListPosition(unsigned long l)

Sets the list position within the SpeciesList object.

Parameters

• l: the input list position.

void setNwrap(unsigned long n)

Sets the number of wraps from the first SpeciesList wrapped lineage. If and only if this is 0, the lineage is within the main grid (i.e xwrap and ywrap should be 0).

Parameters

• n: the desired nwrap.

void setMinmax(double d)

Sets the minmax variable. This is the minimum maximum speciation rate required for speciation to have occured on this branch.

Parameters

• d: the minmax to set.

unsigned long getXpos() const

Get the x position.

Return

the xpos.

unsigned long getYpos() const

Get the y position.

Return

the ypos.

long getXwrap() const

Get the x wrapping.

Return

the xwrap.

long getYwrap() const

Get the y wrapping.

Return

the ywrap.

unsigned long getReference() const

Get the reference position variable.

Return

the mpos.

unsigned long getNext() const

Gets the next element linked to this DataPoint.

Return

the reference of the next individual in the linked list

unsigned long getListpos() const

Gets the list position with the SpeciesList object at the relevant x,y position.

Return

the listpos.

unsigned long getNwrap() const

Get the position in the linked list from the SpeciesList object. If this is 0, indicates the lineage lies on the original grid, and xwrap and ywrap should be 0.

Return

the nwrap.

double getMinmax() const

Get the maximum minimum speciation rate required for speciation to have occured on this branch.

Return

the minmax.

void decreaseNwrap()

Decreases the nwrap by 1 (to a minimum of 0).

template<class T>
void setEndpoint(const T &location)

Sets the position in space.

Parameters

• location: the location of the new end point

bool isOnGrid() const

Checks if the location is directly on the grid without wrapping (i.e. xwrap and ywrap are 0).

Return

true if on the grid

bool operator==(MapLocation const &m) const

Equality operator for MapLocation.

Return

true if the x, y, xwrap and ywrap are identical

Parameters

• m: the MapLocation object to compare against

bool operator!=(MapLocation const &m) const

Inequality operator for MapLocation.

Return

true if locations are not identical

Parameters

• m: the MapLocation object to compare against

Public Members

long x

long y

long xwrap

long ywrap

Friends

ostream &operator<<(ostream &os, const DataPoint &d)

An operator for piping the variables of the Datapoint object to the output stream.

Return

returns the output stream at the end.

Parameters

• os: the output stream.
• d: the Datapoint object to output.

istream &operator>>(istream &is, DataPoint &d)

An operator for piping the variables in to the Datapoint object from the input stream.

Return

returns the input stream at the end.

Parameters

• is: the input stream
• d: the Datapoint object to input to.

Class DispersalCoordinator

• Defined in File DispersalCoordinator.h

Class Documentation

class DispersalCoordinator

Class for generating dispersal distances and provide routines for reading dispersal distance maps as a unwound map-of-maps. This class also handles reading density maps for rejection sampling.

It requires linking to a density map, random number generator and a generation counter from the Tree class.

Note that no element of this object is recorded during a paused simulation, as all objects pointed to are stored elsewhere and behaviours are recalculated upon simulation resume.

Public Functions

DispersalCoordinator()

~DispersalCoordinator()

void setRandomNumber(shared_ptr<RNGController> NR_ptr)

Sets the random number pointer to an NRrand instance.

Parameters

• NR_ptr: the random number object to set to

bool isFullDispersalMap() const

Checks if using a full dispersal map.

“Full” dispersal maps are those which are not “none”, “null” and correspond to an file path.

Return

true if using a full dispersal map

void setMaps(const shared_ptr<Landscape> &landscape_ptr, shared_ptr<ActivityMap> repr_map_ptr)

Sets the pointer to the Landscape object.

Parameters

• landscape_ptr: pointer to a Landscape object
• repr_map_ptr: pointer to the reproduction probability map

void setMaps(const shared_ptr<Landscape> &landscape_ptr)

Sets the pointer to the Landscape object.

Parameters

• landscape_ptr: pointer to a Landscape object

void setGenerationPtr(double *generation_ptr)

Sets the generation pointer to the provided double.

Parameters

• generation_ptr: pointer to the generation double

void setDispersal(const string &dispersal_method, const string &dispersal_file, const unsigned long &dispersal_x, const unsigned long &dispersal_y, const double &m_probin, const double &cutoffin, const double &sigmain, const double &tauin, const bool &restrict_self)

Sets the dispersal method and parameters.

Parameters

• dispersal_method: string containing the dispersal type. Can be one of [normal, fat-tail, norm-uniform]
• dispersal_file: string containing the dispersal file, or “none” if using dispersal kernel
• dispersal_x: the x dimensions of the dispersal file
• dispersal_y: the y dimensions of the dispersal file
• m_probin: the probability of drawing from the uniform distribution. Only relevant for uniform dispersals
• cutoffin: the maximum value to be drawn from the uniform dispersal. Only relevant for uniform dispersals
• sigmain: the fatness of the fat-tailed dispersal kernel
• tauin: the width of the fat-tailed dispersal kernel
• restrict_self: if true, denies possibility that dispersal comes from the same cell as the parent

void setDispersal(shared_ptr<SimParameters> simParameters)

Sets the dispersal parameters from the SimParameters object.

Parameters

• simParameters: pointer to the simulation parameters to set

void importDispersal(const unsigned long &dispersal_dim, const string &dispersal_file)

Imports the dispersal map and fixes the values based on the density and reproduction probabilities.

Parameters

• dispersal_dim: pointer x and y dimension of the dispersal map
• dispersal_file: name of the dispersal file

void setRawDispersalMap()

Saves the raw dispersal data to another memory object to save reading from disk multiple times later on. This is slightly more RAM intensive which may cause issues for certain simulations.

void addDensity()

Adds the density values to the dispersal map.

Parameters

• generation: the current generation counter

void addReproduction()

Adds the reproduction rates to the dispersal map.

void fixDispersal()

Fixes the dispersal map by generating cumulative probability distributions across each row.

void fixDispersalRow(unsigned long row)

Sums probabilities across the given row and divides by the total probability, so that the cumulative probabilities sum to one.

Parameters

• row: the row index to check over

bool checkDispersalRow(unsigned long row)

Checks if the provided row index requires re-scaling to a cumulative probability in the dispersal map.

Return

true if re-scaling of the row is required

Parameters

• row: the row index to check

void verifyDispersalMapDensity()

Ensures that the dispersal map makes sense given the density.

void verifyDispersalMapSetup()

Checks that the dispersal map makes sense with dispersal to and from only cells which have a non-zero density.

void updateDispersalMap()

Updates the dispersal map, if there is one, to reflect changes in landscape density.

void disperseNullDispersalMap(Step &this_step)

Picks a random cell from the whole map and stores the value in the step object.

Parameters

• this_step: the step object to store end points in

void disperseDispersalMap(Step &this_step)

Picks a random dispersal distance from the dispersal map.

Parameters

• this_step: the step object to store end points in

void calculateCellCoordinates(Step &this_step, const unsigned long &col_ref)

Calculates the new coordinates for a column reference. This includes converting between the fine map and sample map. New coordinates are saved in this_step.

Parameters

• this_step: the step to save new coordinates in.
• col_ref: the column reference for

unsigned long calculateCellReference(Step &this_step) const

Calculates the cell reference for a particular coordinate.

The formula for this calculation is x + (y * xdim) where xdim is the x dimension of the fine map, and x and y are the coordinates for the fine map

Return

the cell reference from the dispersal_prob_map which corresponds to the required cell

Parameters

• this_step: the step object containing the x, y location, and x,y wrapping

unsigned long calculateCellIndex(const Cell &cell) const

Calculates the cell index in the dispersal map from the given cell.

Return

the cell index

Parameters

• cell: the cell to calculate the index for

void disperseDensityMap(Step &this_step)

Calls the dispersal kernel from the supplied dispersal distribution.

Parameters

• this_step: the step object to store end points in

void disperseNearestHabitat(Step &this_step)

Disperses to the nearest habitat cell from a given location.

Parameters

• this_step: teh step object to store end points in

void setEndPointFptr(const bool &restrict_self)

Sets the end point function pointer correctly, based on whether it is restricted or not.

Parameters

• restrict_self: if true, denies possibility that dispersal comes from the same cell as the parent

bool checkEndPoint(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)

Check the end point for the given coordinates and density.

Return

true if the end point passes the density and restricted checks

Parameters

• density: the density at the end point - avoids an extra call to Map::getVal()
• oldx: the old x position
• oldy: the old y position
• oldxwrap: the old x wrap
• oldywrap: the old y wrap
• startx: the starting x position
• starty: the starting y position
• startxwrap: the starting x wrap
• startywrap: the ending y wrap

bool checkEndPointDensity(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)

Check the end point for the given coordinates and density.

Return

true if the end point passes the density and restricted checks

Parameters

• density: the density at the end point - avoids an extra call to Map::getVal()
• oldx: the old x position
• oldy: the old y position
• oldxwrap: the old x wrap
• oldywrap: the old y wrap
• startx: the starting x position
• starty: the starting y position
• startxwrap: the starting x wrap
• startywrap: the ending y wrap

bool checkEndPointRestricted(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)

Check the end point for the given coordinates and density.

Return

true if the end point passes the density and restricted checks

Parameters

• density: the density at the end point - avoids an extra call to Map::getVal()
• oldx: the old x position
• oldy: the old y position
• oldxwrap: the old x wrap
• oldywrap: the old y wrap
• startx: the starting x position
• starty: the starting y position
• startxwrap: the starting x wrap
• startywrap: the ending y wrap

bool checkEndPointDensityReproduction(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)

Check the end point for the given coordinates and density.

Return

true if the end point passes the density and restricted checks

Parameters

• density: the density at the end point - avoids an extra call to Map::getVal()
• oldx: the old x position
• oldy: the old y position
• oldxwrap: the old x wrap
• oldywrap: the old y wrap
• startx: the starting x position
• starty: the starting y position
• startxwrap: the starting x wrap
• startywrap: the ending y wrap

bool checkEndPointDensityRestrictedReproduction(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)

Check the end point for the given coordinates and density.

Return

true if the end point passes the density and restricted checks

Parameters

• density: the density at the end point - avoids an extra call to Map::getVal()
• oldx: the old x position
• oldy: the old y position
• oldxwrap: the old x wrap
• oldywrap: the old y wrap
• startx: the starting x position
• starty: the starting y position
• startxwrap: the starting x wrap
• startywrap: the ending y wrap

void disperse(Step &this_step)

Performs the dispersal routine using the Step object to read starting positions and record the end positions.

Parameters

• this_step: the Step object for reading starting position and storing output distances and angles

double getSelfDispersalValue(const Cell &cell) const

Gets the probability of dispersing from the given cell to itself.

Return

the probability of self-dispersal

Parameters

• cell: the cell to check the probability of self-dispersal from

double sumDispersalValues(const Cell &cell) const

Sums the dispersal values from a given cell to all other cells in the landscape.

Return

the sum of all dispersal values

Parameters

• cell:

void reimportRawDispersalMap()

If required, reimports the raw dispersal map from disk.

void removeSelfDispersal()

Removes all self-dispersal events and recalculates the cumulative dispersal map.

Protected Types

typedef void (DispersalCoordinator::*dispersal_fptr)(Step &this_step)

typedef bool (DispersalCoordinator::*end_fptr)(const unsigned long &density, long &oldx, long &oldy, long &oldxwrap, long &oldywrap, const long &startx, const long &starty, const long &startxwrap, const long &startywrap)

Protected Attributes

Map<double> dispersal_prob_map

Map<double> raw_dispersal_prob_map

shared_ptr<RNGController> NR

shared_ptr<Landscape> landscape

shared_ptr<ActivityMap> reproduction_map

double *generation

dispersal_fptr doDispersal

end_fptr checkEndPointFptr

unsigned long xdim

unsigned long ydim

bool full_dispersal_map

Class GillespieHeapNode

• Defined in File GillespieCalculator.h

Class Documentation

class GillespieHeapNode

Public Functions

GillespieHeapNode(const Cell cell, const double time_of_event, const EventType &e, vector<GillespieHeapNode> *heap, unsigned long *locator)

GillespieHeapNode(const double time_of_event, const EventType &e)

GillespieHeapNode()

GillespieHeapNode(const GillespieHeapNode &other)

GillespieHeapNode &operator=(const GillespieHeapNode &other)

GillespieHeapNode(GillespieHeapNode &&other)

GillespieHeapNode &operator=(GillespieHeapNode &&other)

bool operator<(const GillespieHeapNode &n) const

Public Members

Cell cell

double time_of_event

EventType event_type

vector<GillespieHeapNode> *heap

unsigned long *locator

Class GillespieProbability

• Defined in File GillespieCalculator.h

Class Documentation

class GillespieProbability

Public Functions

GillespieProbability()

GillespieProbability(const MapLocation &c)

void setDispersalOutsideCellProbability(const double &d)

void setCoalescenceProbability(const double &c)

void setSpeciationProbability(const double &s)

void setRandomNumber(const double &r)

double getInCellProbability() const

CellEventType generateRandomEvent(const shared_ptr<RNGController> &rng) const

MapLocation &getMapLocation()

const MapLocation &getMapLocation() const

double getLambda(const double &local_death_rate, const double &summed_death_rate, const unsigned long &n) const

Gets the parameter for the exponential function.

The rate is per birth-death event on the whole landscape.

Return

lambda

Parameters

• summed_death_rate:
• n:
• total_n:

double calcTimeToNextEvent(const double &local_death_rate, const double &mean_death_rate, const unsigned long &n) const

void reset()

Protected Attributes

double dispersal_outside_cell_probability

double coalescence_probability

double speciation_probability

double random_number

MapLocation location

Friends

ostream &operator<<(ostream &os, const GillespieProbability &gp)

std::istream &operator>>(std::istream &is, GillespieProbability &gp)

Class Landscape

• Defined in File Landscape.h

Class Documentation

class Landscape

Contains all maps and provides the functions for accessing a grid cell in the correct temporal and spacial location.

The function runDispersal() also provides the move routine, provided two alternative methods for moving individuals. Contains routines for easy setting up and switching between the different coordinate systems required. Set the map parameters with setDims(), import the map files with calcFineMap(), calcCoarseMap() etc, then set up the landscape type using setLandscape() and sethistorical(). Usage is then by runDispersal() for running a dispersal kernel on the landscape, and then getVal() to obtain the density at the desired coordinates. All coordinates should be given in reference to the simulation grid, and offsets for the fine and coarse map are calculated automatically.

Public Functions

Landscape()

The default constructor.

unsigned long getHabitatMax()

Gets the maximum habitat value from any map.

Return

the maximum habitat value

bool hasHistorical()

Returns if the simulation is using historical maps.

Return

true if using historical maps

Map<uint32_t> &getFineMap()

Gets the fine map object.

Return

reference to the fine map

Map<uint32_t> &getCoarseMap()

Gets the coarse map object.

Return

reference to the coarse map

const Map<uint32_t> &getFineMap() const

Gets the fine map object.

Return

reference to the fine map

const Map<uint32_t> &getCoarseMap() const

Gets the coarse map object.

Return

reference to the coarse map

void setDims(shared_ptr<SimParameters> mapvarsin)

Sets the dimensions of the grid, the area where the species are initially sampled from. This function must be run before any of the calc map functions to allow for the correct deme allocation.

Parameters

• mapvarsin: the SimParameters object containing the map variables to import

bool checkMapExists()

Checks that the map files exist (or are none/null).

Return

true if all the paths exist in configs

void calcFineMap()

Imports the fine map object from file and calculates the correct values at each point. Without a map to input, the fine map will simply be a matrix of 1s.

void calcHistoricalFineMap()

Imports the historical fine map object from file and calculates the correct values at each point. Without a map to input, the historical fine map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.

void calcCoarseMap()

Imports the coarse map object from file and calculates the correct values at each point. Without a map to input, the coarse map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.

void calcHistoricalCoarseMap()

Imports the historical coarse map object from file and calculates the correct values at each point. Without a map to input, the historical coarse map will simply be a matrix of 1s. This has the potential to be changed easily in future versions.

void setTimeVars(double gen_since_historical_in, double habitat_change_rate_in)

Sets the time variables.

Parameters

• gen_since_historical_in: the time (in generations) since a historical habitat state was achieved.
• habitat_change_rate_in: the rate of transform of the habitat up until the historical time. A value of 0.2 would mean 20% of the change occurs linearlly up until the historical time and the remaining 80% occurs in a jump to the historical state.

void calcOffset()

Calculates the offset and extremeties of the fine map.

Note that setting dispersal_relative_cost to a value other than 1 can massively increase simulation time.

bool checkAllDimensionsZero()

Checks that all dimensions for all maps are zero.

If this is true, then it means we can calculate actual offsets and dimensions from the maps, otherwise the values from the parameters will be used.

Return

true if all map offsets are zero

void calculateOffsetsFromMaps()

Calculates the offsets from the map files directly.

Assumes that all required maps have been imported.

void calculateOffsetsFromParameters()

Uses the inputted parameters to set the offsets for the map files.

void validateMaps()

Checks that the map file sizes are correct and that each value on the fragmented maps is less than the historical maps. This should be disabled in simulations where habitat sizes are expected to shrink as well as grow.

bool updateMap(double generation)

Checks if an update needs to be performed to the map configuration, and if it does, performs the update.

Return

true if the map has been updated

Parameters

• generation: the current generation timer

bool requiresUpdate()

Checks if the map will require another update.

Return

true if another update will be performed

void doUpdate()

Updates the historical map configuration.

void resetHistorical()

Resets the historical variables to recalculate historical maps.

Required for rcoalescence compatability.

bool isHistorical()

Gets the historical boolean.

Return

the historical map state.

void setHistorical(const bool &historical_in)

Sets the historical state of the system.

Parameters

• historical_in: the historical state.

double getHistorical()

Get the historical map time.

Return

double the historical map time

string getLandscapeType()

void checkHistorical(double generation)

Checks if the historical state has been reached.

If there are no historical maps, this function will do nothing.

Parameters

• generation: the time to check at.

void setLandscape(const string &is_infinite)

Sets the landscape functions to either infinite or finite.

Parameters

• is_infinite: a string of either closed, infinite, tiled_fine or tiled_coarse, corresponding to the relevant landscape type.

unsigned long getVal(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version involves a call to the function pointer, *getValFunc, so that the correct call to either getValFinite() or getValInfinite is made.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValCoarse(const double &xval, const double &yval, const double &current_generation)

Gets the value from the coarse maps, including linear interpolating between the historical and present maps.

Return

the value of the map at the given coordinates and time

Parameters

• xval: the x coordinate
• yval: the y coordinate
• current_generation: the current generation timer

unsigned long getValFine(const double &xval, const double &yval, const double &current_generation)

Gets the value from the fine maps, including linear interpolating between the historical and present maps.

Return

the value of the map at the given coordinates and time

Parameters

• xval: the x coordinate
• yval: the y coordinate
• current_generation: the current generation timer

unsigned long getValFinite(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes finite landscape.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValInfinite(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValCoarseTiled(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of tiled coarse maps.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValFineTiled(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of tiled fine maps.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValCoarseClamped(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of clamped coarse maps.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long getValFineClamped(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &current_generation)

Gets the value at a particular coordinate from the correct map. Takes in to account temporal and spatial referencing. This version assumes an infinite landscape of clamped fine maps.

Return

the value on the correct map at the correct space.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension..
• ywrap: the number of wraps in the y dimension..
• current_generation: the current generation time.

unsigned long convertSampleXToFineX(const unsigned long &x, const long &xwrap) const

Gets the x position on the fine map, given an x and x wrapping.

Note that this function will not check if the value is actually within bounds of the fine map, and an error will likely be thrown by the matrix referencing if this is the case.

Return

the x location on the fine map

Parameters

• x: the x coordinate on the sample mask
• xwrap: the x wrapping of the sample mask.

unsigned long convertSampleYToFineY(const unsigned long &y, const long &ywrap) const

Gets the y position on the fine map, given a y and y wrapping.

Note that this function will not check if the value is actually within bounds of the fine map, and an error will likely be thrown by the matrix referencing if this is the case.

Return

the y location on the fine map

Parameters

• y: the y coordinate on the sample mask
• ywrap: the y wrapping of the sample mask.

void convertFineToSample(long &x, long &xwrap, long &y, long &ywrap)

Converts the fine map coordinates to the sample grid coordinates. Main conversion is in a call to convertCoordinates, but also makes sure the returned types are long integers.

Parameters

• x: the x coordinate to modify
• xwrap: the x wrapping to modify
• y: the y coordinate to modify
• ywrap: the y wrapping to modify

unsigned long getInitialCount(double dSample, DataMask &samplemask)

Counts the number of spaces available in the initial species space. Requires the samplemask to check the sampling area.

Return

the total number of individuals predicted to initially exist on the map.

Parameters

• dSample: the sample proportion (from 0 to 1).
• samplemask: the DataMask object to sample from.

shared_ptr<SimParameters> getSimParameters()

Gets the mapvars object pointer for referencing simulation parameters.

Return

bool checkMap(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &generation)

Checks whether the point is habitat or non-habitat.

Return

a boolean of whether the map is habitat or non-habitat.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xwrap: the number of wraps in the x dimension.
• ywrap: the number of wraps in the y dimension.
• generation: the current generation time.

bool isOnFine(const double &x, const double &y, const long &xwrap, const long &ywrap)

Checks whether the point comes from the fine grid.

Return

a boolean of whether the location is on the fine map

Parameters

• x: the x position
• y: the y position
• xwrap: the number of wraps in the x dimension
• ywrap: the number of wraps in the y dimension

bool isOnCoarse(const double &x, const double &y, const long &xwrap, const long &ywrap)

Checks whether the point comes from the coarse grid.

Return

a boolean of whether the location is on the fine map

Parameters

• x: the x position
• y: the y position
• xwrap: the number of wraps in the x dimension
• ywrap: the number of wraps in the y dimension

bool isOnMap(const double &x, const double &y, const long &xwrap, const long &ywrap)

Checks that the point supplied is within map limits. If the map is inifite, returns true.

Return

a boolean of whether the location is on the fine map

Return

true if the point is within the map limits

Parameters

• x: the x position
• y: the y position
• xwrap: the number of wraps in the x dimension
• ywrap: the number of wraps in the y dimension

void fixGridCoordinates(double &x, double &y, long &xwrap, long &ywrap)

Fixes the coordinates to be correctly within the original grid, altering the xwrap and ywrap consequently.

Parameters

• x: the x position.
• y: the y position.
• xwrap: the number of wraps in the x dimension.
• ywrap: the number of wraps in the y dimension.

unsigned long runDispersal(const double &dist, const double &angle, long &startx, long &starty, long &startxwrap, long &startywrap, bool &disp_comp, const double &generation)

The function that actually performs the dispersal. It is included here for easier programming and efficiency as the function doesn’t need to perform all the checks until the edge of the fine grid.

Return

the density value at the end dispersal point

Parameters

• dist: the distance travelled (or “distance energy” if dispersal_relative_cost is not 1).
• angle: the angle of movement.
• startx: the start x position.
• starty: the start y position.
• startxwrap: the start number of wraps in the x dimension.
• startywrap: the start number of wraps in the y dimension.
• disp_comp: a boolean of whether the dispersal was complete or not. This value is returned false if dispersal is to habitat, false otherwise.
• generation: the time in generations since the start of the simulation.

double distanceToNearestHabitat(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, const double &generation)

Calculates the distance from the start position to the nearest habitat cell.

Return

the distance from the start position to the nearest habitat cell

Parameters

• start_x: the start x coordinate
• start_y: the start y coordinate
• start_x_wrap: the starting x wrapping
• start_y_wrap: the starting y wrapping
• generation: the generation timer

void findNearestHabitatCell(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, double &end_x, double &end_y, const double &generation)

Gets the nearest habitat cells from a particular point, spiraling outwards.

Parameters

• start_x: the start x coordinate
• start_y: the start y coordinate
• start_x_wrap: the starting x wrapping
• start_y_wrap: the starting y wrapping
• end_x: the end x coordinate value to modify
• end_y: the end y coordinate value to modify
• generation: the generation timer

bool findAnyHabitatCell(const long &start_x, const long &start_y, const long &start_x_wrap, const long &start_y_wrap, double &end_x, double &end_y, const double &generation)

Finds the nearest habitat cell using a much slower method (scanning the entire map for cells.

Return

true if a habitat cell is found

Parameters

• start_x: the start x coordinate
• start_y: the start y coordinate
• start_x_wrap: the starting x wrapping
• start_y_wrap: the starting y wrapping
• end_x: the end x coordinate value to modify
• end_y: the end y coordinate value to modify
• generation: the generation timer

string printVars()

Prints some selected Map variables to the terminal.

Return

the string containing the map variables to print

void clearMap()

Wipes the map of all variables. Only really useful for testing purposes.

void recalculateHabitatMax()

Recalculates the habitat map maximum by checking the maximums for each of the relevant map files (fine, coarse and historicals).

Protected Types

typedef unsigned long (Landscape::*fptr)(const double &x, const double &y, const long &xwrap, const long &ywrap, const double &dCurrentGen)

Protected Attributes

Map<uint32_t> fine_map

Map<uint32_t> historical_fine_map

Map<uint32_t> coarse_map

Map<uint32_t> historical_coarse_map

shared_ptr<SimParameters> mapvars

long fine_x_min = {}

long fine_y_min = {}

long coarse_x_min = {}

long coarse_y_min = {}

long fine_x_max = {}

long fine_y_max = {}

long coarse_x_max = {}

long coarse_y_max = {}

long fine_x_offset = {}

long fine_y_offset = {}

long coarse_x_offset = {}

long coarse_y_offset = {}

unsigned long scale = {}

long x_dim = {}

long y_dim = {}

double deme = {}

bool check_set_dim

double dispersal_relative_cost = {}

double update_time = {}

double habitat_change_rate = {}

double gen_since_historical = {}

double current_map_time

bool is_historical

bool has_historical

unsigned long habitat_max

unsigned long fine_max

unsigned long coarse_max

unsigned long historical_fine_max

unsigned long historical_coarse_max

string landscape_type

bool infinite_boundaries

string NextMap

bool has_coarse

fptr getValFunc

Friends

ostream &operator<<(ostream &os, const Landscape &r)

Operator for outputting the Map object variables to an output stream. This is used for storing the Map object to file.

Return

the output stream.

Parameters

• os: the output stream.
• r: the Map object to output.

istream &operator>>(istream &is, Landscape &r)

Operator for inputting the Map object variables from an input stream. This is used for reading the Map object from file.

Return

the input stream.

Parameters

• is: the input stream.
• r: the Map object to input to.

Class LogFile

• Defined in File LogFile.h

Class Documentation

class LogFile

Contains routines for writing to log files.

Public Functions

LogFile()

Default constructor.

LogFile(string file_name_in)

Constructor taking location of a log file.

Parameters

• file_name_in: the path to the log file to open

~LogFile()

Default destructor, including writing closure out to log file.

void init(string file_name_in)

Initialises the LogFile by creating a file at the specified location.

Parameters

• file_name_in: the file to create

void write(const int &level, string message)

Writes the message out to the logfile at the specified logging level.

Parameters

• level: the level of logging severity
• message: the message to write out

void write(const int &level, stringstream &message)

Writes the message out to the logfile at the specified logging level.

Parameters

• level: the level of logging severity
• message: the message to write out

Protected Functions

LogFile(const LogFile&)

LogFile &operator=(const LogFile&)

Protected Attributes

ofstream output_stream

string file_name

map<int, string> levels_map

Class Logger

• Defined in File Logger.h

Inheritance Relationships

Derived Type

• public necsim::PyLogger (Class PyLogger)

Class Documentation

class Logger

Controls writing to console and files for informing of statuses and debugging.

Subclassed by necsim::PyLogger

Public Functions

Logger()

virtual ~Logger()

void writeInfo(string message)

Logs an information message.

Parameters

• message: the message to write out

void writeWarning(string message)

Logs a warning message.

Parameters

• message: the message to write out

void writeError(string message)

Logs an error message.

Parameters

• message: the message to write out

void writeCritical(string message)

Logs a critical message.

Parameters

• message: the message to write out

Template Class Map

• Defined in File Map.h

Inheritance Relationships

Base Type

• public necsim::Matrix< T > (Template Class Matrix)

Class Documentation

template<class T>
class Map : public virtual necsim::Matrix<T>

Read a a tif file to a matrix and obtain spatial metadata.

Template Parameters

• T: The type of the Matrix to create.

Public Functions

Map()

~Map()

void setCPLErrorHandler()

void removeCPLErrorHandler()

void open(const string &filename_in)

Opens the provided filename to the poDataset object.

Parameters

• filename: file to open in read-only mode.

void open()

Overloaded open for using the preset file name.

bool isOpen()

Checks if the connection to the map file has already been opened.

All this does is check if poDataset is a null pointer.

Return

true if poDataset is a null pointer.

void close()

Destroys the connection to the dataset.

void getRasterBand()

Sets the raster band to the first raster.

void getBlockSizes()

Obtains the x and y dimensions from the tif file for reading in blocks.

void getMetaData()

Sets the no data, data type and data type name values from the tif file.

double getUpperLeftX() const

Gets the upper left x (longitude) coordinate.

Return

upper left x of the map

double getUpperLeftY() const

Gets the upper left y (latitude) coordinate.

Return

upper left y of the map

string getFileName() const

Gets the name of the file that has been imported from.

Return

the file name

void import(const string &filename)

Imports the matrix from a csv file.

Exceptions

• runtime_error: if type detection for the filename fails.

Parameters

• filename: the file to import.

bool importTif(const string &filename)

Imports the matrix from a tif file using the gdal library functions.

Note

Opens a connection to the file object, which should be closed.

Parameters

• filename: the path to the file to import.

bool openOffsetMap(Map &offset_map)

Opens the offset map and fetches the metadata.

Return

true if the offset map is opened within this function

Parameters

• offset_map: the offset map to open (should be the larger map).

void closeOffsetMap(Map &offset_map, const bool &opened_here)

void calculateOffset(Map &offset_map, long &offset_x, long &offset_y)

Calculates the offset between the two maps.

The offset_map should be larger and contain this map, otherwise returned values will be negative

Note

Opens a connection to the tif file (if it has not already been opened), which is then closed. If the connection is already open, then it will not be closed and it is assumed logic elsewhere achieves this.

Note

Offsets are returned as rounded integers at the resolution of the smaller map.

Parameters

• offset_map: the offset map to read from
• offset_x: the x offset variable to fill
• offset_y: the y offset variable to fill

unsigned long roundedScale(Map &offset_map)

Calculates the relative scale of this map compared to the offset map.

The offset map should be larger and contain this map.

Note

Only the x resolution is checked, it is assumed the x and y resolutions of both maps is the same (i.e. each cell on the map is a square.

Return

the relative scale of the offset map

Parameters

• offset_map: the offset map object to read from

void internalImport()

Default importer when we rely on the default gdal method of converting between values. Note that importing doubles to ints results in the values being rounded down.

Return

true if a tif file exists and can be imported, false otherwise.

void defaultImport()

Default import routine for any type. Provided as a separate function so implementation can be called from any template class type.

void importFromDoubleAndMakeBool()

Imports from the supplied filename into the GeoTiff object, converting doubles to booleans. The threshold for conversion is x>0.5 -> true, false otherwise.

template<typename T2>
void importUsingBuffer(GDALDataType dt_buff)

Imports from the supplied filename into the GeoTiff object, converting doubles to booleans. The threshold for conversion is x>0.5 -> true, false otherwise.

Parameters

• dt_buff: the buffer type for the data

Template Parameters

• T2: the template type for data reading.

void printNumberComplete(const uint32_t &j, unsigned int &number_printed)

Print the percentage complete during import.

Parameters

• j: the reference for the counter
• number_printed: the number of previously printed lines

void checkTifImportFailure()

Checks the error code of the CPLErr object and formats the error.

Map &operator=(const Map &m)

Assignment operator.

Return

the self Map object

Parameters

• m: the Map object to copy from

template<>
void internalImport()

Overloaded imported for handling conversion of types to boolean. This function should only be once elsewhere, so inlining is fine, allowing this file to remain header only.

template<>
void internalImport()

Overloaded functions for importing from tifs and matching between gdal and C types.

template<>
void internalImport()

template<>
void internalImport()

template<>
void internalImport()

template<>
void internalImport()

template<>
void internalImport()

template<>
void internalImport()

template<>
void internalImport()

void setSize(unsigned long rows, unsigned long cols)

Sets the matrix size. Similar concept to that for Rows.

Parameters

• rows: the number of rows.
• cols: the number of columns.

unsigned long getCols() const

Getter for the number of columns.

Return

the number of columns.

unsigned long getRows() const

Getter for the number of rows.

Return

the number of rows.

void fill(T val)

Fills the matrix with the given value.

Parameters

• val: the value to fill

unsigned long index(const unsigned long &row, const unsigned long &col) const

Gets the index of a particular row and column in the matrix.

Return

the index of row and column within the matrix

Parameters

• row: the row number to index
• col: the column number to index

T &get(const unsigned long &row, const unsigned long &col)

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

const T &get(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

T getCopy(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

vector<T>::iterator begin()

Returns iterators for range-based for loops.

Return

iterator to the start of the vector

vector<T>::const_iterator begin() const

Returns iterators for range-based for loops.

Return

iterator to the start of the vector

vector<T>::iterator end()

Returns end iterators for range-based for loops.

Return

iterator to the end of the vector

vector<T>::const_iterator end() const

Returns end iterators for range-based for loops.

Return

iterator to the end of the vector

double getMean() const

Gets the arithmetic mean of the Matrix.

Return

the mean value in the matrix

T sum() const

Matrix operator+(const Matrix &m) const

Overloading the + operator.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the matrix object which is the sum of the two matrices.

Parameters

• m: the matrix to add to this matrix.

Matrix operator-(const Matrix &m) const

Overloading the - operator.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the matrix object which is the subtraction of the two matrices.

Parameters

• m: the matrix to subtract from this matrix.

Matrix &operator+=(const Matrix &m)

Overloading the += operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator-=(const Matrix &m)

Overloading the -= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to subtract from this matrix.

Matrix operator*(const double s) const

Overloading the * operator for scaling.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the scaled matrix.

Parameters

• s: the constant to scale the matrix by.

Matrix operator*(Matrix &m) const

Overloading the * operator for matrix multiplication.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension. Multiplies each value in the matrix with its corresponding value in the other matrix.

Return

the product of each ith,jth value of the matrix.

Parameters

• m: the matrix to multiply with

Matrix &operator*=(const double s)

Overloading the *= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator*=(const Matrix &m)

Overloading the *= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix operator/(const double s) const

Overloading the / operator for scaling.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the scaled matrix.

Parameters

• s: the constant to scale the matrix by.

Matrix &operator/=(const double s)

Overloading the /= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator/=(const Matrix &m)

Overloading the /= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

void setValue(const unsigned long &row, const unsigned long &col, const char *value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters

• row: the row index.
• col: the column index.
• value: the value to set

void setValue(const unsigned long &row, const unsigned long &col, const T &value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters

• row: the row index.
• col: the column index.
• value: the value to set

bool importCsv(const string &filename)

Imports the matrix from a csv file using the fast-csv-parser method.

Return

true if the csv can be imported.

Parameters

• filename: the path to the file to import.Imports the matrix from a csv file using the standard, slower method.

Parameters

• filename: the path to the file to import.

Protected Attributes

shared_ptr<GDALDataset *> po_dataset

shared_ptr<GDALRasterBand *> po_band

unsigned long block_x_size

unsigned long block_y_size

double no_data_value

string file_name

GDALDataType gdal_data_type

CPLErr cpl_error

double upper_left_x

double upper_left_y

double x_res

double y_res

bool cpl_error_set

unsigned long num_cols = {}

unsigned long num_rows = {}

vector<T> matrix

Friends

ostream &operator>>(ostream &os, const Map &m)

Output operator.

Return

the modified output stream

Parameters

• os: the output stream
• m: the object to write out

istream &operator<<(istream &is, Map &m)

Input operator.

Return

the modified input stream

Parameters

• is: the input stream
• m: the object to write in

Template Class Matrix

• Defined in File Matrix.h

Inheritance Relationships

Derived Type

• public necsim::Map< T > (Template Class Map)

Class Documentation

template<class T>
class Matrix

A class containing the Matrix object, set up as an array of Row objects. Includes basic operations, as well as the importCsv() function for more advanced reading from file.

Template Parameters

• T: the type of the values in the matrix

Subclassed by necsim::Map< T >

Public Functions

Matrix(unsigned long rows = 0, unsigned long cols = 0)

The standard constructor.

Parameters

• rows: optionally provide the number of rows.
• cols: optionally provide the number of columns.

Matrix(const Matrix &m)

The copy constructor.

Parameters

• m: a Matrix object to copy from.

virtual ~Matrix()

The destructor.

void setSize(unsigned long rows, unsigned long cols)

Sets the matrix size. Similar concept to that for Rows.

Parameters

• rows: the number of rows.
• cols: the number of columns.

unsigned long getCols() const

Getter for the number of columns.

Return

the number of columns.

unsigned long getRows() const

Getter for the number of rows.

Return

the number of rows.

void fill(T val)

Fills the matrix with the given value.

Parameters

• val: the value to fill

unsigned long index(const unsigned long &row, const unsigned long &col) const

Gets the index of a particular row and column in the matrix.

Return

the index of row and column within the matrix

Parameters

• row: the row number to index
• col: the column number to index

T &get(const unsigned long &row, const unsigned long &col)

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

const T &get(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

T getCopy(const unsigned long &row, const unsigned long &col) const

Gets the value at a particular index.

Return

the value at the specified row and column

Parameters

• row: the row number to get the value at
• col: the column number to get the value at

vector<T>::iterator begin()

Returns iterators for range-based for loops.

Return

iterator to the start of the vector

vector<T>::iterator end()

Returns end iterators for range-based for loops.

Return

iterator to the end of the vector

vector<T>::const_iterator begin() const

Returns iterators for range-based for loops.

Return

iterator to the start of the vector

vector<T>::const_iterator end() const

Returns end iterators for range-based for loops.

Return

iterator to the end of the vector

double getMean() const

Gets the arithmetic mean of the Matrix.

Return

the mean value in the matrix

T sum() const

Matrix &operator=(const Matrix &m)

Overloading the = operator.

Parameters

• m: the matrix to copy from.

Matrix operator+(const Matrix &m) const

Overloading the + operator.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the matrix object which is the sum of the two matrices.

Parameters

• m: the matrix to add to this matrix.

Matrix operator-(const Matrix &m) const

Overloading the - operator.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the matrix object which is the subtraction of the two matrices.

Parameters

• m: the matrix to subtract from this matrix.

Matrix &operator+=(const Matrix &m)

Overloading the += operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator-=(const Matrix &m)

Overloading the -= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to subtract from this matrix.

Matrix operator*(const double s) const

Overloading the * operator for scaling.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the scaled matrix.

Parameters

• s: the constant to scale the matrix by.

Matrix operator*(Matrix &m) const

Overloading the * operator for matrix multiplication.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension. Multiplies each value in the matrix with its corresponding value in the other matrix.

Return

the product of each ith,jth value of the matrix.

Parameters

• m: the matrix to multiply with

Matrix &operator*=(const double s)

Overloading the *= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator*=(const Matrix &m)

Overloading the *= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix operator/(const double s) const

Overloading the / operator for scaling.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Return

the scaled matrix.

Parameters

• s: the constant to scale the matrix by.

Matrix &operator/=(const double s)

Overloading the /= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

Matrix &operator/=(const Matrix &m)

Overloading the /= operator so that the new object is written to the current object.

Note

If matrices are of different sizes, the operation is performed on the 0 to minimum values of each dimension.

Parameters

• m: the Matrix object to add to this matrix.

void setValue(const unsigned long &row, const unsigned long &col, const char *value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters

• row: the row index.
• col: the column index.
• value: the value to set

void setValue(const unsigned long &row, const unsigned long &col, const T &value)

Sets the value at the specified indices, including handling type conversion from char to the template class.

Parameters

• row: the row index.
• col: the column index.
• value: the value to set

virtual void import(const string &filename)

Imports the matrix from a csv file.

Exceptions

• runtime_error: if type detection for the filename fails.

Parameters

• filename: the file to import.

bool importCsv(const string &filename)

Imports the matrix from a csv file using the fast-csv-parser method.

Return

true if the csv can be imported.

Parameters

• filename: the path to the file to import.Imports the matrix from a csv file using the standard, slower method.

Parameters

• filename: the path to the file to import.

Protected Attributes

unsigned long num_cols = {}

unsigned long num_rows = {}

vector<T> matrix

Friends

ostream &writeOut(ostream &os, const Matrix &m)

Writes the object to the output stream.

Note

This is done slightly inefficiently to preserve the output taking the correct form.

Return

the output stream

Parameters

• os: the output stream to write to
• m: the object to write out

istream &readIn(istream &is, Matrix &m)

Reads in from the input stream.

Return

Parameters

• is: the input stream to read from
• m: the object to read into

ostream &operator<<(ostream &os, const Matrix &m)

Overloading the << operator for outputting to an output stream. This can be used for writing to console or storing to file.

Return

the output stream.

Parameters

• os: the output stream.
• m: the matrix to output.

istream &operator>>(istream &is, Matrix &m)

Overloading the >> operator for inputting from an input stream. This can be used for writing to console or storing to file.

Return

the input stream.

Parameters

• is: the input stream.
• m: the matrix to input to.

Class Metacommunity

• Defined in File Metacommunity.h

Inheritance Relationships

Base Type

• public necsim::Community (Class Community)

Class Documentation

class Metacommunity : public virtual necsim::Community

Generates a metacommunity using spatially implicit neutral simulations, which is used to draw individuals from a community.

Public Functions

Metacommunity()

~Metacommunity()

void setCommunityParameters(shared_ptr<MetacommunityParameters> metacommunity_parameters)

Sets the parameters for the metacommunity.

Parameters

• community_size_in: the number of individuals in the metacommunity
• speciation_rate_in: the speciation rate to use for metacommunity creation
• database_name_in: the path to the database to store the metacommunity in
• metacommunity_option_in: the metacommunity option, either “simulated”, “analytical” or a path to a file
• metacommunity_reference_in: the metacommunity reference in the input metacommunity database

void checkSimulationParameters()

Gets the seed and the job_type from the SIMULATION_PARAMETERS database and stores them in the relevant variables.

Note

Should only be called once, and will have no effect if called multiple times.

void addSpecies(unsigned long &species_count, TreeNode *tree_node, set<unsigned long> &species_list)

Speciates TreeNode and updates the species count, including adding to the set of species ids, if a new species has been selected from the metacommunity.

Parameters

• species_count: the total number of species currently in the community
• tree_node: pointer to the TreeNode object for this lineage
• species_list: the set of all species ids.

void createMetacommunityNSENeutralModel()

Creates the metacommunity in memory using a non-spatially_explicit neutral model, which is run using the Tree class.

void applyNoOutput(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> tree_data)

Applies the speciation parameters to the completed simulation, including running the spatially implicit for the metacommunity structure, but doesn’t write the output.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure.

void approximateSAD()

Approximates the SAD from a NSE neutral model, based on Chisholm and Pacala (2010).

void readSAD()

Reads the SAD from the database provided in metacommunity_option. The database must exist and have a table called SPECIES_ABUNDANCES with the relevant community parameter.

void printMetacommunityParameters()

Prints the metacommunity parameters to the logger.

void setList(shared_ptr<vector<TreeNode>> l)

Set the nodes object to the input Row of Treenode objects.

Parameters

• l: the Row of Treenode objects to link to.

ProtractedSpeciationParameters setupInternal(shared_ptr<SimParameters> sim_parameters, shared_ptr<SQLiteHandler> database)

Sets up the community from a set of simulation parameters and the sqlite3 database connection.

Return

Parameters

• sim_parameters: parameters to use for setting up the community
• database: points to the database object to open

void setDatabase(shared_ptr<SQLiteHandler> dbin)

Sets the database object for the sqlite functions.

Parameters

• dbin: the sqlite3 input database.

bool hasImportedData()

Get the boolean of whether the data has been imported yet.

Return

true if database has been imported.

long double getMinimumSpeciation()

Get the minimum speciation rate the simulation was originally run with. This value is read in from the SIMULATION_PARAMETERS table in the database file.

Return

the minimum speciation rate.

void importSamplemask(string sSamplemask)

Imports the samplemask if it hasn’t already been imported.

Parameters

• sSamplemask: the path to the samplemask file.

unsigned long countSpecies()

Counts the number of species that have speciated currently on the tree.

Return

the number of species

unsigned long calculateCoalescenceTree()

Calculate the number of species in the list for the parameters in the current_community_parameters object. This is the main function which reconstructs the coalescence tree. Each Treenode object will end having its existence value set correctly after a call to this function.

Return

the number of species present.

void calcSpeciesAbundance()

Calculates the species abundance of the dataset. The species abundances will be with rOut after a call do this function. If a samplemask has been applied, only lineages which originally existed in the samplemask will be counted.

void resetTree()

Resets the entire tree. Sets existance to false, speciation to false and removes any species ID.

void openSqlConnection(string input_file)

Opens the connection to the sql database file Note that this imports the database to memory, so functionality should be changed for extremely large database files.

Parameters

• input_file: the sql database output from a necsim simulation.

void closeSqlConnection()

Safely destroys the SQL connection.

void setInternalDatabase()

Opens a connection to an in-memory database. This will eventually be written to the output file.

void internalOption()

Internally sets the file referencing, data import and sql connection flags to true, for allowing checks to pass from internal object creation (so no external files are needed)

void importData(string inputfile)

Imports the data from the desired SQL database object into the array.

Note

Opens the sql connection if it has not already been opened.

Note

If nodes is not of length 0, this function does nothing. This is so that any in-memory data is not overwritten.

Parameters

• inputfile: the path to the input SQLite database.

void setSimParameters(shared_ptr<SimParameters> sim_parameters)

Sets the simulation parameters from a SimParameters object.

Parameters

• sim_parameters: pointer to the SimParameters object to set from

void setSpecSimParameters(shared_ptr<SpecSimParameters> spec_sim_parameters)

Sets the speciation parameters from a SpecSimParameters object.

Note

Be careful of the difference between this function and setSimParameters (which sets the main simulation parameters).

Parameters

• spec_sim_parameters: pointer to the SpecSimParameters object containing community speciation parameters

void importSimParameters(string file)

Imports the simulation parameters by reading the SIMULATION_PARAMETERS table in the provided file. This imports the grid_x_size, grid_y_size (which should also be the sample map dimensions) and the minimum speciation rate.

Note

Opens the sql connection if it has not already been opened.

Note

If bDataImport has already been set, no operation is performed.

Parameters

• file: the sqlite database simulation output which will be used for coalescence tree generation.

void forceSimCompleteParameter()

Forces the sim_complete parameter to be true in SIMULATION_PARAMETERS. Used when speciating all remaining lineages to force a simulation to completion.

bool isSetDatabase()

Gets if the database has been set yet.

Return

true if the database is already set

void getMaxSpeciesAbundancesID()

Gets the maximum species abundance ID from the database and stores it in the max_species_id variable.

Note

Does not check for SPECIES_ABUNDANCES existence and will throw an error if it cannot access it

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Changes the rOut object so that values represent cummulative species abundances.

Allows binary sort on rOut (much faster) and the previous rOut value can be obtained by value = rOut[i] - rOut[i-1]

Return

pointer to sorted Row of species abundances

shared_ptr<vector<unsigned long>> getRowOut()

Returns the row_out object, which should contain species abundances or cumulative abundances.

Note

Does not recalculate species abundances, so if getCumulativeAbundances has been called, will return the cumulative species abundances instead.

Note

Returns a copy, so could cause problems for extremely large simulations with immense numbers of species.

Return

row_out, the species abundances, or the cumulative abundances if getCumulativeAbundances has been called

unsigned long getSpeciesNumber()

Gets the number of species in the most recent calculation.

Return

the number of species in the most recent calculation

void getMaxFragmentAbundancesID()

Gets the maximum fragment abundance ID from the database and stores it in the max_fragment_id variable.

Note

Does not check for FRAGMENT_ABUNDANCES existence and will throw an error if it cannot access it

void getMaxSpeciesLocationsID()

Gets the maximum species locations ID from the database and stores it in the max_locations_id variable.

Note

Does not check for SPECIES_LOCATIONS existence and will throw an error if it cannot access it

void setProtractedParameters(const ProtractedSpeciationParameters &protracted_params)

Sets the protracted parameters for application of protracted speciation.

This overloaded version is for setting protracted parameters before a full simulation has been outputted (i.e. immediately after completion of the simulation).

Parameters

• protracted_params: protracted speciation parameters to add

void overrideProtractedParameters(const ProtractedSpeciationParameters &protracted_params)

Overrides the protracted parameters for the Community object.

Parameters

• protracted_params: the protracted parameters to override with

void setProtracted(bool protracted_in)

Sets the protracted boolean to the input.

Parameters

• protracted_in: the protracted boolean to set

void createDatabase()

Creates a new table in the database file and outputs the database object to the same file as the input file. Calculates the community structure for the set of community parameters in current_community_parameters.

The new SPECIES_ABUNDANCES table contains the species abundance distribution for the whole samplemask. A similar tabe FRAGMENT_ABUNDANCES is generated by createFragmentDatabase() if specified via the command line parameters.

void generateBiodiversity()

Calculates the coalescence tree and generates species abundances.

void outputSpeciesAbundances()

Outputs the species abundances into the database.

bool checkCalculationsPerformed(const long double &speciation_rate, const double &time, const bool &fragments, const MetacommunityParameters &metacomm_parameters, const ProtractedSpeciationParameters &proc_parameters)

Checks if calculations with the given set of parameters has already been performed.

Return

Parameters

• speciation_rate: the speciation rate to check for
• time: the time to check for
• fragments: if true, checks fragments have been used
• metacommunity_size: the metacommunity size to check for
• metacommunity_speciation_rate: the metacommunity speciation rate to check for
• proc_parameters: protracted speciation parameters to add

void addCalculationPerformed(const long double &speciation_rate, const double &time, const bool &fragments, const MetacommunityParameters &metacomm_parameters, const ProtractedSpeciationParameters &protracted_parameters)

Adds a performed calculation to the lists of calculations. Also sets the current_community_parameters pointer to the set of parameters to be applied.

Parameters

• speciation_rate: the speciation rate of the performed calculation
• time: the time of the performed calculation
• fragments: if true, fragments were used
• metacommunity_size: the metacommunity size of the performed calculation
• metacommunity_speciation_rate: the metacommunity speciation rate of the performed calculation
• protracted_parameters: protracted speciation parameters to add

void createFragmentDatabase(const Fragment &f)

Creates a new table in the database file and outputs the database object to the same file as the input file. Essentially creates a species abundance distribution (as in createDatabase()), but for the specified fragment within the samplemask.

Parameters

• f: the Fragment to sample from.

void exportDatabase()

Output the database from memory to the database file. Most of the time, it is desirable for the outputfile to be the same path as the input file and will write to the same object.

bool checkSpeciesLocationsReference()

Checks for the current CommunityParameters reference in the SPECIES_LOCATIONS table.

Return

true if the reference exists in the SPECIES_LOCATIONS table

bool checkSpeciesAbundancesReference()

Checks for the current CommunityParameters reference in the SPECIES_ABUNDANCES table.

Return

return true if the reference exists in the SPECIES_LOCATIONS table

void recordSpatial()

Record the full spatial data. Creates a new table, SPECIES_LOCATIONS containing every species and their parameters. This allows for more in-depth analysis to be performed if necessary.

void calcFragments(string fragment_file)

Calculates the limits of each fragment in the sample map and adds it to the vector of fragments. If the fragment_file is null, then the program will attempt to calculate fragments from the map.

Parameters

• fragment_file: the fragment file to read from.

void applyFragments()

Calculate species abundances for each fragment, and call createFragmentDatabase() for each Fragment.

void getPreviousCalcs()

Gets the previous calculations that have already been performed.

vector<unsigned long> getUniqueCommunityRefs()

Gets the unique community references from the SQL database.

Return

a vector containing the unique references

vector<unsigned long> getUniqueMetacommunityRefs()

Gets the unique metacommunity reference from the SQL database.

Return

a vector containing the unique references

void writeNewCommunityParameters()

Write all performed calculations to the output database.

void writeNewMetacommunityParameters()

Write all performed calculations to the output database.

void createSpeciesList()

Creates a new table, SPECIES_LIST in the output database.

void deleteSpeciesList()

Drops the SPECIES_LIST table from the database.

void writeSpeciesList(const unsigned long &enddata)

Writes the coalescence tree to a table called SPECIES_LIST.

void updateCommunityParameters()

Updates the fragments tag on those simulations which now have had fragments added.

void writeSpeciationRates()

Prints speciation rates to terminal.

void calculateTree()

Calculates the coalescence tree for each set of parameters in speciation_parameters;.

void output()

Outputs the data to the SQL database.

void printEndTimes(time_t tStart, time_t tEnd)

Prints the application times.

Parameters

• tStart: the start time
• tEnd: the end time

void apply(shared_ptr<SpecSimParameters> sp)

Apply the given speciation parameters to the coalescence tree. Overridden for metacommunity application.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void applyNoOutput(shared_ptr<SpecSimParameters> sp)

Applies the given speciation parameters to the coalescence tree, but does not write the output.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void setupApplication(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Sets up the community application by reading parameters and data.

Parameters

• sp: the speciation parameters to use for generating the community
• data: the list of all nodes on the coalescence tree

void doApplication(shared_ptr<SpecSimParameters> sp)

Creates the coalescence tree for the given speciation parameters.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure

void doApplication(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Creates the coalescence tree for the given speciation parameters.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
• data: the Row of TreeNodes that contains the coalescence tree.

void doApplicationInternal(shared_ptr<SpecSimParameters> sp, shared_ptr<vector<TreeNode>> data)

Creates the coalescence tree for the given speciation parameters, using internal file referencing to avoid any actual file creation.

Parameters

• sp: speciation parameters to apply, including speciation rate, times and spatial sampling procedure
• data: the Row of TreeNodes that contains the coalescence tree.

void speciateRemainingLineages(const string &filename)

Speciates the remaining lineages in an incomplete simulation to force it to appear complete.

unsigned long getSpeciesRichness(const unsigned long &community_reference)

Gets the species richness for the community reference from the database.

Return

the number of species

Parameters

• community_reference: the community reference to obtain the species richness for

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances of the community.

Return

a map of species ids to species abundances

Parameters

• community_reference: the reference of the desired community

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundance from the species_abundances internal object.

Return

the species abundances

bool isDatabaseNullPtr()

Check if the database is a null pointer.

Return

true if the database is a null pointer.

Protected Attributes

unsigned long seed

unsigned long job_type

bool parameters_checked

unique_ptr<SpeciesAbundancesHandler> species_abundances_handler

shared_ptr<RNGController> random

unique_ptr<Tree> metacommunity_tree

bool in_mem

bool database_set

shared_ptr<SQLiteHandler> database

bool bSqlConnection

shared_ptr<vector<TreeNode>> nodes

shared_ptr<vector<unsigned long>> species_abundances

unsigned long iSpecies

bool has_imported_samplemask

bool has_imported_data

Samplematrix samplemask

vector<Fragment> fragments

shared_ptr<CommunityParameters> current_community_parameters

shared_ptr<MetacommunityParameters> current_metacommunity_parameters

long double min_spec_rate

unsigned long grid_x_size

unsigned long grid_y_size

unsigned long samplemask_x_size

unsigned long samplemask_y_size

unsigned long samplemask_x_offset

unsigned long samplemask_y_offset

CommunitiesArray past_communities

MetacommunitiesArray past_metacommunities

bool protracted

ProtractedSpeciationParameters minimum_protracted_parameters

ProtractedSpeciationParameters applied_protracted_parameters

unsigned long max_species_id

unsigned long max_fragment_id

unsigned long max_locations_id

shared_ptr<SpecSimParameters> spec_sim_parameters

Class ProtractedSpatialTree

• Defined in File ProtractedSpatialTree.h

Inheritance Relationships

Base Types

• public necsim::SpatialTree (Class SpatialTree)
• public necsim::ProtractedTree (Class ProtractedTree)

Class Documentation

class ProtractedSpatialTree : public virtual necsim::SpatialTree, public virtual necsim::ProtractedTree

Public Functions

void runFileChecks()

Runs the basic file existence checks. Checks for paused simulations and file existence.

void checkFolders()

Checks that the folders exist and the files required for the simulation also exist.

void setParameters()

Sets the map object with the correct variables, taking the SimParameters structure defined elsewhere for the parameters.

Requires that parameters have already been imported into the SimParameters

This function can only be run once, otherwise a Main_Exception will be thrown

void importMaps()

Imports the maps into the landscape.

The simulation variables should have already been imported by setParameters(), otherwise a Fatal_Exception will be thrown.

void importActivityMaps()

Imports the activity maps from the relevant files.

unsigned long getInitialCount()

Counts the number of individuals that exist on the spatial grid.

Return

the number of individuals that will be initially simulated

void setupDispersalCoordinator()

Sets up the dispersal coordinator by linking to the correct functions and choosing the appropriate dispersal method.

void setup()

Contains the setup routines for a spatial landscape. It also checks for paused simulations and imports data if necessary from paused files. importMaps() is called for importing the map files.

unsigned long fillObjects(const unsigned long &initial_count)

Fill the active, data and grid objects with the starting lineages.

Return

the number of lineages added (for validation purposes)

Parameters

• initial_count: the number of individuals expected to exist

unsigned long getIndividualsSampled(const long &x, const long &y, const long &x_wrap, const long &y_wrap, const double &current_gen)

Gets the number of individuals to be sampled at the particular point and time. Round the number down to the nearest whole number for numbers of individuals.

Return

the number of individuals to sample at this location.

Parameters

• x: the x location for individuals to be sampled
• y: the y location for individuals to be sampled
• x_wrap: the number of x wraps for the cell
• y_wrap: the number of y wraps for the cell
• current_gen: the current generation timer

unsigned long getNumberLineagesAtLocation(const MapLocation &location) const

unsigned long getNumberIndividualsAtLocation(const MapLocation &location) const

void removeOldPosition(const unsigned long &chosen)

Removes the old position within active by checking any wrapping and removing connections.

The function also corrects the linked list to identify the correct nwrap for every wrapped lineage in that space.

Parameters

• chosen: the desired active reference to remove from the grid.

void calcMove()

Calculate the move, given a start x,y coordinates and wrapping.

The provided parameters will be altered to contain the new values so no record of the old variables remains after function running. Current dispersal methods use a fattailed dispersal.

long double calcMinMax(const unsigned long &current)

Calculates the minmax for a given branch.

Calculates the speciation rate required for speciation to have occured on this branch.

Parameters

• current: the current active reference to perform calculations over.

void calcNewPos()

Calculates the new position, checking whether coalescence has occured and with which lineage.

This involves correct handling of checking wrapped lineages (outside the original grid). The probability of coalescence is also calculated.

void calcWrappedCoalescence(const unsigned long &nwrap)

Calculates the coalescence event when the target cell is wrapped.

Parameters

• nwrap: the number of wrapped lineages

void switchPositions(const unsigned long &chosen)

Switches the chosen position with the endactive position.

Parameters

• chosen: the chosen lineage to switch with endactive.

void calcNextStep()

Calculates the next step for the simulation.

unsigned long estSpecnum()

Estimates the species number from the second largest minimum speciation rate remaining in active.

This allows for halting of the simulation once this threshold has been reached. However, the function is not currently in use as calculating the coalescence tree is very computionally intensive.

void incrementGeneration()

Increments the generation counter and step references, then updates the map for any changes to habitat cover.

void updateStepCoalescenceVariables()

Updates the coalescence variables in the step object.

void recordLineagePosition()

Zeroes out the coalescence information and stores the origin location.

void addLineages(double generation_in)

Expands the map, generating the new lineages where necessary.

The samplemask provided is used for expansion. Any empty spaces are filled with a new lineage. Lineages which have not moved are changed to tips, with a new data entry so that original and new generations are recorded.

Parameters

• generation_in: the generation that the expansion is occuring at. This is used in recording the new tips

string simulationParametersSqlInsertion()

Creates a string containing the SQL insertion statement for the simulation parameters.

Return

string containing the SQL insertion statement

void simPause()

Pause the simulation and dump data from memory.

void dumpMap(shared_ptr<ofstream> out)

Saves the map object to file.

Parameters

• out: the output file stream to save the object to

void dumpGrid(shared_ptr<ofstream> out)

Saves the grid object to file.

Parameters

• out: the output file stream to save the object to

void simResume()

Resumes the simulation from a previous state.

Reads in the parameters and objects from file and re-starts the simulation.

void loadGridSave(shared_ptr<ifstream> in1)

Loads the grid from the save file into memory.

Note

Requires that both the simulation parameters and the maps have already been loaded.

void loadMapSave(shared_ptr<ifstream> in1)

Loads the map from the save file into memory.

Note

Requires that the simulation parameters have already been loaded.

void verifyActivityMaps()

Checks that the reproduction map makes sense with the fine density map.

void addWrappedLineage(unsigned long numstart, long x, long y)

Adds the lineage to the correct point in the linked list of active lineages.

Parameters

• numstart: the active position to add
• x: the x position of the lineage
• y: the y position of the lineage

unsigned long countCellExpansion(const long &x, const long &y, const long &xwrap, const long &ywrap, const double &generationin, vector<TreeNode> &data_added)

Counts the number of lineages at a particular location that need to be added, after making the correct proportion of those that already exist into tips.

Return

the number of lineages still to add

Parameters

• x: the x coordinate of the location of interest
• y: the y coordinate of the location of interest
• xwrap: the x wrapping of the location
• ywrap: the y wrapping of the location
• generationin: the generation to assign to new tips
• data_added: vector containing TreeNode objects to add to data

void expandCell(long x, long y, long x_wrap, long y_wrap, double generation_in, unsigned long add, vector<TreeNode> &data_added, vector<DataPoint> &active_added)

Expands the cell at the desired location by adding the supplied number of lineages.

This takes into account wrapping to correctly add the right number

Parameters

• x: the x coordinate to add at
• y: the y coordinate to add at
• x_wrap: the x wrapping to add at
• y_wrap: the y wrapping to add at
• generation_in: the generation to set the new lineages to
• add: the total number of lineages to add at this location

void addGillespie(const double &g_threshold)

bool runSimulationGillespie()

void runGillespieLoop()

void setupGillespie()

Sets up the Gillespie algorithm.

void setupGillespieLineages()

Resets lineage speciation rates to 0.

void setupGillespieMaps()

Cell getCellOfMapLocation(const MapLocation &location)

Calculates the x, y position on the fine map of the lineage.

Return

cell object containing the x, y location

Parameters

• location: the map location

void findLocations()

Finds the locations that lineages are at and adds them to the list of locations.

This also involves calculating the event probabilities for each cell.

void checkMapEvents()

void checkSampleEvents()

void gillespieCellEvent(GillespieProbability &origin)

void gillespieUpdateMap()

void gillespieSampleIndividuals()

void gillespieCoalescenceEvent(GillespieProbability &origin)

void gillespieDispersalEvent(GillespieProbability &origin)

void gillespieSpeciationEvent(GillespieProbability &origin)

void gillespieLocationRemainingCheck(GillespieProbability &location)

template<typename T>
double getLocalDeathRate(const T &location) const

template<typename T>
double getLocalSelfDispersalRate(const T &location) const

void clearGillespieObjects()

void setStepVariable(const necsim::GillespieProbability &origin, const unsigned long &chosen, const unsigned long &coal_chosen)

void gillespieUpdateGeneration(const unsigned long &lineage)

void updateCellCoalescenceProbability(GillespieProbability &origin, const unsigned long &n)

void updateInhabitedCellOnHeap(const Cell &pos)

void updateAllProbabilities()

void removeHeapTop()

template<typename T>
Cell convertMapLocationToCell(const T &location) const

void createEventList()

Calculates the times for each event and sorts the event list.

void sortEvents()

template<bool restoreHeap = true>
void addNewEvent(const unsigned long &x, const unsigned long &y)

void addLocation(const MapLocation &location)

Adds the given location.

Calculates the probabilities of coalescence, dispersal and speciation.

Parameters

• location: the location to add and calculate values for

void setupGillespieProbability(GillespieProbability &gp, const MapLocation &location)

void fullSetupGillespieProbability(GillespieProbability &gp, const MapLocation &location)

double calculateCoalescenceProbability(const MapLocation &location) const

template<typename T>
double convertGlobalGenerationsToLocalGenerations(const T &location, const double g) const

unsigned long selectRandomLineage(const MapLocation &location) const

pair<unsigned long, unsigned long> selectTwoRandomLineages(const MapLocation &location) const

vector<unsigned long> detectLineages(const MapLocation &location) const

void assignNonSpeciationProbability(const unsigned long chosen)

Sets the speciation probability of the provided lineage so that speciation has a random chance of occurring, but didn’t occur during this branch of the coalescence tree.

Parameters

• chosen: the index in the active lineages to set the speciation probability for

void importSimulationVariables(const string &configfile)

Import the simulation variables from the command line structure.

This function parses the simulation variables, imports them from the config file, checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSimulation() can be run immediately afterwards.

Parameters

• configfile: the path to the config file containing parameters to parse.

void importSimulationVariables(ConfigParser config)

Import the simulation variables from a ConfigOption.

This function parses the simulation variables, imports them (from either the command line or a config file), checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSim() can be run immediately afterwards.

Parameters

• config: the set of config parameters to import

void wipeSimulationVariables()

Resets all the simulation variables.

void internalSetup(shared_ptr<SimParameters> sim_parameters_in)

Sets up the simulation parameters from the one provided.

Intended for usage with metacommunity application. No output directory is expected.

Parameters

• sim_parameters_in: the simulation parameters to set up the simulation with

bool checkOutputDirectory()

Asserts that the output directory is not null and exists. If it doesn’t exist, it attempts to create it.

Return

true if output creates successfully

Exceptions

• Fatal_Exception: if the output directory creation fails

void checkSims()

Checks for existing paused simulations to resume from Sets bPaused if there are.

This version uses the default values read from the config file.

void checkSims(string output_dir, long seed, long job_type)

Checks for existing paused simulations to resume from.

Sets bPaused if there are.

This version uses the values supplied to the function directly

Parameters

• output_dir: the output directory to check for
• seed: the seed for paused sims
• job_type: the job_type for paused sims

void setProtractedVariables(double speciation_gen_min, double speciation_gen_max)

Sets the protracted variables.

Parameters

• speciation_gen_min: the minimum number of generations to have passed before speciation is allowed
• speciation_gen_max: the maximum number of generations a lineage can exist for before it is speciated.

bool hasPaused()

Gets the has_paused variable for resuming sims.

Return

if the simulation has paused

vector<double> getTemporalSampling()

Gets the map autocorrel times.

long long getSeed()

Getter for the simulation seed.

Return

Returns the seed

long long getJobType()

Gets the job type for the simulation. This is a reference number for the jobs.

Return

Returns the job type

void setSeed(long long seed_in)

Sets the simulation seed for the random number generator.

This function should only be called once.

The seed is set within the NR object. This will be fixed for the simulation and is only performed once.

Parameters

• seed_in: the desired seed to set for the simulation

double getGeneration() const

Gets the generation timer for the simulation.

Return

the number of generations that have passed

unsigned long setObjectSizes()

Sets the sizes of grid, active and data, based on the number of individuals counted from the samplemask.

Return

a count of the number of individuals that exist in the simulation

void setInitialValues()

Sets the starting values for required parameters.

void setSimStartVariables()

Sets the variables at the start of a simulation for temporary data.

This is not the main set-up routine, which creates the permanent data structures including maps, the coalescence tree and active lineage listings.

void printSetup()

Prints the statement for the setup initiation.

This is stored in a separate function so that it can be called in isolation by child classes.

void setTimes()

Sets the temporal sampling points from the time config file.

void determineSpeciationRates()

Determines the speciation rates to apply and then applies them to the coalescence tree post-simulation.

Detects speciation rates from the config files supplied.

void addSpeciationRates(vector<long double> spec_rates_in)

Adds the speciation rates to those to be applied.

void generateObjects()

Assigns the objects sizes in memory and fills with the starting lineages.

void runSingleLoop()

Runs a single loop of the simulation.

bool runSimulation()

Run the entire simulation given the start conditions already defined by setup().

Setup is assumed to have been run already. This function is the main function containing the main loop of the simulation. At the end of the simulation, returns true if the simulation is complete, false otherwise.

Return

true if the simulation has completed

bool runSimulationNoGillespie()

Runs the simulation using the standard coalescence algorithm.

Return

true if the simulation has completed

void writeSimStartToConsole()

Writes to the console that the simulation is beginning.

void writeStepToConsole()

Write the step counter to console. This function should only be called in debugging mode.

void chooseRandomLineage()

Chooses a random lineage from active.

The index of the random lineage is stored in this_step, as chosen. Also records the required variables for the step process, like x, y position.

void speciation(const unsigned long &chosen)

Speciation to supplied lineage.

Also calls the removeOldPos() and switchPositions() functions for removing the lineage out of active reference.

Parameters

• chosen:

void speciateLineage(const unsigned long &data_position)

Performs the actual speciation.

Parameters

• data_position: the position in the array of TreeNodes for this lineage

bool calcSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.

Return

if true, speciation has occured

Parameters

• random_number: the generated random number from 0-1
• speciation_rate: the speciation rate to be applied
• no_generations: the number of generations a lineage has existed for

void coalescenceEvent(const unsigned long &chosen, unsigned long &coalchosen)

Perform the coalescence between lineages. Once coalesced, lineages are removed from the active scope.

Parameters

• chosen: the chosen lineage for coalescence
• coalchosen: the target lineage for coalscence

void checkTimeUpdate()

Checks if the number of lineages should be expanded at another sample point.

bool checkProportionAdded(const double &proportion_added)

Randomly checks if a lineage should be added, based on the proportion added.

Return

true if the lineage should be added, false otherwise

Parameters

• proportion_added: the proportion of lineages that should be added

void checkSimSize(unsigned long req_data, unsigned long req_active)

Checks the size of the main active and data objects is large enough.

Parameters

• req_data: the required data object size
• req_active: the required active object size

void makeTip(const unsigned long &tmp_active, const double &generation_in, vector<TreeNode> &data_added)

Sets the active reference to a tip, if it isn’t one already. Otherwise, creates a new tip for the new generation time.

Parameters

• tmp_active: the reference in active
• generation_in: the generation to set for the new lineage
• data_added: vector of lineages to add to data

void convertTip(unsigned long i, double generationin, vector<TreeNode> &data_added)

Creates a new reference in data containing the tip with a new generation counter.

Parameters

• i: the reference in active of the lineage to make a tip
• generationin: the generation to make the lineage a tip at
• data_added: vector of lineages to add to the data object

bool stopSimulation()

Finalises the simulation, and performs the correct tasks depending if the sim has been paused or finished.

Return

void applySpecRate(long double sr, double t)

Applies the given speciation rate to the tree.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applySpecRate(long double sr)

Overloaded version of applySpecRates for the default generation (0.0).

Parameters

• sr: the speciation rate to apply to the tree

void applySpecRateInternal(long double sr, double t)

Applies the given speciation rate to the tree, but does not output to a file. Instead returns a pointer to the nodes object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Gets the sorted cumulative species abundances from the contained TreeList.

For use with metacommunity applications

Return

row of cumulative species abundances

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances from the internal tree.

Return

the species abundances

Parameters

• community_reference: the community reference

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundances from the internal tree.

Return

the species abundances

ProtractedSpeciationParameters setupCommunity()

Sets up Community member to point to the same output database as the simulation.

Return

the protracted speciation parameters to set up

void setupCommunityCalculation(long double sr, double t)

Sets up the generation of the tree object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applyMultipleRates()

Applies multiple speciation rates to the coalescence tree, ignoring repeated speciation rates.

Speciation rates are read from the speciation_rates object, which should have already been calculated.

bool getProtracted()

Gets the protractedness of the simulation. Overridden by protracted child classes.

Return

string getProtractedVariables()

Gets the protracted variables and returns them as a single, newline separated string. This method is intended to be overridden in derived classes.

Return

string containing the protracted variables, separated by newlines.

double getProtractedGenerationMin()

Gets the minimum number of generations a lineage must exist.

Without overriding this function, should always return 0.0.

Return

double the number of generations a lineage must exist

double getProtractedGenerationMax()

Gets the maximum number of generations a lineage can exist.

Without overriding this function, should always return 0.0 (no maximum).

Return

double the number of generations a lineage must exist

void sqlOutput()

Copy the in-memory database to file.

This function should not be called if the database is already opened on disc, and won’t do anything if it is.

void createAndOutputData()

Creates the output data objects and outputs important simulation data to a database file.

void outputData()

Outputs the simulation data (including the coalescence tree) to an sql database.

void sortData()

Sort and process the species list so that the useful information can be extracted from it.

void writeTimes()

Writes the times to the terminal for simulation information.

void openSQLDatabase()

Opens a connection to the in-memory database, or the on-disk database, depending on the compilation options.

void sqlCreate()

Generates the SQL database file from the full simulation data. This allows for greater analysis of the data after completion of the simulation.

void setupOutputDirectory()

Creates the output directory, if it doesn’t already exist, and deletes any existing database with the output name.

void sqlCreateSimulationParameters()

Creates the SIMULATION_PARAMETERS table in the SQL database.

string protractedVarsToString()

Outputs the protracted variables to a string.

This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.

Return

string containing a list of the protracted speciation variables.

shared_ptr<ofstream> initiatePause()

Checks the output folder exists and initiates the pause.

Return

the output file stream to save objects to

void dumpMain(shared_ptr<ofstream> out)

Saves the main simulation variables to file.

Parameters

• out: the output file stream to save the object to

void dumpActive(shared_ptr<ofstream> out)

Saves the active object to file.

Parameters

• out: the output file stream to save the object to

void dumpData(shared_ptr<ofstream> out)

Saves the data object to file.

Parameters

• out: the output file stream to save the object to

void completePause(shared_ptr<ofstream> out)

Completes the pause routine and outputs the sql dump.

Parameters

• out: the output stream to close up

void setResumeParameters(string pausedir, string outdir, unsigned long seed, unsigned long job_type, unsigned long new_max_time)

Sets the resume variables so that the simulation can be resumed.

The pause directory can be the same as the output directory if it is desirable to save to the same location.

Parameters

• pausedir: the directory containing the pause folder for resuming the simulation
• outdir: the directory to write simulation output to
• seed: the simulation seed
• job_type: the simulation job reference number
• new_max_time: the maximum simulation time to run for in seconds (0 keeps old simulation max time)

void setResumeParameters()

Sets the resume variables to the defaults.

shared_ptr<ifstream> openSaveFile()

void loadMainSave(shared_ptr<ifstream> in1)

Loads the main simulation parameters from the save file into memory.

void loadDataSave(shared_ptr<ifstream> in1)

Loads the data object from the save file into memory.

void loadActiveSave(shared_ptr<ifstream> in1)

Loads the active object from the save file into memory.

void initiateResume()

Checks for resuming and prints to the terminal.

bool calcSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.

Return

if true, speciation has occured

Parameters

• random_number: the generated random number from 0-1
• speciation_rate: the speciation rate to be applied
• no_generations: the number of generations a lineage has existed for

void speciateLineage(const unsigned long &data_position)

Performs the actual speciation. Includes handling of speciated lineages under protracted conditions.

Parameters

• data_position: the position in the array of TreeNodes for this lineage

bool getProtracted()

Gets the protractedness of the simulation. Overridden by protracted child classes.

Return

void setProtractedVariables(double speciation_gen_min, double speciation_gen_max)

Sets the protracted variables.

Parameters

• speciation_gen_min: the minimum number of generations to have passed before speciation is allowed
• speciation_gen_max: the maximum number of generations a lineage can exist for before it is speciated.

string getProtractedVariables()

Gets the protracted variables and returns them as a single, newline separated string.

Return

string containing the protracted variables, separated by newlines.

double getProtractedGenerationMin()

Gets the minimum number of generations a lineage must exist.

Return

double the number of generations a lineage must exist

double getProtractedGenerationMax()

Gets the maximum number of generations a lineage can exist.

Return

double the number of generations a lineage must exist

string protractedVarsToString()

Outputs the protracted variables to a string.

This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.

Return

string containing a list of the protracted speciation variables.

void applySpecRate(double sr, double t)

Applies the given speciation rate to the tree.

Note

Currently this just copies code from the version in tree, which is not ideal, but this avoids creating an extra function.

Parameters

• sr: the required speciation rate

Protected Attributes

DispersalCoordinator dispersal_coordinator

shared_ptr<ActivityMap> death_map

shared_ptr<ActivityMap> reproduction_map

string fine_map_input

string coarse_map_input

string historical_fine_map_input

string historical_coarse_map_input

shared_ptr<Landscape> landscape

Matrix<SpeciesList> grid

unsigned long desired_specnum

DataMask samplegrid

double gillespie_threshold

Matrix<GillespieProbability> probabilities

vector<GillespieHeapNode> heap

Matrix<unsigned long> cellToHeapPositions

Matrix<double> self_dispersal_probabilities

unsigned long global_individuals

double summed_death_rate

shared_ptr<vector<TreeNode>> data

unsigned long enddata

shared_ptr<SimParameters> sim_parameters

shared_ptr<RNGController> NR

vector<long double> speciation_rates

bool seeded

long long seed

long long job_type

string times_file

vector<double> reference_times

bool uses_temporal_sampling

time_t start

time_t sim_start

time_t sim_end

time_t now

time_t sim_finish

time_t out_finish

time_t time_taken

vector<DataPoint> active

unsigned long endactive

unsigned long startendactive

unsigned long maxsimsize

Community community

long steps

unsigned long maxtime

double generation

double deme

double deme_sample

long double spec

string out_directory

shared_ptr<SQLiteHandler> database

bool sim_complete

bool has_imported_vars

Step this_step

string sql_output_database

bool bFullMode

bool bResume

bool bConfig

bool has_paused

bool has_imported_pause

bool bIsProtracted

string pause_sim_directory

bool using_gillespie

Protected Static Attributes

const unsigned long UNUSED = static_cast<unsigned long>(-1)

Class ProtractedTree

• Defined in File ProtractedTree.h

Inheritance Relationships

Base Type

• public necsim::Tree (Class Tree)

Derived Type

• public necsim::ProtractedSpatialTree (Class ProtractedSpatialTree)

Class Documentation

class ProtractedTree : public virtual necsim::Tree

Contains the protracted tree class, for running simulations with procated speciation.

Subclassed by necsim::ProtractedSpatialTree

Public Functions

ProtractedTree()

bool calcSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.

Return

if true, speciation has occured

Parameters

• random_number: the generated random number from 0-1
• speciation_rate: the speciation rate to be applied
• no_generations: the number of generations a lineage has existed for

void speciateLineage(const unsigned long &data_position)

Performs the actual speciation. Includes handling of speciated lineages under protracted conditions.

Parameters

• data_position: the position in the array of TreeNodes for this lineage

bool getProtracted()

Gets the protractedness of the simulation. Overridden by protracted child classes.

Return

void setProtractedVariables(double speciation_gen_min, double speciation_gen_max)

Sets the protracted variables.

Parameters

• speciation_gen_min: the minimum number of generations to have passed before speciation is allowed
• speciation_gen_max: the maximum number of generations a lineage can exist for before it is speciated.

string getProtractedVariables()

Gets the protracted variables and returns them as a single, newline separated string.

Return

string containing the protracted variables, separated by newlines.

double getProtractedGenerationMin()

Gets the minimum number of generations a lineage must exist.

Return

double the number of generations a lineage must exist

double getProtractedGenerationMax()

Gets the maximum number of generations a lineage can exist.

Return

double the number of generations a lineage must exist

string protractedVarsToString()

Outputs the protracted variables to a string.

This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.

Return

string containing a list of the protracted speciation variables.

void applySpecRate(double sr, double t)

Applies the given speciation rate to the tree.

Note

Currently this just copies code from the version in tree, which is not ideal, but this avoids creating an extra function.

Parameters

• sr: the required speciation rate

void importSimulationVariables(const string &configfile)

Import the simulation variables from the command line structure.

This function parses the simulation variables, imports them from the config file, checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSimulation() can be run immediately afterwards.

Parameters

• configfile: the path to the config file containing parameters to parse.

void importSimulationVariables(ConfigParser config)

Import the simulation variables from a ConfigOption.

This function parses the simulation variables, imports them (from either the command line or a config file), checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSim() can be run immediately afterwards.

Parameters

• config: the set of config parameters to import

void runFileChecks()

Runs the basic file existence checks. Checks for paused simulations and file existence.

void wipeSimulationVariables()

Resets all the simulation variables.

void internalSetup(shared_ptr<SimParameters> sim_parameters_in)

Sets up the simulation parameters from the one provided.

Intended for usage with metacommunity application. No output directory is expected.

Parameters

• sim_parameters_in: the simulation parameters to set up the simulation with

bool checkOutputDirectory()

Asserts that the output directory is not null and exists. If it doesn’t exist, it attempts to create it.

Return

true if output creates successfully

Exceptions

• Fatal_Exception: if the output directory creation fails

void checkSims()

Checks for existing paused simulations to resume from Sets bPaused if there are.

This version uses the default values read from the config file.

void checkSims(string output_dir, long seed, long job_type)

Checks for existing paused simulations to resume from.

Sets bPaused if there are.

This version uses the values supplied to the function directly

Parameters

• output_dir: the output directory to check for
• seed: the seed for paused sims
• job_type: the job_type for paused sims

void setParameters()

Move the parameters from the sim_parameters object to their relevant parameters.

bool hasPaused()

Gets the has_paused variable for resuming sims.

Return

if the simulation has paused

vector<double> getTemporalSampling()

Gets the map autocorrel times.

long long getSeed()

Getter for the simulation seed.

Return

Returns the seed

long long getJobType()

Gets the job type for the simulation. This is a reference number for the jobs.

Return

Returns the job type

void setSeed(long long seed_in)

Sets the simulation seed for the random number generator.

This function should only be called once.

The seed is set within the NR object. This will be fixed for the simulation and is only performed once.

Parameters

• seed_in: the desired seed to set for the simulation

double getGeneration() const

Gets the generation timer for the simulation.

Return

the number of generations that have passed

unsigned long getInitialCount()

Gets the initial number of individuals.

Return

the number of initial individuals to simulate

unsigned long setObjectSizes()

Sets the sizes of grid, active and data, based on the number of individuals counted from the samplemask.

Return

a count of the number of individuals that exist in the simulation

void setup()

The setup function for generating the simulation objects.

The simulation parameters are set from comargs using setParameters(). Generates and fills the active and grid objects as well as importing all the maps from the supplied files.

void setInitialValues()

Sets the starting values for required parameters.

void setSimStartVariables()

Sets the variables at the start of a simulation for temporary data.

This is not the main set-up routine, which creates the permanent data structures including maps, the coalescence tree and active lineage listings.

void printSetup()

Prints the statement for the setup initiation.

This is stored in a separate function so that it can be called in isolation by child classes.

void setTimes()

Sets the temporal sampling points from the time config file.

void determineSpeciationRates()

Determines the speciation rates to apply and then applies them to the coalescence tree post-simulation.

Detects speciation rates from the config files supplied.

void addSpeciationRates(vector<long double> spec_rates_in)

Adds the speciation rates to those to be applied.

void generateObjects()

Assigns the objects sizes in memory and fills with the starting lineages.

unsigned long fillObjects(const unsigned long &initial_count)

Fills the active and data objects with the starting lineages.

Parameters

• initial_count: the number of individuals expected to exist

void runSingleLoop()

Runs a single loop of the simulation.

bool runSimulation()

Run the entire simulation given the start conditions already defined by setup().

Setup is assumed to have been run already. This function is the main function containing the main loop of the simulation. At the end of the simulation, returns true if the simulation is complete, false otherwise.

Return

true if the simulation has completed

bool runSimulationNoGillespie()

Runs the simulation using the standard coalescence algorithm.

Return

true if the simulation has completed

void writeSimStartToConsole()

Writes to the console that the simulation is beginning.

void writeStepToConsole()

Write the step counter to console. This function should only be called in debugging mode.

void incrementGeneration()

Increments the generation counter and step references.

void chooseRandomLineage()

Chooses a random lineage from active.

The index of the random lineage is stored in this_step, as chosen. Also records the required variables for the step process, like x, y position.

void updateStepCoalescenceVariables()

Updates the coalescence variables in the step object.

void speciation(const unsigned long &chosen)

Speciation to supplied lineage.

Also calls the removeOldPos() and switchPositions() functions for removing the lineage out of active reference.

Parameters

• chosen:

void removeOldPosition(const unsigned long &chosen)

Removes the old position within active.

Parameters

• chosen: the desired active reference to remove from the grid.

void switchPositions(const unsigned long &chosen)

Switches the chosen position with the endactive position.

Parameters

• chosen: the chosen lineage to switch with endactive.

void calcNextStep()

Calculates the next step for the simulation.

void coalescenceEvent(const unsigned long &chosen, unsigned long &coalchosen)

Perform the coalescence between lineages. Once coalesced, lineages are removed from the active scope.

Parameters

• chosen: the chosen lineage for coalescence
• coalchosen: the target lineage for coalscence

void checkTimeUpdate()

Checks if the number of lineages should be expanded at another sample point.

void addLineages(double generation_in)

Adds the required lineages at the generation time.

Parameters

• generation_in: the generation to add lineages at

bool checkProportionAdded(const double &proportion_added)

Randomly checks if a lineage should be added, based on the proportion added.

Return

true if the lineage should be added, false otherwise

Parameters

• proportion_added: the proportion of lineages that should be added

void checkSimSize(unsigned long req_data, unsigned long req_active)

Checks the size of the main active and data objects is large enough.

Parameters

• req_data: the required data object size
• req_active: the required active object size

void makeTip(const unsigned long &tmp_active, const double &generation_in, vector<TreeNode> &data_added)

Sets the active reference to a tip, if it isn’t one already. Otherwise, creates a new tip for the new generation time.

Parameters

• tmp_active: the reference in active
• generation_in: the generation to set for the new lineage
• data_added: vector of lineages to add to data

void convertTip(unsigned long i, double generationin, vector<TreeNode> &data_added)

Creates a new reference in data containing the tip with a new generation counter.

Parameters

• i: the reference in active of the lineage to make a tip
• generationin: the generation to make the lineage a tip at
• data_added: vector of lineages to add to the data object

bool stopSimulation()

Finalises the simulation, and performs the correct tasks depending if the sim has been paused or finished.

Return

void applySpecRate(long double sr, double t)

Applies the given speciation rate to the tree.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applySpecRate(long double sr)

Overloaded version of applySpecRates for the default generation (0.0).

Parameters

• sr: the speciation rate to apply to the tree

void applySpecRateInternal(long double sr, double t)

Applies the given speciation rate to the tree, but does not output to a file. Instead returns a pointer to the nodes object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Gets the sorted cumulative species abundances from the contained TreeList.

For use with metacommunity applications

Return

row of cumulative species abundances

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances from the internal tree.

Return

the species abundances

Parameters

• community_reference: the community reference

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundances from the internal tree.

Return

the species abundances

ProtractedSpeciationParameters setupCommunity()

Sets up Community member to point to the same output database as the simulation.

Return

the protracted speciation parameters to set up

void setupCommunityCalculation(long double sr, double t)

Sets up the generation of the tree object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applyMultipleRates()

Applies multiple speciation rates to the coalescence tree, ignoring repeated speciation rates.

Speciation rates are read from the speciation_rates object, which should have already been calculated.

void sqlOutput()

Copy the in-memory database to file.

This function should not be called if the database is already opened on disc, and won’t do anything if it is.

void createAndOutputData()

Creates the output data objects and outputs important simulation data to a database file.

void outputData()

Outputs the simulation data (including the coalescence tree) to an sql database.

void sortData()

Sort and process the species list so that the useful information can be extracted from it.

void writeTimes()

Writes the times to the terminal for simulation information.

void openSQLDatabase()

Opens a connection to the in-memory database, or the on-disk database, depending on the compilation options.

void sqlCreate()

Generates the SQL database file from the full simulation data. This allows for greater analysis of the data after completion of the simulation.

void setupOutputDirectory()

Creates the output directory, if it doesn’t already exist, and deletes any existing database with the output name.

void sqlCreateSimulationParameters()

Creates the SIMULATION_PARAMETERS table in the SQL database.

string simulationParametersSqlInsertion()

Creates a string containing the SQL insertion statement for the simulation parameters.

Return

string containing the SQL insertion statement

void simPause()

Pause the simulation and dump data from memory.

shared_ptr<ofstream> initiatePause()

Checks the output folder exists and initiates the pause.

Return

the output file stream to save objects to

void dumpMain(shared_ptr<ofstream> out)

Saves the main simulation variables to file.

Parameters

• out: the output file stream to save the object to

void dumpActive(shared_ptr<ofstream> out)

Saves the active object to file.

Parameters

• out: the output file stream to save the object to

void dumpData(shared_ptr<ofstream> out)

Saves the data object to file.

Parameters

• out: the output file stream to save the object to

void completePause(shared_ptr<ofstream> out)

Completes the pause routine and outputs the sql dump.

Parameters

• out: the output stream to close up

void setResumeParameters(string pausedir, string outdir, unsigned long seed, unsigned long job_type, unsigned long new_max_time)

Sets the resume variables so that the simulation can be resumed.

The pause directory can be the same as the output directory if it is desirable to save to the same location.

Parameters

• pausedir: the directory containing the pause folder for resuming the simulation
• outdir: the directory to write simulation output to
• seed: the simulation seed
• job_type: the simulation job reference number
• new_max_time: the maximum simulation time to run for in seconds (0 keeps old simulation max time)

void setResumeParameters()

Sets the resume variables to the defaults.

shared_ptr<ifstream> openSaveFile()

void loadMainSave(shared_ptr<ifstream> in1)

Loads the main simulation parameters from the save file into memory.

void loadDataSave(shared_ptr<ifstream> in1)

Loads the data object from the save file into memory.

void loadActiveSave(shared_ptr<ifstream> in1)

Loads the active object from the save file into memory.

void initiateResume()

Checks for resuming and prints to the terminal.

void simResume()

Resumes the simulation from a previous state.

Reads in the parameters and objects from file and re-starts the simulation.

void addGillespie(const double &g_threshold)

bool runSimulationGillespie()

Protected Attributes

shared_ptr<vector<TreeNode>> data

unsigned long enddata

shared_ptr<SimParameters> sim_parameters

shared_ptr<RNGController> NR

vector<long double> speciation_rates

bool seeded

long long seed

long long job_type

string times_file

vector<double> reference_times

bool uses_temporal_sampling

time_t start

time_t sim_start

time_t sim_end

time_t now

time_t sim_finish

time_t out_finish

time_t time_taken

vector<DataPoint> active

unsigned long endactive

unsigned long startendactive

unsigned long maxsimsize

Community community

long steps

unsigned long maxtime

double generation

double deme

double deme_sample

long double spec

string out_directory

shared_ptr<SQLiteHandler> database

bool sim_complete

bool has_imported_vars

Step this_step

string sql_output_database

bool bFullMode

bool bResume

bool bConfig

bool has_paused

bool has_imported_pause

bool bIsProtracted

string pause_sim_directory

bool using_gillespie

Class PyLogger

• Defined in File PyLogger.h

Inheritance Relationships

Base Type

• public necsim::Logger (Class Logger)

Class Documentation

class PyLogger : public necsim::Logger

Public Functions

PyLogger()

Default constructor for PyLogger.

~PyLogger()

Safely deletes the Python references.

void setLogger(PyObject *logger)

Sets the logger object.

Parameters

• logger: the log object that is written out to

void setLogFunction(PyObject *log_function)

Sets the logger function.

Parameters

• log_function: the function that will be used for writing out logs

bool isSetup()

Checks if the logger has been setup.

Return

true if the logger object and the logger function have been set

void writeInfo(string message)

Writes a message to the log object with level 20.

Parameters

• message: the message to write out

void writeWarning(string message)

Writes a message to the log object with level 30.

Parameters

• message: the message to write out

void writeError(string message)

Writes a message to the log object with level 40.

Parameters

• message: the message to write out

void writeCritical(string message)

Writes a message to the log object with level 50.

Parameters

• message: the message to write out

void write(const int &level, string message)

Writes a message to the log object with the supplied leve.

Parameters

• level: the logging level to write out at
• message: the message to write out

void write(const int &level, stringstream &message)

Writes a message to the log object with the supplied leve.

Parameters

• level: the logging level to write out at
• message: the message to write out

void writeInfo(string message)

Logs an information message.

Parameters

• message: the message to write out

void writeWarning(string message)

Logs a warning message.

Parameters

• message: the message to write out

void writeError(string message)

Logs an error message.

Parameters

• message: the message to write out

void writeCritical(string message)

Logs a critical message.

Parameters

• message: the message to write out

Class Samplematrix

• Defined in File Community.h

Inheritance Relationships

Base Type

• public necsim::DataMask (Class DataMask)

Class Documentation

class Samplematrix : public necsim::DataMask

A child of the Matrix class as booleans. Used for determining where to sample species from.

Public Functions

Samplematrix()

Inherit construction from the Matrix class, but also set the booleans.

bool getTestVal(unsigned long xval, unsigned long yval, long xwrap, long ywrap)

Returns the value at the x,y position. This is used for testing purposes only.

Return

the value at x,y.

Parameters

• xval: the x coordinate.
• yval: the y coordinate
• xwrap: the x wrapping
• ywrap: the y wrapping

bool getMaskVal(unsigned long x1, unsigned long y1, long x_wrap, long y_wrap)

Returns the value at the x,y position, with the given x and y wrap. Also checks whether or not the map is set to null, or whether the value comes from within a fragment.

Return

the value at x,y.

Parameters

• x1: the x coordinate.
• y1: the y coordinate
• xwrap: the x wrapping
• ywrap: the y wrapping

void setFragment(Fragment &fragment_in)

Set the fragment for the samplemask to some calculated fragment. This can be set multiple times.

Parameters

• fragment_in: the Fragment to set the samplemask to.

void removeFragment()

Removes the fragment.

bool isNull()

Returns if the simulation is using the a null samplemask, and therefore does not need to store the full sample grid in memory.

Return

true if using a null samplemask

void setup(shared_ptr<SimParameters> sim_parameters)

Sets the parameters for the datamask, including the dimensions of the map, the offsets from the grid and the dimensions of the grid itself for recalculating coordinates.

Parameters

• sim_parameters: Simulation parameter to set the data mask from

bool checkCanUseDefault(shared_ptr<SimParameters> sim_parameters)

void importBooleanMask(unsigned long xdim, unsigned long ydim, unsigned long mask_xdim, unsigned long mask_ydim, unsigned long xoffset, unsigned long yoffset, string inputfile_in)

Imports the sample mask as a boolean mask and sets the relevant sample mask dimensions. Should only be called if the import is actually required (i.e. the map is not null or none).

Parameters

• xdim: the x dimension of the grid area
• ydim: the y dimension of the grid area
• mask_xdim: the x dimension of the sample map file
• mask_ydim: the y dimension of the sample map file
• xoffset: the x offset of the grid area from the sample map file
• yoffset: the y offset of the grid area from the sample map file
• inputfile_in: the path to the sample map file

void doImport()

Imports the boolean map object.

void completeBoolImport()

Sets the map dimensions and the getVal function pointer.

void setupNull(shared_ptr<SimParameters> mapvarin)

Sets up the null sampling map.

void importSampleMask(shared_ptr<SimParameters> mapvarin)

Imports the specified file for the sampling percentage within each cell.

The map should consist of floating points representing the relative sampling rates in each cell. Note that the actual sampling proportion is equal to the cell value multiplied by global deme sampling proportion.

Parameters

• mapvarin: the SimParameters object containing the samplemask file location and dimensions

bool getVal(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Calculates the matrix value at the provided x, y location. If everywhere is sampled, simply returns true, as no sample_mask will be stored in memory. This is to save RAM where possible.

Return

the sample_mask value at x,y (or true if the file was “null”)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps
• ywrap: the number of y wraps

double getNullProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Separate return function for always returning 1.0 as density value.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getBoolProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, for calculating the proportion of individuals to be sampled in each cell.

Note

this function assumes that the file is not “null” and the exact sampling mask has been imported. No error checks on these conditions are performed except in debugging mode.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getSampleProportion(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, for calculating the proportion of individuals to be sampled in each cell.

Note

this function assumes that the file is not “null” and the exact sampling mask has been imported. No error checks on these conditions are performed except in debugging mode.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

double getExactValue(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Returns the exact value from the spatial sampling map, as returned by the pointer function.

Return

the sample_mask_exact value at (x, y)

Parameters

• x: the x position on the grid
• y: the y position on the grid
• xwrap: the number of x wraps around the map
• ywrap: the number of y wraps around the map

void convertBoolean(shared_ptr<Landscape> map1, const double &deme_sampling, const double &generation)

Converts the spatial map into the boolean grid required for continued simulation. This is done so that the faster boolean accesses are possible.

Parameters

• map1: the map object to obtain density values from
• deme_sampling: the proportion of individuals to sample
• generation: the generation individuals are added at

void clearSpatialMask()

Removes the spatial mask from memory. This should be performed if no more map expansions are required.

void recalculateCoordinates(long &x, long &y, long &x_wrap, long &y_wrap)

Converts the coordinates back into the grid format. Changes the values in the provided variables to be correct.

Parameters

• x: the x value to convert
• y: the y value to convert
• x_wrap: the xwrap variable to place the value into
• y_wrap: the ywrap variable to place the value into

Public Members

Map<bool> sample_mask

A binary grid telling whether or not the cell should be sampled.

Map<double> sample_mask_exact

Exact grid for determining sampling proportion.

Protected Types

typedef double (DataMask::*fptr)(const long &x, const long &y, const long &xwrap, const long &ywrap) const

Protected Attributes

string inputfile

bool isNullSample

bool isGridOffset

unsigned long x_offset

unsigned long y_offset

unsigned long x_dim

unsigned long y_dim

unsigned long mask_x_dim

unsigned long mask_y_dim

fptr getProportionfptr

Class SimulateDispersal

• Defined in File SimulateDispersal.h

Class Documentation

class SimulateDispersal

Contains routines for importing a density map file, running a dispersal kernel n times on a landscape and record the dispersal distances.

Public Functions

SimulateDispersal()

necsim::SimulateDispersal::~ SimulateDispersal()

void setSequential(bool bSequential)

Sets the is_sequential flag.

Parameters

• bSequential: if true, dispersal events are selected using the end point of the last dispersal distance for the start of the next move event

void setSimulationParameters(shared_ptr<SimParameters> sim_parameters, bool print = true)

Sets the pointer to the simulation parameters object.

Parameters

• sim_parameters: pointer to the simulation parameters to use
• print: if true, writes the parameters out using writeInfo()

void importMaps()

Import the maps from the simulation parameters.

void setSizes()

Creates the map of steps to parameter references and initialises object sizes.

void setDispersalParameters()

Sets the dispersal parameters in the DispersalCoordinator.

void setSeed(unsigned long s)

Sets the seed for the random number generator.

Parameters

• s: the seed

void setOutputDatabase(string out_database)

Sets the output database for writing results to.

Parameters

• out_database: path to the output database

void setNumberRepeats(unsigned long n)

Sets the number of repeats to run the dispersal kernel for.

Parameters

• n: the number of repeats

void setNumberSteps(const vector<unsigned long> &s)

Sets the number of steps to run each repeat of the dispersal kernel for when recording mean distance travelled.

Parameters

• s: a vector containing each step variable to record the distance at

void setNumberWorkers(unsigned long n)

Sets the number of threads launched to parallelise the distance simulation.

Parameters

• n: the number of workers

unsigned long getMaxNumberSteps()

Gets the maximum number of steps that is to be applied.

Return

void storeCellList()

Calculates the list of cells to choose randomly from.

const Cell &getRandomCell()

Gets a random cell from the list of cells.

Return

a Cell object reference containing the x and y positions to choose from

void getEndPoint(Cell &this_cell)

Checks the density a given distance from the start point, calling the relevant landscape function.

This also takes into account the rejection sampling of density based on the maximal density value from the map.

Parameters

• this_cell: Cell containing the x and y coordinates of the starting position

void getEndPoint(Cell &this_cell, DispersalCoordinator &dispersal_coordinator)

Checks the density a given distance from the start point, calling the relevant landscape function.

This also takes into account the rejection sampling of density based on the maximal density value from the map.

Parameters

• this_cell: Cell containing the x and y coordinates of the starting position
• dispersal_coordinator: Reference to the dispersal coordinator to use

template<bool chooseRandomCells = false>
void runDistanceLoop(const unsigned long bidx, const unsigned long eidx, const unsigned long num_repeats, std::mutex &mutex, unsigned long &finished, DispersalCoordinator &dispersal_coordinator, double &generation)

Runs the distance simulation edix-bidx times and reports the progress.

Template Parameters

• chooseRandomCells: If true random walks will be chosen randomly from the cells vector, otherwise uses cells[bidx:edix]

Parameters

• bidx: First inclusive index into the cells vector of random walk origins to simulate in this worker
• eidx: Last exclusive index into the cells vector of random walk origins to simulate in this worker
• num_repeats: The number of repeats to average over for each cell
• mutex: The mutex to synchronise progress feedback to the user
• finished: The total number of cells simulated across all workers
• dispersal_coordinator: Reference to the dispersal corrdinator to use
• generation: Reference to the generation variable used byt the dispersal coordinator

template<bool chooseRandomCells = false>
void runDistanceWorker(const unsigned long seed, const unsigned long bidx, const unsigned long eidx, const unsigned long num_repeats, std::mutex &mutex, unsigned long &finished)

Runs the distance simulation eidx-bidx times on a separate worker and reports the progress.

Template Parameters

• chooseRandomCells: If true random walks will be chosen randomly from the cells vector, otherwise uses cells[bidx:edix]

Parameters

• seed: Seed to use to initialse the per worker rng and dispersal coordinator
• bidx: First inclusive index into the cells vector of random walk origins to simulate in this worker
• eidx: Last exclusive index into the cells vector of random walk origins to simulate in this worker
• num_repeats: The number of repeats to average over for each cell
• mutex: The mutex to synchronise progress feedback to the user
• finished: The total number of cells simulated across all workers

void runMeanDispersalDistance()

Simulates the dispersal kernel for the set parameters, storing the mean dispersal distance.

void runMeanDistanceTravelled()

Simulates the dispersal kernel for the set parameters, storing the mean distance travelled.

void runAllDistanceTravelled()

Simulates the dispersal kernel for the set parameters on all habitable cells, storing the mean distance travelled.

void runSampleDistanceTravelled(const vector<Cell> &samples)

Simulates the dispersal kernel for the set parameters on the given sample cells, storing the mean distance travelled.

Parameters

• samples: Vector of cells to be sampled during the distance simulation

void writeRepeatInfo(unsigned long i)

Writes the information about this repeat to the logger.

void writeDatabase(string table_name)

Writes out the distances to the SQL database.

Parameters

• table_name: the name of the table to output to, either ‘DISPERSAL_DISTANCE’ or ‘DISTANCES_TRAVELLED’

void writeParameters(string table_name)

Writes the simulation parameters to the output SQL database.

Parameters

• table_name: the name of the table to output to, either ‘DISPERSAL_DISTANCE’ or ‘DISTANCES_TRAVELLED’

void clearParameters()

Clears the parameters from the internal objects so that another dispersal simulation can be run, if necessary.

void checkMaxParameterReference()

Gets the maximum parameter reference from the output SQL database and saves val + 1 to parameter_reference Assumes that the database exists.

unsigned long checkMaxIdNumber(string table_name)

Gets the maximum id number from the output SQL database and returns val + 1 Assumes that the database exists.

Note

this function does not check for SQL injection attacks and should not be used with variable function names.

Return

the maximum id + 1 from the given table

Parameters

• table_name: the name of the table to check for max(id) in

Protected Attributes

shared_ptr<Landscape> density_landscape

DataMask data_mask

DispersalCoordinator dispersal_coordinator = {}

shared_ptr<SimParameters> simParameters

shared_ptr<RNGController> random

unsigned long seed

SQLiteHandler database

vector<tuple<unsigned long, Cell, double>> distances

map<unsigned long, unsigned long> parameter_references

vector<Cell> cells

unsigned long num_repeats

set<unsigned long> num_steps

unsigned long num_workers

double generation

bool is_sequential

unsigned long max_parameter_reference

Class SimulatedSpeciesAbundancesHandler

• Defined in File SimulatedSpeciesAbundancesHandler.h

Inheritance Relationships

Base Type

• public necsim::SpeciesAbundancesHandler (Class SpeciesAbundancesHandler)

Class Documentation

class SimulatedSpeciesAbundancesHandler : public virtual necsim::SpeciesAbundancesHandler

Generates species identities from a set of species abundances.

Public Functions

SimulatedSpeciesAbundancesHandler()

Default constructor.

~SimulatedSpeciesAbundancesHandler()

Default destructor.

unsigned long getRandomSpeciesID()

Gets a randomly generated species identity.

Return

the species identity

void setAbundanceList(const shared_ptr<map<unsigned long, unsigned long>> &abundance_list_in)

Sets the abundance list.

Parameters

• abundance_list_in: map of species ids to abundances

void setAbundanceList(shared_ptr<vector<unsigned long>> abundance_list_in)

Sets the abundance list.

Parameters

• abundance_list_in: vector of species abundances

void generateAbundanceTable(shared_ptr<vector<unsigned long>> abundance_list)

Generates the species abundance hash tables for efficiently storing the species identities.

Parameters

• abundance_list: vector of species abundances

void generateCumulativeAbundances(shared_ptr<vector<unsigned long>> abundance_list)

Generates the cumulative abundances, rescaled from 0-1, for randomly choosing an abundance using binary search.

Parameters

• abundance_list: vector of species abundances

unsigned long getRandomAbundanceOfIndividual()

Gets a random species abundance.

Return

the randomly generated abundance

void setup(shared_ptr<RNGController> random, const unsigned long &metacommunity_size, const long double &speciation_rate, const unsigned long &local_community_size)

Creates the SpeciesAbundancesHandler object.

Parameters

• random: the random number generator
• metacommunity_size: the number of individuals in the metacommunity
• speciation_rate: the speciation rate of the metacommunity
• local_community_size: the number of individuals in the local community

Protected Attributes

map<unsigned long, vector<unsigned long>> species_abundances

map<unsigned long, unsigned long> species_richness_per_abundance

shared_ptr<map<unsigned long, unsigned long>> cumulative_abundance_map

double total_species_number

unsigned long number_of_individuals

shared_ptr<RNGController> random

unsigned long max_species_id

unsigned long metacommunity_size

unsigned long local_community_size

long double speciation_rate

Class SpatialTree

• Defined in File SpatialTree.h

Inheritance Relationships

Base Type

• public necsim::Tree (Class Tree)

Derived Type

• public necsim::ProtractedSpatialTree (Class ProtractedSpatialTree)

Class Documentation

class SpatialTree : public virtual necsim::Tree

Represents the output phylogenetic tree, when run on a spatially explicit landscape.

Contains all functions for running simulations, outputting data and calculating coalescence tree structure.

Subclassed by necsim::ProtractedSpatialTree

Public Functions

SpatialTree()

The constructor for SpatialTree.

~SpatialTree()

void runFileChecks()

Runs the basic file existence checks. Checks for paused simulations and file existence.

void checkFolders()

Checks that the folders exist and the files required for the simulation also exist.

void setParameters()

Sets the map object with the correct variables, taking the SimParameters structure defined elsewhere for the parameters.

Requires that parameters have already been imported into the SimParameters

This function can only be run once, otherwise a Main_Exception will be thrown

void importMaps()

Imports the maps into the landscape.

The simulation variables should have already been imported by setParameters(), otherwise a Fatal_Exception will be thrown.

void importActivityMaps()

Imports the activity maps from the relevant files.

unsigned long getInitialCount()

Counts the number of individuals that exist on the spatial grid.

Return

the number of individuals that will be initially simulated

void setupDispersalCoordinator()

Sets up the dispersal coordinator by linking to the correct functions and choosing the appropriate dispersal method.

void setup()

Contains the setup routines for a spatial landscape. It also checks for paused simulations and imports data if necessary from paused files. importMaps() is called for importing the map files.

unsigned long fillObjects(const unsigned long &initial_count)

Fill the active, data and grid objects with the starting lineages.

Return

the number of lineages added (for validation purposes)

Parameters

• initial_count: the number of individuals expected to exist

unsigned long getIndividualsSampled(const long &x, const long &y, const long &x_wrap, const long &y_wrap, const double &current_gen)

Gets the number of individuals to be sampled at the particular point and time. Round the number down to the nearest whole number for numbers of individuals.

Return

the number of individuals to sample at this location.

Parameters

• x: the x location for individuals to be sampled
• y: the y location for individuals to be sampled
• x_wrap: the number of x wraps for the cell
• y_wrap: the number of y wraps for the cell
• current_gen: the current generation timer

unsigned long getNumberLineagesAtLocation(const MapLocation &location) const

unsigned long getNumberIndividualsAtLocation(const MapLocation &location) const

void removeOldPosition(const unsigned long &chosen)

Removes the old position within active by checking any wrapping and removing connections.

The function also corrects the linked list to identify the correct nwrap for every wrapped lineage in that space.

Parameters

• chosen: the desired active reference to remove from the grid.

void calcMove()

Calculate the move, given a start x,y coordinates and wrapping.

The provided parameters will be altered to contain the new values so no record of the old variables remains after function running. Current dispersal methods use a fattailed dispersal.

long double calcMinMax(const unsigned long &current)

Calculates the minmax for a given branch.

Calculates the speciation rate required for speciation to have occured on this branch.

Parameters

• current: the current active reference to perform calculations over.

void calcNewPos()

Calculates the new position, checking whether coalescence has occured and with which lineage.

This involves correct handling of checking wrapped lineages (outside the original grid). The probability of coalescence is also calculated.

void calcWrappedCoalescence(const unsigned long &nwrap)

Calculates the coalescence event when the target cell is wrapped.

Parameters

• nwrap: the number of wrapped lineages

void switchPositions(const unsigned long &chosen)

Switches the chosen position with the endactive position.

Parameters

• chosen: the chosen lineage to switch with endactive.

void calcNextStep()

Calculates the next step for the simulation.

unsigned long estSpecnum()

Estimates the species number from the second largest minimum speciation rate remaining in active.

This allows for halting of the simulation once this threshold has been reached. However, the function is not currently in use as calculating the coalescence tree is very computionally intensive.

void incrementGeneration()

Increments the generation counter and step references, then updates the map for any changes to habitat cover.

void updateStepCoalescenceVariables()

Updates the coalescence variables in the step object.

void recordLineagePosition()

Zeroes out the coalescence information and stores the origin location.

void addLineages(double generation_in)

Expands the map, generating the new lineages where necessary.

The samplemask provided is used for expansion. Any empty spaces are filled with a new lineage. Lineages which have not moved are changed to tips, with a new data entry so that original and new generations are recorded.

Parameters

• generation_in: the generation that the expansion is occuring at. This is used in recording the new tips

string simulationParametersSqlInsertion()

Creates a string containing the SQL insertion statement for the simulation parameters.

Return

string containing the SQL insertion statement

void simPause()

Pause the simulation and dump data from memory.

void dumpMap(shared_ptr<ofstream> out)

Saves the map object to file.

Parameters

• out: the output file stream to save the object to

void dumpGrid(shared_ptr<ofstream> out)

Saves the grid object to file.

Parameters

• out: the output file stream to save the object to

void simResume()

Resumes the simulation from a previous state.

Reads in the parameters and objects from file and re-starts the simulation.

void loadGridSave(shared_ptr<ifstream> in1)

Loads the grid from the save file into memory.

Note

Requires that both the simulation parameters and the maps have already been loaded.

void loadMapSave(shared_ptr<ifstream> in1)

Loads the map from the save file into memory.

Note

Requires that the simulation parameters have already been loaded.

void verifyActivityMaps()

Checks that the reproduction map makes sense with the fine density map.

void addWrappedLineage(unsigned long numstart, long x, long y)

Adds the lineage to the correct point in the linked list of active lineages.

Parameters

• numstart: the active position to add
• x: the x position of the lineage
• y: the y position of the lineage

unsigned long countCellExpansion(const long &x, const long &y, const long &xwrap, const long &ywrap, const double &generationin, vector<TreeNode> &data_added)

Counts the number of lineages at a particular location that need to be added, after making the correct proportion of those that already exist into tips.

Return

the number of lineages still to add

Parameters

• x: the x coordinate of the location of interest
• y: the y coordinate of the location of interest
• xwrap: the x wrapping of the location
• ywrap: the y wrapping of the location
• generationin: the generation to assign to new tips
• data_added: vector containing TreeNode objects to add to data

void expandCell(long x, long y, long x_wrap, long y_wrap, double generation_in, unsigned long add, vector<TreeNode> &data_added, vector<DataPoint> &active_added)

Expands the cell at the desired location by adding the supplied number of lineages.

This takes into account wrapping to correctly add the right number

Parameters

• x: the x coordinate to add at
• y: the y coordinate to add at
• x_wrap: the x wrapping to add at
• y_wrap: the y wrapping to add at
• generation_in: the generation to set the new lineages to
• add: the total number of lineages to add at this location

void addGillespie(const double &g_threshold)

bool runSimulationGillespie()

void runGillespieLoop()

void setupGillespie()

Sets up the Gillespie algorithm.

void setupGillespieLineages()

Resets lineage speciation rates to 0.

void setupGillespieMaps()

Cell getCellOfMapLocation(const MapLocation &location)

Calculates the x, y position on the fine map of the lineage.

Return

cell object containing the x, y location

Parameters

• location: the map location

void findLocations()

Finds the locations that lineages are at and adds them to the list of locations.

This also involves calculating the event probabilities for each cell.

void checkMapEvents()

void checkSampleEvents()

void gillespieCellEvent(GillespieProbability &origin)

void gillespieUpdateMap()

void gillespieSampleIndividuals()

void gillespieCoalescenceEvent(GillespieProbability &origin)

void gillespieDispersalEvent(GillespieProbability &origin)

void gillespieSpeciationEvent(GillespieProbability &origin)

void gillespieLocationRemainingCheck(GillespieProbability &location)

template<typename T>
double getLocalDeathRate(const T &location) const

template<typename T>
double getLocalSelfDispersalRate(const T &location) const

void clearGillespieObjects()

void setStepVariable(const necsim::GillespieProbability &origin, const unsigned long &chosen, const unsigned long &coal_chosen)

void gillespieUpdateGeneration(const unsigned long &lineage)

void updateCellCoalescenceProbability(GillespieProbability &origin, const unsigned long &n)

void updateInhabitedCellOnHeap(const Cell &pos)

void updateAllProbabilities()

void removeHeapTop()

template<typename T>
Cell convertMapLocationToCell(const T &location) const

void createEventList()

Calculates the times for each event and sorts the event list.

void sortEvents()

template<bool restoreHeap = true>
void addNewEvent(const unsigned long &x, const unsigned long &y)

void addLocation(const MapLocation &location)

Adds the given location.

Calculates the probabilities of coalescence, dispersal and speciation.

Parameters

• location: the location to add and calculate values for

void setupGillespieProbability(GillespieProbability &gp, const MapLocation &location)

void fullSetupGillespieProbability(GillespieProbability &gp, const MapLocation &location)

double calculateCoalescenceProbability(const MapLocation &location) const

template<typename T>
double convertGlobalGenerationsToLocalGenerations(const T &location, const double g) const

unsigned long selectRandomLineage(const MapLocation &location) const

pair<unsigned long, unsigned long> selectTwoRandomLineages(const MapLocation &location) const

vector<unsigned long> detectLineages(const MapLocation &location) const

void assignNonSpeciationProbability(const unsigned long chosen)

Sets the speciation probability of the provided lineage so that speciation has a random chance of occurring, but didn’t occur during this branch of the coalescence tree.

Parameters

• chosen: the index in the active lineages to set the speciation probability for

void importSimulationVariables(const string &configfile)

Import the simulation variables from the command line structure.

This function parses the simulation variables, imports them from the config file, checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSimulation() can be run immediately afterwards.

Parameters

• configfile: the path to the config file containing parameters to parse.

void importSimulationVariables(ConfigParser config)

Import the simulation variables from a ConfigOption.

This function parses the simulation variables, imports them (from either the command line or a config file), checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSim() can be run immediately afterwards.

Parameters

• config: the set of config parameters to import

void wipeSimulationVariables()

Resets all the simulation variables.

void internalSetup(shared_ptr<SimParameters> sim_parameters_in)

Sets up the simulation parameters from the one provided.

Intended for usage with metacommunity application. No output directory is expected.

Parameters

• sim_parameters_in: the simulation parameters to set up the simulation with

bool checkOutputDirectory()

Asserts that the output directory is not null and exists. If it doesn’t exist, it attempts to create it.

Return

true if output creates successfully

Exceptions

• Fatal_Exception: if the output directory creation fails

void checkSims()

Checks for existing paused simulations to resume from Sets bPaused if there are.

This version uses the default values read from the config file.

void checkSims(string output_dir, long seed, long job_type)

Checks for existing paused simulations to resume from.

Sets bPaused if there are.

This version uses the values supplied to the function directly

Parameters

• output_dir: the output directory to check for
• seed: the seed for paused sims
• job_type: the job_type for paused sims

void setProtractedVariables(double speciation_gen_min, double speciation_gen_max)

Sets the protracted variables.

Parameters

• speciation_gen_min: the minimum number of generations to have passed before speciation is allowed
• speciation_gen_max: the maximum number of generations a lineage can exist for before it is speciated.

bool hasPaused()

Gets the has_paused variable for resuming sims.

Return

if the simulation has paused

vector<double> getTemporalSampling()

Gets the map autocorrel times.

long long getSeed()

Getter for the simulation seed.

Return

Returns the seed

long long getJobType()

Gets the job type for the simulation. This is a reference number for the jobs.

Return

Returns the job type

void setSeed(long long seed_in)

Sets the simulation seed for the random number generator.

This function should only be called once.

The seed is set within the NR object. This will be fixed for the simulation and is only performed once.

Parameters

• seed_in: the desired seed to set for the simulation

double getGeneration() const

Gets the generation timer for the simulation.

Return

the number of generations that have passed

unsigned long setObjectSizes()

Sets the sizes of grid, active and data, based on the number of individuals counted from the samplemask.

Return

a count of the number of individuals that exist in the simulation

void setInitialValues()

Sets the starting values for required parameters.

void setSimStartVariables()

Sets the variables at the start of a simulation for temporary data.

This is not the main set-up routine, which creates the permanent data structures including maps, the coalescence tree and active lineage listings.

void printSetup()

Prints the statement for the setup initiation.

This is stored in a separate function so that it can be called in isolation by child classes.

void setTimes()

Sets the temporal sampling points from the time config file.

void determineSpeciationRates()

Determines the speciation rates to apply and then applies them to the coalescence tree post-simulation.

Detects speciation rates from the config files supplied.

void addSpeciationRates(vector<long double> spec_rates_in)

Adds the speciation rates to those to be applied.

void generateObjects()

Assigns the objects sizes in memory and fills with the starting lineages.

void runSingleLoop()

Runs a single loop of the simulation.

bool runSimulation()

Run the entire simulation given the start conditions already defined by setup().

Setup is assumed to have been run already. This function is the main function containing the main loop of the simulation. At the end of the simulation, returns true if the simulation is complete, false otherwise.

Return

true if the simulation has completed

bool runSimulationNoGillespie()

Runs the simulation using the standard coalescence algorithm.

Return

true if the simulation has completed

void writeSimStartToConsole()

Writes to the console that the simulation is beginning.

void writeStepToConsole()

Write the step counter to console. This function should only be called in debugging mode.

void chooseRandomLineage()

Chooses a random lineage from active.

The index of the random lineage is stored in this_step, as chosen. Also records the required variables for the step process, like x, y position.

void speciation(const unsigned long &chosen)

Speciation to supplied lineage.

Also calls the removeOldPos() and switchPositions() functions for removing the lineage out of active reference.

Parameters

• chosen:

void speciateLineage(const unsigned long &data_position)

Performs the actual speciation.

Parameters

• data_position: the position in the array of TreeNodes for this lineage

bool calcSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.

Return

if true, speciation has occured

Parameters

• random_number: the generated random number from 0-1
• speciation_rate: the speciation rate to be applied
• no_generations: the number of generations a lineage has existed for

void coalescenceEvent(const unsigned long &chosen, unsigned long &coalchosen)

Perform the coalescence between lineages. Once coalesced, lineages are removed from the active scope.

Parameters

• chosen: the chosen lineage for coalescence
• coalchosen: the target lineage for coalscence

void checkTimeUpdate()

Checks if the number of lineages should be expanded at another sample point.

bool checkProportionAdded(const double &proportion_added)

Randomly checks if a lineage should be added, based on the proportion added.

Return

true if the lineage should be added, false otherwise

Parameters

• proportion_added: the proportion of lineages that should be added

void checkSimSize(unsigned long req_data, unsigned long req_active)

Checks the size of the main active and data objects is large enough.

Parameters

• req_data: the required data object size
• req_active: the required active object size

void makeTip(const unsigned long &tmp_active, const double &generation_in, vector<TreeNode> &data_added)

Sets the active reference to a tip, if it isn’t one already. Otherwise, creates a new tip for the new generation time.

Parameters

• tmp_active: the reference in active
• generation_in: the generation to set for the new lineage
• data_added: vector of lineages to add to data

void convertTip(unsigned long i, double generationin, vector<TreeNode> &data_added)

Creates a new reference in data containing the tip with a new generation counter.

Parameters

• i: the reference in active of the lineage to make a tip
• generationin: the generation to make the lineage a tip at
• data_added: vector of lineages to add to the data object

bool stopSimulation()

Finalises the simulation, and performs the correct tasks depending if the sim has been paused or finished.

Return

void applySpecRate(long double sr, double t)

Applies the given speciation rate to the tree.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applySpecRate(long double sr)

Overloaded version of applySpecRates for the default generation (0.0).

Parameters

• sr: the speciation rate to apply to the tree

void applySpecRateInternal(long double sr, double t)

Applies the given speciation rate to the tree, but does not output to a file. Instead returns a pointer to the nodes object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Gets the sorted cumulative species abundances from the contained TreeList.

For use with metacommunity applications

Return

row of cumulative species abundances

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances from the internal tree.

Return

the species abundances

Parameters

• community_reference: the community reference

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundances from the internal tree.

Return

the species abundances

ProtractedSpeciationParameters setupCommunity()

Sets up Community member to point to the same output database as the simulation.

Return

the protracted speciation parameters to set up

void setupCommunityCalculation(long double sr, double t)

Sets up the generation of the tree object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applyMultipleRates()

Applies multiple speciation rates to the coalescence tree, ignoring repeated speciation rates.

Speciation rates are read from the speciation_rates object, which should have already been calculated.

bool getProtracted()

Gets the protractedness of the simulation. Overridden by protracted child classes.

Return

string getProtractedVariables()

Gets the protracted variables and returns them as a single, newline separated string. This method is intended to be overridden in derived classes.

Return

string containing the protracted variables, separated by newlines.

double getProtractedGenerationMin()

Gets the minimum number of generations a lineage must exist.

Without overriding this function, should always return 0.0.

Return

double the number of generations a lineage must exist

double getProtractedGenerationMax()

Gets the maximum number of generations a lineage can exist.

Without overriding this function, should always return 0.0 (no maximum).

Return

double the number of generations a lineage must exist

void sqlOutput()

Copy the in-memory database to file.

This function should not be called if the database is already opened on disc, and won’t do anything if it is.

void createAndOutputData()

Creates the output data objects and outputs important simulation data to a database file.

void outputData()

Outputs the simulation data (including the coalescence tree) to an sql database.

void sortData()

Sort and process the species list so that the useful information can be extracted from it.

void writeTimes()

Writes the times to the terminal for simulation information.

void openSQLDatabase()

Opens a connection to the in-memory database, or the on-disk database, depending on the compilation options.

void sqlCreate()

Generates the SQL database file from the full simulation data. This allows for greater analysis of the data after completion of the simulation.

void setupOutputDirectory()

Creates the output directory, if it doesn’t already exist, and deletes any existing database with the output name.

void sqlCreateSimulationParameters()

Creates the SIMULATION_PARAMETERS table in the SQL database.

string protractedVarsToString()

Outputs the protracted variables to a string.

This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.

Return

string containing a list of the protracted speciation variables.

shared_ptr<ofstream> initiatePause()

Checks the output folder exists and initiates the pause.

Return

the output file stream to save objects to

void dumpMain(shared_ptr<ofstream> out)

Saves the main simulation variables to file.

Parameters

• out: the output file stream to save the object to

void dumpActive(shared_ptr<ofstream> out)

Saves the active object to file.

Parameters

• out: the output file stream to save the object to

void dumpData(shared_ptr<ofstream> out)

Saves the data object to file.

Parameters

• out: the output file stream to save the object to

void completePause(shared_ptr<ofstream> out)

Completes the pause routine and outputs the sql dump.

Parameters

• out: the output stream to close up

void setResumeParameters(string pausedir, string outdir, unsigned long seed, unsigned long job_type, unsigned long new_max_time)

Sets the resume variables so that the simulation can be resumed.

The pause directory can be the same as the output directory if it is desirable to save to the same location.

Parameters

• pausedir: the directory containing the pause folder for resuming the simulation
• outdir: the directory to write simulation output to
• seed: the simulation seed
• job_type: the simulation job reference number
• new_max_time: the maximum simulation time to run for in seconds (0 keeps old simulation max time)

void setResumeParameters()

Sets the resume variables to the defaults.

shared_ptr<ifstream> openSaveFile()

void loadMainSave(shared_ptr<ifstream> in1)

Loads the main simulation parameters from the save file into memory.

void loadDataSave(shared_ptr<ifstream> in1)

Loads the data object from the save file into memory.

void loadActiveSave(shared_ptr<ifstream> in1)

Loads the active object from the save file into memory.

void initiateResume()

Checks for resuming and prints to the terminal.

Protected Attributes

DispersalCoordinator dispersal_coordinator

shared_ptr<ActivityMap> death_map

shared_ptr<ActivityMap> reproduction_map

string fine_map_input

string coarse_map_input

string historical_fine_map_input

string historical_coarse_map_input

shared_ptr<Landscape> landscape

Matrix<SpeciesList> grid

unsigned long desired_specnum

DataMask samplegrid

double gillespie_threshold

Matrix<GillespieProbability> probabilities

vector<GillespieHeapNode> heap

Matrix<unsigned long> cellToHeapPositions

Matrix<double> self_dispersal_probabilities

unsigned long global_individuals

double summed_death_rate

shared_ptr<vector<TreeNode>> data

unsigned long enddata

shared_ptr<SimParameters> sim_parameters

shared_ptr<RNGController> NR

vector<long double> speciation_rates

bool seeded

long long seed

long long job_type

string times_file

vector<double> reference_times

bool uses_temporal_sampling

time_t start

time_t sim_start

time_t sim_end

time_t now

time_t sim_finish

time_t out_finish

time_t time_taken

vector<DataPoint> active

unsigned long endactive

unsigned long startendactive

unsigned long maxsimsize

Community community

long steps

unsigned long maxtime

double generation

double deme

double deme_sample

long double spec

string out_directory

shared_ptr<SQLiteHandler> database

bool sim_complete

bool has_imported_vars

Step this_step

string sql_output_database

bool bFullMode

bool bResume

bool bConfig

bool has_paused

bool has_imported_pause

bool bIsProtracted

string pause_sim_directory

bool using_gillespie

Protected Static Attributes

const unsigned long UNUSED = static_cast<unsigned long>(-1)

Class SpeciationCommands

• Defined in File SpeciationCommands.h

Class Documentation

class SpeciationCommands

Routines for parsing command-line arguments to apply speciation rates to a necsim output post-simulation.

Public Functions

SpeciationCommands()

Default constructor for SpeciationCommands class.

void parseArgs()

Run the command line arguments check. Writes arguments to the SpecSimParameters object.

Parameters

• argc: the number of arguments.
• comargs: a vector filled with the command line arguments

int applyFromComargs(int argc_in, char **argv)

Runs the main program including parsing command line arguments and running the main analyses.

Return

Parameters

• argc: the number of command line arguments
• argv: the array of command line arguments

Class SpeciesAbundancesHandler

• Defined in File SpeciesAbundancesHandler.h

Inheritance Relationships

Derived Types

• public necsim::AnalyticalSpeciesAbundancesHandler (Class AnalyticalSpeciesAbundancesHandler)
• public necsim::SimulatedSpeciesAbundancesHandler (Class SimulatedSpeciesAbundancesHandler)

Class Documentation

class SpeciesAbundancesHandler

Base class for defining species abundances.

Subclassed by necsim::AnalyticalSpeciesAbundancesHandler, necsim::SimulatedSpeciesAbundancesHandler

Public Functions

SpeciesAbundancesHandler()

Default constructor.

virtual ~SpeciesAbundancesHandler()

Default destructor.

void setup(shared_ptr<RNGController> random, const unsigned long &metacommunity_size, const long double &speciation_rate, const unsigned long &local_community_size)

Creates the SpeciesAbundancesHandler object.

Parameters

• random: the random number generator
• metacommunity_size: the number of individuals in the metacommunity
• speciation_rate: the speciation rate of the metacommunity
• local_community_size: the number of individuals in the local community

virtual unsigned long getRandomSpeciesID() = 0

Gets a randomly generated species identity.

Return

the species identity

void setAbundanceList(const shared_ptr<map<unsigned long, unsigned long>> &abundance_list_in)

Sets the abundance list.

Parameters

• abundance_list_in: list of abundances for each species

void setAbundanceList(shared_ptr<vector<unsigned long>> abundance_list_in)

Sets the abundance list.

Parameters

• abundance_list_in: list of abundances for each species

Protected Attributes

shared_ptr<RNGController> random

unsigned long max_species_id

unsigned long metacommunity_size

unsigned long local_community_size

long double speciation_rate

Class SpeciesList

• Defined in File SpeciesList.h

Class Documentation

class SpeciesList

Contains a list of the species that exist at one location. The Row object, list, contains the active reference number, for looking up the lineage in a Row of Datapoint objects. Also contains the functions for correctly generating coalescence probabilities and list management.

Note that the maximum size of the list is constrained by the maximum size of unsigned long. Any simulation requiring more individuals per cell than this will unlikely finish in any reasonable time anyway.

Public Functions

SpeciesList()

Default constructor.

~SpeciesList()

Default destructor.

void initialise(unsigned long maxsizein)

Initialises the list to the specified size.

Parameters

• maxsizein: the maximum list size.

void setMaxsize(unsigned long maxsizein)

Sets the maxsize without altering the actual size of list.

Parameters

• maxsizein: The new maximum size to set.

void setSpecies(unsigned long index, unsigned long new_val)

Set specific entry to a particular species reference number.

This version throws an error if the space is empty.

Parameters

• index: the location in list of the species.
• new_val: the new species reference to set list[index] to.

void setSpeciesEmpty(unsigned long index, unsigned long new_val)

Set specific entry to a particular species reference number.

Note this version will throw a runtime_error if the space is not empty

Parameters

• index: the location in list of the species
• new_val: the new species reference to set list[index] to

void setNext(unsigned long n)

Set the next active lineage (for wrapping purposes).

Parameters

• n: the lineage to set as the first wrapped lineage.

void setNwrap(unsigned long nr)

Set the number of wrapping lineages.

Parameters

• nr: the number of wrapped lineages.

unsigned long addSpecies(const unsigned long &new_spec)

Add a new species to the first empty place and return the position of the lineage.

Return

the location the species has been added to.

Parameters

• new_spec: the new species reference to place in the first empty space.

void deleteSpecies(unsigned long index)

Removes the species at the specified index. The species number will be replaced with 0, indicating no species present.

Older versions of this function re-shuffled the list so that all species came at the top.

Parameters

• index: the index of the species to remove from the list.

void decreaseNwrap()

Decreases the nwrap by one.

Indicates the number of species wrapped at the location of this SpeciesList object has decreased by one.

void increaseListSize()

Increases the list size by one.

void increaseNwrap()

Increases the nwrap by one.

Indicates the number of species wrapped at the location of this SpeciesList object has increased by one.

void changePercentCover(unsigned long newmaxsize)

Changes the maximum size of the SpeciesList. Currently identical to setMaxsize.

Parameters

• newmaxsize: the new maximum size to be applied.

unsigned long getRandLineage(const shared_ptr<RNGController> &rand_no)

Get a random species reference number from all the potential entries. Updated alternative version returns any entry, including empty cells, giving the probability of coalescence as well.

Return

the reference of the random lineage. 0 indicates an empty space.

Parameters

• rand_no: the random number object to pass (for maintaining the same seed throughout simulations).

unsigned long getLineageIndex(unsigned long index) const

Get the species reference number from a particular entry.

Return

the species reference at the specified location.

Parameters

• index: the location of the species to reference.

unsigned long getNext() const

Get the next_active variable.

Return

the next linked species reference.

unsigned long getNwrap() const

Getter for the nwrap.

Return

the number of wrapped lineages currently at this grid cell.

unsigned long getListSize() const

Getter for the list size.

Return

the number of lineages currently directly within the SpeciesList.

unsigned long getMaxSize() const

Getter for the maximum size of the SpeciesList object.

Return

the maximum number of lineages that can exist currently.

unsigned long getListLength() const

Gets the length of the list object.

Return

the length of the list object

void wipeList()

Empties the list of any data and fills the list with zeros.

double getCoalescenceProbability() const

Gets the probability of coalescence within this object in a single time step.

Return

the probability of coalescence

Friends

ostream &operator<<(ostream &os, const SpeciesList &r)

Outputs the SpeciesList object to an output stream. Allows for piping to the terminal or writing the object to a file.

Return

the output stream.

Parameters

• os: the output stream.
• r: the SpeciesList object to output.

istream &operator>>(istream &is, SpeciesList &r)

Inputs the SpeciesList object from an input stream. Allows for reading data from a file or string stream.

Parameters

• is: the input stream.
• r: the SpeciesList object to input to.

Class SpecSimParameters

• Defined in File SpecSimParameters.h

Class Documentation

class SpecSimParameters

Contains the simulation parameters that are read from the command line.

Public Functions

SpecSimParameters()

SpecSimParameters(const string &fragment_config_file)

void addSpeciationRate(const double &speciation_rate)

Adds a speciation rate to the speciation parameters list.

Parameters

• speciation_rate: the speciation rate to add

void setup(string file_in, bool use_spatial_in, string sample_file, const string &use_fragments_in)

Sets the application arguments for the inputs.

Parameters

• file_in: the database to apply speciation rates to
• use_spatial_in: if true, record full spatial data
• sample_file: the sample file to select lineages from the map
• use_fragments_in: fragment file, or “T”/”F” for automatic detection/no detection

void setup(string file_in, bool use_spatial_in, string sample_file, const vector<double> &times, const string &use_fragments_in, vector<double> speciation_rates)

Sets the application arguments for the inputs.

Parameters

• file_in: the database to apply speciation rates to
• use_spatial_in: if true, record full spatial data
• sample_file: the sample file to select lineages from the map
• times: vector of times to apply
• use_fragments_in: fragment file, or “T”/”F” for automatic detection/no detection
• speciation_rates: the speciation rates to apply

void setup(string file_in, bool use_spatial_in, string sample_file, const vector<double> &times, const string &use_fragments_in)

Sets the application arguments for the inputs. Overloaded version without speciation rates.

Parameters

• file_in: the database to apply speciation rates to
• use_spatial_in: if true, record full spatial data
• sample_file: the sample file to select lineages from the map
• times: vector of times to apply
• use_fragments_in: fragment file, or “T”/”F” for automatic detection/no detection

void addMetacommunityParameters(const unsigned long &metacommunity_size_in, const double &metacommunity_speciation_rate_in, const string &metacommunity_option_in, const unsigned long &metacommunity_reference_in)

Sets the metacommunity parameters for the simulation.

Parameters

• metacommunity_size_in: the number of individuals in the metacommunity
• metacommunity_speciation_rate_in: the speciation rate for the metacommunity

void importTimeConfig()

Import the time config file, if there is one.

void wipe()

Deletes all the parameters.

void addTime(double time)

Adds an additional time to the times vector.

Parameters

• time: a time to calculate speciation rates at

void addProtractedParameters(double proc_spec_min, double proc_spec_max)

Adds a set of protracted speciation parameters to the protracted parameters vector.

Parameters

• proc_spec_min: the minimum protracted speciation generation
• proc_spec_max: the maximum protracted speciation generation

Public Members

bool use_spatial

bool bMultiRun

bool use_fragments

string filename

set<double> all_speciation_rates

string samplemask

string times_file

set<double> all_times

string fragment_config_file

vector<ProtractedSpeciationParameters> protracted_parameters

MetacommunitiesArray metacommunity_parameters

Class SQLiteHandler

• Defined in File SQLiteHandler.h

Class Documentation

class SQLiteHandler

Handler for the SQLite connection, including proper opening and closing of the database object.

Public Functions

SQLiteHandler()

Default constructor.

~SQLiteHandler()

Default destructor.

void open(const std::string &file_name)

Opens a database connection to the specified file name. If the file name is “:memory:”, instead opens a connection to an in-memory database object.

Parameters

• file_name: the name of the file to open (or “:memory:” for in-memory databases)

void close()

Closes the sqlite3 connection to the database.

std::string getErrorMsg(int rc)

Gets the error message from the sqlite3 database operations.

Return

string containing the result code and the error message

Parameters

• rc: the result code of the previous operation, to print out

std::string getErrorMsg()

Gets the error message from the database.

Return

the error message

void backupFrom(SQLiteHandler &sqlite_handler)

Copies the data from the provided SQLiteHander object to this database.

Parameters

• sqlite_handler: the database containing data to copy

shared_ptr<SQLStatement> prepare(const std::string &command)

Prepares the given commmand within the statement object.

Return

pointer to the prepared statement

Parameters

• command: the command to execute
• stmt: the statement to prepare within

void createStatement()

Creates a new statement for the database handler.

void useStatement(shared_ptr<SQLStatement> stmt)

Use the supplied statement object for the database.

Parameters

• stmt:

void step()

Steps the prepared statement forwards and reports any errors.

Note

stmt should have been opened from the same SQLiteHandler object using prepare()

Parameters

• stmt: the statement to step forwards

void finalise()

Finalises the sqlite statement and reports any errors.

Note

stmt should have been opened from the same SQLiteHandler object using prepare()

Parameters

• stmt: the statement to finalise

void execute(const string &command)

Executes a command from the database and reports any errors.

Parameters

• command: the command to execute within the database

void beginTransaction()

Starts a transaction from this database object.

void endTransaction()

Ends the transaction from this database object.

bool isOpen()

Checks if the database is open.

Return

true, if the database is not a nullptr.

bool hasTable(const std::string &table_name)

Checks if the database has the specified table.

Return

true if the table exists

Parameters

• table_name: the table name to check for existence

Protected Attributes

sqlite3 *database

std::string file_name

shared_ptr<SQLStatement> stmt

Class Step

• Defined in File Step.h

Inheritance Relationships

Base Type

• public necsim::MapLocation (Struct MapLocation)

Class Documentation

class Step : public virtual necsim::MapLocation

Stores the elements associated with a single step in a coalescence simulation.

This object should only contain transient variables that are used within a single simulation step and therefore should not be important for pausing/resuming simulations.

Public Functions

Step()

Step constructor.

Return

Step(const Cell &cell)

void wipeData()

Removes all stored data from the step. This should be run at the start of a single coalescence step.

bool isOnGrid() const

Checks if the location is directly on the grid without wrapping (i.e. xwrap and ywrap are 0).

Return

true if on the grid

bool operator==(MapLocation const &m) const

Equality operator for MapLocation.

Return

true if the x, y, xwrap and ywrap are identical

Parameters

• m: the MapLocation object to compare against

bool operator!=(MapLocation const &m) const

Inequality operator for MapLocation.

Return

true if locations are not identical

Parameters

• m: the MapLocation object to compare against

Public Members

unsigned long chosen

unsigned long coalchosen

bool coal

bool bContinueSim

unsigned int time_reference

long x

long y

long xwrap

long ywrap

Class Tree

• Defined in File Tree.h

Inheritance Relationships

Derived Types

• public necsim::ProtractedTree (Class ProtractedTree)
• public necsim::SpatialTree (Class SpatialTree)

Class Documentation

class Tree

Main simulation class for performing a non-spatial neutral simulation and generating the phylogenetic tree of the individuals.

Subclassed by necsim::ProtractedTree, necsim::SpatialTree

Public Functions

Tree()

virtual ~Tree()

void importSimulationVariables(const string &configfile)

Import the simulation variables from the command line structure.

This function parses the simulation variables, imports them from the config file, checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSimulation() can be run immediately afterwards.

Parameters

• configfile: the path to the config file containing parameters to parse.

void importSimulationVariables(ConfigParser config)

Import the simulation variables from a ConfigOption.

This function parses the simulation variables, imports them (from either the command line or a config file), checks that the input files exist and checks for any paused simulations. The flags are then set correctly, meaning that setup() and runSim() can be run immediately afterwards.

Parameters

• config: the set of config parameters to import

void runFileChecks()

Runs the basic file existence checks. Checks for paused simulations and file existence.

void wipeSimulationVariables()

Resets all the simulation variables.

void internalSetup(shared_ptr<SimParameters> sim_parameters_in)

Sets up the simulation parameters from the one provided.

Intended for usage with metacommunity application. No output directory is expected.

Parameters

• sim_parameters_in: the simulation parameters to set up the simulation with

bool checkOutputDirectory()

Asserts that the output directory is not null and exists. If it doesn’t exist, it attempts to create it.

Return

true if output creates successfully

Exceptions

• Fatal_Exception: if the output directory creation fails

void checkSims()

Checks for existing paused simulations to resume from Sets bPaused if there are.

This version uses the default values read from the config file.

void checkSims(string output_dir, long seed, long job_type)

Checks for existing paused simulations to resume from.

Sets bPaused if there are.

This version uses the values supplied to the function directly

Parameters

• output_dir: the output directory to check for
• seed: the seed for paused sims
• job_type: the job_type for paused sims

void setParameters()

Move the parameters from the sim_parameters object to their relevant parameters.

void setProtractedVariables(double speciation_gen_min, double speciation_gen_max)

Sets the protracted variables.

Parameters

• speciation_gen_min: the minimum number of generations to have passed before speciation is allowed
• speciation_gen_max: the maximum number of generations a lineage can exist for before it is speciated.

bool hasPaused()

Gets the has_paused variable for resuming sims.

Return

if the simulation has paused

vector<double> getTemporalSampling()

Gets the map autocorrel times.

long long getSeed()

Getter for the simulation seed.

Return

Returns the seed

long long getJobType()

Gets the job type for the simulation. This is a reference number for the jobs.

Return

Returns the job type

void setSeed(long long seed_in)

Sets the simulation seed for the random number generator.

This function should only be called once.

The seed is set within the NR object. This will be fixed for the simulation and is only performed once.

Parameters

• seed_in: the desired seed to set for the simulation

double getGeneration() const

Gets the generation timer for the simulation.

Return

the number of generations that have passed

unsigned long getInitialCount()

Gets the initial number of individuals.

Return

the number of initial individuals to simulate

unsigned long setObjectSizes()

Sets the sizes of grid, active and data, based on the number of individuals counted from the samplemask.

Return

a count of the number of individuals that exist in the simulation

void setup()

The setup function for generating the simulation objects.

The simulation parameters are set from comargs using setParameters(). Generates and fills the active and grid objects as well as importing all the maps from the supplied files.

void setInitialValues()

Sets the starting values for required parameters.

void setSimStartVariables()

Sets the variables at the start of a simulation for temporary data.

This is not the main set-up routine, which creates the permanent data structures including maps, the coalescence tree and active lineage listings.

void printSetup()

Prints the statement for the setup initiation.

This is stored in a separate function so that it can be called in isolation by child classes.

void setTimes()

Sets the temporal sampling points from the time config file.

void determineSpeciationRates()

Determines the speciation rates to apply and then applies them to the coalescence tree post-simulation.

Detects speciation rates from the config files supplied.

void addSpeciationRates(vector<long double> spec_rates_in)

Adds the speciation rates to those to be applied.

void generateObjects()

Assigns the objects sizes in memory and fills with the starting lineages.

unsigned long fillObjects(const unsigned long &initial_count)

Fills the active and data objects with the starting lineages.

Parameters

• initial_count: the number of individuals expected to exist

void runSingleLoop()

Runs a single loop of the simulation.

bool runSimulation()

Run the entire simulation given the start conditions already defined by setup().

Setup is assumed to have been run already. This function is the main function containing the main loop of the simulation. At the end of the simulation, returns true if the simulation is complete, false otherwise.

Return

true if the simulation has completed

bool runSimulationNoGillespie()

Runs the simulation using the standard coalescence algorithm.

Return

true if the simulation has completed

void writeSimStartToConsole()

Writes to the console that the simulation is beginning.

void writeStepToConsole()

Write the step counter to console. This function should only be called in debugging mode.

void incrementGeneration()

Increments the generation counter and step references.

void chooseRandomLineage()

Chooses a random lineage from active.

The index of the random lineage is stored in this_step, as chosen. Also records the required variables for the step process, like x, y position.

void updateStepCoalescenceVariables()

Updates the coalescence variables in the step object.

void speciation(const unsigned long &chosen)

Speciation to supplied lineage.

Also calls the removeOldPos() and switchPositions() functions for removing the lineage out of active reference.

Parameters

• chosen:

void speciateLineage(const unsigned long &data_position)

Performs the actual speciation.

Parameters

• data_position: the position in the array of TreeNodes for this lineage

void removeOldPosition(const unsigned long &chosen)

Removes the old position within active.

Parameters

• chosen: the desired active reference to remove from the grid.

void switchPositions(const unsigned long &chosen)

Switches the chosen position with the endactive position.

Parameters

• chosen: the chosen lineage to switch with endactive.

void calcNextStep()

Calculates the next step for the simulation.

bool calcSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Calculates the speciation probability from the random number, speciation rate and number of generations a lineage has existed for.

Return

if true, speciation has occured

Parameters

• random_number: the generated random number from 0-1
• speciation_rate: the speciation rate to be applied
• no_generations: the number of generations a lineage has existed for

void coalescenceEvent(const unsigned long &chosen, unsigned long &coalchosen)

Perform the coalescence between lineages. Once coalesced, lineages are removed from the active scope.

Parameters

• chosen: the chosen lineage for coalescence
• coalchosen: the target lineage for coalscence

void checkTimeUpdate()

Checks if the number of lineages should be expanded at another sample point.

void addLineages(double generation_in)

Adds the required lineages at the generation time.

Parameters

• generation_in: the generation to add lineages at

bool checkProportionAdded(const double &proportion_added)

Randomly checks if a lineage should be added, based on the proportion added.

Return

true if the lineage should be added, false otherwise

Parameters

• proportion_added: the proportion of lineages that should be added

void checkSimSize(unsigned long req_data, unsigned long req_active)

Checks the size of the main active and data objects is large enough.

Parameters

• req_data: the required data object size
• req_active: the required active object size

void makeTip(const unsigned long &tmp_active, const double &generation_in, vector<TreeNode> &data_added)

Sets the active reference to a tip, if it isn’t one already. Otherwise, creates a new tip for the new generation time.

Parameters

• tmp_active: the reference in active
• generation_in: the generation to set for the new lineage
• data_added: vector of lineages to add to data

void convertTip(unsigned long i, double generationin, vector<TreeNode> &data_added)

Creates a new reference in data containing the tip with a new generation counter.

Parameters

• i: the reference in active of the lineage to make a tip
• generationin: the generation to make the lineage a tip at
• data_added: vector of lineages to add to the data object

bool stopSimulation()

Finalises the simulation, and performs the correct tasks depending if the sim has been paused or finished.

Return

void applySpecRate(long double sr, double t)

Applies the given speciation rate to the tree.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applySpecRateInternal(long double sr, double t)

Applies the given speciation rate to the tree, but does not output to a file. Instead returns a pointer to the nodes object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

shared_ptr<vector<unsigned long>> getCumulativeAbundances()

Gets the sorted cumulative species abundances from the contained TreeList.

For use with metacommunity applications

Return

row of cumulative species abundances

shared_ptr<map<unsigned long, unsigned long>> getSpeciesAbundances(const unsigned long &community_reference)

Gets the species abundances from the internal tree.

Return

the species abundances

Parameters

• community_reference: the community reference

shared_ptr<vector<unsigned long>> getSpeciesAbundances()

Gets the species abundances from the internal tree.

Return

the species abundances

ProtractedSpeciationParameters setupCommunity()

Sets up Community member to point to the same output database as the simulation.

Return

the protracted speciation parameters to set up

void setupCommunityCalculation(long double sr, double t)

Sets up the generation of the tree object.

Parameters

• sr: the required speciation rate
• t: the required time of speciation

void applySpecRate(long double sr)

Overloaded version of applySpecRates for the default generation (0.0).

Parameters

• sr: the speciation rate to apply to the tree

void applyMultipleRates()

Applies multiple speciation rates to the coalescence tree, ignoring repeated speciation rates.

Speciation rates are read from the speciation_rates object, which should have already been calculated.

bool getProtracted()

Gets the protractedness of the simulation. Overridden by protracted child classes.

Return

string getProtractedVariables()

Gets the protracted variables and returns them as a single, newline separated string. This method is intended to be overridden in derived classes.

Return

string containing the protracted variables, separated by newlines.

double getProtractedGenerationMin()

Gets the minimum number of generations a lineage must exist.

Without overriding this function, should always return 0.0.

Return

double the number of generations a lineage must exist

double getProtractedGenerationMax()

Gets the maximum number of generations a lineage can exist.

Without overriding this function, should always return 0.0 (no maximum).

Return

double the number of generations a lineage must exist

void sqlOutput()

Copy the in-memory database to file.

This function should not be called if the database is already opened on disc, and won’t do anything if it is.

void createAndOutputData()

Creates the output data objects and outputs important simulation data to a database file.

void outputData()

Outputs the simulation data (including the coalescence tree) to an sql database.

void sortData()

Sort and process the species list so that the useful information can be extracted from it.

void writeTimes()

Writes the times to the terminal for simulation information.

void openSQLDatabase()

Opens a connection to the in-memory database, or the on-disk database, depending on the compilation options.

void sqlCreate()

Generates the SQL database file from the full simulation data. This allows for greater analysis of the data after completion of the simulation.

void setupOutputDirectory()

Creates the output directory, if it doesn’t already exist, and deletes any existing database with the output name.

void sqlCreateSimulationParameters()

Creates the SIMULATION_PARAMETERS table in the SQL database.

string simulationParametersSqlInsertion()

Creates a string containing the SQL insertion statement for the simulation parameters.

Return

string containing the SQL insertion statement

string protractedVarsToString()

Outputs the protracted variables to a string.

This function is intended to be overridden by derived classes. It is intended the output is used for writing to SQL databases.

Return

string containing a list of the protracted speciation variables.

void simPause()

Pause the simulation and dump data from memory.

shared_ptr<ofstream> initiatePause()

Checks the output folder exists and initiates the pause.

Return

the output file stream to save objects to

void dumpMain(shared_ptr<ofstream> out)

Saves the main simulation variables to file.

Parameters

• out: the output file stream to save the object to

void dumpActive(shared_ptr<ofstream> out)

Saves the active object to file.

Parameters

• out: the output file stream to save the object to

void dumpData(shared_ptr<ofstream> out)

Saves the data object to file.

Parameters

• out: the output file stream to save the object to

void completePause(shared_ptr<ofstream> out)

Completes the pause routine and outputs the sql dump.

Parameters

• out: the output stream to close up

void setResumeParameters(string pausedir, string outdir, unsigned long seed, unsigned long job_type, unsigned long new_max_time)

Sets the resume variables so that the simulation can be resumed.

The pause directory can be the same as the output directory if it is desirable to save to the same location.

Parameters

• pausedir: the directory containing the pause folder for resuming the simulation
• outdir: the directory to write simulation output to
• seed: the simulation seed
• job_type: the simulation job reference number
• new_max_time: the maximum simulation time to run for in seconds (0 keeps old simulation max time)

void setResumeParameters()

Sets the resume variables to the defaults.

shared_ptr<ifstream> openSaveFile()

void loadMainSave(shared_ptr<ifstream> in1)

Loads the main simulation parameters from the save file into memory.

void loadDataSave(shared_ptr<ifstream> in1)

Loads the data object from the save file into memory.

void loadActiveSave(shared_ptr<ifstream> in1)

Loads the active object from the save file into memory.

void initiateResume()

Checks for resuming and prints to the terminal.

void simResume()

Resumes the simulation from a previous state.

Reads in the parameters and objects from file and re-starts the simulation.

void addGillespie(const double &g_threshold)

bool runSimulationGillespie()

Protected Attributes

shared_ptr<vector<TreeNode>> data

unsigned long enddata

shared_ptr<SimParameters> sim_parameters

shared_ptr<RNGController> NR

vector<long double> speciation_rates

bool seeded

long long seed

long long job_type

string times_file

vector<double> reference_times

bool uses_temporal_sampling

time_t start

time_t sim_start

time_t sim_end

time_t now

time_t sim_finish

time_t out_finish

time_t time_taken

vector<DataPoint> active

unsigned long endactive

unsigned long startendactive

unsigned long maxsimsize

Community community

long steps

unsigned long maxtime

double generation

double deme

double deme_sample

long double spec

string out_directory

shared_ptr<SQLiteHandler> database

bool sim_complete

bool has_imported_vars

Step this_step

string sql_output_database

bool bFullMode

bool bResume

bool bConfig

bool has_paused

bool has_imported_pause

bool bIsProtracted

string pause_sim_directory

bool using_gillespie

Class TreeNode

• Defined in File TreeNode.h

Class Documentation

class TreeNode

The TreeNode class that acts as a data storage object for the phylogenetic tree.

Also contains all the necessary routines for changes to a lineage’s attributes, called by TreeList objects when generating new coalescence trees.

Public Functions

TreeNode()

The default constructor.

~TreeNode()

The default destructor.

void setup(bool z, unsigned long xp, unsigned long yp, long xi, long yi)

Sets up variables with initial conditions.

Parameters

• z: whether this lineage is a tip or not (represents the end of a tree).
• xp: the x position on the grid.
• yp: the y position on the grid.
• xi: the number of wraps in the x dimension.
• yi: the number of wraps in the y dimension.

void setup(bool z)

Sets up variables with initial conditions.

Parameters

• z: whether this lineage is a tip or not (represents the end of a tree)

void setup(const bool &is_tip, const long &xp, const long &yp, const long &xi, const long &yi, const long double &generation)

Overloaded setup() function, additionally taking a generation time point.

Used when creating lineages after the start of the simulation, when the generation is not 0.

Parameters

• is_tip: whether this lineage is a tip or not (represents the end of a tree).
• xp: the x position on the grid.
• yp: the y position on the grid.
• xi: the number of wraps in the x dimension.
• yi: the number of wraps in the y dimension.
• generation: the current generation at creation time.

void setExistence(bool b)

Setter for the existence of the lineage.

Parameters

• b: existence boolean.

void setParent(unsigned long x)

Setter for the parent reference.

Parameters

• x: a reference for the parent location.

void qReset()

Resets the lineage. Remove any species ID, existence and speciation record.

void setPosition(long x, long y, long xw, long yw)

Set a new position for the lineage.

Parameters

• x: the x position on the grid.
• y: the y position on the grid.
• xw: the number of wraps in the x dimension.
• yw: the number of wraps in the y dimension.

void setSpec(long double d)

Setter for the randomly generated number (from NRrand.d0()) for the speciation probability for this lineage.

Parameters

• d: the speciation probability.

void setGenerationRate(unsigned long g)

Setter for the number of generations this lineage has existed for.

Parameters

• g: the number of generations that the lineage has existed.

void setGeneration(long double d)

Setter for the birth generation timer for the lineage.

Note that moves that don’t involve coalescence do not create a new Treenode object, and therefore the generation_added does not get updated. However, coalescence events will cause a new Treenode object creation. The lineage birth generation is generally only important for calculating the age of tips.

Parameters

• d:

void setSpeciation(bool s)

Setter for the speciation boolean.

Parameters

• s: the speciation boolean.

void burnSpecies(unsigned long idin)

Setter for the species ID. Once set to something other than 0, this cannot be changed with a call to qReset() or resetSpecies().

Parameters

• idin: the species ID.

void setTip(bool b)

Setter for the tip boolean.

Parameters

• b: the tip boolean.

void resetSpecies()

Reset the species ID to 0.

void increaseGen()

Increases the generation counter by one.

bool exists() const

Getter for the existence boolean.

Return

the existence boolean.

bool isTip() const

Getter for the tip boolean.

Return

the tip boolean.

unsigned long getParent() const

Getter for the parent location.

Return

the parent reference.

unsigned long getXpos() const

Getter for the x position.

Return

the x position.

unsigned long getYpos() const

Getter for the y position.

Return

the y position.

long getXwrap() const

Getter for the number of times the lineage is wrapped in the x dimension.

Return

the number of times the lineage is wrapped in the x dimension.

long getYwrap() const

Getter for the number of times the lineage is wrapped in the y dimension.

Return

the number of times the lineage is wrapped in the y dimension.

bool hasSpeciated() const

Getter for the speciation boolean.

Return

the speciation boolean.

unsigned long getSpeciesID() const

Getter for the species ID.

Return

the species ID.

long double getSpecRate() const

Getter for the randomly generated speciation probability.

Return

the speciation probability.

unsigned long getGenerationRate() const

Getter for the number of generations the lineage has existed.

Return

the number of generations of existence.

long double getGeneration() const

Getter for the generation the lineage was created.

Return

the generation counter the lineage was created.

void speciate()

Sets the speciation boolean to true.

TreeNode &operator=(const TreeNode &t)

Overloading the equality operator for TreeNodes

Parameters

• t: the input TreeNode

Friends

ostream &operator<<(ostream &os, const TreeNode &t)

Overloading the << operator for outputting a Treenode object to an output stream.

Return

the output stream.

Parameters

• os: the output stream.
• t: a Treenode object to output.

istream &operator>>(istream &is, TreeNode &t)

Overloading the >> operator for inputting the Treenode object from an input stream.

Return

the input stream.

Parameters

• is: the input stream.
• t: a Treenode object to input to.

Class ProtractedTree

• Defined in File ProtractedSpatialTree.h

Class Documentation

class ProtractedTree

Contains the protracted tree class, for running simulations with procated speciation.

Template Class PyCommunityTemplate

• Defined in File CCommunity.h

Inheritance Relationships

Base Type

• public PyTemplate< T > (Template Class PyTemplate)

Class Documentation

template<class T>
class PyCommunityTemplate : public PyTemplate<T>

Template for CCommunity and CMetacommunity objects for exporting to Python.

Template Parameters

• T: the type of the Community

Public Members

shared_ptr<SpecSimParameters> specSimParameters

PyObject_HEAD PyObject* PyTemplate::logger = nullptr

PyObject *log_function = nullptr

std::unique_ptr<T> base_object = nullptr

Class PyLMC

• Defined in File CLandscapeMetricsCalculator.h

Inheritance Relationships

Base Type

• public PyTemplate< LandscapeMetricsCalculator > (Template Class PyTemplate)

Class Documentation

class PyLMC : public PyTemplate<LandscapeMetricsCalculator>

Public Members

unique_ptr<LandscapeMetricsCalculator> landscapeMetricsCalculator

bool has_imported_map

PyObject_HEAD PyObject* PyTemplate::logger

PyObject *log_function

std::unique_ptr<LandscapeMetricsCalculator> base_object

Class PySimulateDispersal

• Defined in File CSimulateDispersal.h

Inheritance Relationships

Base Type

• public PyTemplate< SimulateDispersal > (Template Class PyTemplate)

Class Documentation

class PySimulateDispersal : public PyTemplate<SimulateDispersal>

Public Functions

PySimulateDispersal()

void checkCompleted()

Checks that the output database has been set, and the maps have been imported. Raises an error if either case is no true.

void setDispersalParameters()

Sets the dispersal parameters in the base object.

Public Members

shared_ptr<SimParameters> dispersalParameters

bool has_imported_maps

unique_ptr<std::string> output_database

bool printing

bool needs_update

PyObject_HEAD PyObject* PyTemplate::logger

PyObject *log_function

std::unique_ptr<SimulateDispersal> base_object

Template Class PyTemplate

• Defined in File PyTemplates.h

Inheritance Relationships

Derived Type

• public PyCommunityTemplate< T > (Template Class PyCommunityTemplate)

Class Documentation

template<class T>
class PyTemplate

Subclassed by PyCommunityTemplate< T >

Public Functions

virtual ~PyTemplate()

Public Members

PyObject_HEAD PyObject* PyTemplate::logger = nullptr

PyObject *log_function = nullptr

std::unique_ptr<T> base_object = nullptr

Class RNGController

• Defined in File RNGController.h

Inheritance Relationships

Base Type

• public random_numbers::Xoroshiro256plus (Class Xoroshiro256plus)

Class Documentation

class RNGController : public virtual random_numbers::Xoroshiro256plus

Contains the functions for random number generation, based on the Xoroshiro256+ algorithm.

Public Functions

RNGController()

Standard constructor.

void setSeed(uint64_t seed)

Sets the seed to the given input. Is only seeded if the seed hasn’t already been provided.

Parameters

• seed: the input seed.

void wipeSeed()

Clears the seed, if it has already been set. Keeps other simulation parameters, such as sigma and tau.

unsigned long i0(unsigned long max)

Generates a random number uniformly from 0 to the maximum value provided.

Return

an integer of the produced random number.

Parameters

• max: the maximum number.

double norm()

Generates a normally distributed number Uses the standard normal distribution using the Ziggurat method.

Return

the random number from a normal distribution.

double rayleigh()

Returns a random distance from a 2 dimensional normal distribution, also called the rayleigh distribution.

Return

dispersal distance of a rayleigh distribution

double rayleighMinDist(const double &dist)

Generates a random distance from a rayleigh distribution, given that the distance is more than some minimum.

Return

a random distance greater than the minimum provided

Parameters

• dist: the minimum distance to generate

double rayleighCDF(const double &dist)

Gets the cumulative probability of a distance from the rayleigh distribution.

Return

the probability of producing the given distance

Parameters

• dist: the distance to obtain the probability of

void setDispersalParams(const double sigmain, const double tauin)

Sets the dispersal parameters, avoiding requirement to provide these numbers each function call. This is only relevant for fat-tailed dispersal calls.

Parameters

• sigmain: the fatness of the fat-tailed dispersal kernel.
• tauin: the width of the fat-tailed dispersal kernel.

double fattail(double z)

Call from the fat-tailed dispersal kernel with the provided sigma.

Return

a random number drawn from the fat-tailed dispersal kernel.

Parameters

• z: the desired sigma.

double fattailCDF(const double &distance)

Gets the cumulative probability density of travelling the distance.

Return

the probability of dispersing less than or equal to distance

Parameters

• distance: the distance to obtain the cumulative probability for

double fattailMinDistance(const double &min_distance)

Gets a fat-tailed random distance greater than some minimum.

Return

a fat-tailed distance greater than the minimum

Parameters

• min_distance: the minimum distance to return

double fattail()

Call from fat-tailed dispersal kernel. This function requires setDispersalParams() has already been called.

Return

a random number drawn from the fat-tailed dispersal kernel.

double fattail_old()

Old version of the function call reparameterised for different nu and sigma.

Return

a random number drawn from the fat-tailed dispersal kernel.

double direction()

Generates a direction in radians.

Return

the direction in radians

bool event(double event_probability)

For a given event probability, returns the probability that the event has occured.

Return

whether or not the event has occured.

Parameters

• event_probability: the event probability.

double normUniform()

Normal distribution, with percentage chance to choose a uniform distribution instead.

Note

This function will not produce the same output as norm() for the same parameters, even with a zero chance of picking from the uniform distribution (due to random number draws).

Return

normally (or uniformly) distributed number

double normUniformMinDistance(const double &min_distance)

Generates a random distance from a norm-uniform distribution, given that the distance is more than some minimum.

Return

a random distance greater than the minimum provided

Parameters

• dist: the minimum distance to generate

double uniform()

Draws a random number from a uniform distribution between 0 and cutoff.

Return

a random number in (0, cutoff)

double uniformMinDistance(const double &min_distance)

Generates a random distance from a uniform distribution, given that the distance is more than some minimum.

Return

a random distance greater than the minimum provided

Parameters

• dist: the minimum distance to generate

double uniformUniform()

Two uniform distributions, the first between 0 and 0.1*cutoff, and the second between 0.9*cutoff and cutoff. Selects from both distributions equally.

Note

The mean for this function should be identical to a uniform distribution between 0 and cutoff.

Return

uniformly distributed number

double uniformUniformMinDistance(const double &min_distance)

Generates a random distance from a uniform-uniform distribution, given that the distance is more than some minimum.

Return

a random distance greater than the minimum provided

Parameters

• dist: the minimum distance to generate

void setDispersalMethod(const string &dispersal_method, const double &m_probin, const double &cutoffin)

Sets the dispersal method by creating the link between dispersalFunction() and the correct dispersal character.

Parameters

• dispersal_method: string containing the dispersal type. Can be one of [normal, fat-tail, norm-uniform]
• m_probin: the probability of drawing from the uniform distribution. Only relevant for uniform dispersals.
• cutoffin: the maximum value to be drawn from the uniform dispersal. Only relevant for uniform dispersals.

double dispersal()

Runs the dispersal with the allocated dispersal function.

Note

This function will never return a value larger than the size of LONG_MAX to avoid issues of converting doubles to integers. For dispersal distance within coalescence simulations, this is seemed a reasonable assumption, but may cause issues if code is re-used in later projects.

Return

distance the dispersal distance

double dispersalMinDistance(const double &min_distance)

Get a dispersal distance with some minimum.

This function will never return doubles larger than LONG_MAX to avoid integer overflows.

Return

the random dispersal distance greater than or equal to the minimum

Parameters

• min_distance: the minimum distance to disperse

unsigned long randomLogarithmic(long double alpha)

Sample from a logarithmic distribution.

Uses the LK sampling method for generating random numbers from a logarithmic distribution, as described by Kemp (1981).

Return

the randomly generated logarithmic number

Parameters

• alpha: alpha parameter for the logarithmic distribution

double randomExponential(double lambda)

uint64_t next()

Generates the next random integer.

Return

a random integer from 0 to max of 2^64

double d01()

Generates a random number in the range [0, 1)

Return

a random double

void jump()

Jumps the generator forwards by the equivalent of 2^128 calls of next() - useful for parallel computations where different random number sequences are required.

Public Static Functions

template<typename T>
static const T exponentialDistribution(const T lambda, const T r)

Protected Attributes

std::array<uint64_t, 4> shuffle_table

Friends

ostream &operator<<(ostream &os, const RNGController &r)

Outputs the NRrand object to the output stream. Used for saving the object to file.

Return

the output stream.

Parameters

• os: the output stream.
• r: the NRrand object to output.

istream &operator>>(istream &is, RNGController &r)

Inputs the NRrand object from the input stream. Used for reading the NRrand object from a file.

Return

the input stream.

Parameters

• is: the input stream.
• r: the NRrand object to input to.

Class SplitMix64

• Defined in File Xoroshiro256plus.h

Class Documentation

class SplitMix64

A random number generator using the splitmix64 algorithm - this is provided for generating the shuffle table within the main Xoroshiro256+ algorithm.

Public Functions

SplitMix64(uint64_t seed)

Default constructor, taking the RNG seed.

Parameters

• seed: the seed to use

uint64_t next()

Generates the next random integer.

Return

a random integer in the range of 0 to 2^64

void shuffle()

Shuffle the random number 8 times.

double d01()

Gets a random double in the range [0, 1)

Return

a random double

Class Xoroshiro256plus

• Defined in File Xoroshiro256plus.h

Inheritance Relationships

Derived Type

• public random_numbers::RNGController (Class RNGController)

Class Documentation

class Xoroshiro256plus

A random number generator using the xoroshiro.

Note

From the authors of the algorthim: This is xoshiro256+ 1.0, our best and fastest generator for floating-point numbers. We suggest to use its upper bits for floating-point generation, as it is slightly faster than xoshiro256**. It passes all tests we are aware of except for the lowest three bits, which might fail linearity tests (and just those), so if low linear complexity is not considered an issue (as it is usually the case) it can be used to generate 64-bit outputs, too. We suggest to use a sign test to extract a random Boolean value, and right shifts to extract subsets of bits. The state must be seeded so that it is not everywhere zero. If you have a 64-bit seed, we suggest to seed a splitmix64 generator and use its output to fill the shuffle table.

Subclassed by random_numbers::RNGController

Public Functions

Xoroshiro256plus()

virtual ~Xoroshiro256plus()

Xoroshiro256plus(uint64_t seed)

Explicit constructor which sets the rng seed.

Parameters

• seed: the random seed

virtual void setSeed(uint64_t seed)

uint64_t next()

Generates the next random integer.

Return

a random integer from 0 to max of 2^64

double d01()

Generates a random number in the range [0, 1)

Return

a random double

void jump()

Jumps the generator forwards by the equivalent of 2^128 calls of next() - useful for parallel computations where different random number sequences are required.

Protected Attributes

std::array<uint64_t, 4> shuffle_table

Friends

std::ostream &operator<<(std::ostream &os, const Xoroshiro256plus &x)

Writes the random number generator to an output stream.

Return

Parameters

• os: the output stream to write to
• x: the random number generator to save

std::istream &operator>>(std::istream &is, Xoroshiro256plus &x)

Inputs the NRrand object from the input stream. Used for reading the NRrand object from a file.

Return

the input stream.

Parameters

• is: the input stream.
• r: the NRrand object to input to.

Enum CellEventType

• Defined in File GillespieCalculator.h

Enum Documentation

enum necsim::CellEventType

Values:

undefined

dispersal_event

coalescence_event

speciation_event

Enum EventType

• Defined in File GillespieCalculator.h

Enum Documentation

enum necsim::EventType

Container for the different event types that can occur during the Gillespie Algorithm.

Values:

undefined

cell_event

map_event

sample_event

Template Function addGillespie

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *addGillespie(PyTemplate<T> *self, PyObject *args)

Template Function addProtractedParameters

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *addProtractedParameters(PyCommunityTemplate<T> *self, PyObject *args)

Adds a set of protracted parameters to the speciation parameters.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object
• args: the arguments to pass

Template Function addTime

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *addTime(PyCommunityTemplate<T> *self, PyObject *args)

Adds a time to the speciation parameters.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object
• args: the arguments to pass

Template Function apply

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *apply(PyCommunityTemplate<T> *self)

Applies the speciation parameters to the coalescence tree to generate the community.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object

Template Function applySpeciationRates

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *applySpeciationRates(PyTemplate<T> *self, PyObject *args)

Applies the provided speciation rates to the simulation to generate multiple communities.

Template Parameters

• T: the simulation type

Parameters

• self: the Python self object
• args: arguments to parse

Function calculateCLUMPY

• Defined in File CLandscapeMetricsCalculator.h

Function Documentation

static PyObject *calculateCLUMPY(PyLMC *self)

Calculates the CLUMPY metric for the imported map file.

Return

PyFloatType object containing the mean distance to the nearest neighbour

Parameters

• self: the Python self pointer

Function calculateMNN

• Defined in File CLandscapeMetricsCalculator.h

Function Documentation

static PyObject *calculateMNN(PyLMC *self)

Calculates the mean distance to the nearest neighbour for each cell on the imported map file.

Return

PyFloatType object containing the mean distance to the nearest neighbour

Parameters

• self: the Python self pointer

Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, const T&)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T>
void eastl::adjust_heap(RandomAccessIterator first, Distance topPosition, Distance heapSize, Distance position, const T &value)

adjust_heap

Given a position that has just been vacated, this function moves new values into that vacated position appropriately. The value argument is an entry which will be inserted into the heap after we move nodes into the positions that were vacated.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, T&&)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T>
void eastl::adjust_heap(RandomAccessIterator first, Distance topPosition, Distance heapSize, Distance position, T &&value)

adjust_heap

Given a position that has just been vacated, this function moves new values into that vacated position appropriately. The value argument is an entry which will be inserted into the heap after we move nodes into the positions that were vacated.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, const T&, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename Compare>
void eastl::adjust_heap(RandomAccessIterator first, Distance topPosition, Distance heapSize, Distance position, const T &value, Compare compare)

adjust_heap

The Compare function must work equivalently to the compare function used to make and maintain the heap.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::adjust_heap(RandomAccessIterator, Distance, Distance, Distance, T&&, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename Compare>
void eastl::adjust_heap(RandomAccessIterator first, Distance topPosition, Distance heapSize, Distance position, T &&value, Compare compare)

adjust_heap

The Compare function must work equivalently to the compare function used to make and maintain the heap.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::adjust_heap_impl(RandomAccessIterator, Distance, Distance, Distance, T)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename ValueType>
void eastl::adjust_heap_impl(RandomAccessIterator first, Distance topPosition, Distance heapSize, Distance position, T value)

Template Function eastl::adjust_heap_impl(RandomAccessIterator, Distance, Distance, Distance, T, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename Compare, typename ValueType>
void eastl::adjust_heap_impl(RandomAccessIterator first, Distance topPosition, Distance heapSize, Distance position, T value, Compare compare)

Template Function eastl::change_heap(RandomAccessIterator, Distance, Distance)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance>
void eastl::change_heap(RandomAccessIterator first, Distance heapSize, Distance position)

change_heap

Given a value in the heap that has changed in priority, this function adjusts the heap appropriately. The heap size remains unchanged after this operation.

Template Function eastl::change_heap(RandomAccessIterator, Distance, Distance, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename Compare>
void eastl::change_heap(RandomAccessIterator first, Distance heapSize, Distance position, Compare compare)

change_heap

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Template Function eastl::is_heap(RandomAccessIterator, RandomAccessIterator)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator>
bool eastl::is_heap(RandomAccessIterator first, RandomAccessIterator last)

is_heap

This is a useful debugging algorithm for verifying that a random

access container is in heap format.

Template Function eastl::is_heap(RandomAccessIterator, RandomAccessIterator, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Compare>
bool eastl::is_heap(RandomAccessIterator first, RandomAccessIterator last, Compare compare)

is_heap

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Template Function eastl::is_heap_until(RandomAccessIterator, RandomAccessIterator)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator>
RandomAccessIterator eastl::is_heap_until(RandomAccessIterator first, RandomAccessIterator last)

is_heap_until

Template Function eastl::is_heap_until(RandomAccessIterator, RandomAccessIterator, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Compare>
RandomAccessIterator eastl::is_heap_until(RandomAccessIterator first, RandomAccessIterator last, Compare compare)

is_heap_until

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Template Function eastl::make_heap(RandomAccessIterator, RandomAccessIterator)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator>
void eastl::make_heap(RandomAccessIterator first, RandomAccessIterator last)

make_heap

Given an array, this function converts it into heap format. The complexity is O(n), where n is count of the range. The input range is not required to be in any order.

Template Function eastl::make_heap(RandomAccessIterator, RandomAccessIterator, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Compare>
void eastl::make_heap(RandomAccessIterator first, RandomAccessIterator last, Compare compare)

Template Function eastl::pop_heap(RandomAccessIterator, RandomAccessIterator)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator>
void eastl::pop_heap(RandomAccessIterator first, RandomAccessIterator last)

pop_heap

Removes the first item from the heap (which is an array), and adjusts the heap so that the highest priority item becomes the new first item.

Example usage: vector<int> heap;

heap.push_back(2); heap.push_back(3); heap.push_back(1); <use heap[0], which is the highest priority item in the heap> pop_heap(heap.begin(), heap.end()); // Moves heap[0] to the back of the heap and adjusts the heap. heap.pop_back(); // Remove value that was just at the top of the heap

Template Function eastl::pop_heap(RandomAccessIterator, RandomAccessIterator, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Compare>
void eastl::pop_heap(RandomAccessIterator first, RandomAccessIterator last, Compare compare)

pop_heap

This version is useful for cases where your object comparison is unusual or where you want to have the heap store pointers to objects instead of storing the objects themselves (often in order to improve cache coherency while doing sorting).

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, const T&)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T>
void eastl::promote_heap(RandomAccessIterator first, Distance topPosition, Distance position, const T &value)

promote_heap

Moves a value in the heap from a given position upward until it is sorted correctly. It’s kind of like bubble-sort, except that instead of moving linearly from the back of a list to the front, it moves from the bottom of the tree up the branches towards the top. But otherwise is just like bubble-sort.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, T&&)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T>
void eastl::promote_heap(RandomAccessIterator first, Distance topPosition, Distance position, T &&value)

promote_heap

Moves a value in the heap from a given position upward until it is sorted correctly. It’s kind of like bubble-sort, except that instead of moving linearly from the back of a list to the front, it moves from the bottom of the tree up the branches towards the top. But otherwise is just like bubble-sort.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, const T&, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename Compare>
void eastl::promote_heap(RandomAccessIterator first, Distance topPosition, Distance position, const T &value, Compare compare)

promote_heap

Takes a Compare(a, b) function (or function object) which returns true if a < b. For example, you could use the standard ‘less’ comparison object.

The Compare function must work equivalently to the compare function used to make and maintain the heap.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::promote_heap(RandomAccessIterator, Distance, Distance, T&&, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename Compare>
void eastl::promote_heap(RandomAccessIterator first, Distance topPosition, Distance position, T &&value, Compare compare)

promote_heap

Takes a Compare(a, b) function (or function object) which returns true if a < b. For example, you could use the standard ‘less’ comparison object.

The Compare function must work equivalently to the compare function used to make and maintain the heap.

This function requires that the value argument refer to a value that is currently not within the heap.

Template Function eastl::promote_heap_impl(RandomAccessIterator, Distance, Distance, T)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename ValueType>
void eastl::promote_heap_impl(RandomAccessIterator first, Distance topPosition, Distance position, T value)

Template Function eastl::promote_heap_impl(RandomAccessIterator, Distance, Distance, T, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename T, typename Compare, typename ValueType>
void eastl::promote_heap_impl(RandomAccessIterator first, Distance topPosition, Distance position, T value, Compare compare)

Template Function eastl::push_heap(RandomAccessIterator, RandomAccessIterator)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator>
void eastl::push_heap(RandomAccessIterator first, RandomAccessIterator last)

push_heap

Adds an item to a heap (which is an array). The item necessarily comes from the back of the heap (array). Thus, the insertion of a new item in a heap is a two step process: push_back and push_heap.

Example usage: vector<int> heap;

heap.push_back(3); push_heap(heap.begin(), heap.end()); // Places ‘3’ appropriately.

Template Function eastl::push_heap(RandomAccessIterator, RandomAccessIterator, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Compare>
void eastl::push_heap(RandomAccessIterator first, RandomAccessIterator last, Compare compare)

push_heap

This version is useful for cases where your object comparison is unusual or where you want to have the heap store pointers to objects instead of storing the objects themselves (often in order to improve cache coherency while doing sorting).

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Template Function eastl::remove_heap(RandomAccessIterator, Distance, Distance)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance>
void eastl::remove_heap(RandomAccessIterator first, Distance heapSize, Distance position)

remove_heap

Removes an arbitrary entry from the heap and adjusts the heap appropriately. This function is unlike pop_heap in that pop_heap moves the top item to the back of the heap, whereas remove_heap moves an arbitrary item to the back of the heap.

Note: Since this function moves the element to the back of the heap and doesn’t actually remove it from the given container, the user must call the container erase function if the user wants to erase the element from the container.

Template Function eastl::remove_heap(RandomAccessIterator, Distance, Distance, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Distance, typename Compare>
void eastl::remove_heap(RandomAccessIterator first, Distance heapSize, Distance position, Compare compare)

remove_heap

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Note: Since this function moves the element to the back of the heap and doesn’t actually remove it from the given container, the user must call the container erase function if the user wants to erase the element from the container.

Template Function eastl::sort_heap(RandomAccessIterator, RandomAccessIterator)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator>
void eastl::sort_heap(RandomAccessIterator first, RandomAccessIterator last)

sort_heap

After the application if this algorithm, the range it was applied to is no longer a heap, though it will be a reverse heap (smallest first). The item with the lowest priority will be first, and the highest last. This is not a stable sort because the relative order of equivalent elements is not necessarily preserved. The range referenced must be valid; all pointers must be dereferenceable and within the sequence the last position is reachable from the first by incrementation. The complexity is at most O(n * log(n)), where n is count of the range.

Template Function eastl::sort_heap(RandomAccessIterator, RandomAccessIterator, Compare)

• Defined in File heap.h

Function Documentation

template<typename RandomAccessIterator, typename Compare>
void eastl::sort_heap(RandomAccessIterator first, RandomAccessIterator last, Compare compare)

sort_heap

The Compare function must work equivalently to the compare function used to make and maintain the heap.

Template Function genCommunityMethods

• Defined in File CCommunity.h

Function Documentation

template<class T>
PyMethodDef *genCommunityMethods()

Methods associated with the Python CCommunity object.

Template Parameters

• T: the type of the Community

Template Function genCommunityType(char *, char *)

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyTypeObject genCommunityType(char *tp_name, char *tp_doc)

Generates the community type using the object name and description.

Return

Template Parameters

• T: the C++ class to generate a Python object for

Parameters

• tp_name: the Python class name
• tp_doc: the Python documentation

Template Function genCommunityType(string, string)

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyTypeObject genCommunityType(string tp_name, string tp_doc)

Generates the community type using the object name and description.

Return

Template Parameters

• T: the C++ class to generate a Python object for

Parameters

• tp_name: the Python class name
• tp_doc: the Python documentation

Function genLMCType

• Defined in File CLandscapeMetricsCalculator.h

Function Documentation

PyTypeObject genLMCType()

Template Function genPySimulationMethods

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyMethodDef *genPySimulationMethods()

Function genSimulateDispersalType

• Defined in File CSimulateDispersal.h

Function Documentation

static PyTypeObject genSimulateDispersalType()

Template Function genSimulationType

• Defined in File CSimulation.h

Function Documentation

template<class T>
PyTypeObject genSimulationType(char *tp_name, char *tp_doc)

Template Function importConfig

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *importConfig(PyTemplate<T> *self, PyObject *args)

Imports the config parameters from a file. The file should be of the format generated by ConfigFileParser in Python.

Template Parameters

• T: the simulation type

Parameters

• self: the Python self object
• args: arguments to parse

Template Function importConfigFromString

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *importConfigFromString(PyTemplate<T> *self, PyObject *args)

Imports the config parameters from a string. The string should be equivalent to a file written by ConfigFileParser in Python.

Template Parameters

• T: the simulation type

Parameters

• self: the Python self object
• args: arguments to parse

Function importPyListsToVectorCell(PyObject *, PyObject *, vector<Cell>&, const string&)

• Defined in File PyImports.cpp

Function Documentation

bool importPyListsToVectorCell(PyObject *x_list_input, PyObject *y_list_input, vector<Cell> &output, const string &err_msg)

Function importPyListsToVectorCell(PyObject *, PyObject *, vector<Cell>&, const string&)

• Defined in File PyImports.h

Function Documentation

bool importPyListsToVectorCell(PyObject *x_list_input, PyObject *y_list_input, vector<Cell> &output, const string &err_msg)

Function importPyListToVectorDouble(PyObject *, vector<double>&, const string&)

• Defined in File PyImports.cpp

Function Documentation

bool importPyListToVectorDouble(PyObject *list_input, vector<double> &output, const string &err_msg)

Imports the provided input list to the output vector. Sets the Python error message and returns false if one of the list elements is not a float type.

Return

true if no error is thrown, false otherwise

Parameters

• list_input: a Python list object to iterate over
• output: the output vector of doubles to push to
• err_msg: error message to through if an element is not of float type

Function importPyListToVectorDouble(PyObject *, vector<double>&, const string&)

• Defined in File PyImports.h

Function Documentation

bool importPyListToVectorDouble(PyObject *list_input, vector<double> &output, const string &err_msg)

Imports the provided input list to the output vector. Sets the Python error message and returns false if one of the list elements is not a float type.

Return

true if no error is thrown, false otherwise

Parameters

• list_input: a Python list object to iterate over
• output: the output vector of doubles to push to
• err_msg: error message to through if an element is not of float type

Function importPyListToVectorString(PyObject *, vector<string>&, const string&)

• Defined in File PyImports.cpp

Function Documentation

bool importPyListToVectorString(PyObject *list_input, vector<string> &output, const string &err_msg)

Imports the provided input list to the output vector. Sets the Python error message and returns false if one of the list elements is not a string type.

Return

true if no error is thrown, false otherwise

Parameters

• list_input: a Python list object to iterate over
• output: the output vector of strings to push to
• err_msg: error message to through if an element is not of float type

Function importPyListToVectorString(PyObject *, vector<string>&, const string&)

• Defined in File PyImports.h

Function Documentation

bool importPyListToVectorString(PyObject *list_input, vector<string> &output, const string &err_msg)

Imports the provided input list to the output vector. Sets the Python error message and returns false if one of the list elements is not a string type.

Return

true if no error is thrown, false otherwise

Parameters

• list_input: a Python list object to iterate over
• output: the output vector of strings to push to
• err_msg: error message to through if an element is not of float type

Function importPyListToVectorULong(PyObject *, vector<unsigned long>&, const string&)

• Defined in File PyImports.cpp

Function Documentation

bool importPyListToVectorULong(PyObject *list_input, vector<unsigned long> &output, const string &err_msg)

Imports the provided input list to the output vector. Sets the Python error message and returns false if one of the list elements is not of int type.

Return

true if no error is thrown, false otherwise

Parameters

• list_input: a Python list object to iterate over
• output: the output vector of int to push to
• err_msg: error message to through if an element is not of float type

Function importPyListToVectorULong(PyObject *, vector<unsigned long>&, const string&)

• Defined in File PyImports.h

Function Documentation

bool importPyListToVectorULong(PyObject *list_input, vector<unsigned long> &output, const string &err_msg)

Imports the provided input list to the output vector. Sets the Python error message and returns false if one of the list elements is not of int type.

Return

true if no error is thrown, false otherwise

Parameters

• list_input: a Python list object to iterate over
• output: the output vector of int to push to
• err_msg: error message to through if an element is not of float type

Template Function initialise_logger

• Defined in File PyTemplates.h

Function Documentation

template<class T>
void initialise_logger(PyTemplate<T> *self)

Function initlibnecsim(void)

• Defined in File necsim.cpp

Function Documentation

PyMODINIT_FUNC initlibnecsim(void)

Function initlibnecsim(void)

• Defined in File necsim.h

Function Documentation

PyMODINIT_FUNC initlibnecsim(void)

Function necsim::archimedesSpiralX

• Defined in File Landscape.cpp

Function Documentation

unsigned long necsim::archimedesSpiralX(const double &centre_x, const double &centre_y, const double &radius, const double &theta)

Gets the x coordinate of the archimedes spiral.

Parameters

• centre_x: the x coordinate of the spiral centre
• centre_y: the y coordinate of the spiral centre
• radius: the radius of the spiral
• theta: the theta of rotation of the spiral

Function necsim::archimedesSpiralY

• Defined in File Landscape.cpp

Function Documentation

unsigned long necsim::archimedesSpiralY(const double &centre_x, const double &centre_y, const double &radius, const double &theta)

Gets the y coordinate of the archimedes spiral.

Parameters

• centre_x: the x coordinate of the spiral centre
• centre_y: the y coordinate of the spiral centre
• radius: the radius of the spiral
• theta: the theta of rotation of the spiral

Function necsim::calculateDistance

• Defined in File Landscape.cpp

Function Documentation

double necsim::calculateDistance(const double &start_x, const double &start_y, const double &end_x, const double &end_y)

Calculates the distance between two points.

Return

the distance between the points

Parameters

• start_x: the start x coordinate
• start_y: the start y coordinate
• end_x: the end x coordinate
• end_y: the end y coodinate

Function necsim::cantorPairing

• Defined in File file_system.cpp

Function Documentation

unsigned long necsim::cantorPairing(const unsigned long &x1, const unsigned long &x2)

Generates a unique ID for the pair of provided parameters.

Maps ZxZ -> N, so only relevant for positive numbers. For any A and B, generates C such that no D and E produce C unless D=A and B=E.

Return

a unique reference for the two provided integers

Parameters

• x1: the first integer reference
• x2: the second integer reference

Function necsim::checkSpeciation

• Defined in File Community.cpp

Function Documentation

bool necsim::checkSpeciation(const long double &random_number, const long double &speciation_rate, const unsigned long &no_generations)

Checks whether speciation has occured for the provided parameters. Provided here for ease of use when bug-fixing.

Return

bool the speciation state of the lineage

Parameters

• random_number: the random number associated with a lineage
• speciation_rate: the global speciation rate
• number_of_generations: the number of generations the lineage has existed

Function necsim::cplNecsimCustomErrorHandler

• Defined in File cpl_custom_handler.cpp

Function Documentation

void necsim::cplNecsimCustomErrorHandler(CPLErr eErrClass, int err_no, const char *msg)

Contains a custom CPLErrorHandler for reporting errors from GDAL imports.

Parameters

• eErrClass: the error class (CE_None, CE_Debug, CE_Warning, CE_Failure or CE_Fatal)
• err_no: the error number to report
• msg: the message to report

Function necsim::createParent

• Defined in File file_system.cpp

Function Documentation

void necsim::createParent(string file)

Checks that parent folder to the supplied file exists, and if it doesn’t creates it.

Parameters

• file: the file path to check for

Function necsim::distanceBetweenCells

• Defined in File Cell.cpp

Function Documentation

double necsim::distanceBetweenCells(const Cell &c1, const Cell &c2)

Calculates the distance between two cells.

Return

the distance between the two points

Parameters

• c1: Cell containing one point
• c2: Cell containing second point

Function necsim::doesExist

• Defined in File file_system.cpp

Function Documentation

bool necsim::doesExist(string testfile)

Checks the existance of a file on the hard drive.

Return

should always return true, or raise an error (if the file doesn’t exist)

Parameters

• testfile: the file to examine

Function necsim::doesExistNull

• Defined in File file_system.cpp

Function Documentation

bool necsim::doesExistNull(string testfile)

Checks for the existance of a file, but returns true if the file name is ‘null’. Note: this function just calls doesExist().

Return

if true, file exists (or is null).

Parameters

• testfile: the file to examine

Function necsim::doubleCompare(double, double, double)

• Defined in File double_comparison.cpp

Function Documentation

bool necsim::doubleCompare(double d1, double d2, double epsilon)

Compares two doubles and returns a boolean of whether they are equal, within the epsilon deviation. This is useful for floating point errors in saving and reading doubles from file.

Return

true if the doubles are within epsilon of each other

Parameters

• d1: the first double.
• d2: the second double.
• epsilon: the deviation within which the values are assumed to be equal.

Function necsim::doubleCompare(long double, long double, long double)

• Defined in File double_comparison.cpp

Function Documentation

bool necsim::doubleCompare(long double d1, long double d2, long double epsilon)

Compares two doubles and returns a boolean of whether they are equal, within the epsilon deviation. This is useful for floating point errors in saving and reading doubles from file. Overloaded version for long doubles.

Return

true if the doubles are within epsilon of each other

Parameters

• d1: the first double.
• d2: the second double.
• epsilon: the deviation within which the values are assumed to be equal.

Function necsim::doubleCompare(long double, long double, double)

• Defined in File double_comparison.cpp

Function Documentation

bool necsim::doubleCompare(long double d1, long double d2, double epsilon)

Compares two doubles and returns a boolean of whether they are equal, within the epsilon deviation. This is useful for floating point errors in saving and reading doubles from file. Overloaded version for long doubles and double epsilon.

Return

true if the doubles are within epsilon of each other

Parameters

• d1: the first double.
• d2: the second double.
• epsilon: the deviation within which the values are assumed to be equal.

Function necsim::elegantPairing

• Defined in File file_system.cpp

Function Documentation

unsigned long necsim::elegantPairing(const unsigned long &x1, const unsigned long &x2)

A more elegant version of cantor pairing, which allows for storing of a greater number of digits without experiencing integer overflow issues.

Note

For scenarios when performance is critical, and the integers are known to be small, cantorPairing provides equivalent functionality.

Return

Parameters

• x1: the first integer
• x2:

Template Function necsim::findMinCols

• Defined in File Matrix.h

Function Documentation

template<typename T>
const unsigned long necsim::findMinCols(const Matrix<T> &matrix1, const Matrix<T> &matrix2)

Find the minimum columns of the two objects.

Return

the minimum number of columns between the two matrices

Template Parameters

• T: The type of the Matrix class

Parameters

• matrix1: the first matrix
• matrix2: the second matrix

Template Function necsim::findMinRows

• Defined in File Matrix.h

Function Documentation

template<typename T>
const unsigned long necsim::findMinRows(const Matrix<T> &matrix1, const Matrix<T> &matrix2)

Find the minimum rows of the two objects.

Return

the minimum number of rows between the two matrices

Template Parameters

• T: The type of the Matrix class

Parameters

• matrix1: the first matrix
• matrix2: the second matrix

Function necsim::getConfigFileFromCmdArgs

• Defined in File SimulationTemplates.h

Function Documentation

const string &necsim::getConfigFileFromCmdArgs(const vector<string> &com_args)

Gets the [2] element from the vector (which should contain the config file from command-line arguments.

Return

the string at the [2] position containing the path to the config file

Parameters

• com_args: the vector of command-line arguments

Function necsim::getCsvLineAndSplitIntoTokens

• Defined in File file_system.cpp

Function Documentation

vector<string> necsim::getCsvLineAndSplitIntoTokens(istream &str)

Gets the next line from a csv filestream and splits the row into a vector of strings, where each string is the value from the csv file, delimited by a comma (i.e. each column of the row).

Return

a vector where each element corresponds to the respective row from the csv.

Parameters

• str: the input stream from the csv file.

Function necsim::getDefaultLogFile

• Defined in File LogFile.cpp

Function Documentation

string necsim::getDefaultLogFile()

Gets the default log file path. Stored at log/DDMMYYYY_HHMMSS.log where DDMMYYYY_HHMMSS are replaced by the current date and time.

Return

location of the default logging position.

Function necsim::getGlobalLogger

• Defined in File PyLogging.cpp

Function Documentation

PyLogger *necsim::getGlobalLogger(PyObject *logger, PyObject *log_function)

Generates the global logger object and adds the logger and log functions to the Python logger.

Each call to getGlobalLogger should be matched by a call to removeGlobalLogger

Return

the global logger object as a pointer.

Parameters

• logger: the Python logger object to use
• log_function: the Python logging function to use

Function necsim::getTime

• Defined in File LogFile.cpp

Function Documentation

string necsim::getTime()

Gets the current system time in string form.

Return

the system time in string form

Function necsim::getUniqueFileName

• Defined in File LogFile.cpp

Function Documentation

void necsim::getUniqueFileName(string &basic_string)

Modifies the file name so that it doesn’t point to an existing file.

Parameters

• basic_string: the file name to modify

Function necsim::importArgs

• Defined in File ConfigParser.cpp

Function Documentation

void necsim::importArgs(const unsigned int &argc, char *argv[], vector<string> &comargs)

Import the command line arguments in to the vector for future processing. Arguments will be placed in the vector comargs.

Parameters

• argc: the number of arguments.
• argv: a point to the array of arguments in raw character form.
• comargs: a vector of the command-line arguments to be filled.

Function necsim::importToMapAndRound

• Defined in File Landscape.cpp

Function Documentation

uint32_t necsim::importToMapAndRound(string map_file, Map<uint32_t> &map_in, unsigned long map_x, unsigned long map_y, double scalar)

Imports the provided given file to the provided matrix, given the x and y dimensions. The integer value in the final matrix is multiplied by the scalar to generate the final matrix. Note that this doubles the memory usage.

Return

the maximum value from the imported matrix

Parameters

• map_file: the path to the map file to import
• map_in: the matrix to change the values of
• map_x: the x dimension of the matrix
• map_y: the y dimension of the matrix
• scalar: the scalar to multiply all values in the final matrix by (before rounding to integer)

Function necsim::inverseSpeciation

• Defined in File Community.cpp

Function Documentation

long double necsim::inverseSpeciation(const long double &speciation_rate, const unsigned long &no_generations)

Calculates the random number required for speciation to occur in exactly n generations This is equivalent to calculating 1 - the probability that speciation does not occur in n generations.

Return

Parameters

• speciation_rate: the speciation rate
• no_generations: the number of generations speciation can occur over

Function necsim::loggerIsSetup

• Defined in File Logging.cpp

Function Documentation

bool necsim::loggerIsSetup()

Checks if the global logger object has been set up.

Function necsim::main

• Defined in File main.cpp

Function Documentation

int necsim::main(int argc, char *argv[])

Main function containing program structure.

Return

a program exit code, 0 if successful, -1 (generally) indicates an error.

Parameters

• argc: the number of command-line arguments provided
• argv: a pointer to the arguments

Function necsim::openSQLiteDatabase

• Defined in File file_system.cpp

Function Documentation

void necsim::openSQLiteDatabase(const string &database_name, sqlite3 *&database)

Safely opens a connection to the provided SQLite database.

Adds type safety for usage on different filesystems.

Parameters

• database_name:
• database:

Function necsim::operator<<(ostream&, ActivityMap&)

• Defined in File ActivityMap.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, ActivityMap &r)

Return

the os object

Parameters

• os: the ostream to output to
• r: the ActivityMap to read from

Function necsim::operator<<(ostream&, const SectionOption&)

• Defined in File ConfigParser.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, const SectionOption &k)

Return

os the output stream.

Parameters

• os: the output stream.
• k: the KeyOption object.

Function necsim::operator<<(ostream&, const ConfigParser&)

• Defined in File ConfigParser.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, const ConfigParser &c)

Return

os the output stream.

Parameters

• os: the output stream.
• c: the ConfigOption object.

Function necsim::operator<<(ostream&, const DataPoint&)

• Defined in File DataPoint.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, const DataPoint &d)

Return

returns the output stream at the end.

Parameters

• os: the output stream.
• d: the Datapoint object to output.

Template Function necsim::operator<<(ostream&, const vector<T>&)

• Defined in File file_system.h

Function Documentation

template<class T>
ostream &necsim::operator<<(ostream &os, const vector<T> &v)

Overload the output operator for vectors.

Return

the modified output operator

Template Parameters

• T: the template type of the vector

Parameters

• os: the output stream to write to
• v: the vector to write out

Function necsim::operator<<(ostream&, const GillespieProbability&)

• Defined in File GillespieCalculator.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, const GillespieProbability &gp)

Function necsim::operator<<(std::ostream&, const MapLocation&)

• Defined in File MapLocation.cpp

Function Documentation

std::ostream &necsim::operator<<(std::ostream &os, const MapLocation &m)

Return

the output stream

Parameters

• os: the output stream to write to
• m: the object to write out

Function necsim::operator<<(ostream&, const SpeciesList&)

• Defined in File SpeciesList.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, const SpeciesList &r)

Return

the output stream.

Parameters

• os: the output stream.
• r: the SpeciesList object to output.

Function necsim::operator<<(ostream&, const TreeNode&)

• Defined in File TreeNode.cpp

Function Documentation

ostream &necsim::operator<<(ostream &os, const TreeNode &t)

Return

the output stream.

Parameters

• os: the output stream.
• t: a Treenode object to output.

Function necsim::operator>>(istream&, ActivityMap&)

• Defined in File ActivityMap.cpp

Function Documentation

istream &necsim::operator>>(istream &is, ActivityMap &r)

Return

the is object

Parameters

• is: the istream to input from
• r: the ActivityMap to input to

Function necsim::operator>>(istream&, SectionOption&)

• Defined in File ConfigParser.cpp

Function Documentation

istream &necsim::operator>>(istream &is, SectionOption &k)

Return

is the input stream

Parameters

• is: the input stream
• k: the KeyOption object

Function necsim::operator>>(istream&, ConfigParser&)

• Defined in File ConfigParser.cpp

Function Documentation

istream &necsim::operator>>(istream &is, ConfigParser &c)

Return

is the input stream

Parameters

• is: the input stream
• c: the ConfigOption object

Function necsim::operator>>(istream&, DataPoint&)

• Defined in File DataPoint.cpp

Function Documentation

istream &necsim::operator>>(istream &is, DataPoint &d)

Return

returns the input stream at the end.

Parameters

• is: the input stream
• d: the Datapoint object to input to.

Template Function necsim::operator>>(istream&, vector<T>&)

• Defined in File file_system.h

Function Documentation

template<class T>
istream &necsim::operator>>(istream &is, vector<T> &v)

Overloaded input stream operator for a vector of objects.

Return

the input stream

Template Parameters

• T: the objects stored in a vector

Parameters

• is: the input stream
• v: the vector of objects to read in to

Function necsim::operator>>(std::istream&, GillespieProbability&)

• Defined in File GillespieCalculator.cpp

Function Documentation

std::istream &necsim::operator>>(std::istream &is, GillespieProbability &gp)

Function necsim::operator>>(std::istream&, MapLocation&)

• Defined in File MapLocation.cpp

Function Documentation

std::istream &necsim::operator>>(std::istream &is, MapLocation &m)

Return

the input stream

Parameters

• is: the input stream to read from
• m: the object to read to

Function necsim::operator>>(istream&, SpeciesList&)

• Defined in File SpeciesList.cpp

Function Documentation

istream &necsim::operator>>(istream &is, SpeciesList &r)

Parameters

• is: the input stream.
• r: the SpeciesList object to input to.

Function necsim::operator>>(istream&, TreeNode&)

• Defined in File TreeNode.cpp

Function Documentation

istream &necsim::operator>>(istream &is, TreeNode &t)

Return

the input stream.

Parameters

• is: the input stream.
• t: a Treenode object to input to.

Function necsim::removeComOption

• Defined in File setup.cpp

Function Documentation

void necsim::removeComOption(unsigned long &argc, vector<string> &comargs)

Removes the command line options supplied, leaving just a clean vector with the correct data in.

Function necsim::removeGlobalLogger

• Defined in File PyLogging.cpp

Function Documentation

void necsim::removeGlobalLogger()

Safely deletes the global logger object.

Function necsim::runAsDefault

• Defined in File setup.cpp

Function Documentation

void necsim::runAsDefault(vector<string> &comargs)

Sets up the command-line arguments for default parameters.

This is intended for testing purposes only.

Parameters

• comargs: a vector of command-line arguments for putting the parameters into.

Function necsim::runLarge

• Defined in File setup.cpp

Function Documentation

void necsim::runLarge(vector<string> &comargs)

Sets up the command-line arguments for larger-scale default parameters.

This is intended for testing purposes only.

Parameters

• comargs: a vector of command-line arguments for putting the parameters into.

Template Function necsim::runMain

• Defined in File SimulationTemplates.h

Function Documentation

template<class T>
void necsim::runMain(const string &config_file)

Template class for running simulations from all Tree types.

Template Parameters

• T: the class (either Tree, or a child of Tree) of the simulation

Parameters

• config_file: the config file to read simulation parameters from

Function necsim::runXL

• Defined in File setup.cpp

Function Documentation

void necsim::runXL(vector<string> &comargs)

Sets up the command-line arguments for default very large scale parameters.

This is intended for testing purposes only.

Parameters

• comargs: a vector of command-line arguments for putting the parameters into.

Function necsim::writeCritical

• Defined in File Logging.cpp

Function Documentation

void necsim::writeCritical(string message)

Writes to cerr, or to critical in logging module if being compiled with python.

Parameters

• message: the message to write out

Function necsim::writeError

• Defined in File Logging.cpp

Function Documentation

void necsim::writeError(string message)

Writes to cerr, or to error in logging module if being compiled with python.

Parameters

• message: the message to write out

Function necsim::writeInfo

• Defined in File Logging.cpp

Function Documentation

void necsim::writeInfo(string message)

Writes to cout, or to info in logging module if being compiled with python.

Parameters

• message: the message to write out

Function necsim::writeWarning

• Defined in File Logging.cpp

Function Documentation

void necsim::writeWarning(string message)

Writes to cerr, or to warning in logging module if being compiled with python.

Parameters

• message: the message to write out

Function neutral_analytical::calcFundamentalBiodiversityNumber

• Defined in File neutral_analytical.cpp

Function Documentation

long double neutral_analytical::calcFundamentalBiodiversityNumber(const unsigned long &community_size, const long double &speciation_rate)

Gets the fundamental biodiversity number for the system.

Return

the fundamental biodiversity number

Parameters

• community_size: the number of individuals in the community
• speciation_rate: the speciation rate

Function neutral_analytical::calcSpeciationRate

• Defined in File neutral_analytical.cpp

Function Documentation

long double neutral_analytical::calcSpeciationRate(const long double &fundamental_biodiversity_number, const unsigned long &metacommunity_size)

Calculates the speciation rate from the fundamental biodiversity number and the metacommunity size.

Return

the speciation rate to maintain the given fundamental biodiversity number

Parameters

• fundamental_biodiversity_number: the fundamental biodiversity number (theta)
• metacommunity_size: the number of individuals in the metacommunity

Function neutral_analytical::siMetacommunitySpeciesWithAbundance

• Defined in File neutral_analytical.cpp

Function Documentation

long double neutral_analytical::siMetacommunitySpeciesWithAbundance(const unsigned long &n, const unsigned long &metacommunity_size, const long double &speciation_rate)

Calculate the expected number of species with abundance n within a spatially implicit neutral model.

Implementation of the SAD approximation from Vallade and Houchmandzadeh (2003).

Return

the number of species with abundance n

Parameters

• n: the number of individuals expected within the species
• metacommunity_size: the total number of individuals in the community
• speciation_rate: the speciation rate

Function neutral_analytical::siSpeciesAbundanceCumulativeDistribution

• Defined in File neutral_analytical.cpp

Function Documentation

std::map<unsigned long, long double> neutral_analytical::siSpeciesAbundanceCumulativeDistribution(const unsigned long &community_size, const long double &speciation_rate)

Get the species abundances probability distribution for a set of community parameters within a spatially implicit neutral model of ecology.

The abundances will be cumulative probabilities.

Return

Parameters

• community_size: the number of individuals in the community
• speciation_rate: the speciation rate

Function neutral_analytical::siSpeciesRichness

• Defined in File neutral_analytical.cpp

Function Documentation

long double neutral_analytical::siSpeciesRichness(const unsigned long &community_size, const long double &speciation_rate)

Gets the expected species richness for a spatially implicit neutral model.

Using an analytical approximation identified here by Sam Thompson (but likely an old published result).

Return

the number of species expected to exist

Parameters

• community_size: the number of individuals in the community
• speciation_rate: the speciation rate

Function neutral_analytical::siSpeciesRichnessDeprecated

• Defined in File neutral_analytical.cpp

Function Documentation

long double neutral_analytical::siSpeciesRichnessDeprecated(const unsigned long &community_size, const long double &speciation_rate)

Gets the expected species richness for a spatially implicit explicit neutral model.

Using the sampling formula from Vallade and Houchmandzadeh (2003).

Return

the number of species expected to exist

Parameters

• community_size: the number of individuals in the community
• speciation_rate: the speciation rate

Template Function output

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *output(PyCommunityTemplate<T> *self)

Outputs the community to database.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object

Template Function pyAddMetacommunityParameters

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *pyAddMetacommunityParameters(PyCommunityTemplate<T> *self, PyObject *args)

Adds a set of metacommunity parameters to the speciation parameters.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object
• args: the arguments to pass

Template Function PyCommunity_dealloc

• Defined in File CCommunity.h

Function Documentation

template<class T>
static void PyCommunity_dealloc(PyCommunityTemplate<T> *self)

Template Function PyCommunity_init

• Defined in File CCommunity.h

Function Documentation

template<class T>
static int PyCommunity_init(PyCommunityTemplate<T> *self, PyObject *args, PyObject *kwds)

Initialises the Community object.

Return

Template Parameters

• T: the template type

Parameters

• self: the Python self object
• args: arguments to pass to constructor
• kwds: keyword arguments to pass to constructor

Function PyLMC_dealloc

• Defined in File CLandscapeMetricsCalculator.h

Function Documentation

static void PyLMC_dealloc(PyLMC *self)

Function PyLMC_init

• Defined in File CLandscapeMetricsCalculator.h

Function Documentation

static int PyLMC_init(PyLMC *self, PyObject *args, PyObject *kwds)

Function PySimulateDispersal_dealloc

• Defined in File CSimulateDispersal.h

Function Documentation

static void PySimulateDispersal_dealloc(PySimulateDispersal *self)

Function PySimulateDispersal_init

• Defined in File CSimulateDispersal.h

Function Documentation

static int PySimulateDispersal_init(PySimulateDispersal *self, PyObject *args, PyObject *kwds)

Function PySimulateDispersal_new

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *PySimulateDispersal_new(PyTypeObject *type, PyObject *args, PyObject *kwds)

Template Function pySpeciateRemainingLineages

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *pySpeciateRemainingLineages(PyCommunityTemplate<T> *self, PyObject *args)

Template Function PyTemplate_clear

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static int PyTemplate_clear(PyTemplate<T> *self)

Template Function PyTemplate_dealloc

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static void PyTemplate_dealloc(PyTemplate<T> *self)

Template Function PyTemplate_gen_getsetters

• Defined in File PyTemplates.h

Function Documentation

template<typename T>
PyGetSetDef *PyTemplate_gen_getsetters()

Template Function PyTemplate_getCallLogger

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static PyObject *PyTemplate_getCallLogger(PyTemplate<T> *self, void *closure)

Template Function PyTemplate_getLogging

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static PyObject *PyTemplate_getLogging(PyTemplate<T> *self, void *closure)

Template Function PyTemplate_init

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static int PyTemplate_init(PyTemplate<T> *self, PyObject *args, PyObject *kwds)

Template Function PyTemplate_new

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static PyObject *PyTemplate_new(PyTypeObject *type, PyObject *args, PyObject *kwds)

Template Function PyTemplate_setCallLogger

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static int PyTemplate_setCallLogger(PyTemplate<T> *self, PyObject *value, void *closure)

Template Function PyTemplate_setLogging

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static int PyTemplate_setLogging(PyTemplate<T> *self, PyObject *value, void *closure)

Template Function PyTemplate_traverse

• Defined in File PyTemplates.h

Function Documentation

template<class T>
static int PyTemplate_traverse(PyTemplate<T> *self, visitproc visit, void *arg)

Function random_numbers::intToDouble

• Defined in File Xoroshiro256plus.h

Function Documentation

static double random_numbers::intToDouble(const uint64_t &i)

Converts a uniform integer on [0, UINT64_MAX) to a double.

Return

double equivalent of the integer

Parameters

• i: the integer to convert

Function random_numbers::rotl

• Defined in File Xoroshiro256plus.h

Function Documentation

static uint64_t random_numbers::rotl(const uint64_t &value, int bits)

Rotate the value a specified number of times.

Return

the rotated and shifted value

Parameters

• value: the value to rotate
• bits: the number of bits to shift

Function readyPyTypeObject

• Defined in File necsim.cpp

Function Documentation

Warning

doxygenfunction: Cannot find function “readyPyTypeObject” in doxygen xml output for project “necsim” from directory: ../docs/necsim_doc/xml/

Template Function reset

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *reset(PyCommunityTemplate<T> *self)

Resets the internal community object.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object

Template Function run

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *run(PyTemplate<T> *self, PyObject *args)

Runs the simulation.

Return

Py_RETURN_TRUE if the simulation completes, Py_RETURN_FALSE otherwise.

Template Parameters

• T: the simulation type

Parameters

• self: the Python self object
• args: arguments to parse

Function runADT

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *runADT(PySimulateDispersal *self, PyObject *args)

Runs the mean distance travelled simulation on all cells.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Function runMDT

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *runMDT(PySimulateDispersal *self, PyObject *args)

Runs the mean distance travelled simulation.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Function runMeanDispersal

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *runMeanDispersal(PySimulateDispersal *self, PyObject *args)

Runs the simulation for mean dispersal distance.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Function runSRW

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *runSRW(PySimulateDispersal *self, PyObject *args)

Runs the mean distance travelled simulation on sampled cells.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Function set_all_map_parameters

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *set_all_map_parameters(PySimulateDispersal *self, PyObject *args)

Sets all the map parameters, including historical maps, with a single import.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Function set_dispersal_parameters

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *set_dispersal_parameters(PySimulateDispersal *self, PyObject *args)

Sets the dispersal parameters.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Function set_historical_map_parameters

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *set_historical_map_parameters(PySimulateDispersal *self, PyObject *args)

Sets the historical map parameters.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse, should be lists of the fine and coarse map parameters

Function set_map

• Defined in File CLandscapeMetricsCalculator.h

Function Documentation

PyObject *set_map(PyLMC *self, PyObject *args)

Sets the map parameters and imports the maps.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse, should contain all key map parameters

Function set_maps

• Defined in File CSimulateDispersal.h

Function Documentation

PyObject *set_maps(PySimulateDispersal *self, PyObject *args)

Sets the map parameters and imports the maps.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse, should contain all key map parameters

Function set_output_database

• Defined in File CSimulateDispersal.h

Function Documentation

static PyObject *set_output_database(PySimulateDispersal *self, PyObject *args)

Sets the key simulation parameters.

Return

pointer to the Python object

Parameters

• self: the Python self object
• args: arguments to parse

Template Function setup

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *setup(PyTemplate<T> *self, PyObject *args)

Sets up the simulation, including importing map files and generating in-memory objects.

Template Parameters

• T: the simulation type

Parameters

• self: the Python self object
• args: arguments to parse

Template Function setupApplySpeciation

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *setupApplySpeciation(PyCommunityTemplate<T> *self, PyObject *args)

Sets up the speciation parameters.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object
• args: the arguments to pass

Template Function setupResume

• Defined in File CSimulation.h

Function Documentation

template<class T>
static PyObject *setupResume(PyTemplate<T> *self, PyObject *args)

Sets up the simulation by reading the dumped files from a paused simulation.

Template Parameters

• T: the simulation type

Parameters

• self: the Python self object
• args: arguments to parse

Template Function wipeProtractedParameters

• Defined in File CCommunity.h

Function Documentation

template<class T>
static PyObject *wipeProtractedParameters(PyCommunityTemplate<T> *self)

Wipes the protracted parameters vectors.

Return

Py_RETURN_NONE

Template Parameters

• T: the type of the Community

Parameters

• self: the reference to the Python self object

Variable _state

• Defined in File necsim.h

Variable Documentation

struct module_state _state

Variable C_CommunityType

• Defined in File CCommunity.h

Variable Documentation

PyTypeObject C_CommunityType = genCommunityType<Community>((char *)"libnecsim.CCommunity", (char *)"C class for generating communities from neutral simulations")

The type object containing the Community to pass on to Python.

Variable C_LMCType

• Defined in File CLandscapeMetricsCalculator.h

Variable Documentation

PyTypeObject C_LMCType = genLMCType()

Variable C_MetacommunityType

• Defined in File CCommunity.h

Variable Documentation

PyTypeObject C_MetacommunityType = genCommunityType<Metacommunity>((char *)"libnecsim.CMetacommunity", (char *)"C class for generating communities from neutral simulations")

The type object containing the Metacommunity to pass on to Python.

Variable C_NSESimulationType

• Defined in File CSimulation.h

Variable Documentation

PyTypeObject C_NSESimulationType = genSimulationType<Tree>((char *)"libnecsim.CNSESimulation", (char *)"C class for non-spatial simulations.")

Variable C_ProtractedNSESimulationType

• Defined in File CSimulation.h

Variable Documentation

PyTypeObject C_ProtractedNSESimulationType = genSimulationType<ProtractedTree>((char *)"libnecsim.CPNSESimulation", (char *)"C class for protracted non-spatial simulations.")

Variable C_ProtractedSpatialSimulationType

• Defined in File CSimulation.h

Variable Documentation

PyTypeObject C_ProtractedSpatialSimulationType = genSimulationType<ProtractedSpatialTree>((char *)"libnecsim.CPSpatialSimulation", (char *)"C class for protracted spatial simulations.")

Variable C_SimulateDispersalType

• Defined in File CSimulateDispersal.h

Variable Documentation

PyTypeObject C_SimulateDispersalType = genSimulateDispersalType()

Variable C_SpatialSimulationType

• Defined in File CSimulation.h

Variable Documentation

PyTypeObject C_SpatialSimulationType = genSimulationType<SpatialTree>((char *)"libnecsim.CSpatialSimulation", (char *)"C class for spatial simulations.")

Variable necsim::gdal_data_sizes

• Defined in File Matrix.h

Variable Documentation

const int necsim::gdal_data_sizes[] = {0, 8, 16, 16, 32, 32, 32, 64}

Variable necsim::log_name

• Defined in File setup.h

Variable Documentation

string necsim::log_name

Variable necsim::logger

• Defined in File Logger.cpp

Variable Documentation

Logger *necsim::logger

Global object for logging.

Variable necsim::pyLogger

• Defined in File PyLogger.cpp

Variable Documentation

PyLogger *necsim::pyLogger = nullptr

Variable necsim::saved_stdout

• Defined in File setup.h

Variable Documentation

int necsim::saved_stdout

Variable necsimError

• Defined in File necsim.h

Variable Documentation

PyObject *necsimError

A Python error container for all run-time errors.

Variable NecsimMethods

• Defined in File necsim.cpp

Variable Documentation

Warning

doxygenvariable: Cannot find variable “NecsimMethods” in doxygen xml output for project “necsim” from directory: ../docs/necsim_doc/xml/

Variable PyLMCMethods

• Defined in File CLandscapeMetricsCalculator.h

Variable Documentation

PyMethodDef PyLMCMethods[] = {{"import_map", (PyCFunction) set_map, METH_VARARGS, "Imports the map file to calculate landscape metrics on. Should only be run once."}, {"calculate_MNN", (PyCFunction) calculateMNN, METH_NOARGS, "Calculates the mean nearest-neighbour for the landscape"}, {"calculate_CLUMPY", (PyCFunction) calculateCLUMPY, METH_NOARGS, "Calculates the CLUMPY metric for the landscape"}, {nullptr, nullptr, 0, nullptr}}

Variable random_numbers::ktab

• Defined in File RNGController.h

Variable Documentation

constexpr unsigned long random_numbers::ktab[128] = {0, 12590644, 14272653, 14988939, 15384584, 15635009, 15807561, 15933577, 16029594, 16105155, 16166147, 16216399, 16258508, 16294295, 16325078, 16351831, 16375291, 16396026, 16414479, 16431002, 16445880, 16459343, 16471578, 16482744, 16492970, 16502368, 16511031, 16519039, 16526459, 16533352, 16539769, 16545755, 16551348, 16556584, 16561493, 16566101, 16570433, 16574511, 16578353, 16581977, 16585398, 16588629, 16591685, 16594575, 16597311, 16599901, 16602354, 16604679, 16606881, 16608968, 16610945, 16612818, 16614592, 16616272, 16617861, 16619363, 16620782, 16622121, 16623383, 16624570, 16625685, 16626730, 16627708, 16628619, 16629465, 16630248, 16630969, 16631628, 16632228, 16632768, 16633248, 16633671, 16634034, 16634340, 16634586, 16634774, 16634903, 16634972, 16634980, 16634926, 16634810, 16634628, 16634381, 16634066, 16633680, 16633222, 16632688, 16632075, 16631380, 16630598, 16629726, 16628757, 16627686, 16626507, 16625212, 16623794, 16622243, 16620548, 16618698, 16616679, 16614476, 16612071, 16609444, 16606571, 16603425, 16599973, 16596178, 16591995, 16587369, 16582237, 16576520, 16570120, 16562917, 16554758, 16545450, 16534739, 16522287, 16507638, 16490152, 16468907, 16442518, 16408804, 16364095, 16301683, 16207738, 16047994, 15704248, 15472926}

Variable random_numbers::wtab

• Defined in File RNGController.h

Variable Documentation

constexpr double random_numbers::wtab[128]

Variable random_numbers::ytab

• Defined in File RNGController.h

Variable Documentation

constexpr double random_numbers::ytab[128] = {1, 0.963598623011, 0.936280813353, 0.913041104253, 0.892278506696, 0.873239356919, 0.855496407634, 0.838778928349, 0.822902083699, 0.807732738234, 0.793171045519, 0.779139726505, 0.765577436082, 0.752434456248, 0.739669787677, 0.727249120285, 0.715143377413, 0.703327646455, 0.691780377035, 0.68048276891, 0.669418297233, 0.65857233912, 0.647931876189, 0.637485254896, 0.62722199145, 0.617132611532, 0.607208517467, 0.597441877296, 0.587825531465, 0.578352913803, 0.569017984198, 0.559815170911, 0.550739320877, 0.541785656682, 0.532949739145, 0.524227434628, 0.515614886373, 0.507108489253, 0.498704867478, 0.490400854812, 0.482193476986, 0.47407993601, 0.466057596125, 0.458123971214, 0.450276713467, 0.442513603171, 0.434832539473, 0.427231532022, 0.419708693379, 0.41226223212, 0.404890446548, 0.397591718955, 0.390364510382, 0.383207355816, 0.376118859788, 0.369097692334, 0.362142585282, 0.355252328834, 0.348425768415, 0.341661801776, 0.334959376311, 0.328317486588, 0.321735172063, 0.31521151497, 0.308745638367, 0.302336704338, 0.29598391232, 0.289686497571, 0.283443729739, 0.27725491156, 0.271119377649, 0.265036493387, 0.259005653912, 0.253026283183, 0.247097833139, 0.241219782932, 0.235391638239, 0.229612930649, 0.223883217122, 0.218202079518, 0.212569124201, 0.206983981709, 0.201446306496, 0.195955776745, 0.190512094256, 0.185114984406, 0.179764196185, 0.174459502324, 0.169200699492, 0.1639876086, 0.158820075195, 0.153697969964, 0.148621189348, 0.143589656295, 0.138603321143, 0.133662162669, 0.128766189309, 0.123915440582, 0.119109988745, 0.114349940703, 0.10963544023, 0.104966670533, 0.100343857232, 0.0957672718266, 0.0912372357329, 0.0867541250127, 0.082318375932, 0.0779304915295, 0.0735910494266, 0.0693007111742, 0.065060233529, 0.0608704821745, 0.056732448584, 0.05264727098, 0.0486162607163, 0.0446409359769, 0.0407230655415, 0.0368647267386, 0.0330683839378, 0.0293369977411, 0.0256741818288, 0.0220844372634, 0.0185735200577, 0.0151490552854, 0.0118216532614, 0.00860719483079, 0.00553245272614, 0.00265435214565}

These variables contain the special numbers for random number generation.

Variable saved_stdout

• Defined in File setup.cpp

Variable Documentation

int necsim::saved_stdout

Variable SimulateDispersalMethods

• Defined in File CSimulateDispersal.h

Variable Documentation

PyMethodDef SimulateDispersalMethods[] = { {"set_dispersal_parameters", (PyCFunction) set_dispersal_parameters, METH_VARARGS, "Sets the dispersal current_metacommunity_parameters for this simulation."}, {"set_output_database", (PyCFunction) set_output_database, METH_VARARGS, "Sets the output database for the simulation."}, {"run_mean_dispersal_distance", (PyCFunction) runMeanDispersal, METH_VARARGS, "Runs the dispersal simulation for the set current_metacommunity_parameters, calculating the mean distance per step."}, {"run_mean_distance_travelled", (PyCFunction) runMDT, METH_VARARGS, "Runs the dispersal simulation for the set current_metacommunity_parameters, calculating the mean distance travelled."}, {"run_all_distance_travelled", (PyCFunction) runADT, METH_VARARGS, "Runs the dispersal simulation for the set current_metacommunity_parameters on all habitable cells, calculating the mean distance travelled."}, {"run_sample_distance_travelled", (PyCFunction) runSRW, METH_VARARGS, "Runs the dispersal simulation for the set current_metacommunity_parameters on the given sample habitable cells, calculating the mean distance travelled."}, {"import_maps", (PyCFunction) set_maps, METH_VARARGS, "Imports the map files for the simulation. Should only be run once."}, {"import_all_maps", (PyCFunction) set_all_map_parameters, METH_VARARGS, "Imports all the map files with a single import."}, {"set_historical_map_parameters", (PyCFunction) set_historical_map_parameters, METH_VARARGS, "Sets the historical map current_metacommunity_parameters."}, {nullptr, nullptr, 0, nullptr} }

Define _USE_MATH_DEFINES

• Defined in File file_system.h

Define Documentation

_USE_MATH_DEFINES

Define _USE_MATH_DEFINES

• Defined in File Landscape.cpp

Define Documentation

_USE_MATH_DEFINES

Define _USE_MATH_DEFINES

• Defined in File RNGController.h

Define Documentation

_USE_MATH_DEFINES

Define GETSTATE

• Defined in File necsim.h

Define Documentation

GETSTATE(m)

Define INITERROR

• Defined in File necsim.cpp

Define Documentation

INITERROR

Define INITERROR

• Defined in File necsim.h

Define Documentation

INITERROR

Define LOGNAME_FORMAT

• Defined in File LogFile.h

Define Documentation

LOGNAME_FORMAT

Define null

• Defined in File Matrix.h

Define Documentation

null

Define PARAM_R

• Defined in File RNGController.h

Define Documentation

PARAM_R

Define PYTHON_COMPILE

• Defined in File SimulateDispersal.h

Define Documentation

PYTHON_COMPILE

Define PYTHON_COMPILE

• Defined in File necsim.cpp

Define Documentation

PYTHON_COMPILE

Define PYTHON_COMPILE

• Defined in File PyLogger.h

Define Documentation

PYTHON_COMPILE

Define PYTHON_COMPILE

• Defined in File PyLogging.cpp

Define Documentation

PYTHON_COMPILE

Define SPECIATIONCOUNTER_FILESYSTEM_H

• Defined in File file_system.h

Define Documentation

SPECIATIONCOUNTER_FILESYSTEM_H

Define SPECIATIONCOUNTER_PROTRACTEDSPATIALTREE_H

• Defined in File ProtractedSpatialTree.h

Define Documentation

SPECIATIONCOUNTER_PROTRACTEDSPATIALTREE_H

Simulating and generating landscapes

Introduction

pycoalescence provides functionality for generating fragmented landscapes for simulations, and simulating dispersal kernels to produce a variety of landscape-level dispersal metrics. Generation of landscapes is provided through the FragmentedLandscape class. Simulations of dispersal kernels is provided through the DispersalSimulation class.

Generating landscapes

Fragmented Landscapes

For our purposes, we define fragmented landscapes as continuous, fully spatial landscapes of a particular size, with n individuals split across i equally (or as close to) sized fragments, which are evenly spaced across the landscape. pycoalescence provides the routines for generating these landscapes within FragmentedLandscape class.

The parameters for generating a fragmented landscape are the total landscape size, the habitat area within the landscape (i.e. the number of individuals) and the number of fragments to place. The habitat area cannot be more than 50% of the landscape size, as at this point fragments become non-distinct. The process is:

from pycoalescence import FragmentedLandscape
f = FragmentedLandscape(size=100, number_fragments=10, total=20, output_file="fragment.tif")
f.generate()

Patched Landscapes

We define patched landscapes as a number of interconnected patches, each containing a certain number of well-mixed individuals (the patch’s density) and every patch is has some probability of dispersal to every other patch (which can be 0). Another imagination of this concept is of a series of connected islands, where each island is modelled non-spatially, and every island has a probability of dispersing to all other islands. pycoalescence provides the routines for generating these landscapes within PatchedLandscape class.

Creation of a patched landscape requires first defining all the patches that exist in the landscape, and then setting the dispersal probability between each island. If any dispersal probability is not set, it is assumed to be 0. The dispersal probability from one patch to itself must be provided (but can be 0). The probability values provided are then re-scaled to sum to 1, and re-generated as cumulative probabilities.

Simulated landscapes

To simulate a dispersal kernel on a landscape, there are two processes; simulating a single step and simulating multiple steps. For a single step, the distance travelled is recorded into the output database. The mean, standard deviation and other metrics can be obtained from this. For multiple steps, the total distance travelled after n steps is recorded. Both methods follow the same structure,

from pycoalescence import DispersalSimulation
m = DispersalSimulation(dispersal_db="path/output.db")
m.test_mean_dispersal(number_repeats=100000, output_database=out_db, map_file="path/map.tif", seed=seed,
                      dispersal_method="normal", sigma=sigma, landscape_type="tiled")
m.test_mean_distance_travelled(number_repeats=1000, number_steps=10,
                               map_file="path/map.tif", seed=seed, dispersal_method="normal",
                               sigma=sigma, landscape_type="tiled")
# The reference parameters correspond to the order they were simulated with
parameters_list = m.getdatabase_parameters()
# Each of these contain parameters for the first and second simulation
parameters_1 = parameters_list[1]
parameters_2 = parameters_list[2]
# We can therefore just use the reference numbers (1 or 2) to obtain metrics
m.get_mean_dispersal(parameter_reference=1)
m.get_mean_distance_travelled(parameter_reference=2)
m.get_stdev_dispersal(parameters_reference=1)

Reading and writing tif files

The Map class is used for detecting offsets and dimensions of tif files for the main program. There are therefore a number of additional features in this class.

• Data can be read using get_subset() and get_cached_subset().
• Dimensions can be determined using get_dimensions(). The entire tif file can also be read into a numpy array using open() and then indexing on data.
• A shapefile can be rasterised to a new tif file using rasterise().
• Tif files can be re-projected to either a new or the same file using open().

Note

All processing is done using the gdal module.

Obtaining landscape metrics

LandscapeMetrics contains methods for calculating some landscape metrics on a map file. This is a work in progress, and additional metrics may be added later.

MNN here refers to the mean distance from each cell to its nearest neighbouring habitat cell. The distance can be calculated for a landscape using the following:

>> from pycoalescence import LandscapeMetrics
>> lm = LandscapeMetrics("map_file.tif")
>> lm.get_mnn()
1.50

The clumpiness metric is a measure of the proportional deviation of proportion of like adjacencies involving the corresponding class from that expected under a spatially random distribution. It produces a \(\text{CLUMPY}\) value, where \(-1 <= \text{CLUMPY} <= 1\). -1 represents a perfectly disaggregated landscape. 1 represents a perfectly aggregated landscape. 0 represents a random landscape. The formula outlined below works where there are \(k\) patches; in our scenario there \(k=2\) as we have just habitat or non-habitat.

We have:

• \(g_ii\), the number of adjacencies between pixels of patch type \(i\) using the the double count method.
• \(g_ik\), the number of adjacencies between pixels of patches \(i\) and \(j\)
• \(\text{min}(e_i)\), the minimum perimeter (in cell surfaces) for a maximally-clumped class \(i\)
• \(P_i\), the proportion of the landscape occupied by class \(i\).

Given

\[G_i = (\frac{g_{ii}}{(\sum_{k=1}^{n} g_{ik}) - \text{min} (e_i)}\]

then

\[\begin{split}\text{CLUMPY} = \begin{cases} \frac{G_i - P_i}{P_i}, & \text{if}\ G_i < P_i\ \&\ P_i < 0.5 \\ \frac{G_i - P_i}{1-P_i}, & \text{otherwise} \end{cases}\end{split}\]

The \(\text{CLUMPY}\) metric can be calculated similarly as

>> from pycoalescence import LandscapeMetrics
>> lm = LandscapeMetrics("map_file.tif")
>> lm.get_clumpiness()
0.8

Merging simulation outputs

Introduction

Simulations can be merged using the Merger class. Here, multiple simulations are combined into a single database, with each simulation being associated with a particular “guild”. These guilds could represent different environmental niches, body sizes or other differentiating factors.

Usage

Add simulations using add_simulation() and then use write().

Previously calculated metrics are all stored in *_GUILDS tables. Species identities are preserved (without allowing for a species to exist in more than one guild), meaning all metrics can be re-calculated using apply() and functions such as calculate_richness(). Alternatively, use add_simulations()

merger = Merger("output.db")
merger.add_simulation("input1.db")
merger.add_simulation("input2.db")
merger.write()

Code examples

Example simulations and analysis using pycoalescence

This jupyter notebook shows a variety of full example simulations that can be run using the files provided in the sample folder in pycoalescence. They are intended to be used as templates for your own simulations.

Note that this notebook requires Python 3.x and a full install of pycoalescence.

First import the necessary modules

import os

from pycoalescence import Simulation, CoalescenceTree

Define our input and output directories - change these as required

input_dir = "../../pycoalescence/tests/sample"
output_dir = "output"

Basic spatial simulation and analysis

Basic spatial simulation on just one map file, with a closed landscape. For this example we run with full logging (at ‘debug’ level). All other examples will be run using ‘critical’ level, which shouldn’t output any information unless there is a problem.

Use a speciation rate of 0.1, a dispersal of 2.0 (sigma) and 10 individuals per cell (deme).

The output will be stored in output/data_1_1.db

sim1 = Simulation(logging_level=10)
sim1.set_simulation_parameters(seed=1, task=1, output_directory=output_dir, min_speciation_rate=0.1,
                                                       sigma=2.0, deme=10)
# Use automatic detection of the map file dimensions
sim1.set_map(os.path.join(input_dir, "SA_sample_fine.tif"))
sim1.run()

Checking folder existance...../../pycoalescence/tests/sample/SA_sample_fine.tif exists.
Checking folder existance...output exists.
Checking folder existance...done.
Checking for unfinished simulations...done.
No files found containing unfinished simulations.
*************************************************
Setting up simulation...
Dispersal (tau, sigma): 1, 2
Dispersal method: normal
Fine map
-file: ../../pycoalescence/tests/sample/SA_sample_fine.tif
-dimensions: (13, 13)
-offset: (0, 0)
Coarse map
-file: none
-dimensions: (13, 13)
-offset: (0, 0)
-scale: 1
Sample grid
-dimensions: (13, 13)
-optimised area: (13, 13)
-optimised offsets: (0, 0)
Seed: 1
Speciation rate: 0.1
Job Type: 1
Max time: 3600
Deme: 10
Deme sample: 1
Output directory: output
Disp Rel Cost: 1
Times:  0.0
Checking folder existance...../../pycoalescence/tests/sample/SA_sample_fine.tif exists.
Importing ../../pycoalescence/tests/sample/SA_sample_fine.tif
No data value is: 0
Getting geo transform...done.
Affine transform is -78.375, 0.00833333, 0, 0.858333, 0, -0.00833333
Importing ../../pycoalescence/tests/sample/SA_sample_fine.tif ...................done.
No data value is: 0
Getting geo transform...done.
Affine transform is -78.375, 0.00833333, 0, 0.858333, 0, -0.00833333
Using dispersal kernel.
Initial count is 380980
Setting up simulation...done.
Number of individuals simulating: 380980
*************************************************
Beginning simulations...done.
Finalising data...done.
Creating SQL database file...
        Checking for existing folders....
        Generating species list....
        Executing SQL commands....
No additional speciation rates to apply.
Speciation rate is: 0.1.
Time is: 0.
Applying speciation rate 0.1 at time 0...
        Generating biodiversity...
        Calculating coalescence tree...
        Assigning species IDs...
        Calculating species abundances...
        Number of species: 96296
        Generating SPECIES_ABUNDANCES table...
        Writing to output/data_1_1.db...
Total generations simulated (steps): 191.025 (963375)
Setup time was 0 minutes 0 seconds
Simulation time was 0 hours 0 minutes 1 seconds
File output and species calculation time was 0 minutes 1 seconds
SQL output time was 0 minutes 0 seconds
Total simulation and output time was 0 hours 0 minutes 2 seconds

Re-create the coalescence tree for different speciation rates

tree1 = CoalescenceTree(sim1, logging_level=10)
tree1.set_speciation_parameters(speciation_rates=[0.1, 0.2, 0.4])
tree1.apply()

No sample file provided, defaulting to null.
No times provided, defaulting to 0.0.
***************************
STARTING COALESCENCE TREE CALCULATIONS
Input file is output/data_1_1.db
Speciation rates are: 0.1, 0.2, 0.4.
Beginning data import...
        Detected 665665 events in the coalescence tree.
Beginning data import...done.
Getting previous calculations...previous calculations detected.
Calculation already performed for speciation rate=0.1, time=0 and protracted parameters 0, 0
Applying speciation rate 0.2 at time 0...
        Generating biodiversity...
        Calculating coalescence tree...
        Assigning species IDs...
        Calculating species abundances...
        Number of species: 152176
        Generating SPECIES_ABUNDANCES table...
Applying speciation rate 0.4 at time 0...
        Generating biodiversity...
        Calculating coalescence tree...
        Assigning species IDs...
        Calculating species abundances...
        Number of species: 232205
        Generating SPECIES_ABUNDANCES table...
Writing out to output/data_1_1.db...

Print out the species richness for each speciation rate by looping over our community parameters.

for reference in tree1.get_community_references():
    spec_rate = tree1.get_community_parameters(reference=reference)["speciation_rate"]
    print("Species richness for speciation rate of {} is {}".format(spec_rate,
                                                                                                                                    tree1.get_species_richness(reference)))

Species richness for speciation rate of 0.1 is 96296
Species richness for speciation rate of 0.2 is 152176
Species richness for speciation rate of 0.4 is 232205

More complex spatial example

Here we use a sample area, a fine map file (defining high-resolution density around the area) and a coarse map file (defining the low-resolution density over a larger area).

Additionally, we provide a historical fine and coarse maps to define the density at 100 generations in the past (with a rate of 0.5) and 200 generations in the past (with a rate of 0.0).

Within the simulation, we sample the community at times 0, 50 and 100 generations in the past.

The output will be stored in output/data_1_2.db

Define our file paths

sample_file = os.path.join(input_dir, "SA_samplemaskINT.tif")
fine_file = os.path.join(input_dir, "SA_sample_fine.tif")
coarse_file = os.path.join(input_dir, "SA_sample_coarse.tif")
pristine_fine_file1 = os.path.join(input_dir, "SA_sample_fine_pristine1.tif")
pristine_coarse_file1 = os.path.join(input_dir, "SA_sample_coarse_pristine1.tif")
pristine_fine_file2 = os.path.join(input_dir, "SA_sample_fine_pristine2.tif")
pristine_coarse_file2 = os.path.join(input_dir, "SA_sample_coarse_pristine2.tif")

sim2 = Simulation(logging_level=50)
sim2.set_simulation_parameters(seed=2, task=1, output_directory=output_dir, min_speciation_rate=0.1,
                                                       sigma=2.0, deme=1)
sim2.set_speciation_rates([0.1, 0.2, 0.3])
# Use automatic detection of the map file dimensions
sim2.set_map_files(sample_file=sample_file, fine_file=fine_file, coarse_file=coarse_file)
sim2.add_historical_map(fine_file=pristine_fine_file1, coarse_file=pristine_coarse_file1, time=100,
                                            rate=0.5)
sim2.add_historical_map(fine_file=pristine_fine_file2, coarse_file=pristine_coarse_file2, time=100,
                                            rate=0.5)
sim2.add_sample_time(50)
sim2.add_sample_time(100)
sim2.run()

Print the species richness for each time and speciation rate.

tree2 = CoalescenceTree(sim2)
for reference in tree2.get_community_references():
    # Contains a dictionary of the parameters
    community_parameters = tree2.get_community_parameters(reference)
    spec_rate = community_parameters["speciation_rate"]
    time = community_parameters["time"]
    print("Species richness at time {} with speciation rate of {} is {}.".format(time,
                                                                                                                                                             spec_rate,
                                                                                                                                                             tree2.get_species_richness(reference)))

Species richness at time 0.0 with speciation rate of 0.1 is 7386.
Species richness at time 50.0 with speciation rate of 0.1 is 7332.
Species richness at time 100.0 with speciation rate of 0.1 is 7420.
Species richness at time 0.0 with speciation rate of 0.2 is 8756.
Species richness at time 50.0 with speciation rate of 0.2 is 8742.
Species richness at time 100.0 with speciation rate of 0.2 is 8751.
Species richness at time 0.0 with speciation rate of 0.3 is 9568.
Species richness at time 50.0 with speciation rate of 0.3 is 9579.
Species richness at time 100.0 with speciation rate of 0.3 is 9607.

Example using protracted speciation and a metacommunity

This is the same as the first example, but with protracted speciation preventing speciation from occuring before 1000 generations, and forcing speciation to occur at 10000 generations.

The coalescence tree is generated with and without a metacommunity as well.

sim3 = Simulation(logging_level=50)
sim3.set_simulation_parameters(seed=3, task=1, output_directory=output_dir,
                                                       min_speciation_rate=0.1, sigma=2.0, deme=1,
                                                       protracted=True, min_speciation_gen=1000, max_speciation_gen=10000)
sim3.set_speciation_rates([0.1, 0.2, 0.3])
# Use automatic detection of the map file dimensions
sim3.set_map(os.path.join(input_dir, "SA_sample_fine.tif"))
sim3.run()

Re-create the coalescence tree using sampling from a metacommunity instead of a speciation rate.

tree3 = CoalescenceTree(sim3)
tree3.set_speciation_parameters(speciation_rates=[0.1, 0.2, 0.3], protracted_speciation_min=1000,
                                                            protracted_speciation_max=10000, metacommunity_speciation_rate=0.001,
                                                            metacommunity_size=100000)
tree3.add_protracted_parameters(10, 5000)
tree3.add_protracted_parameters(50, 800)
tree3.apply()

Print out the species richness for each parameter set

for reference in tree3.get_community_references():
    params = tree3.get_community_parameters(reference)
    spec_rate = params["speciation_rate"]
    proc_min = params["min_speciation_gen"]
    proc_max = params["max_speciation_gen"]
    print("Speciation rate of {}, (min gen={}, max gen={})".format(spec_rate, proc_min, proc_max))
    if params["metacommunity_reference"] != 0:
            meta_params = tree3.get_metacommunity_parameters(params["metacommunity_reference"])
            meta_spec = meta_params["speciation_rate"]
            meta_size = meta_params["metacommunity_size"]
            print("Metacommunity used of size {} with speciation rate {}.".format(meta_size, meta_spec))
    print("Species richness: {}".format(tree3.get_species_richness(reference)))

Speciation rate of 0.1, (min gen=1000.0, max gen=10000.0)
Species richness: 71
Speciation rate of 0.2, (min gen=1000.0, max gen=10000.0)
Species richness: 71
Speciation rate of 0.3, (min gen=1000.0, max gen=10000.0)
Species richness: 71
Speciation rate of 0.1, (min gen=1000.0, max gen=10000.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 61
Speciation rate of 0.2, (min gen=1000.0, max gen=10000.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 52
Speciation rate of 0.3, (min gen=1000.0, max gen=10000.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 52
Speciation rate of 0.1, (min gen=10.0, max gen=5000.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 376
Speciation rate of 0.2, (min gen=10.0, max gen=5000.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 405
Speciation rate of 0.3, (min gen=10.0, max gen=5000.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 422
Speciation rate of 0.1, (min gen=50.0, max gen=800.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 259
Speciation rate of 0.2, (min gen=50.0, max gen=800.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 274
Speciation rate of 0.3, (min gen=50.0, max gen=800.0)
Metacommunity used of size 100000.0 with speciation rate 0.001.
Species richness: 280

Clean up

Delete the objects from memory to clear from RAM - this is not usually required as objects will be deleted when they fall out of scope.

sim1 = None
sim2 = None
sim3 = None
tree1 = None
tree2 = None
tree3 = None

Code Documentation

Modules

pycoalescence package

pycoalescence provides the facilities for running spatially explicit neutral coalescence ecological simulations and performing basic analysis of the simulation outputs. The program requires necsim to function properly.

Key submodules

These are the most important modules for running and analysing spatially explicit neutral models, and are most likely to be used directly.

simulation module

Run spatially explicit neutral simulations on provided landscapes with support for a wide range of scenarios and parameters. Detailed here.

The main class is Simulation, which contains routines for setting up and running simulations, plus basic tree generation after simulations have been completed.

input:

• Simulation parameters (such as dispersal kernel, speciation rate)
• Map files representing density over space
• [optional] map files representing relative reproductive ability
• [optional] map files representing dispersal potential
• [optional] historical density map files

output:

• Database containing generated coalescence tree, simulation parameters and basic biodiversity metrics.
• If the simulation does not complete, will instead dump data to a Dump_main_*_*.csv file for resuming simulations.

class Simulation(logging_level=30, log_output=None, **kwargs)

Bases: pycoalescence.landscape.Landscape

A class containing routines to set up and run simulations, including detecting map dimensions from tif files.

add_death_map(death_map)

Adds a death map to the simulation.

Parameters:death_map (str/pycoalescence.Map) – the death map to import Return type:None

add_dispersal_map(dispersal_map)

Adds a dispersal map to the simulation.

Parameters:dispersal_map (str/pycoalescence.Map) – the dispersal map to import Return type:None

add_gillespie(generations=0.0)

Uses the Gillespie algorithm from the given number of generations into the simulation. :param generations: the number of generations at which to use gillespie.

Return type:None Returns:None

add_reproduction_map(reproduction_map)

Adds a death map to the simulation.

Parameters:reproduction_map (str/pycoalescence.Map) – the death map to import Return type:None

add_sample_time(time)

Adds an extra sample time to the list of times.

This allows for multiple temporal sample points from within the same simulation.

Parameters:time – the sample time to add

apply_speciation_rates(speciation_rates=None)

Applies the speciation rates to the coalescence tree and outputs to the database.

Parameters:speciation_rates – a list of speciation rates to apply Return type:None

calculate_sql_database()

Saves the output database location to self.output_database.

check_can_use_gillespie()

Checks if the simulation can use the Gillespie algorithm.

Returns:true if the simulation can use Gillespie Return type:bool

check_death_map()

Checks that the death map dimensions match the fine map dimensions.

check_dimensions_match_fine(map_to_check, name='')

Checks that the dimensions of the provided map matches the fine map.

Parameters:

• map_to_check (Map) – map to check the dimensions of against the fine map
• name (str) – name to write out in error message

Returns:

true if the dimensions match

check_dispersal_map()

Checks that the dispersal map dimensions match the fine map dimensions.

check_file_parameters(expected=False)

Check that all the required files exist for the simulation and the output doesn’t already exist.

Parameters:expected – set to true if we expect the output file to already exist Raises:RuntimeError – if previous set-up routines are not complete

check_maps()

Checks that the maps all exist and that the file structure makes sense.

Raises:ValueError – if the grid is not within the sample map. Returns:None

check_reproduction_map()

Checks that the reproduction map dimensions match the fine map dimensions.

check_sample_map_equals_sample_grid()

Checks if the grid and sample map are the same size and offset (in which case, future operations can be simplified).

Returns:true if the grid and sample map dimensions and offsets are equal Return type:bool

check_simulation_parameters(expected=False, ignore_errors=False)

Checks that simulation parameters have been correctly set and the program is ready for running.

Parameters:

• ignore_errors – if true, any FileNotFoundError and FileExistsError raised by checking the output database are ignored
• expected – set to true if we expect the output file to exist

check_sql_database(expected=False)

Checks whether the output database exists. If the existance does not match the expected variable, raises an error.

Raises:

• FileExistsError – if the file already exists when it’s not expected to
• FileNotExistsError – if the file does not exist when we expect it to

Parameters:

expected – boolean for expected existance of the output file

Return type:

None

count_individuals()

Estimates the number of individuals to be simulated. This may be inaccurate if using multiple time points and historical maps.

Returns:a count of the number of individuals to be simulated Return type:float

create_config(output_file=None)

Generates the configuration. This will be written out either by providing an output file here, or by calling write_config();

Parameters:output_file (str) – the file to generate the config option. Must be a path to a .txt file.

create_map_config(output_file=None)

Generates the map config file from reading the spatial structure of each of the provided files.

Parameters:output_file (str) – the file to output configuration data to (the map config file)

create_temporal_sampling_config()

Creates the time-sampling config file.

Function is called automatically when creating a config file, and should not be manually called.

detect_map_dimensions()

Detects all the map dimensions for the provided files (where possible) and sets the respective values. This is intended to be run after set_map_files()

Returns:None

finalise_setup(expected=False, ignore_errors=False)

Runs all setup routines to provide a complete simulation. Should be called immediately before run_coalescence() to ensure the simulation setup is complete.

Parameters:

• ignore_errors – if true, any FileNotFoundError and FileExistsError raised by checking the output database are ignored
• expected – set to true if we expect the output file to exist

get_average_density()

Gets the average density across the fine map, subsetted for the sample grid.

get_optimised_solution()

Gets the optimised solution as a dictionary containing the important optimised variables. This can be read back in with set_optimised_solution

Returns:dict containing the important optimised variables Return type:dict

get_protracted()

Gets whether the simulation pointed to by this object is a protracted simulation or not.

get_species_richness(reference=1)

Calls coal_analyse.get_species_richness() with the supplied variables.

Requires successful import of coal_analyse and sqlite3.

Parameters:reference (int) – the community reference to obtain the metrics for. Returns:the species richness.

grid_density_actual(x_off, y_off, x_dim, y_dim)

Counts the density total for a subset of the grid by sampling from the fine map.

Note that for large maps this can take a very long time.

Parameters:

• x_off – the x offset of the grid map subset
• y_off – the y offset of the grid map subset
• x_dim – the x dimension of the grid map subset
• y_dim – the y dimension of the grid map subset

Returns:

the total individuals that exist in the subset.

Return type:

int

grid_density_estimate(x_off, y_off, x_dim, y_dim)

Counts the density total for a subset of the grid by sampling from the fine map

Note:

This is an approximation (based on the average density of the fine map) and does not produce a perfect value. This is done for performance reasons. The actual value can be obtained with grid_density_actual().

Parameters:

• x_off – the x offset of the grid map subset
• y_off – the y offset of the grid map subset
• x_dim – the x dimension of the grid map subset
• y_dim – the y dimension of the grid map subset

Returns:

an estimate of the total individuals that exist in the subset.

Return type:

int

import_fine_map_array()

Imports the fine map array to the in-memory object, subsetted to the same size as the sample grid.

Return type:None

import_sample_map_array()

Imports the sample map array to the in-memory object.

Return type:None

load_config(config_file)

Loads the config file by reading the lines in order.

Parameters:config_file (str) – the config file to read in.

optimise_ram(ram_limit)

Optimises the maps for a specific RAM usage.

If ram_limit is None, this function does nothing.

Note:Assumes that the C++ compiler has sizeof(long) = 8 bytes for calculating space usage. Note:Only optimises RAM for a square area of the map. For rectangular shapes, will use the shortest length as a maximum size. Parameters:ram_limit – the desired amount of RAM to limit to, in GB Raises:MemoryError – if the desired simulation cannot be compressed into available RAM

persistent_ram_usage()

This is the persistent RAM usage which cannot be optimised by the program for a particular set of maps

Returns:the total persistent RAM usage in bytes

resume_coalescence(pause_directory, seed, task, max_time, out_directory=None, protracted=None, spatial=None)

Resumes the simulation from the specified directory, looking for the simulation with the specified seed and task referencing.

Parameters:

• pause_directory – the directory to search for the paused simulation
• seed – the seed of the paused simulation
• task – the task of the paused simulation
• max_time – the maximum time to run simulations for
• out_directory – optionally provide an alternative output location. Defaults to same location as

pause_directory :param bool protracted: protractedness of the simulation :param bool spatial: if the simulation is to be run with spatial complexity

Returns:None

run()

Convenience function which completes setup, runs the simulation and calculates the coalescence tree for the set speciation rates in one step.

Return type:None

run_coalescence()

Attempt to run the simulation with the given simulation set-up. This is the main routine performing the actual simulation which will take a considerable amount of time.

Returns:True if the simulation completes successfully, False if the simulation pauses. Return type:bool

run_simple(seed, task, output, speciation_rate, sigma, size)

Runs a simple coalescence simulation on a square infinite landscape with the provided parameters. This requires a separate compilation of the inf_land version of the coalescence simulator.

Note that this function returns richness=0 for failure to read from the file. It is assumed that there will be at least one species in the simulation.

Note that the maximum time for this function is set as 10 hours (36000 seconds) and will raise an exception if the simulation does not complete in this time).

Raises:

RuntimeError – if the simulation didn’t complete in time.

Parameters:

• seed – the simulation seed
• task – the task (for file naming)
• output – the output directory
• speciation_rate – the probability of speciation
• sigma – the normal distribution sigma value for dispersal
• size – the size of the world (so there will be size^2 individuals simulated)

Returns:

the species richness in the simulation

set_config_file(output_file=None)

Sets the config file to the output, over-writing any existing config file that has been stored.

Parameters:output_file – path to config file to output to

set_map_files(sample_file, fine_file=None, coarse_file=None, historical_fine_file=None, historical_coarse_file=None, dispersal_map=None, death_map=None, reproduction_map=None)

Sets the map files (or to null, if none specified). It then calls detect_map_dimensions() to correctly read in the specified dimensions.

If sample_file is “null”, dimension values will remain at 0. If coarse_file is “null”, it will default to the size of fine_file with zero offset. If the coarse file is “none”, it will not be used. If the historical fine or coarse files are “none”, they will not be used.

Note

the dispersal map should be of dimensions xy by xy where x, y are the fine map dimensions. Dispersal rates from each row/column index represents dispersal from the row index to the column index according to index = x+(y*xdim), where x,y are the coordinates of the cell and xdim is the x dimension of the fine map. See the PatchedLandscape class for routines for generating these landscapes.

Parameters:

• sample_file (str) – the sample map file. Provide “null” if on samplemask is required
• fine_file (str) – the fine map file. Defaults to “null” if none provided
• coarse_file (str) – the coarse map file. Defaults to “none” if none provided
• historical_fine_file (str) – the historical fine map file. Defaults to “none” if none provided
• historical_coarse_file (str) – the historical coarse map file. Defaults to “none” if none provided
• dispersal_map (str) – the dispersal map for reading dispersal values. Default to “none” if none provided
• death_map (str) – a map of relative death probabilities, at the scale of the fine map
• reproduction_map (str) – a map of relative reproduction probabilities, at the scale of the fine map

Return type:

None

Returns:

None

set_optimised_solution(dict_in)

Sets the optimised RAM solution from the variables in the provided dictionary. This should contain the grid_x_size, grid_y_size, grid_file_name, sample_x_offset and sample_y_offset.

Parameters:dict_in (dict) – the dictionary containing the optimised RAM solution variables Return type:None

set_seed(seed)

Sets the seed for the simulation.

A seed < 1 should not be set for the necsim, as equivalent behaviour is produce for seed and abs(seed), plus for seed = 1 and seed = 0. Consequently, for any values less than 1, we take a very large number plus the seed, instead. Therefore a error is raised if the seed exceeds this very large number (this is an acceptable decrease in userability as a seed that large is unlikely to ever be used).

Parameters:seed (int) – the random number seed

set_simulation_parameters(seed, task, output_directory, min_speciation_rate, sigma=1.0, tau=1.0, deme=1.0, sample_size=1.0, max_time=3600, dispersal_method=None, m_prob=0.0, cutoff=0, dispersal_relative_cost=1, min_num_species=1, restrict_self=False, landscape_type=False, protracted=False, min_speciation_gen=None, max_speciation_gen=None, spatial=True, uses_spatial_sampling=False, times=None)

Set all the simulation parameters apart from the map objects.

Parameters:

• seed (int) – the unique job number for this simulation set
• task (int) – the task reference number (used for easy file identification after simulations are complete)
• output_directory (str) – the output directory to store the SQL database
• min_speciation_rate (float) – the minimum speciation rate to simulate
• sigma (float) – the dispersal sigma value
• tau (float) – the fat-tailed dispersal tau value
• deme (float) – the deme size (in individuals per cell)
• sample_size (float) – the sample size of the deme (decimal 0-1)
• max_time (float) – the maximum allowed simulation time (in seconds)
• dispersal_method (str) – the dispersal kernel method. Should be one of [normal, fat-tail, norm-uniform]
• m_prob (float) – the probability of drawing from the uniform dispersal. Only relevant for uniform dispersals
• cutoff (float) – the maximum value for the uniform dispersal. Only relevant for uniform dispersals.
• dispersal_relative_cost (float) – the relative cost of travelling through non-habitat (defaults to 1)
• min_num_species (int) – the minimum number of species known to exist (defaults to 1
• restrict_self (bool) – if true, restricts dispersal from own cell
• landscape_type (bool/str) – if false or “closed”, restricts dispersal to the provided maps, otherwise can be “infinite”, or a tiled landscape using “tiled_coarse” or “tiled_fine”, or a clamped landscape using “clamped_coarse” or “clamped_fine”.
• protracted (bool) – if true, uses protracted speciation application
• min_speciation_gen (float) – the minimum amount of time a lineage must exist before speciation occurs.
• max_speciation_gen (float) – the maximum amount of time a lineage can exist before speciating.
• spatial (bool) – if true, means that the simulation is spatial
• uses_spatial_sampling (bool) – if true, the sample mask is interpreted as a proportional sampling mask, where the number of individuals sampled in the cell is equal to the density * deme_sample * cell sampling proportion
• times (list) – list of temporal sampling points to apply (in generations)

set_speciation_rates(speciation_rates)

Add speciation rates for analysis at the end of the simulation. This is optional

Parameters:speciation_rates (list) – a list of speciation rates to apply at the end of the simulation

setup_necsim()

Calculates the type of the simulation (spatial/non-spatial, protracted/non-protracted) and sets the c object appropriately.

Return type:None

write_config(config_file)

Writes the config to the config file provided, overwriting any existing config files.

Parameters:config_file – the config file to write out to Return type:None

coalescence_tree module

Generate the coalescence tree and acquire a number of biodiversity metrics for different parameter sets. Can also be used to compare against a comparison simulation object.

input:

• Completed simulation database from Simulation
• Parameters and operations to apply

output:

• A variety of biodiversity metrics, including species richness and abundance distributions, locations of each species, alpha and beta diversity, plus equivalent fragment biodiversity metrics.
• Modifies the simulation database in place.

class CoalescenceTree(database=None, logging_level=30, log_output=None)

Bases: object

Contains the coalescence tree and performs various calculations of different biodiversity metrics, which are then stored in the SQLite database.

The general process is

• Import the database (set_database()) and import the comparison data, if required (import_comparison_data())
• Apply additional speciation rates (if required) using set_speciation_parameters() and then apply()
• Calculate required metrics (such as calculate_fragment_richness())
• Optionally, calculate the goodness of fit (calculate_goodness_of_fit())

add_metacommunity_parameters(metacommunity_size=None, metacommunity_speciation_rate=None, metacommunity_option=None, metacommunity_reference=0)

Adds the metacommunity parameters to the object.

Parameters:

• metacommunity_size (float) – the number of individuals in the metacommunity
• metacommunity_speciation_rate (float) – the speciation rate within the metacommunity
• metacommunity_option (str) – either “simulated”, “analytical”, or a path to a database to read SADs from
• metacommunity_reference (int) – the metacommunity reference if using a database to provide the metacommunity

Return type:

None

add_multiple_protracted_parameters(min_speciation_gens=None, max_speciation_gens=None, speciation_gens=None)

Adds the protracted parameter set, taking an iterable as an input.

Note

Using the keyword arguments, one can supply either a list of tuples for pairs of speciation generations, or two lists of generations for the min and max, matching in order.

Parameters:

• min_speciation_gens – the minimum number of generations required before speciation is permitted. Order should match that of max_speciation_gens
• max_speciation_gens – the maximum number of generations required before speciation is permitted. Order should match that of min_speciation_gens
• speciation_gens – a list of tuples of min/max speciation generations.

add_protracted_parameters(min_speciation_gen, max_speciation_gen)

Adds the protracted parameter set.

Note

Wipes (0.0, 0.0) from protracted parameters, if it is there alone.

Parameters:

• min_speciation_gen – the minimum number of generations required before speciation is permitted
• max_speciation_gen – the maximum number of generations required before speciation is permitted

add_time(time)

Adds the time to the list to be applied.

Parameters:time – the time to be applied

add_times(times)

Adds the list of times to those to be applied.

Parameters:times – list of times to be applied

adjust_data()

Ensures that the numbers of individuals are equalised between the comparison and simulated datasets, and modifies the relevant tables with the new data

apply()

Generates the cooalescence tree for the set of speciation parameters. This must be run after the main coalescence simulations are complete. It will create additional fields and tables in the SQLite database which contains the requested data.

apply_incremental()

Generates the coalescence tree for the set of speciation parameters. Does not write changes to the database, just holds the changes internally.

apply_non_spatial_remaining(database)

Applies the non-spatial neutral model to the remaining lineages. This approximation is reasonable on a closed landscape once the lineages themselves are close to randomly distributed.

Parameters:database – the database file to open Returns:None Return type:None

calculate_alpha_diversity(output_metrics=True)

Calculates the system alpha diversity for each set of parameters stored in COMMUNITY_PARAMETERS. Stores the output in ALPHA_DIVERSITY table.

Parameters:output_metrics (bool) – output to the BIODIVERSITY_METRICS table

calculate_beta_diversity(output_metrics=True)

Calculates the beta diversity for the system for each speciation parameter set and stores the output in BETA_DIVERSITY. Will calculate alpha diversity and species richness tables if they have not already been performed.

Parameters:output_metrics (bool) – output to the BIODIVERSITY_METRICS table

calculate_comparison_octaves(store=False)

Calculates the octave classes for the comparison data and for fragments (if required). If the octaves exist in the FRAGMENT_OCTAVES table in the comparison database, the data will be imported instead of being re-calculated.

Note

If store is True, will store an EDITED version of the comparison octaves, such that the number of

individuals is equal between the comparison and simulated data.

Parameters:store – if True, stores within the comparison database.

calculate_fragment_abundances()

Calculates the fragment abundances, including equalising with the comparison database, if it has already been set.

Sets fragment_abundances object.

calculate_fragment_octaves()

Calculates the octave classes for each fragment. Outputs the calculated richness into the SQL database within a FRAGMENT_OCTAVES table

calculate_fragment_richness(output_metrics=True)

Calculates the fragment richness and stores it in a new table called FRAGMENT_RICHNESS. Also adds the record to BIODIVERSITY METRICS for If the table already exists, it will simply be returned. Each time point and speciation rate combination will be recorded as a new variable.

Parameters:output_metrics (bool) – output to the BIODIVERSITY_METRICS table

calculate_goodness_of_fit()

Calculates the goodness-of-fit measure based on the calculated biodiversity metrics, scaling each metric by the number of individuals involved in the metric.

This requires that import_comparison_data() has already been successfully run.

Note

This doesn’t calculate anything for values which have not yet been written to the BIODIVERSITY_METRICS table. All in-built functions (e.g. calculate_alpha_diversity, calculate_fragment_richness) write to the BIODIVERSITY_METRICS table automatically, so this is only relevant for custom functions.

The resulting value will then be written to the BIODIVERSITY_METRICS table in the SQL database.

calculate_octaves()

Calculates the octave classes for the landscape. Outputs the calculated richness into the SQL database within a FRAGMENT_OCTAVES table.

calculate_octaves_error()

Calculates the error in octaves classes between the simulated data and the comparison data. Stores each error value as a new entry in BIODIVERSITY_METRICS under fragment_octaves. Calculates the error by comparing each octave class and summing the relative difference. Octaves are then averaged for each fragment.

calculate_richness(output_metrics=True)

Calculates the landscape richness from across all fragments and stores result in a new table in SPECIES_RICHNESS Stores a separate result for each community reference.

Parameters:output_metrics (bool) – output to the BIODIVERSITY_METRICS table

calculate_species_distance_similarity(output_metrics=True)

Calculates the probability two individuals are of the same species as a function of distance.

Stores the mean distance between individuals of the same species in the BIODIVERSITY_METRICS table, and stores the full data in new table (SPECIES_DISTANCE_SIMILARITY). Distances are binned to the nearest integer.

Parameters:output_metrics – if true, outputs to the BIODIVERSITY_METRICS table as well, for metric comparison

Note

Extremely slow for large landscape sizes.

check_biodiversity_table_exists()

Checks whether the biodiversity table exists and creates the table if required.

Returns:the max reference value currently existing

clear_calculations()

Removes the BIODIVERSITY_METRICS and FRAGMENT_OCTAVES tables completely.

Note

that this cannot be undone (other than re-running the calculations).

dispersal_parameters()

Reads the dispersal parameters from the database and returns them.

Returns:a dict of the dispersal parameters (dispersal method, sigma, tau, m_probability and cutoff)

downsample(sample_proportion)

Down-samples the individuals by a given proportion globally, and at each location.

The original SPECIES_LIST is stored in a new table called SPECIES_LIST_ORIGINAL and a new SPECIES_LIST object is created containing the down-sampled coalescence tree.

Parameters:sample_proportion (float) – the proportion of individuals to sample at each location Returns:None Return type:None

downsample_at_locations(fragment_csv, ignore_errors=False)

Downsamples the SPECIES_LIST object using a fragment csv.

Each row in the csv file should contain the fragment name, x min, y min, x max, y max and the number of individuals per cell in that fragment.

Parameters:

• fragment_csv – a csv file to use for downsampling individuals
• ignore_errors – ignore the errors from mismatches in numbers of individuals

Returns:

None

Return type:

None

get_all_fragment_abundances()

Returns the whole table of fragment abundances from the database.

Returns:a list of reference, fragment, species_id, no_individuals

get_alpha_diversity(reference=1)

Gets the system alpha diversity for the provided community reference parameters. Alpha diversity is the mean number of species per fragment. :param reference: the community reference for speciation parameters :return: the alpha diversity of the system

get_alpha_diversity_pd()

Gets the alpha diversity for each set of community parameters.

Returns:all alpha diversity values Return type:pandas.DataFrame

get_beta_diversity(reference=1)

Gets the system beta diversity for the provided community reference parameters. Beta diversity is the true beta diversity (gamma / alpha). :param reference: the community reference for speciation parameters :return: the beta diversity of the system

get_beta_diversity_pd()

Gets the beta diversity for each set of community parameters.

Returns:all beta diversity values Return type:pd.DataFrame

get_biodiversity_metrics()

Get calculated biodiversity metrics.

Returns:all biodiversity metrics Return type:pandas.DataFrame

get_community_parameters(reference=1)

Returns a dictionary containing the parameters for the calculated community.

Parameters:reference – the reference key for the calculated parameters (default is 1) Returns:dictionary containing the speciation_rate, time, fragments, metacommunity_reference and min/max speciation generation for protracted sims Return type:dict

get_community_parameters_pd()

Gets all the calculated community parameter sets from the database.

Returns:the community parameters Return type:pd.DataFrame

get_community_reference(speciation_rate, time, fragments, metacommunity_size=0, metacommunity_speciation_rate=0.0, metacommunity_option=None, external_reference=0, min_speciation_gen=0.0, max_speciation_gen=0.0)

Gets the community reference associated with the supplied community parameters

Raises:

KeyError – if COMMUNITY_PARAMETERS (or METACOMMUNITY_PARAMETERS) does not exist in database or no reference exists for the supplied parameters

Parameters:

• speciation_rate (float) – the speciation rate of the community
• time (float) – the time in generations of the community
• fragments (bool/int) – whether fragments were determined for the community
• metacommunity_size (int/float) – the metacommunity size
• metacommunity_speciation_rate (float) – the metacommunity speciation rate
• metacommunity_option (str) – option used for metacommunity creation
• external_reference (int) – the metacommunity reference for external metacommunity databases
• min_speciation_gen (float) – the minimum number of generations required before speciation
• max_speciation_gen (float) – the maximum number of generations required before speciation

Returns:

the reference associated with this set of simulation parameters

get_community_references()

Gets a list of all the commuity references already calculated for the simulation.

Returns:list of all calculated community references Return type:list

get_fragment_abundances(fragment, reference)

Gets the species abundances for the supplied fragment and community reference.

Parameters:

• fragment – the name of the fragment to obtain
• reference – the reference for speciation parameters to obtain for

Returns:

a list of species ids and abundances

get_fragment_abundances_pd()

Gets the fragment abundances for each set of community parameters.

Returns:the fragment abundances for each associated community reference Return type:pandas.DataFrame

get_fragment_list(community_reference=1)

Returns a list of all fragments that exist in FRAGMENT_ABUNDANCES.

Parameters:community_reference – community reference to obtain for (default 1) Returns:list all all fragment names

get_fragment_octaves(fragment=None, reference=None)

Get the pre-calculated octave data for the specified fragment, speciation rate and time. If fragment and speciation_rate are None, returns the entire FRAGMENT_OCTAVES object This requires self.calculate_fragment_octaves() to have been run successfully at some point previously.

Returns are of form [id, fragment, community_reference, octave class, number of species]

Parameters:

• fragment – the desired fragment (defaults to None)
• reference – the reference key for the calculated community parameters

Returns:

output from FRAGMENT_OCTAVES for the selected variables

get_fragment_octaves_pd()

Gets the octave classes for each fragment and community parameter set

Returns:all fragment octave classes Return type:pandas.DataFrame

get_fragment_richness(fragment=None, reference=None)

Gets the fragment richness for each speciation rate and time for the specified simulation.

If the fragment richness has not yet been calculated, it tries to calculate the fragment richness,

Parameters:

• fragment (str) – the desired fragment (defaults to None)
• reference (int) – the reference key for the calculated community parameters

Raises:

sqlite3.Error if no table FRAGMENT_ABUNDANCES exists

Raises:

RuntimeError if no data for the specified fragment, speciation rate and time exists.

Returns:

A list containing the fragment richness, or a value of the fragment richness

Return type:

list

get_fragment_richness_pd()

Gets the fragment richness for each set of community parameters.

Returns:the fragment richness for each associated community reference Return type:pandas.DataFrame

get_goodness_of_fit(reference=1)

Returns the goodness of fit from the file.

Parameters:reference – the community reference to get from Returns:the full output from the SQL query Return type:float

get_goodness_of_fit_fragment_octaves(reference=1)

Returns the goodness of fit for fragment octaves from the file.

Note

If more than one metric matches the specified criteria, only the first will be returned.

Raises:ValueError – if BIODIVERSITY_METRICS table does not exist. Parameters:reference – the community reference number Returns:the full output from the SQL query Return type:double

get_goodness_of_fit_fragment_richness(reference=1)

Returns the goodness of fit for fragment richness from the file.

Raises:ValueError – if BIODIVERSITY_METRICS table does not exist. Parameters:reference – the community reference number Returns:the full output from the SQL query Return type:float

get_goodness_of_fit_metric(metric, reference=1)

Gets the goodness-of-fit measure for the specified metric and community reference.

Parameters:

• metric – the metric goodness of fit has been calculated for to obtain
• reference – the community reference to fetch fits for

Returns:

the goodness of fit value

Return type:

float

get_job()

Gets the job number (the seed) and the task identifier.

Returns:list containing [seed, task]

get_metacommunity_parameters(reference=1)

Returns a dictionary containing the parameters for the calculated community.

Parameters:

reference – the reference key for the calculated parameters. (default is 1)

Raises:

• sqlite3.Error – if the METACOMMUNITY_PARAMETERS table does not exist, or some other sqlite error occurs
• KeyError – if the supplied reference does not exist in the METACOMMUNITY_PARAMETERS table

Returns:

dictionary containing the speciation_rate, metacommunity_size, metacommunity option and metacommunity reference.

Return type:

dict

get_metacommunity_parameters_pd()

Gets all the calculated metacommunity parameter sets from the database.

Returns:the metacommunity parameters Return type:pd.DataFrame

get_metacommunity_references()

Gets a list of all the metacommuity references already calculated for the simulation.

Note

Returns an empty list and logs an error message if the METACOMMUNITY_PARAMETERS table does not exist.

Returns:list of all calculated metacommunity references Return type:list

get_number_individuals(fragment=None, community_reference=None)

Gets the number of individuals that exist, either in the provided fragment, or on the whole landscape in one time slice. Counts individuals from FRAGMENT_ABUNDANCES or SPECIES_ABUNDANCES, respectively.

If a community reference is provided, only individuals for that time slice will be counted, otherwise a mean is taken across time slices.

Parameters:

• fragment – the name of the fragment to get a count of individuals from
• community_reference – the reference to the community parameters

Returns:

the number of individuals that exists in the desired location

get_octaves(reference)

Get the pre-calculated octave data for the parameters associated with the supplied reference. This will call self.calculate_octaves() if it hasn’t been called previously.

Returns are of form [id, ‘whole’, time, speciation rate, octave class, number of species]

Parameters:reference – community reference which contains the parameters of interest Returns:output from FRAGMENT_OCTAVES on the whole landscape for the selected variables

get_octaves_pd()

Gets the species octaves for all calculated community parameters

Returns:all octave classes for the whole landscape Return type:pandas.DataFrame

get_parameter_description(key=None)

Gets the description of the parameter matching the key from those contained in SIMULATION_PARAMETERS

Simply accesses the _parameter_descriptions data stored in parameter_descriptions.json

Returns:string containing the parameter description or a dict containing all values if no key is supplied Return type:str

get_simulation_parameters(guild=None)

Reads the simulation parameters from the database and returns them.

Returns:a dictionary mapping names to values for seed, task, output_dir, speciation_rate, sigma,

L_value, deme, sample_size, maxtime, dispersal_relative_cost, min_spec, habitat_change_rate, gen_since_historical, time_config, coarse_map vars, fine map vars, sample_file, gridx, gridy, historical coarse map, historical fine map, sim_complete, dispersal_method, m_probability, cutoff, landscape_type, protracted, min_speciation_gen, max_speciation_gen, dispersal_map

get_species_abundances(fragment=None, reference=None)

Gets the species abundance for a particular fragment, speciation rate and time. If fragment is None, returns the whole landscape species abundances.

Parameters:

• fragment (str) – the fragment to obtain the species abundance of. If None, returns landscape abundances.
• reference (int) – the commmunity reference to obtain metrics for

Returns:

list of species abundances [reference, species ID, speciation rate, number of individuals, generation]

get_species_abundances_pd()

Gets the species abundances for all community parameter sets.

Returns:all species abundances Return type:pandas.DataFrame

get_species_distance_similarity(community_reference=1)

Gets the species distance similarity table for the provided community reference.

Returns:list containing the distance, number of similar species with that distance

get_species_list()

Gets the entirety of the SPECIES_LIST table, returning a tuple with an entry for each row. This can be used to construct custom analyses of the coalescence tree.

Note

The species list will be produced in an unprocessed format

Returns:a list of each coalescence and speciation event, with locations, performed in the simulation Return type:tuple

get_species_locations(community_reference=None)

Gets the list of species locations after coalescence.

If a community reference is provided, will return just the species for that community reference, otherwise returns the whole table

Parameters:community_reference (int) – community reference number Returns:a list of lists containing each row of the SPECIES_LOCATIONS table

get_species_richness(reference=1)

Get the system richness for the parameters associated with the supplied community reference.

Note

Richness of 0 is returned if there has been some problem; it is assumed that species richness will be above 0 for any simulation.

Note

if species richness has previously been calculated and stored in SPECIES_RICHNESS table, it gets the species richness value from there, otherwise it calculates the species richness

Parameters:reference – community reference which contains the parameters of interest Returns:either a list containing the community references and respective species richness values OR (if community_reference is provided), the species richness for that community reference. Return type:int, list

get_species_richness_pd()

Gets the species richness for all calculated parameters from the database.

Returns:all species richness values with their associated community reference Return type:pandas.DataFrame

get_total_number_individuals()

Gets the total number of individuals that exist in the simulation. :return: the total number of individuals simulated across time slices

import_comparison_data(filename, ignore_mismatch=False)

Imports the SQL database that contains the biodiversity metrics that we want to compare against.

This can either be real data (for comparing simulated data) or other simulated data (for comparing between models).

If the SQL database does not contain the relevant biodiversity metrics, they will be calculated (if possible) or skipped.

The expected form of the database is the same as the BIODIVERSITY_METRICS table, except without any speciation rates or time references, and a new column containing the number of individuals involved in each metric.

Note

This also equalises the comparison data if ignore_mismatch is not True, so that the number of individuals is equal between the simulated and comparison datasets.

Parameters:

• filename (str) – the file containing the comparison biodiversity metrics.
• ignore_mismatch (bool) – set to true to ignore abundance mismatches between the comparison and simulated

data.

is_protracted()

Indicates whether the simulation is a protracted simulation or not. This is read from the completed database file.

Returns:boolean, true if the simulation was performed with protracted speciation.

output()

Outputs the coalescence trees to the same simulation database object.

revert_downsample()

Reverts the downsample process by restoring the original SPECIES_LIST table.

Returns:None Return type:None

sample_fragment_richness(fragment, number_of_individuals, community_reference=1, n=1)

Samples from the database from FRAGMENT_ABUNDANCES, the desired number of individuals.

Randomly selects the desired number of individuals from the database n times and returns the mean richness for the random samples.

Raises:

IOError – if the FRAGMENT_ABUNDANCES table does not exist in the database.

Parameters:

• fragment – the reference of the fragment to aquire the richness for
• number_of_individuals – the number of individuals to sample
• community_reference – the reference for the community parameters
• n – number of times to repeatedly sample

Returns:

the mean of the richness from the repeats

Return type:

float

sample_landscape_richness(number_of_individuals, n=1, community_reference=1)

Samples from the landscape the required number of individuals, returning the mean of the species richnesses produced.

If number_of_individuals is a dictionary mapping fragment names to numbers sampled, will sample the respective number from each fragment and return the whole landscape richness.

Raises:

KeyError – if the dictionary supplied contains more sampled individuals than exist in a fragment, or if the fragment is not contained within the dictionary.

Parameters:

• number_of_individuals (int/dict) – either an int containing the number of individuals to be sampled, or a dictionary mapping fragment names to numbers of individuals to be sampled
• n – the number of repeats to average over
• community_reference – the community reference to fetch abundances for

Returns:

the mean of the richness from the repeats for the whole landscape

Return type:

float

set_database(filename)

Sets the database to the specified file and opens the sqlite connection.

This must be done before any other operations can be performed and the file must exist.

Raises:IOError – if the simulation is not complete, as analysis can only be performed on complete simulations. However, the database WILL be set before the error is thrown, allowing for analysis of incomplete simulations if the error is handled correctly. Parameters:filename (pycoalescence.simulation.Simulation/str) – the SQLite database file to import

set_speciation_parameters(speciation_rates, record_spatial=False, record_fragments=False, sample_file=None, times=None, protracted_speciation_min=None, protracted_speciation_max=None, metacommunity_size=None, metacommunity_speciation_rate=None, metacommunity_option=None, metacommunity_reference=None)

Set the parameters for the application of speciation rates. If no config files or time_config files are provided, they will be taken from the main coalescence simulation.

Parameters:

• speciation_rates (float/list) – a single float, or list of speciation rates to apply
• str record_spatial (bool,) – a boolean of whether to record spatial data (default=False)
• str record_fragments (bool,) – either a csv file containing fragment data, or T/F for whether fragments should be calculated from squares of continuous habitat (default=False)
• sample_file (str) – a sample tif or csv specifying the sampling mask
• times (list) – a list of times to apply (should have been run with the original simulation)
• protracted_speciation_min (float) – the minimum number of generations required for speciation to occur
• protracted_speciation_max (float) – the maximum number of generations before speciation occurs
• metacommunity_size (float) – the size of the metacommunity to apply
• metacommunity_speciation_rate (float) – speciation rate for the metacommunity
• metacommunity_option (str) – either “simulated”, “analytical”, or a path to a database to read SADs from
• metacommunity_reference (int) – the metacommunity reference if using a database to provide the metacommunity

Return type:

None

speciate_remaining(database)

Speciates the remaining lineages in a paused database.

Parameters:database (str/pycoalescence.simulation.Simulation) – the paused database to open Return type:None

wipe_data()

Wipes all calculated data apart from the original, unformatted coalescence tree. The Speciation_Counter program will have to be re-run to perform any analyses.

write_all_to_csvs(output_location, file_naming)

Outputs all tables from the database to csvs contained in the provided directory and following the naming structure of the supplied file naming.

Parameters:

• output_location (str) – the folder to generate files in
• file_naming – the naming for the output csvs - will be appended with _{table_name}.csv

Returns:

Note

dots and “.csv” extensions are removed from the file_naming output

write_to_csv(output_csv, table_name)

Writes a specified table from the database to the output database.

Parameters:

• output_csv (str) – path to the csv output location
• table_name (str) – name of the output table

Returns:

None

Return type:

None

get_parameter_description(key=None)

Gets the parameter descriptions for the supplied key. If the key is None, returns all keys.

Parameters:key – the simulation parameter Returns:string containing the parameter description or a dict containing all values if no key is supplied

scale_simulation_fit(simulated_value, actual_value, number_individuals, total_individuals)

Calculates goodness of fit for the provided values, and scales based on the total number of individuals that exist. The calculation is 1 - (abs(x - y)/max(x, y)) * n/n_tot for x, y simulated and actual values, n, n_tot for metric and total number of individuals.

Parameters:

• simulated_value – the simulated value of the metric
• actual_value – the actual value of the metric
• number_individuals – the number of individuals this metric relates to
• total_individuals – the total number of individuals across all sites for this metric

Returns:

the scaled fit value

Additional submodules

All additional modules which are required for package functionality, but are unlikely to be used directly.

dispersal_simulation module

Simulate dispersal kernels on landscapes. Detailed here.

input:

• Map file to simulate on
• Set of dispersal pararameters, including the dispersal kernel, number of repetitions and landscape properties

output:

• Database containing each distance travelled so that metrics can be calculated.
• A table is created for mean dispersal distance over a single step or for mean distance travelled.

class DispersalSimulation(dispersal_db=None, file=None, logging_level=30)

Bases: pycoalescence.landscape.Landscape

Simulates a dispersal kernel upon a tif file to calculate landscape-level dispersal metrics.

check_base_parameters(number_repeats=None, seed=None, sequential=None, number_workers=None, dispersal=False)

Checks that the parameters have been set properly.

Parameters:

• number_repeats (int) – the number of times to iterate on the map
• seed (int) – the random seed
• sequential (bool) – if true, runs repeats in the dispersal simulation sequentially
• number_workers (int) – the number of threads (>= 1) launched to run the distance simulation in parallel

Prarm bool dispersal:  

True iff a dispersal instead of a distance simulation is to be run

Return type:

None

complete_setup()

Completes the setup for the dispersal simulation, including importing the map files and setting the historical maps.

get_all_dispersal(database=None, parameter_reference=1)

Gets all mean dispersal values from the database if run_mean_dispersal has already been run.

Raises:

ValueError if dispersal_database is None and so run_mean_dispersal() has not been run

Raises:

IOError if the output database does not exist

Parameters:

• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (default 1)

Returns:

the dispersal values from the database

get_all_distances(database=None, parameter_reference=1)

Gets all total distances travelled from the database if run_mean_distance_travelled or run_all_distance_travelled or run_sample_distance_travelled has already been run.

Raises:

ValueError if dispersal_database is None and so run_mean_dispersal() has not been run

Raises:

IOError if the output database does not exist

Parameters:

• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (default 1)

Returns:

the dispersal values from the database

get_database_parameters(reference=None)

Gets the dispersal simulation parameters from the dispersal_db

Parameters:reference – the reference to obtain parameters for Returns:the dispersal simulation parameters Return type:dict

get_database_references()

Gets the references from the database.

Returns:a list of references from the database Return type:list

get_distances_map(shape, database=None, parameter_reference=1)

Gets all total distances travelled from the database if run_mean_distance_travelled or run_all_distance_travelled or run_sample_distance_travelled has already been run and puts them inside a numpy matrix

Raises:

ValueError if dispersal_database is None and so run_mean_dispersal() has not been run

Raises:

IOError if the output database does not exist

Raises:

IndexError if the output database contains coordinates outside a matrix with shape=shape

Parameters:

• int) shape ((int,) – shape of the numpy matrix to return which will contain the distances
• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (default 1)

Returns:

the dispersal values from the database

get_mean_dispersal(database=None, parameter_reference=1)

Gets the mean dispersal for the map if run_mean_dispersal has already been run.

Raises:

ValueError if dispersal_database is None and so run_mean_dispersal() has not been run

Raises:

IOError if the output database does not exist

Parameters:

• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (default 1)).

Returns:

mean dispersal from the database

get_mean_distance_travelled(database=None, parameter_reference=1)

Gets the mean dispersal for the map if run_mean_distance_travelled or run_all_distance_travelled or run_sample_distance_travelled has already been run.

Raises:

ValueError if dispersal_database is None and so test_average_dispersal() has not been run

Raises:

IOError if the output database does not exist

Parameters:

• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (or 1 for default parameter reference).

Returns:

mean of dispersal from the database

get_stdev_dispersal(database=None, parameter_reference=1)

Gets the standard deviation of dispersal for the map if run_mean_dispersal has already been run.

Raises:

ValueError if dispersal_database is None and so test_average_dispersal() has not been run

Raises:

IOError if the output database does not exist

Parameters:

• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (or 1 for default parameter reference).

Returns:

standard deviation of dispersal from the database

get_stdev_distance_travelled(database=None, parameter_reference=1)

Gets the standard deviation of the distance travelled for the map if run_mean_distance_travelled or run_all_distance_travelled or run_sample_distance_travelled has already been run.

Raises:

ValueError if dispersal_database is None and so test_average_dispersal() has not been run

Raises:

IOError if the output database does not exist

Parameters:

• database (str) – the database to open
• parameter_reference (int) – the parameter reference to use (or 1 for default parameter reference).

Returns:

standard deviation of dispersal from the database

Return type:

float

run_all_distance_travelled(number_repeats=None, number_steps=None, seed=None, number_workers=None)

Tests the dispersal kernel on all cells on the provided map, producing a database containing the average distance travelled after number_steps have been moved.

Parameters:

• number_repeats (int) – the number of times to average over for each cell
• number_steps (int/list) – the number of steps to take each time before recording the distance travelled
• seed (int) – the random seed
• number_workers (int) – the number of threads (>= 1) launched to run the distance simulation in parallel

Return type:

None

run_mean_dispersal(number_repeats=None, seed=None, sequential=None)

Tests the dispersal kernel on the provided map, producing a database containing each dispersal distance for analysis purposes.

Note

should be equivalent to run_mean_distance_travelled() with number_steps = 1

Parameters:

• number_repeats (int) – the number of times to iterate on the map
• seed (int) – the random seed
• sequential (bool) – if true, runs repeats sequentially

run_mean_distance_travelled(number_repeats=None, number_steps=None, seed=None, number_workers=None)

Tests the dispersal kernel on the provided map, producing a database containing the average distance travelled after number_steps have been moved.

Note

mean distance travelled with number_steps=1 should be equivalent to running run_mean_dispersal()

Parameters:

• number_repeats (int) – the number of times to iterate on the map
• number_steps (int/list) – the number of steps to take each time before recording the distance travelled
• seed (int) – the random seed
• number_workers (int) – the number of threads (>= 1) launched to run the distance simulation in parallel

Return type:

None

run_sample_distance_travelled(samples_X, samples_Y, number_repeats=None, number_steps=None, seed=None, number_workers=None)

Tests the dispersal kernel on the sampled cells on the provided map, producing a database containing the average distance travelled after number_steps have been moved.

Parameters:

• samples_X (list) – list of the integer x coordinates of the sampled cells
• samples_Y (list) – list of the integer y coordinates of the sampled cells
• number_repeats (int) – the number of times to average over for each cell
• number_steps (int/list) – the number of steps to take each time before recording the distance travelled
• seed (int) – the random seed
• number_workers (int) – the number of threads (>= 1) launched to run the distance simulation in parallel

Return type:

None

set_dispersal_parameters(dispersal_method='normal', dispersal_file='none', sigma=1, tau=1, m_prob=1, cutoff=100, dispersal_relative_cost=1, restrict_self=False)

Sets the dispersal parameters.

Parameters:

• dispersal_method (str) – the dispersal method to use (“normal”, “fat-tailed” or “norm-uniform”)
• dispersal_file (str) – path to the dispersal map file, or none.
• sigma (float) – the sigma value to use for normal and norm-uniform dispersal
• tau (float) – the tau value to use for fat-tailed dispersal
• m_prob (float) – the m_prob to use for norm-uniform dispersal
• cutoff (float) – the cutoff value to use for norm-uniform dispersal

:param float dispersal_relative_cost:relative dispersal ability through non-habitat :param bol restrict_self: if true, self-dispersal is prohibited

set_map_files(fine_file, sample_file='null', coarse_file=None, historical_fine_file=None, historical_coarse_file=None, deme=1)

Sets the map files.

Uses a null sampling regime, as the sample file should have no effect.

Parameters:

• fine_file (str) – the fine map file. Defaults to “null” if none provided
• coarse_file (str) – the coarse map file. Defaults to “none” if none provided
• historical_fine_file (str) – the historical fine map file. Defaults to “none” if none provided
• historical_coarse_file (str) – the historical coarse map file. Defaults to “none” if none provided
• deme (int) – the number of individuals per cell

Return type:

None

set_simulation_parameters(number_repeats=None, output_database='output.db', seed=1, number_workers=1, dispersal_method='normal', landscape_type='closed', sigma=1, tau=1, m_prob=1, cutoff=100, sequential=False, dispersal_relative_cost=1, restrict_self=False, number_steps=1, dispersal_file='none')

Sets the simulation parameters for the dispersal simulations.

Parameters:

• number_repeats (int) – the number of times to iterate on the map
• output_database (str) – the path to the output database
• seed (int) – the random seed
• number_workers (int) – the number of threads (>= 1) launched to run the distance simulation in parallel
• dispersal_method (str) – the dispersal method to use (“normal”, “fat-tailed” or “norm-uniform”)
• landscape_type (str) – the landscape type to use (“infinite”, “tiled_coarse”, “tiled_fine”, “clamped_coarse”, “clamped_fine” or “closed”)
• sigma (float) – the sigma value to use for normal and norm-uniform dispersal
• tau (float) – the tau value to use for fat-tailed dispersal
• m_prob (float) – the m_prob to use for norm-uniform dispersal
• cutoff (float) – the cutoff value to use for norm-uniform dispersal
• sequential (bool) – if true, end locations of one dispersal event are used as the start for the next. Otherwise,

a new random cell is chosen :param float dispersal_relative_cost: relative dispersal ability through non-habitat :param bool restrict_self: if true, self-dispersal is prohibited :param list/int number_steps: the number to calculate for mean distance travelled, provided as an int or a list

of ints

Parameters:dispersal_file (str) – path to the dispersal map file, or none.

update_parameters(number_repeats=None, number_steps=None, seed=None, number_workers=None, dispersal_method=None, dispersal_file=None, sigma=None, tau=None, m_prob=None, cutoff=None, dispersal_relative_cost=None, restrict_self=None)

Provides a convenience function for updating all parameters which can be updated.

Parameters:

• number_repeats (int) – the number of repeats to perform the dispersal simulation for
• number_steps (list/int) – the number of steps to iterate for in calculating the mean distance travelled
• seed (int) – the random number seed
• number_workers (int) – the number of threads (>= 1) launched to run the distance simulation in parallel
• dispersal_method (str) – the method of dispersal
• dispersal_file (str) – the dispersal file (alternative to dispersal_method)
• sigma (float) – the sigma dispersal value
• tau (float) – the tau dispersal value
• m_prob (float) – the probability of drawing from a uniform distribution
• cutoff (float) – the maximum value for the uniform distribution
• dispersal_relative_cost (float) – the relative cost of moving through non-habitat
• restrict_self (bool) – if true, prohibits dispersal from the same cell

Return type:

None

fragments module

Generate fragmented landscapes with specific properties. Detailed here.

Contains FragmentedLandscape for creating a fragmented landscape using hexagonal packing and an even spread of individuals between fragments. Requires scipy and matplotlib.

class Fragment(x=None, y=None)

Bases: object

Simple class containing the centres of fragments for a fragmented landscape

place_on_grid()

Changes the x and y positions to integers (always rounds down).

Return type:None

setup(x, y)

Sets up the fragment from the x and y position.

Parameters:

• x – the x position of the fragment centre
• y – the y position of the fragment centre

Return type:

None

class FragmentedLandscape(number_fragments=None, size=None, total=None, output_file=None)

Bases: object

Contains hexagonal packing algorithms for spacing clumps evenly on the landscape. Includes a LLoyd’s smoothing algorithm for better spacing of fragments.

Note

Fragments will not be distinct units for unfragmented landscapes (with above around 50% habitat cover).

create(override_smoothing=None, n=10)

Creates the landscape, including running the hexagonal packing and smoothing algorithms (if required).

Note

smoothing is recommended for any landscape that is doesn’t contain a square number of fragments.

Parameters:

• override_smoothing – if true, overrides the default smoothing settings (enabled for landscapes with fewer than 100000 fragments.
• n – the number of iterations to run Lloyd’s algorithm for

Return type:

None

fill_grid()

Distributes the sizes evenly between the fragments, generating the actual landscape.

Return type:None

generate(override_smoothing=None, n=10)

Convenience function for creating fragments in one function. Generates the landscape and writes out to the output file.

If smoothing is true, will run Lloyd’s algorithm after the hexagonal packing algorithm to increase the equality of the spacing.

Note

smoothing is recommended for any landscape that is doesn’t contain a square number of fragments.

Parameters:

• override_smoothing – if true, overrides the default smoothing settings (enabled for landscapes with fewer than 100000 fragments.
• n – the number of iterations to run Lloyd’s algorithm for

Return type:

None

place_fragments(smoothing=True, n=10)

Places the fragments evenly on the landscape. If smoothing is true, will run Lloyd’s algorithm after the hexagonal packing algorithm to increase the equality of the spacing.

Note

smoothing is recommended for any landscape that is doesn’t contain a square number of fragments.

Parameters:

• smoothing – if true, runs Lloyd’s algorithm after the hexagonal packing
• n – the number of iterations to run Lloyd’s algorithm for

Return type:

None

plot()

Returns a matplotlib.pyplot.figure object containing an image of the fragmented landscape (with axes removed).

Requires that the fragmented landscape has been created already using create().

Returns:figure object containing the fragmented landscape. Return type:matplotlib.pyplot.figure

setup(number_fragments, size, total, output_file)

Sets up the landscape by checking parameters and setting object sizes.

Parameters:

• number_fragments – the number of individual fragments to exist on the landscape
• size – the size of the x and y dimensions of the landscape
• total – the total number of individuals to place on the landscape
• output_file – the output tif file to write the output to

Return type:

None

write_to_raster()

Writes the landscape to a tif file.

Raises:FileExistsError – if the output file already exists Parameters:output_file – the path to the tif file to write out to. Return type:None

fragments config module

Generate the fragment config files from a supplied shapefile and a raster file to offset from.

The function generate_fragment_csv() contains the full pipeline to generate the fragment csv.

class FragmentConfigHandler

Bases: object

Contains routines for calculating the offsets from a config file.

generate_config(input_shapefile, input_raster, field_name='fragment', field_area='area')

Generates the config file from the shapefile containing the fragments, writing the coordinates of the extent of each fragment to the output csv. The coordinates are calculated from their relevant position on the input raster.

Parameters:

• input_shapefile (str) – shapefile containing the fragments in a “fragments” field, with each defined as a polygon.
• input_raster (str) – the raster to calculate the coordinates from
• field_name (str) – optionally provide a field to extract fragment names from
• field_area (str) – optionally provide a field to extract fragment areas from (the number of individuals that exist in the fragment.

read_csv(input_csv)

Reads the input csv file into the fragments object.

Parameters:input_csv – the csv file to read in Returns:None Return type:None

write_csv(output_csv)

Writes the fragments to the output csv.

Parameters:output_csv (str) – the csv to write the output to

generate_fragment_csv(input_shapefile, input_raster, output_csv, field_name='fragment', field_area='area')

Generates the fragment csv from the provided shapefile and raster file. Coordinates for outputted to the csv are calculated from the extent of each polygon in the shapefile as their relative position on the input raster.

The fragment extents are used solely, so overlapping extents of fragments results in individuals in those areas appearing in both fragments. Therefore, rectangular fragments alone should be used.

Important

The input shapefile and raster must have the same projection.

Parameters:

• input_shapefile – the shapefile containing polygons defining fragments. Should contain fields of field_name and field_area
• input_raster – raster file to calculate the relative coordinates on
• output_csv – output csv to create
• field_name – name of the field in the shapefile to acquire fragment names from
• field_area – name of the field in the shapefile to acquire the number of individuals from

helper file

Port older simulation outputs to the updated naming conventions. Should not be required by most users.

update_parameter_names(database)

Alters the parameters names of SIMULATION_PARAMETERS in the database so that it matches the updated naming convention.

Provided for back-compatibility with older simulations.

Note

If the simulation does not require updating, this function exits silently.

Parameters:database – the database path to alter the names of Returns:None Return type:None

hpc_setup file

Compile necsim with a number of intel compiler optimisations for running on high-performance computing systems.

build_hpc()

Compiles necsim with the flags for optimisation on high-performance intel-based systems. On systems with a global variable containing INTEL_LICENSE_FILE, most of these options will be turned on automatically.

Return type:None

installer file

Compile necsim with default or provided compilation options. Intended for internal usage during pip or conda builds, although manual installation is also possible by running this file from the command line. python installer.py configures the install by detecting system components and compiles the C++ files, if possible. Command line flags can be provided to installer.py to modify the install (see Compilation Options for more information).

class Installer(dist, **kwargs)

Bases: setuptools.command.build_ext.build_ext

Wraps configuration and compilation of C++ code.

autoconf()

Runs the autoconf bash function (assuming that autoconf is available) to create the configure executable.

backup_makefile()

Copies the makefile to a saved folder so that even if the original is overwritten, the last successful compilation can be recorded.

build_extension(ext)

Builds the C++ and Python extension.

clean()

Runs make clean in the NECSim directory to wipe any previous potential compile attempts.

clean_cmake()

Deletes the cmake files and object locations if they exist.

configure(opts=None)

Runs ./configure –opts with the supplied options. This should create the makefile for compilation, otherwise a RuntimeError will be thrown.

Parameters:opts – a list of options to pass to the ./configure call

configure_and_compile(argv=[None], logging_level=20)

Calls the configure script, then runs the compilation.

Parameters:

• argv – the arguments to pass to configure script
• logging_level – the logging level to utilise (defaults to INFO).

Return type:

None

copy_makefile()

Copies the backup makefile to the main directory, if it exists. Throws an IOError if no makefile is found.

create_default_depend()

Runs the default makedepend command, outputting dependencies to lib/depends_default.

Used to generate a default dependency file on a system where makedepend exists, for a system where it does not.

do_compile()

Compiles the C++ necsim program by running make. This changes the working directory to wherever the module has been installed for the subprocess call.

get_build_dir()

Gets the build directory.

Returns:the build directory path

get_compilation_flags(display_warnings=False)

Generates the compilation flags for passing to ./configure. :param display_warnings: If true, runs with the -Wall flag for compilation (displaying all warnings). Default is False.

Returns:list of compilation flags. Return type:list

get_default_cmake_args(output_dir)

Returns the default cmake configure and build arguments.

Parameters:output_dir – the output directory to use Returns:tuple of two lists, first containing cmake configure arguments, second containing build arguments Return type:tuple

get_ldflags()

Get the ldflags that Python was compiled with, removing some problematic options.

get_ldshared()

Get the ldshared Python variables and replaces -bundle with -shared for proper compilation.

get_obj_dir()

Gets the obj directory for installing obj files to.

Returns:the obj directory path

make_depend()

Runs make depend in the lib directory to calculate all dependencies for the header and source files.

Note

Fails silently if makedepend is not installed, printing an error to logging.

move_shared_object_file()

Moves the shared object (.so) file to the build directory. :return:

run()

Runs installation and generates the shared object files - entry point for setuptools

run_cmake(src_dir, cmake_args, build_args, tmp_dir, env)

Runs cmake to compile necsim.

Parameters:

• src_dir – the source directory for necsim .cpp and .h files
• cmake_args – arguments to pass to the cmake project
• tmp_dir – the build directory to output cmake files to
• env – the os.environ (or other environmental variables) to pass on

run_configure(argv=None, logging_level=20, display_warnings=False)

Configures the install for compile options provided via the command line, or with default options if no options exist. Running with -help or -h will display the compilation configurations called from ./configure.

Parameters:

• argv – the arguments to pass to configure script
• logging_level – the logging level to utilise (defaults to INFO).
• display_warnings – If true, runs with the -Wall flag for compilation (displaying all warnings). Default is False.

setuptools_cmake(ext)

Configures cmake for setuptools usage.

Parameters:ext – the extension to build cmake on

use_default_depends()

Uses the default dependencies, copying all contents of depends_default to the end of Makefile.

Note

Zero error-checking is done here as the Makefiles should not change, and the depends_default file should be created using create_default_depend()

get_python_library(python_version)

Get path to the Python library associated with the current Python interpreter.

landscape file

Generate landscapes and check map file combinations. Child class for Simulation and DispersalSimulation. Contains Map objects for each relevant map file internally.

class Landscape

Bases: object

Calculates offsets and dimensions of a selection of tif files making up a landscape.

add_historical_map(fine_file, coarse_file, time, rate=0.0)

Adds an extra map to the list of historical maps.

Parameters:

• fine_file (str) – the historical fine map file to add
• coarse_file (str) – the historical coarse map file to add
• time – the time to add (when the map is accurate)
• rate – the rate to add (the rate of habitat change at this time)

check_maps()

Checks that the maps all exist and that the file structure makes sense.

Raises:

• TypeError – if a dispersal map or reproduction map is specified, we must have a fine map specified, but not a coarse map.
• IOError – if one of the required maps does not exist

Returns:

None

detect_map_dimensions()

Detects all the map dimensions for the provided files (where possible) and sets the respective values. This is intended to be run after set_map_files()

Raises:

• TypeError – if a dispersal map or reproduction map is specified, we must have a fine map specified, but not a coarse map.
• IOError – if one of the required maps does not exist
• ValueError – if the dimensions of the dispersal map do not make sense when used with the fine map provided

Returns:

None

set_map(map_file, x_size=None, y_size=None)

Quick function for setting a single map file for both the sample map and fine map, of dimensions x and y. Sets the sample file to “null” and coarse file and historical files to “none”.

Parameters:

• map_file (str) – path to the map file
• x_size (int) – the x dimension, or None to detect automatically from the “.tif” file
• y_size (int) – the y dimension, or None to detect automatically from the “.tif” file

set_map_files(sample_file, fine_file=None, coarse_file=None, historical_fine_file=None, historical_coarse_file=None)

Sets the map files (or to null, if none specified). It then calls detect_map_dimensions() to correctly read in the specified dimensions.

If sample_file is “null”, dimension values will remain at 0. If coarse_file is “null”, it will default to the size of fine_file with zero offset. If the coarse file is “none”, it will not be used. If the historical fine or coarse files are “none”, they will not be used.

Parameters:

• sample_file (str) – the sample map file. Provide “null” if on samplemask is required
• fine_file (str) – the fine map file. Defaults to “null” if none provided
• coarse_file (str) – the coarse map file. Defaults to “none” if none provided
• historical_fine_file (str) – the historical fine map file. Defaults to “none” if none provided
• historical_coarse_file (str) – the historical coarse map file. Defaults to “none” if none provided

Return type:

None

Returns:

None

set_map_parameters(sample_file, sample_x, sample_y, fine_file, fine_x, fine_y, fine_x_offset, fine_y_offset, coarse_file, coarse_x, coarse_y, coarse_x_offset, coarse_y_offset, coarse_scale, historical_fine_map, historical_coarse_map)

Set up the map objects with the required parameters. This is required for csv file usage.

Note that this function is not recommended for tif file usage, as it is much simpler to call set_map_files() and which should automatically calculate map offsets, scaling and dimensions.

Parameters:

• sample_file – the sample file to use, which should contain a boolean mask of where to sample
• sample_x – the x dimension of the sample file
• sample_y – the y dimension of the sample file
• fine_file – the fine map file to use (must be equal to or larger than the sample file)
• fine_x – the x dimension of the fine map file
• fine_y – the y dimension of the fine map file
• fine_x_offset – the x offset of the fine map file
• fine_y_offset – the y offset of the fine map file
• coarse_file – the coarse map file to use (must be equal to or larger than fine map file)
• coarse_x – the x dimension of the coarse map file
• coarse_y – the y dimension of the coarse map file
• coarse_x_offset – the x offset of the coarse map file at the resolution of the fine map
• coarse_y_offset – the y offset of the coarse map file at the resoultion of the fine map
• coarse_scale – the relative scale of the coarse map compared to the fine map (must match x and y scaling)
• historical_fine_map – the historical fine map file to use (must have dimensions equal to fine map)
• historical_coarse_map – the historical coarse map file to use (must have dimensions equal to coarse map)

sort_historical_maps()

Sorts the historical maps by time.

landscape_metrics file

Calculates landscape-level metrics, including mean distance to nearest-neighbour for each habitat cell and clumpiness.

class LandscapeMetrics(file=None, logging_level=30)

Bases: pycoalescence.map.Map

Calculates the mean nearest-neighbour for cells across a landscape. See here for details.

get_clumpiness()

Calculates the clumpiness metric for the landscape, a measure of how spread out the points are across the landscape. See here for details.

Returns:the CLUMPY metric Return type:float

get_mnn()

Calculates the mean nearest-neighbour for cells across a landscape. See here for details.

Returns:the mean distance to the nearest neighbour of a cell. Return type:float

map module

Open tif files and detect properties and data using gdal. Detailed here.

class GdalErrorHandler(logger)

Bases: object

Custom error handler for GDAL warnings and errors.

handler(err_level, err_no, err_msg)

Parameters:

• err_level – the level at which to log outputs
• err_no – the error number to use
• err_msg – the error message

Returns:

class Map(file=None, is_sample=None, logging_level=30)

Bases: object

Contains the file name and the variables associated with this map object.

The internal array of the tif file is stored in self.data, and band 1 of the file can be opened by using open()

Important

Currently, Map does not support skewed rasters (not north/south).

Variables:data – if the map file has been opened, contains the full tif data as a numpy array.

calculate_offset(file_offset)

Calculates the offset of the map object from the supplied file_offset.

The self map should be the smaller

Parameters:file_offset (str/Map) – the path to the file to calculate the offset. Can also be a Map object with the filename contained. Raises:TypeError – if the spatial reference systems of the two files do not match Returns:the offset x and y (at the resolution of the file_home) in integers

calculate_scale(file_scaled)

Calculates the scale of map object from the supplied file_scaled.

Parameters:file_scaled (str/Map) – the path to the file to calculate the scale. Returns:the scale (of the x dimension)

check_map()

Checks that the dimensions for the map have been set and that the map file exists

convert_lat_long(lat, long)

Converts the input latitude and longitude to x, y coordinates on the Map

Parameters:

• lat – the latitude to obtain the y coordinate of
• long – the longitude to obtain the x coordinate of

Raises:

IndexError – if the provided coordinates are outside the Map object.

Returns:

[x, y] coordinates on the Map

create(file, bands=1, datatype=<MagicMock name='mock.GDT_Byte' id='140531727779936'>, geotransform=None, projection=None)

Create the file output and writes the data to the output.

Parameters:

• file (str) – the output file to create
• bands (int) – optionally provide a number of bands to create
• datatype (gdal.GDT_Byte) – the databae of the output
• geotransform (tuple) – optionally provide a geotransform to set for the raster - defaults to (0, 1, 0, 0,

0, -1) :param string projection: optionally provide a projection to set for the raster, in WKT format

create_copy(dst_file, src_file=None)

Creates a file copying projection and other attributes over from the desired copy

Parameters:

• dst_file – existing file to create
• src_file – the source file to copy from

get_band_number()

Gets the number of raster bands in the file.

Return type:int Returns:the number of bands in the raster

get_cached_subset(x_offset, y_offset, x_size, y_size)

Gets a subset of the map file, BUT rounds all numbers to integers to save RAM and keeps the entire array in memory to speed up fetches.

Parameters:

• x_offset (int) – the x offset from the top left corner of the map
• y_offset (int) – the y offset from the top left corner of the map
• x_size (int) – the x size of the subset to obtain
• y_size (int) – the y size of the subset to obtain

Returns:

a numpy array containing the subsetted data

get_dataset(file=None, permissions=<MagicMock name='mock.GA_Update' id='140531727767424'>)

Gets the dataset from the file.

Parameters:

• file (str) – path to the file to open
• permissions (int) – the gdal permission reference to open the dataset

Raises:

• ImportError – if the gdal module has not been imported correctly
• IOError – if the supplied filename is not a tif or vrt
• IOError – if the map does not exist

Returns:

an opened dataset object

get_dimensions()

Calls read_dimensions() if dimensions have not been read, or reads stored information.

Returns:a list containing [0] x, [1] y, [2] x offset, [3] y offset, [4] x resolution, [5] y resolution, [6] upper left x, [7] upper left y

get_dtype(band_no=None)

Gets the data type of the provided band number

Parameters:band_no – band number to obtain the data type of Return type:int Returns:the gdal data type number in the raster file

get_extent()

Gets the min and max x, and min and max y values, including accounting for skew :return: list of the x min, x max, y min, y max values. :rtype: list

get_geo_transform()

Gets the geotransform of the file.

Returns:list containing the geotransform parameters

get_no_data(band_no=None)

Gets the no data value for the tif map.

Parameters:band_no – the band number to obtain the no data value from Returns:the no data value Return type:float

get_projection()

Gets the projection of the map.

Returns:the projection object of the map in WKT format Return type:str

get_subset(x_offset, y_offset, x_size, y_size, no_data_value=None)

Gets a subset of the map file

Parameters:

• x_offset (int) – the x offset from the top left corner of the map
• y_offset (int) – the y offset from the top left corner of the map
• x_size (int) – the x size of the subset to obtain
• y_size (int) – the y size of the subset to obtain
• no_data_value (float/int) – optionally provide a value to replace all no data values with.

Returns:

a numpy array containing the subsetted data

get_x_y()

Simply returns the x and y dimension of the file.

Returns:the x and y dimensions

has_equal_dimensions(equal_map)

Checks if the supplied Map has equal dimensions to this Map.

Note

Dimension matching uses an absolute value (0.0001) for latitude/longitude, and relative value for pixel resolution. The map sizes must fit perfectly.

Parameters:equal_map (Map) – the Map object to check if dimensions match Returns:true if the dimensions match, false otherwise Return type:bool

is_within(outside_map)

Checks if the object is within the provided Map object.

Note

Uses the extents of the raster file for checking location, ignoring any offsetting

Parameters:outside_map (Map) – the Map object to check if this class is within Returns:true if this Map is entirely within the supplied Map Return type:bool

map_exists(file=None)

Checks if the output (or provided file) exists.

If file is provided, self.file_name is set to file.

Parameters:file – optionally, the file to check exists Returns:true if the output file does exist Rtype bool:

open(file=None, band_no=1)

Reads the raster file from memory into the data object. This allows direct access to the internal numpy array using the data object.

Parameters:

• file (str) – path to file to open (or None to use self.file_name
• band_no (int) – the band number to read from

Return type:

None

plot()

Returns a matplotlib.pyplot.figure object containing an image of the fragmented landscape (with axes removed).

Requires that the fragmented landscape has been created already using create().

Returns:figure object containing the fragmented landscape. Return type:matplotlib.pyplot.figure

rasterise(shape_file, raster_file=None, x_res=None, y_res=None, output_srs=None, geo_transform=None, field=None, burn_val=None, data_type=<MagicMock name='mock.GDT_Float32' id='140531727704752'>, attribute_filter=None, x_buffer=None, y_buffer=None, extent=None, **kwargs)

Rasterises the provided shape file to produce the output raster.

If x_res or y_res are not provided, self.x_res and self.y_res will be used.

If a field is provided, the value in that field will become the value in the raster.

If a geo_transform is provided, it overrides the x_res, y_res, x_buffer and y_buffer.

Parameters:shape_file (str/os.path) – path to the .shp vector file to rasterise, or an ogr.DataSource object contain

the shape file :param str/os.path raster_file: path to the output raster file (should not already exist) :param int/float x_res: the x resolution of the output raster :param int/float y_res: the y resolution of the output raster :param str/osr.SpatialReference output_srs: optionally define the output projection of the raster file :param list/tuple geo_transform: optionally define the geotransform of the raster file (cannot use resolution or

buffer arguments with this option)

Parameters:

• field (str) – the field to set as raster values
• burn_val (list/int) – the r,g,b value to use if there is no field for the location
• data_type (int) – the gdal type for output data
• attribute_filter (str) – optionally provide a filter to extract features by, of the form “field=fieldval”
• x_buffer (int/float) – number of extra pixels to include at left and right sides
• y_buffer (int/float) – number of extra pixels to include at top and bottom
• extent (list) – list containing the new extent, provided as [ulx, lrx, uly, lry] (output from get_extent())
• kwargs – additional options to provide to gdal.RasterizeLayer

Raises:

• IOError – if the shape file does not exist
• IOError – if the output raster already exists
• ValueError – if the provided shape_file is not a .shp file
• RuntimeError – if gdal throws an error during rasterisation

Return type:

None

read_dimensions()

Return a list containing the geospatial coordinate system for the file.

Returns:a list containing [0] x, [1] y, [2] upper left x, [3] upper left y, [4] x resolution, [5] y resolution

reproject_raster(dest_projection=None, source_file=None, dest_file=None, x_scalar=1.0, y_scalar=1.0, resample_algorithm=<MagicMock name='mock.GRA_NearestNeighbour' id='140531727792448'>, warp_memory_limit=0.0)

Re-writes the file with a new projection.

Note

Writes to an in-memory file which then overwrites the original file, unless dest_file is not None.

Parameters:

• dest_projection (str/os.path) – the destination file projection, can only be None if rescaling
• source_file (str/os.path) – optionally provide a file name to reproject. Defaults to self.file_name
• dest_file (str/os.path) – the destination file to output to (if None, overwrites original file)
• x_scalar (float) – multiplier to change the x resolution by, defaults to 1
• y_scalar (float) – multiplier to change the y resolution by, defaults to 1
• resample_algorithm (gdal.GRA) – should be one of the gdal.GRA algorithms
• warp_memory_limit (float) – optionally provide a memory cache limit (uses default if 0.0)

set_dimensions(file_name=None, x_size=None, y_size=None, x_offset=None, y_offset=None)

Sets the dimensions and file for the Map object

Parameters:

• file_name (str/pycoalescence.Map) – the location of the map object (a csv or tif file). If None, required that file_name is already provided.
• x_size (int) – the x dimension
• y_size (int) – the y dimension
• x_offset (int) – the x offset from the north-west corner
• y_offset (int) – the y offset from the north-west corner

Returns:

None

set_sample(is_sample)

Set the is_sample attribute to true if this is a sample mask rather than an offset map

Parameters:is_sample (bool) – indicates this is a sample mask rather than offset map

translate(dest_file, source_file=None, **kwargs)

Translates the provided source file to the output file, given a set of options to pass to gdal.Translate()

Parameters:

• dest_file (str) – the destination file to create
• source_file (str) – the source file to translate, or None to translate this file
• kwargs – additional keywords to pass to gdal.Translate()

Return type:

None

write(file=None, band_no=None)

Writes the array in self.data to the output array. The output file must exist, and the array will be overridden in the band. Intended for writing changes to the same file the data was read from.

Parameters:

• file – the path to the file to write to
• band_no – the band number to write into

:rtype None

write_subset(array, x_off, y_off)

Writes over a subset of the array to file. The size of the overwritten area is detected from the inputted array, and the offsets describe the location in the output map to overwrite.

The output map must file must exist and be larger than the array.

Parameters:

• array (numpy.ndarray) – the array to write out
• x_off (int) – the x offset to begin writing out from
• y_off (int) – the y offset to begin writing out from

Return type:

None

zero_offsets()

Sets the x and y offsets to 0

shapefile_from_wkt(wkts, dest_file, EPSG=4326, fields=None)

Generates a shape file from a WKT string.

Parameters:

• wkts – a list of well-known text polygons to create in the shapefile
• dest_file – a destination file to create
• EPSG – the EPSG to use for the spatial referencing
• fields – list of dictionaries containing fields to add to the geometries

Return type:

None

merger module

Combine simulation outputs from separate guilds. Detailed here.

Merger will output a single database file, merging the various biodiversity tables into one.

Metrics are also calculated for the entire system, with a guild reference of 0.

All standard routines provided in CoalescenceTree can then be performed on the combined database.

class Merger(database=None, logging_level=30, log_output=None, expected=False)

Bases: pycoalescence.coalescence_tree.CoalescenceTree

Merges simulation outputs into a single database. Inherits from CoalescenceTree to provide all routines in the same object.

add_simulation(input_simulation)

Adds a simulation to the list of merged simulations.

This also calls the relevant merges for the tables that exist in the provided database.

Parameters:input_simulation – either the path to the input simulation, a Coalescence class object, or a CoalescenceTree object which contains the completed simulation. Returns:None Return type:None

add_simulations(simulation_list)

A convenience function that adds each simulation from the list of simulations provided and then writes to the database.

Parameters:simulation_list – list of paths to completed simulations

apply()

Generates the cooalescence tree for the set of speciation parameters. This must be run after the main coalescence simulations are complete. It will create additional fields and tables in the SQLite database which contains the requested data.

apply_incremental()

Generates the coalescence tree for the set of speciation parameters. Does not write changes to the database, just holds the changes internally.

generate_guild_tables()

Generates a set of tables containing the biodiversity metrics for each guild.

Return type:None

get_added_simulations()

Gets the simulations which have already been added to the database.

Returns:dictionary of simulations and guild numbers Return type:dict

output()

Outputs the coalescence trees to the same simulation database object.

set_database(filename, expected=False)

Sets the output database for the merged simulations

Assumes no database currently exists, and will create one.

Raises:

IOError – if the output database already exists

Parameters:

• filename – the filename to output merged simulations into
• expected – if true, expects the output to exist

Return type:

None

write()

Writes out all stored simulation parameters to the output database and wipes the in-memory objects.

This should be called after all simulation have been added, or when RAM usage gets too large for large simulations

patched_landscape module

Generate landscapes of interconnected patches for simulating within a spatially explicit neutral model. Detailed here.

Dispersal probabilities are defined between different patches, and each patch will be contain n individuals.

class Patch(id, density)

Bases: object

Contains a single patch, to which the probability of dispersal to every other patch can be added.

add_patch(patch, probability)

Adds dispersal from this patch to another patch object with a set probability. The patch should not already have been added.

Note

The probabilities can be relative, as they can be re-scaled to sum to 1 using re_scale_probabilities().

Raises:

• KeyError – if the patch already exists in the dispersal probabilities.
• ValueError – if the dispersal probability is less than 0.

Parameters:

• patch – the patch id to disperse to
• probability – the probability of dispersal

re_scale_probabilities()

Re-scales the probabilities so that they sum to 1. Also checks to make sure dispersal from within this patch is defined.

Raises:ValueError – if the self dispersal probability has not been defined, or the dispersal probabilities do not sum to > 0.

class PatchedLandscape(output_fine_map, output_dispersal_map)

Bases: object

Landscape made up of a list of patches with dispersal probabilities to each other.

add_dispersal(source_patch, target_patch, dispersal_probability)

Adds a dispersal probability from the source patch to the target patch.

Note

Both the source and target patch should already have been added using add_patch().

Parameters:

• source_patch – the id of the source patch
• target_patch – the id of the target patch
• dispersal_probability – the probability of dispersal from source to target

add_patch(id, density, self_dispersal=None, dispersal_probabilities=None)

Add a patch with the given parameters.

Parameters:

• id – the unique reference for the patch
• density – the number of individuals that exist in the patch
• self_dispersal – the relative probability of dispersal from within the same patch
• dispersal_probabilities – dictionary containing all other patches and their relative dispersal probabilities

generate_files()

Re-scales the dispersal probabilities and generates the patches landscape files. These include the fine map file containing the densities and the dispersal probability map.

The fine map file will be dimensions 1xN where N is the number of patches in the landscape.

The dispersal probability map will be dimensions NxN, where dispersal occurs from the y index cell to the x index cell.

generate_fragment_csv(fragment_csv)

Generates a fragment csv for usage within a coalescence simulation, with each patch becomming one fragment on the landscape.

Parameters:fragment_csv – the path to the output csv to create Raises:IOError – if the output fragment csv already exists

generate_from_matrix(density_matrix, dispersal_matrix)

Generates the patched landscape from the input matrix and writes out to the files.

Note

Uses a slightly inefficient method of generating the full patched landscape, and then writing back out to the map files so that full error-checking is included. A more efficient implementation is possible by simply writing the matrix to file using the Map class.

Note

The generated density map will have dimensions 1 by xy (where x, y are the dimensions of the original density matrix. However, the dispersal matrix should still be compatible with the original density matrix as a x by y tif file.

Parameters:

• density_matrix – a numpy matrix containing the density probabilities
• dispersal_matrix – a numpy matrix containing the dispersal probabilities

has_patch(id)

Checks if the patches object already contains a patch with the provided id.

Parameters:id – id to check for in patches Returns:true if the patch already exists

convert_index_to_x_y(index, dim)

Converts an index to an x, y coordinate.

Used when mapping from 1-D space to 2-D space.

Parameters:

• index – the index to convert from
• dim – the x dimension of the matrix

Returns:

a tuple of integers containing the x and y coordinates

Return type:

tuple

spatial_algorithms file

Simple spatial algorithms required for package functionality.

Algorithms include generation of Voronoi diagrams and spacing points on a landscape using Lloyd’s algorithm.

archimedes_spiral(centre_x, centre_y, radius, theta)

Gets the x, y coordinates on a spiral, given a radius and theta

Parameters:

• centre_x (int) – the x coordinate of the centre of the spiral
• centre_y (int) – the y coordinate of the centre of the spiral
• radius (float) – the distance from the centre of the spiral
• theta (float) – the angle of rotation

Returns:

tuple of x and y coordinates

Return type:

tuple

calculate_centre_of_mass(points_list)

Calculates the centre of mass for the non-intersecting polygon defined by points_list.

Note

the centre of mass will be incorrect for intersecting polygons.

Note

it is assumed that points_list defines, in order, the vertices of the polygon. The last point is assumed to connect to the first point.

Parameters:points_list – a list of x, y points defining the non-intersecting polygon Returns:the x,y centre of mass

calculate_distance_between(x1, y1, x2, y2)

Calculates the distance between the points (x1, y1) and (x2, y2)

Note

Returns the absolute value

Parameters:

• x1 – x coordinate of the first point
• y1 – y coordinate of the first point
• x2 – x coordinate of the second point
• y2 – y coordinate of the second point

Returns:

the absolute distance between the points

convert_coordinates(x, y, input_srs, output_srs)

Converts the coordinates from the input srs to the output srs.

Parameters:

• x – the x coordinate to transform
• y – the y coordinate to transform
• input_srs – the input srs to transform from
• output_srs – the output srs to transform to

Return type:

list

Returns:

transformed [x, y] coordinates

estimate_sigma_from_distance(distance, n)

Estimates the sigma value from a rayleigh distribution (2-d normal) from a total distance travelled in n steps.

Parameters:

• distance (float) – the total distance travelled
• n (int) – the number of steps

Returns:

an estimation of the sigma value required to generate the distance travelled in n steps

lloyds_algorithm(points_list, maxima, n=7)

Equally spaces the points in the given landscape defined by (0, x_max), (0, y_max) using Lloyd’s algorithm.

Algorthim is:

• Reflect the points at x=0, x=x_max, y=0 and y=y_max to make boundaries of the Voronoi diagram on the original

set of points have finite edges

• Define the Voronoi diagram separating the points
• Find the centres of the regions of the voronoi diagram for our original set of points
• Move the our points to the centres of their voronoi regions
• Repeat n times (for convergence)
• Edits the points_list to contain the equally-spaced points

Note

all points are assumed to be in the range x in (0, x_max) and y in (0, y_max)

Parameters:

• points_list – a list of points to be equally spaced in the landscape
• maxima – the maximum size of the landscape to space out within
• n – the number of iterations to perform Lloyd’s algorthim for.

:return list containing the new point centres.

reflect_dimensions(points, maximums)

Reflects the provided points across x=0, y=0, x=x_max and y=y_max (essentially tiling the polygon 4 times, around the original polygon).

Parameters:

• points (list) – a list of 2-d points to reflect
• maximums (tuple) – tuple containing the x and y maximums

Returns:

a list of reflected points

sqlite_connection file

Safely open, close and fetch data from an sqlite connection.

SQLiteConnection contains context management for opening sql connections, plus basic functionality for detecting existence and structure of databases.

class SQLiteConnection(filename)

Bases: object

Class containing context management for opening sqlite3 connections. The file name provided can either be a string containing the path to the file, or an sqlite3.Connection object, which will NOT be closed on destruction. This provides two points of entry to the system with the same interface.

check_sql_column_exists(database, table_name, column_name)

Checks if the column exists in the database.

Parameters:

• database (str/sqlite3.Connection) – the database to check existence in
• table_name (str) – the table name to check within
• column_name (str) – the column name to check for

Returns:

true if the column exists.

Return type:

bool

check_sql_table_exist(database, table_name)

Checks that the supplied table exists in the supplied database.

Parameters:

• database (str/sqlite3.Connection) – the database to check existence in
• table_name (str) – the table name to check for

Returns:

true if the table exists

Return type:

bool

fetch_table_from_sql(database, table_name, column_names=False)

Returns a list of the data contained by the provided table in the database.

Raises:

sqlite3.Error – if the table is not contained in the database (protects SQL injections).

Parameters:

• database (str/sqlite3.Connection) – the database to obtain from
• table_name (str) – the table name to fetch data from
• column_names (bool) – if true, return the column names as the first row in the output

Returns:

a list of lists, containing all data within the provided table in the database

get_table_names(database)

Gets a list of all table names in the database.

Parameters:database (str/sqlite3.Connection) – the path to the database connection or an already-open database object Returns:a list of all table names from the database Return type:list

sql_get_max_from_column(database, table_name, column_name)

Returns the maximum value from the specified column.

Parameters:

• database (str/sqlite3.Connection) – the database to fetch from
• table_name (str) – the table name to attain
• column_name (str) – the column name to obtain from

Returns:

system_operations file

Basic system-level operations required for package functionality, including subprocess calls, logging methods and file management.

The functions are contained here as they are required by many different modules. Note that logging will not raise an exception if there has been no call to set_logging_method()

cantor_pairing(x1, x2)

Creates a unique integer from the two provided positive integers.

Maps ZxZ -> N, so only relevant for positive numbers. For any A and B, generates C such that no D and E produce C unless D=A and B=E.

Assigns consecutive numbers to points along diagonals of a plane

Parameters:

• x1 – the first number
• x2 – the second number

Returns:

a unique reference combining the two integers

check_file_exists(file_name)

Checks that the specified filename exists, if it is not “null” or “none”.

Parameters:file_name – file path to check for Returns:None Raises:IOError if no file exists

check_parent(file_path)

Checks if the parent file exists, and creates it if it doesn’t.

Note

if file_path is a directory (ends with a “/”), it will be created

Parameters:file_path – the file or directory to check if the parent exists Return type:None

create_logger(logger, file=None, logging_level=30, **kwargs)

Creates a logger object to be assigned to NECSim sims and dispersal tests.

Parameters:

• logger – the logger to alter
• file – the file to write out to, defaults to None, writing to terminal
• logging_level – the logging level to write out at (defaults to INFO)
• kwargs – optionally provide additional arguments for logging to

Returns:

elegant_pairing(x1, x2)

A more elegant version of cantor pairing, which allows for storing of a greater number of digits without experiencing integer overflow issues.

Cantor pairing assigns consecutive numbers to points along diagonals of a plane

Parameters:

• x1 – the first number
• x2 – the second number

Returns:

a unique reference combining the two integers.

execute(cmd, silent=False, **kwargs)

Calls the command using subprocess and yields the running output for printing to terminal. Any errors produced by subprocess call will be redirected to logging.warning() after the subprocess call is complete.

Parameters:

• cmd – the command to execute using subprocess.Popen()
• silent – if true, does not log any warnings

:return a line from the execution output

execute_log_info(cmd, **kwargs)

Calls execute() with the supplied command and keyword arguments, and redirects stdout to the logging object.

Parameters:

• cmd – the command to execute using subprocess.Popen()
• kwargs – keyword arguments to be passed to subprocess.Popen()

Returns:

None

Return type:

None

execute_silent(cmd, **kwargs)

Calls execute() silently with the supplied command and keyword arguments.

Note

If this function fails, no error will be thrown due to its silent nature, unless a full failure occurs.

Parameters:

• cmd – the command to execute using subprocess.Popen()
• kwargs – keyword arguments to be passed to subprocess.Popen()

Returns:

None

Return type:

None

set_logging_method(logging_level=20, output=None, **kwargs)

Initiates the logging method.

Parameters:

• logging_level – the detail in logging output: can be one of logging.INFO (default), logging.WARNING, logging.DEBUG, logging.ERROR or logging.CRITICAL
• output – the output logfile (or None to redirect to terminal via stdout)
• kwargs – additional arguments to pass to the logging.basicConfig() call

Returns:

None

write_to_log(i, message, logger)

Writes the message to the provided logger, at the provided level.

This is used by necsim to access to logging module more easily.

Parameters:

• i (int) – the level to log at (10: debug, 20: info, 30: warning, 40: error, 50: critical)
• message (str) – the message to write to the logger.
• logger (logging.Logger) –

Return type:

None

necsim package

The full documentation for the c++ code which performs the actual simulations is provided below. An API is provided in Python which should be sufficient for most users (see here).

Full API

Namespaces

Classes and Structs

Enums

Functions

Variables

Defines

Indices and tables

• Search Page

Version 1.2.7.post13

Citations

[Hubbell2001]

Hubbell, S. P. (2001). The Unified Neutral Theory of Biodiversity and Biogeography. Monographs in Population Biology, 17(3), 375. http://doi.org/10.1016/S0006-3207(02)00228-8