Skip to content
Merged

urls #442

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,6 @@ by CeMPA (Centre for Microsimulation and Policy Analysis).

SimPaths is an open-source framework for modelling individual and household life course events across multiple domains. The framework projects life histories over time, developing detailed representations of career paths, family and intergenerational relationships, health, and financial circumstances. As a family of models, SimPaths offers a dynamic simulation of how life events evolve and interact within populations.

SimPaths models currently exist for the UK, Greece, Hungary, Italy, and Poland. This page refers to the UK model; the other European models are available at the corresponding [SimPathsEU](https://github.com/centreformicrosimulation/SimPathsEU) page.
SimPaths models currently exist for the UK, Greece, Hungary, Italy, and Poland. This page refers to the UK model; the other European models are available at the corresponding [SimPathsEU](https://github.com/simpaths/SimPathsEU) page.

The entire SimPaths documentation is available on its [website](https://centreformicrosimulation.github.io/SimPaths/), which includes: a detailed description of its building blocks; instructions on how to set up and run the model; information about contributing to the model's development.
The entire SimPaths documentation is available on its [website](https://simpaths.github.io/SimPaths/), which includes: a detailed description of its building blocks; instructions on how to set up and run the model; information about contributing to the model's development.
4 changes: 2 additions & 2 deletions documentation/wiki/developer-guide/how-to/new-variable.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

# 1. An application using "Ethnicity"

This page explains how to add a new variable to the SimPaths model. A similar approach can be used to add other variables. This example concerns the insertion of an additional variable, "Ethnicity", named `dot01`, defined in six categories, and whose issue is detailed [here](https://github.com/centreformicrosimulation/SimPaths/issues/212).
This page explains how to add a new variable to the SimPaths model. A similar approach can be used to add other variables. This example concerns the insertion of an additional variable, "Ethnicity", named `dot01`, defined in six categories, and whose issue is detailed [here](https://github.com/simpaths/SimPaths/issues/212).

# 2. Update the input data

Before starting, the user must ensure that they have the updated version of the data for the model, which shall include the variable(s) to be added to the code. If not, they should get the [UKHLS](https://beta.ukdataservice.ac.uk/datacatalogue/studies/study?id=6914) (Understanding Society) and [WAS](https://beta.ukdataservice.ac.uk/datacatalogue/studies/study?id=7215) (Wealth and Assets Survey) data from the [UK Data Service](https://ukdataservice.ac.uk/) (DS) and generate the input data for the model using these datasets and the [do files from GitHub](https://github.com/centreformicrosimulation/SimPaths/tree/main/input/InitialPopulations/compile).
Before starting, the user must ensure that they have the updated version of the data for the model, which shall include the variable(s) to be added to the code. If not, they should get the [UKHLS](https://beta.ukdataservice.ac.uk/datacatalogue/studies/study?id=6914) (Understanding Society) and [WAS](https://beta.ukdataservice.ac.uk/datacatalogue/studies/study?id=7215) (Wealth and Assets Survey) data from the [UK Data Service](https://ukdataservice.ac.uk/) (DS) and generate the input data for the model using these datasets and the [do files from GitHub](https://github.com/simpaths/SimPaths/tree/main/input/InitialPopulations/compile).


# 3. Load the `dot01` variable in SimPaths
Expand Down
6 changes: 3 additions & 3 deletions documentation/wiki/developer-guide/internals/api.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# SimPaths API

SimPaths APIs are published [here](https://centreformicrosimulation.github.io/SimPaths/javadoc/).
SimPaths APIs are published [here](https://simpaths.github.io/SimPaths/javadoc/).

# 1. Introduction

The SimPaths API documentation is generated using [Maven's Javadoc Plugin](https://maven.apache.org/plugins/maven-javadoc-plugin/).

Javadoc is a Java tool that automatically generates HTML documentation from [Javadoc comments](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html) embedded in the source code.

The documentation website is updated automatically whenever a commit is pushed to the `develop` branch of SimPaths. This process is handled via GitHub Actions using a [Javadoc-publisher workflow developed by MathieuSoysal](https://github.com/MathieuSoysal/Javadoc-publisher.yml). The workflow file is available [here](https://github.com/centreformicrosimulation/SimPaths/blob/develop/.github/workflows/publish-javadoc.yml).
The documentation website is updated automatically whenever a commit is pushed to the `develop` branch of SimPaths. This process is handled via GitHub Actions using a [Javadoc-publisher workflow developed by MathieuSoysal](https://github.com/MathieuSoysal/Javadoc-publisher.yml). The workflow file is available [here](https://github.com/simpaths/SimPaths/blob/develop/.github/workflows/publish-javadoc.yml).

To update the API documentation, add or modify Javadoc comments in the source code following [this guide](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html), then push your changes to the `develop` branch.

# 2. Workflow Details

[The workflow](https://github.com/centreformicrosimulation/SimPaths/blob/develop/.github/workflows/publish-javadoc.yml) automates the generation and publishing of HTML documentation from Javadoc comments whenever changes are pushed to the `develop` branch.
[The workflow](https://github.com/simpaths/SimPaths/blob/develop/.github/workflows/publish-javadoc.yml) automates the generation and publishing of HTML documentation from Javadoc comments whenever changes are pushed to the `develop` branch.

```
on:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ However, please note that _training_ data is provided. It allows the simulation

**How to Request Access to Data:**

If you have a need for the data, please contact the repository maintainers through the [issue tracker](https://github.com/centreformicrosimulation/SimPaths/issues).
If you have a need for the data, please contact the repository maintainers through the [issue tracker](https://github.com/simpaths/SimPaths/issues).


### Forking the Repository
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Start Class Implementation

The [SimPathsStart](https://github.com/centreformicrosimulation/SimPaths/blob/main/src/main/java/simpaths/experiment/SimPathsStart.java) class is the entry point for running the SimPaths microsimulation model. It provides essential functionalities for initializing the simulation environment and offers methods for configuring simulation parameters, database setup, and user interactions.
The [SimPathsStart](https://github.com/simpaths/SimPaths/blob/main/src/main/java/simpaths/experiment/SimPathsStart.java) class is the entry point for running the SimPaths microsimulation model. It provides essential functionalities for initializing the simulation environment and offers methods for configuring simulation parameters, database setup, and user interactions.

# 1. Overview

Expand Down
2 changes: 1 addition & 1 deletion documentation/wiki/developer-guide/repository-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -521,4 +521,4 @@ Or via IDE test runner.
## Additional Resources

- **Full Documentation**: See `documentation/wiki/` for comprehensive guides
- **Issues**: [GitHub Issues](https://github.com/centreformicrosimulation/SimPaths/issues)
- **Issues**: [GitHub Issues](https://github.com/simpaths/SimPaths/issues)
16 changes: 8 additions & 8 deletions documentation/wiki/developer-guide/working-in-github.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,23 +24,23 @@ A fork is a copy of an entire repository (including its history) under a differe

# 3. SimPaths GitHub Repository

SimPaths code is stored in a public [GitHub repo](https://github.com/centreformicrosimulation/SimPaths). The operative branches are `main`, which contains the most stable release, and `develop`, where modifications and updates are implemented. As outlined in the diagram below, to make changes in SimPaths, users are requested to: 1) fork the original repo under their GitHub account; 2) carry out all the modifications on a new branch originated from the `develop` branch of their forked repository; 3) commit and send a pull request to the maintainers.
SimPaths code is stored in a public [GitHub repo](https://github.com/simpaths/SimPaths). The operative branches are `main`, which contains the most stable release, and `develop`, where modifications and updates are implemented. As outlined in the diagram below, to make changes in SimPaths, users are requested to: 1) fork the original repo under their GitHub account; 2) carry out all the modifications on a new branch originated from the `develop` branch of their forked repository; 3) commit and send a pull request to the maintainers.

![image](https://www.dropbox.com/scl/fi/0dhv5z8rbcqfwi58khjgj/scheme.png?rlkey=dk735e2nrcz35pqltsxfkvmgm&raw=1)

These steps are detailed below.

## 3.1 Forking SimPaths Repo

1. On the [SimPaths repo homepage](https://github.com/centreformicrosimulation/SimPaths) (see below), click on the top-right button "Fork". When hovering over it, the message _Fork your own copy of centreformicrosimulation/SimPaths_ will automatically appear.
1. On the [SimPaths repo homepage](https://github.com/simpaths/SimPaths) (see below), click on the top-right button "Fork". When hovering over it, the message _Fork your own copy of simpaths/SimPaths_ will automatically appear.

![image](https://www.dropbox.com/scl/fi/ql0ac9lpfc7olpttjidxv/Capture-d-cran-2025-07-16-15.54.25.png?rlkey=mlwykxxixgbxyvkihkoaw191l&st=ientbqmv&raw=1)

2. Once clicked on "Fork," the following page will open. It is recommendable to give a distinguishable name to the repository (_e.g._, "SimPathsFork"). Regardless of the name, please ensure that the box _Copy the_ `main` _branch only_ is unticked (as in the image below). Then, click on the green button "Create fork".

![image](../jasmine-reference/collection-filters.md)

After the fork is created, a page identical to the SimPaths repo homepage will open automatically. The only difference is that, instead of the white-and-purple SimPaths logo, there will be the user GitHub account icon/picture, with text below saying _forked from centreformicrosimulation/SimPaths_. This confirms the creation of a copy of the entire SimPaths repo under the user GitHub account.
After the fork is created, a page identical to the SimPaths repo homepage will open automatically. The only difference is that, instead of the white-and-purple SimPaths logo, there will be the user GitHub account icon/picture, with text below saying _forked from simpaths/SimPaths_. This confirms the creation of a copy of the entire SimPaths repo under the user GitHub account.

3. At this point, the user is ready to clone the code by clicking on the green button "<> Code", and then on the icon with the two overlapping squares to the right of the url (see image below). When hovering over it, an automatic message _Copy url to clipboard_ will appear, which will turn automatically in _Copied!_, once clicked.

Expand Down Expand Up @@ -85,7 +85,7 @@ Now that the forked repository has been created ("SimPathsFork" in our case), th
At the end of these four steps, the user will have their forked repository under their GitHub account.

## 3.2 Making Changes
1. From the develop branch in the new forked repository, the user should create a new branch devoted to the modifications they wish to make. Again, this can be done either from GitHub Desktop or directly from the IDE (IntelliJ IDEA). In any case, the branch should be named according to our [naming convention](https://github.com/centreformicrosimulation/SimPaths?tab=readme-ov-file#branch-naming-conventions). The first part of the name should indicate why that branch was created. For example, if the purpose is to fix a bug, this first part could be called "bug-fix". The following parts should get into the details of the broader objective of the branch indicated in the first part. Continuing with the same example, if the bug to fix is related to a specific class of the model, the second part of the name could be the name of the class. Every part of the name should be separated by a "/" symbol. Therefore, in our example, the branch would be called "bug-fix/class_name". While other details can be added as additional parts of the branch name (separated by the "/" symbol), we suggest to keep the branch names relatively short.
1. From the develop branch in the new forked repository, the user should create a new branch devoted to the modifications they wish to make. Again, this can be done either from GitHub Desktop or directly from the IDE (IntelliJ IDEA). In any case, the branch should be named according to our [naming convention](https://github.com/simpaths/SimPaths?tab=readme-ov-file#branch-naming-conventions). The first part of the name should indicate why that branch was created. For example, if the purpose is to fix a bug, this first part could be called "bug-fix". The following parts should get into the details of the broader objective of the branch indicated in the first part. Continuing with the same example, if the bug to fix is related to a specific class of the model, the second part of the name could be the name of the class. Every part of the name should be separated by a "/" symbol. Therefore, in our example, the branch would be called "bug-fix/class_name". While other details can be added as additional parts of the branch name (separated by the "/" symbol), we suggest to keep the branch names relatively short.
**IntelliJ IDEA**
In our forked project ("SimPathsFork" in our case), follow the exact same path illustrated to switch branch from `main` to `develop` (Section 1. "Forking SimPaths Repo"; point 4; second image). In this case, however, in the drop-down menu, select "+ New Branch...". In the small window that opens, rename the branch, make sure that the option "Checkout branch" is ticked, and then click on "Create". The user will land automatically on the new branch of the forked repository.
**GitHub Desktop**
Expand All @@ -99,7 +99,7 @@ Whether it is directly via IntelliJ IDEA or through GitHub, at the end of this f
2. At this point, the user is free to make the desired changes. When they are done, it is of paramount importance that the model is tested after the editing. If the model compiles and runs correctly without error messages, the user can proceed to the next and final step.

## 3.3 Committing Changes
Once all the modifications have been implemented and the model has been tested to function correctly, the updated version of the model can be made available to everyone. This is done via a two-step procedure. First, the changes must be committed, _i.e._, "sent" and fully integrated into the corresponding branch.[1](#footnote-1) After the commit, the newly published branch will contain all these modifications. Second, the branch must be merged, via a pull request, with the `develop` branch of the public repo centreformicrosimulation/SimPaths, so that everyone may access the updated version of the model.
Once all the modifications have been implemented and the model has been tested to function correctly, the updated version of the model can be made available to everyone. This is done via a two-step procedure. First, the changes must be committed, _i.e._, "sent" and fully integrated into the corresponding branch.[1](#footnote-1) After the commit, the newly published branch will contain all these modifications. Second, the branch must be merged, via a pull request, with the `develop` branch of the public repo simpaths/SimPaths, so that everyone may access the updated version of the model.
As in the previous points, this can be done either from GitHub Desktop or directly from the IDE (IntelliJ IDEA). For the sake of simplicity, in this case, only the procedure using GitHub Desktop is presented.

1. The GitHub Desktop homepage should look as follows.:
Expand All @@ -108,12 +108,12 @@ As in the previous points, this can be done either from GitHub Desktop or direct

In the left column, all the modifications that have been made are listed. If we click on any of them, the actual changes appear on the righ-hand side of the window (red: what has been deleted; green: what has been added). Before committing the changes, it is very important to: i) untick any modifications that entail the upload of data (data cannot be uploaded on GitHub for confidentiality reasons); ii) add a relevant summary and description to the commit in the bottom-left corner. When both these operations are completed, the user is ready to commit the changes by clicking the blue button at the end of the page "Commit X files to branch-name". After committing, the branch should be published by clicking on "Publish branch" (third entry of the menu tab on the top).

2. At this point, the user should switch to GitHub on their browser and access the [Pull requests](https://github.com/centreformicrosimulation/SimPaths/pulls) section of centreformicrosimulation/SimPaths, where they shall select the green button "New pull request" on the right. Before being able to send the pull request, the user will be asked to choose the branches to compare, as illustrated below:
2. At this point, the user should switch to GitHub on their browser and access the [Pull requests](https://github.com/simpaths/SimPaths/pulls) section of simpaths/SimPaths, where they shall select the green button "New pull request" on the right. Before being able to send the pull request, the user will be asked to choose the branches to compare, as illustrated below:

![image](https://www.dropbox.com/scl/fi/fqcpwa93rqgyyf6gaoeid/Capture-d-cran-2025-07-23-18.09.10.png?rlkey=qycxsye2t2pzk8cms4wwrrg7j&st=op2rc1t3&raw=1)

On the left-hand side, the base repository should always be set to centreformicrosimulation/SimPaths, and the branch on `develop`. On the right-hand side, the user should select their forked repository and the branch where they made all the changes. At this point, the changes will automatically appear underneath and the user will be able to click on the green button on the right "Create pull request". In the window that opens, the title and description will be precompiled from the commit. If they are already self-explanatory, the user can simply click again on the green button on the right "Create pull request" to complete the operation. At this point, an automatic system of tests will be launched to run the model on the server and double-check it works, but no actions are required by the user.
The last step is simply to add one or more reviewers in the "Reviewers" tab at the top right of the page. The reviewer(s) will receive a notification and can review the changes committed before merging them into the centreformicrosimulation/SimPaths repository.
On the left-hand side, the base repository should always be set to simpaths/SimPaths, and the branch on `develop`. On the right-hand side, the user should select their forked repository and the branch where they made all the changes. At this point, the changes will automatically appear underneath and the user will be able to click on the green button on the right "Create pull request". In the window that opens, the title and description will be precompiled from the commit. If they are already self-explanatory, the user can simply click again on the green button on the right "Create pull request" to complete the operation. At this point, an automatic system of tests will be launched to run the model on the server and double-check it works, but no actions are required by the user.
The last step is simply to add one or more reviewers in the "Reviewers" tab at the top right of the page. The reviewer(s) will receive a notification and can review the changes committed before merging them into the simpaths/SimPaths repository.

# 4. Further changes

Expand Down
Binary file added documentation/wiki/figures.textClipping
Binary file not shown.
Loading
Loading