Thank you for taking the time to contribute to Individual. We’re grateful that you would take some time to make Individual-Based Modeling easier in R. Pull requests are very welcome.


For major changes, please open an issue first to give other developers a heads up on what you would like to add or change. That way we can reduce any redundant efforts and give any resources if needed.

For bug reports please include:


We use Git on this project. Which means we use master, dev, feat/*, bug/*, hotfix/* and release/* branches. Please refer to this post for more information of each type of branch. NOTE: bug/* branches are feat/* branches which fix a bug.

Practically speaking, all new code contributions should be feature branches. You should branch off of the dev branch into one called feat/[your feature name here]. When we consider pull requests from forked repositories to the mrc-ide/individual repository, we will expect this convention.

We periodically merge dev into master for small release updates. These releases will appear on the GitHub releases page. Please use Conventional Commits as it helps us version Individual properly.

Large releases will have a release/* branch to manage the transition. No new features will be merged into release/* branches. Only documentation and bug fixes will be considered.

Code organisation

R/simulation.R - Contains the main entry point and configuration for models

R/variables.R - Defines classes for the available variables

R/events.R - Defines classes for the available events

src/ - The C++ side of the R interface and tests

inst/include/Variable.h - The implementations of Variables

inst/include/Event.h - The implementations of Events

tests/ - are divided into unit, integration and performance tests. Integration tests are strongly recommended for large functions and unit tests for everything else

Pull Requests

Here’s a checklist for a successful PR:

These are the things we check for:

Our review process is based off of RESIDE’s PR review process


We use google benchmark for our microbenchmarks. You can compile and run the benchmarks like this:

cd tests/performance
g++ *_benchmark.cpp -std=c++14 -lbenchmark -lpthread -o benchmark.out