SimPaths

by Matteo Richiardi, Patryk Bronka, Justin van de Ven

Introduction

SimPaths is a family of models for individual and household life course events, all sharing common components. The framework is designed to project life histories through time, building up a detailed picture of career paths, family (inter)relations, health, and financial circumstances. The framework builds upon standardised assumptions and data sources, which facilitates adaptation to alternative countries – versions currently exist for the UK and Italy. Careful attention is paid to model validation, and sensitivity of projections to key assumptions. The modular nature of the SimPaths framework is designed to facilitate analysis of alternative assumptions concerning the tax and benefit system, sensitivity to parameter estimates and alternative approaches for projecting labour/leisure and consumption/savings decisions. Projections for a workhorse model parameterised to the UK context are reported in Bronka, P., Richiardi, M., & van de Ven, J. (2023). SimPaths: an open-source microsimulation model for life course analysis (No. CEMPA6/23), Centre for Microsimulation and Policy Analysis at the Institute for Social and Economic Research*, which closely reflect observed data throughout a 10-year validation window.

Getting Started

To contribute to this project, you need to fork the repository and set up your development environment.

Access to Data

We are committed to maintaining transparency and open-source principles in this project. All the code, documentation, and resources related to our project are available on GitHub for you to explore, use, and contribute to.

The data used by this project is not freely shareable. If you are interested in accessing the data necessary to run the simulation, get in touch with the repository maintainers for further instructions.

However, please note that training data is provided. It allows the simulation to be run and developed, but results obtained on the basis of the training dataset should not be interpreted, except for the purpose of training and development.

How to Request Access to Data:

If you have a need for the data, please contact the repository maintainers through the issue tracker.

Forking the Repository

1. Click the "Fork" button at the top-right corner of this repository.
2. Untick the Copy only the main branch box.
3. This will create a copy of the repository in your own GitHub account.
4. Follow instructions here to periodically synchronize your fork with the most recent version of this ("upstream") repository. This will ensure you use an up-to-date version of the model.

Setting up your development environment

1. Java Development Kit (JDK): Ensure you have a JDK (Java Development Kit) installed on your system. You can download and install the latest version of OpenJDK from Adoptium.
2. Download an IDE (integrated development environment) of your choice - we recommend IntelliJ IDEA; download the Community (free) or Ultimate (paid) edition, depending on your needs.
3. Clone your forked repository to your local machine. Import the cloned repository into IntelliJ as a Maven project

Compiling and running SimPaths with Maven in the CLI

SimPaths can also be compiled by Maven (installation instructions here) and run from the command line without an IDE. After cloning the repository and setting up the JDK, in the root directory you can run:

$ mvn clean package

... to create two runnable jars for single- and multi-run SimPaths:

.
SimPaths/
      ...
      |-- multirun.jar
      |-- singlerun.jar
      `-- src

To run the SimPathsStart setup phases and set up a population for subsequent multiruns, singlerun.jar takes the following options:

• -c Country ['UK' or 'IT']
• -s Start year
• -g [true/false] show/hide gui
• -r Re-write policy schedule from detected policy files
• -Setup do setup phases (creating input populations database) only

e.g.

$ java -jar singlerun.jar -c UK -s 2017 -g false -Setup

For multiple runs, multirun.jar takes the following options:

• -r random seed for first run (incremented by +1 for subsequent runs)
• -p simulated population size
• -n number of runs
• -s start year of runs
• -e end year of runs
• -g [true/false] show/hide gui
• -f write console output and logs to file (in 'output/logs/run_[seed].txt')

e.g.

$ java -jar multirun.jar -r 100 -p 50000 -n 20 -s 2017 -e 2020 -g false -f

Run java -jar singlerun.jar -h or java -jar multirun.jar -h to show these help messages.

Contributing

1. Create a new branch for your contributions. This will likely be based on either the main branch of this repository (if you seek to modify the stable version of the model) or develop (if you seek to modify the most recent version of the model). Please see branch naming convention below.
2. Make your changes, add your code, and write tests if applicable.
3. Commit your changes.
4. Push your changes to your fork.
5. Open a Pull Request (PR) on this repository from your fork. Be sure to provide a detailed description of your changes in the PR.

Branch Naming Conventions

In our open-source project, we follow a clear and consistent branch naming convention to streamline the development process and maintain a structured repository. These conventions help our team of contributors collaborate effectively. Here are the primary branch naming patterns:

1. Main Branches:

   • main: Represents the stable version of our model.
   • develop: Used for ongoing development and integration of new features.

2. Feature Branches:

   • feature/your-feature-name: Create feature branches for developing new features.

3. Bug Fix Branches:

   • bugfix/issue-number-description: Use bug fix branches for specific issue resolutions. For example, bugfix/123-fix-health-process-issue.

4. Experimental or Miscellaneous Branches:

   • experimental/your-description: For experimental or miscellaneous work not tied to specific features or bug fixes. For instance, experimental/new-architecture.

5. Documentation Branches:

   • docs/documentation-topic: Prefix documentation branches with docs for updating or creating documentation. For example, docs/update-readme.

These branch naming conventions are designed to make it easy for our contributors to understand the purpose of each branch and maintain consistency within our repository. Please adhere to these conventions when creating branches for your contributions.