diff --git a/README.md b/README.md index 7bf11d49e..d2c4d774d 100644 --- a/README.md +++ b/README.md @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/documentation/figures/modules/disability_module.png b/documentation/figures/modules/disability_module.png deleted file mode 100644 index a4faccc78..000000000 Binary files a/documentation/figures/modules/disability_module.png and /dev/null differ diff --git a/documentation/figures/modules/education_module.png b/documentation/figures/modules/education_module.png deleted file mode 100644 index 589533d30..000000000 Binary files a/documentation/figures/modules/education_module.png and /dev/null differ diff --git a/documentation/figures/modules/family_composition_module.png b/documentation/figures/modules/family_composition_module.png deleted file mode 100644 index 4cb87e1ac..000000000 Binary files a/documentation/figures/modules/family_composition_module.png and /dev/null differ diff --git a/documentation/figures/modules/fertility_module.png b/documentation/figures/modules/fertility_module.png deleted file mode 100644 index a528d0b20..000000000 Binary files a/documentation/figures/modules/fertility_module.png and /dev/null differ diff --git a/documentation/figures/modules/health_module.png b/documentation/figures/modules/health_module.png deleted file mode 100644 index 69a3c7923..000000000 Binary files a/documentation/figures/modules/health_module.png and /dev/null differ diff --git a/documentation/figures/modules/mental_health_cases_module.png b/documentation/figures/modules/mental_health_cases_module.png deleted file mode 100644 index 7be636b81..000000000 Binary files a/documentation/figures/modules/mental_health_cases_module.png and /dev/null differ diff --git a/documentation/figures/modules/mental_health_levels_module.png b/documentation/figures/modules/mental_health_levels_module.png deleted file mode 100644 index 071b4e1a2..000000000 Binary files a/documentation/figures/modules/mental_health_levels_module.png and /dev/null differ diff --git a/documentation/figures/modules/partnership_module.png b/documentation/figures/modules/partnership_module.png deleted file mode 100644 index 6fcace007..000000000 Binary files a/documentation/figures/modules/partnership_module.png and /dev/null differ diff --git a/documentation/figures/modules/union_matching_module.png b/documentation/figures/modules/union_matching_module.png deleted file mode 100644 index 5ed31eb80..000000000 Binary files a/documentation/figures/modules/union_matching_module.png and /dev/null differ diff --git a/documentation/wiki/developer-guide/how-to/new-variable.md b/documentation/wiki/developer-guide/how-to/new-variable.md index b751b83a8..919b1759a 100644 --- a/documentation/wiki/developer-guide/how-to/new-variable.md +++ b/documentation/wiki/developer-guide/how-to/new-variable.md @@ -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 diff --git a/documentation/wiki/developer-guide/internals/api.md b/documentation/wiki/developer-guide/internals/api.md index 7ec3d830a..b6f4cb9c0 100644 --- a/documentation/wiki/developer-guide/internals/api.md +++ b/documentation/wiki/developer-guide/internals/api.md @@ -1,6 +1,6 @@ # 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 @@ -8,13 +8,13 @@ The SimPaths API documentation is generated using [Maven's Javadoc Plugin](https 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: diff --git a/documentation/wiki/developer-guide/internals/multirun-implementation.md b/documentation/wiki/developer-guide/internals/multirun-implementation.md index 71ea39ffc..cf7a1e53b 100644 --- a/documentation/wiki/developer-guide/internals/multirun-implementation.md +++ b/documentation/wiki/developer-guide/internals/multirun-implementation.md @@ -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 diff --git a/documentation/wiki/developer-guide/internals/start-class-implementation.md b/documentation/wiki/developer-guide/internals/start-class-implementation.md index 7375c052d..40799f6e9 100644 --- a/documentation/wiki/developer-guide/internals/start-class-implementation.md +++ b/documentation/wiki/developer-guide/internals/start-class-implementation.md @@ -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 diff --git a/documentation/wiki/developer-guide/repository-guide.md b/documentation/wiki/developer-guide/repository-guide.md index 8e87f15b8..db44c112c 100644 --- a/documentation/wiki/developer-guide/repository-guide.md +++ b/documentation/wiki/developer-guide/repository-guide.md @@ -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) diff --git a/documentation/wiki/developer-guide/working-in-github.md b/documentation/wiki/developer-guide/working-in-github.md index a4b7c2086..2f51e33ec 100644 --- a/documentation/wiki/developer-guide/working-in-github.md +++ b/documentation/wiki/developer-guide/working-in-github.md @@ -24,7 +24,7 @@ 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) @@ -32,7 +32,7 @@ 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) @@ -40,7 +40,7 @@ These steps are detailed below. ![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. @@ -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** @@ -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.: @@ -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 diff --git a/documentation/wiki/figures.textClipping b/documentation/wiki/figures.textClipping new file mode 100644 index 000000000..6ccd3227e Binary files /dev/null and b/documentation/wiki/figures.textClipping differ diff --git a/documentation/figures/GUI/Chart Properties.png b/documentation/wiki/figures/GUI/Chart Properties.png similarity index 100% rename from documentation/figures/GUI/Chart Properties.png rename to documentation/wiki/figures/GUI/Chart Properties.png diff --git a/documentation/figures/GUI/Charts.png b/documentation/wiki/figures/GUI/Charts.png similarity index 100% rename from documentation/figures/GUI/Charts.png rename to documentation/wiki/figures/GUI/Charts.png diff --git a/documentation/figures/GUI/Output stream.png b/documentation/wiki/figures/GUI/Output stream.png similarity index 100% rename from documentation/figures/GUI/Output stream.png rename to documentation/wiki/figures/GUI/Output stream.png diff --git a/documentation/figures/GUI/SimPaths GUI.png b/documentation/wiki/figures/GUI/SimPaths GUI.png similarity index 100% rename from documentation/figures/GUI/SimPaths GUI.png rename to documentation/wiki/figures/GUI/SimPaths GUI.png diff --git a/documentation/figures/GUI/SimPaths parameters.png b/documentation/wiki/figures/GUI/SimPaths parameters.png similarity index 100% rename from documentation/figures/GUI/SimPaths parameters.png rename to documentation/wiki/figures/GUI/SimPaths parameters.png diff --git a/documentation/figures/GUI/SimPaths-Buttons.png b/documentation/wiki/figures/GUI/SimPaths-Buttons.png similarity index 100% rename from documentation/figures/GUI/SimPaths-Buttons.png rename to documentation/wiki/figures/GUI/SimPaths-Buttons.png diff --git a/documentation/figures/GUI/SimPaths-Chart-Zoom.png b/documentation/wiki/figures/GUI/SimPaths-Chart-Zoom.png similarity index 100% rename from documentation/figures/GUI/SimPaths-Chart-Zoom.png rename to documentation/wiki/figures/GUI/SimPaths-Chart-Zoom.png diff --git a/documentation/wiki/figures/modules/disability_module.png b/documentation/wiki/figures/modules/disability_module.png new file mode 100644 index 000000000..cb54c72bf Binary files /dev/null and b/documentation/wiki/figures/modules/disability_module.png differ diff --git a/documentation/wiki/figures/modules/education_module.png b/documentation/wiki/figures/modules/education_module.png new file mode 100644 index 000000000..9dccc43b4 Binary files /dev/null and b/documentation/wiki/figures/modules/education_module.png differ diff --git a/documentation/wiki/figures/modules/family_composition_module.png b/documentation/wiki/figures/modules/family_composition_module.png new file mode 100644 index 000000000..d1dbd51ae Binary files /dev/null and b/documentation/wiki/figures/modules/family_composition_module.png differ diff --git a/documentation/wiki/figures/modules/fertility_module.png b/documentation/wiki/figures/modules/fertility_module.png new file mode 100644 index 000000000..c820f056c Binary files /dev/null and b/documentation/wiki/figures/modules/fertility_module.png differ diff --git a/documentation/wiki/figures/modules/health_module.png b/documentation/wiki/figures/modules/health_module.png new file mode 100644 index 000000000..fdf77b7cd Binary files /dev/null and b/documentation/wiki/figures/modules/health_module.png differ diff --git a/documentation/wiki/figures/modules/mental_health_cases_module.png b/documentation/wiki/figures/modules/mental_health_cases_module.png new file mode 100644 index 000000000..79a2f2492 Binary files /dev/null and b/documentation/wiki/figures/modules/mental_health_cases_module.png differ diff --git a/documentation/wiki/figures/modules/mental_health_levels_module.png b/documentation/wiki/figures/modules/mental_health_levels_module.png new file mode 100644 index 000000000..2df96e2a0 Binary files /dev/null and b/documentation/wiki/figures/modules/mental_health_levels_module.png differ diff --git a/documentation/wiki/figures/modules/partnership_module.png b/documentation/wiki/figures/modules/partnership_module.png new file mode 100644 index 000000000..33af9fcf2 Binary files /dev/null and b/documentation/wiki/figures/modules/partnership_module.png differ diff --git a/documentation/wiki/figures/modules/union_matching_module.png b/documentation/wiki/figures/modules/union_matching_module.png new file mode 100644 index 000000000..c5a70675c Binary files /dev/null and b/documentation/wiki/figures/modules/union_matching_module.png differ diff --git a/documentation/wiki/figures/modules/update_full_time_hourly_earnings_module.png b/documentation/wiki/figures/modules/update_full_time_hourly_earnings_module.png new file mode 100644 index 000000000..70442755f Binary files /dev/null and b/documentation/wiki/figures/modules/update_full_time_hourly_earnings_module.png differ diff --git a/documentation/wiki/getting-started/data/index.md b/documentation/wiki/getting-started/data/index.md index 14497eb67..289733fe2 100644 --- a/documentation/wiki/getting-started/data/index.md +++ b/documentation/wiki/getting-started/data/index.md @@ -2,9 +2,9 @@ SimPaths uses three types of data as input: -1. The initial population to be evolved over time. [Available here](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input/InitialPopulations/training) -2. Donor populations used to impute the effects of tax and benefit policy. [Available here](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input/EUROMODoutput/training) -3. Estimated parameters governing transition probabilities assumed by the model. [Available here](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input) +1. The initial population to be evolved over time. [Available here](https://github.com/simpaths/SimPaths/tree/develop/input/InitialPopulations/training) +2. Donor populations used to impute the effects of tax and benefit policy. [Available here](https://github.com/simpaths/SimPaths/tree/develop/input/EUROMODoutput/training) +3. Estimated parameters governing transition probabilities assumed by the model. [Available here](https://github.com/simpaths/SimPaths/tree/develop/input) Training data are provided for the first two of these data sets, while 'release' data are provided for the third data set. diff --git a/documentation/wiki/getting-started/environment-setup.md b/documentation/wiki/getting-started/environment-setup.md index e3731590a..99be75070 100644 --- a/documentation/wiki/getting-started/environment-setup.md +++ b/documentation/wiki/getting-started/environment-setup.md @@ -13,7 +13,7 @@ ## Cloning the repository ```bash -git clone https://github.com/centreformicrosimulation/SimPaths.git +git clone https://github.com/simpaths/SimPaths.git cd SimPaths ``` diff --git a/documentation/wiki/index.md b/documentation/wiki/index.md index c403823b1..3f1e0b464 100644 --- a/documentation/wiki/index.md +++ b/documentation/wiki/index.md @@ -20,7 +20,7 @@ hide:
Get Started → Read the Docs - View on GitHub + View on GitHub
diff --git a/documentation/wiki/overview/index.md b/documentation/wiki/overview/index.md index e86c068f3..09e43725b 100644 --- a/documentation/wiki/overview/index.md +++ b/documentation/wiki/overview/index.md @@ -2,7 +2,7 @@ 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. It builds upon standardised assumptions and data sources, which facilitates adaptation to alternative countries. -Although differences in the main structure with the [EU models](https://github.com/centreformicrosimulation/SimPathsEU) are minimal, this documentation is specific to the UK model. Careful attention is paid to model validation, and sensitivity of projections to key assumptions. +Although differences in the main structure with the [EU models](https://github.com/simpaths/SimPathsEU) are minimal, this documentation is specific to the UK model. 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. diff --git a/documentation/wiki/overview/model-description.md b/documentation/wiki/overview/model-description.md index a1ac089cc..2fa44fe59 100644 --- a/documentation/wiki/overview/model-description.md +++ b/documentation/wiki/overview/model-description.md @@ -18,4 +18,4 @@ SimPaths implements a hierarchical architecture where individuals are organised Each module is composed of one or more processes; for example, the ageing module contains ageing, mortality, child maturation, and population alignment processes. Empirical specification of dynamic processes makes extensive use of cross-module characteristics (state variables). A graphical representation of the simulated modules is shown below: -![model_structure](https://github.com/centreformicrosimulation/SimPaths/assets/56582427/d4c773a2-b720-4546-bca6-c76d07282dc4) \ No newline at end of file +![model_structure](https://github.com/simpaths/SimPaths/assets/56582427/d4c773a2-b720-4546-bca6-c76d07282dc4) \ No newline at end of file diff --git a/documentation/wiki/overview/parameterisation.md b/documentation/wiki/overview/parameterisation.md index f951f7b8c..73473832f 100644 --- a/documentation/wiki/overview/parameterisation.md +++ b/documentation/wiki/overview/parameterisation.md @@ -4,15 +4,15 @@ The estimates for the utility functions used in the labour supply model are sepa The estimates for the psychological distress models are separately described in Kopasker, D., et al. "_Evaluating the influence of taxation and social security policies on psychological distress: a microsimulation study of the UK during the COVID-19 economic crisis._" Social Science & Medicine (2024): 116953. -The model has been parametrised for the UK using data described in the [data section](https://github.com/centreformicrosimulation/SimPaths/wiki/4.-Data). +The model has been parametrised for the UK using data described in the [data section](https://github.com/simpaths/SimPaths/wiki/4.-Data). -The most recent parametrisation of the model is [stored on Github](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input). +The most recent parametrisation of the model is [stored on Github](https://github.com/simpaths/SimPaths/tree/develop/input). ## 1. Description of the tax and benefit system display -Description of the tax and benefit system is provided through UKMOD output files stored in the [EUROMODoutput](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input/EUROMODoutput/) folder. Version developed on the basis of test data, which can be shared on GitHub, is available in the [training subfolder](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input/EUROMODoutput/training). +Description of the tax and benefit system is provided through UKMOD output files stored in the [EUROMODoutput](https://github.com/simpaths/SimPaths/tree/develop/input/EUROMODoutput/) folder. Version developed on the basis of test data, which can be shared on GitHub, is available in the [training subfolder](https://github.com/simpaths/SimPaths/tree/develop/input/EUROMODoutput/training). To learn more about UKMOD, visit [UKMOD's website](https://www.microsimulation.ac.uk/ukmod/). @@ -20,7 +20,7 @@ To learn more about UKMOD, visit [UKMOD's website](https://www.microsimulation.a ## 2. Model parameters -Source: [Github](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input). +Source: [Github](https://github.com/simpaths/SimPaths/tree/develop/input). **align_ files** Files listed below contain alignment targets. @@ -37,7 +37,7 @@ Files listed below contain demographic projections. * projections_mortality.xlsx **reg_ files** -Files listed below contain regression estimates for specific processes described in the [model structure](https://github.com/centreformicrosimulation/SimPaths/wiki/1.-Model-structure) section. +Files listed below contain regression estimates for specific processes described in the [model structure](https://github.com/simpaths/SimPaths/wiki/1.-Model-structure) section. * reg_RMSE.xlsx * reg_childcarecost.xlsx diff --git a/documentation/wiki/overview/simulated-modules.md b/documentation/wiki/overview/simulated-modules.md index b16eaa480..886cefa87 100644 --- a/documentation/wiki/overview/simulated-modules.md +++ b/documentation/wiki/overview/simulated-modules.md @@ -22,7 +22,7 @@ The education module determines transitions into and out of student status. Stud
-Education +Education _Student status_ @@ -48,7 +48,7 @@ The health module projects an individual’s health status, comprising both self Physical health status is projected on a discrete 5-point scale, designed to reflect self-reported survey responses (between “poor” and “excellent” health). Physical health dynamics are based on an ordered probit, distinguishing those still in continuous education. For continuing full-time students, the ordered probit conditions on gender, age, lagged benefit unit income quintile, lagged physical health status, region, and year. The same variables are considered for individuals who have left continuous education, with the addition of education level, lagged employment status, and lagged benefit unit composition. -Health (self-rated) +Health (self-rated) @@ -58,7 +58,7 @@ Physical health status is projected on a discrete 5-point scale, designed to ref Any individual aged 16 and above who is not in continuous education can become long-term sick or disabled. The probability of being long-term sick or disabled is described by a probit equation defined with respect to lagged disability status, prevailing and lagged physical health status, gender, age, education, income quintile, and lagged family demographics. -Disability +Disability This Disability module is integrated in the `Person.health()` (Physical health) method in the current SimPaths model. We split disability out for illustration purpose. @@ -72,14 +72,14 @@ We split disability out for illustration purpose. * Psychological distress 1 (baseline level and caseness) In each simulation cycle, a baseline level of psychological distress for individuals aged 16 and over is determined using the 12-item General Health Questionnaire (GHQ-12). Two indicators of psychological distress are computed: a Likert score, between 0 and 36, estimated using a linear regression model; and a dichotomous indicator of the presence of potentially clinically significant common mental disorders is obtained using a logistic regression model. Both specifications are conditional on the lagged number of dependent children, lagged health status, lagged mental health, gender, age, level of education, household composition, region, and year. -Mental health (levels)\ +Mental health (levels)\ **Figure, psychological distress in levels** * Psychological distress 2 (impact of economic transitions and exposure to the Covid-19 pandemic) The baseline measures of the level and caseness of psychological distress described above are modified by the effects of economic transitions and non-economic exposure to the Covid-19 pandemic. Fixed effects regressions are used to estimate the direct impact of transitions from employment to non-employment, non-employment to employment, non-employment to long-term non-employment, non-poverty to poverty, poverty to non-poverty, and poverty to long-term poverty, as well as changes in growth rate of household income, a decrease in household income, and non-economic effect of the exposure to Covid-19 pandemic in years 2020 and 2021. The effects of economic transitions are estimated on pre-pandemic data to ensure validity in other periods. The non-economic effects of the pandemic are estimated using a multilevel mixed-effects generalized linear model. -Mental health (cases)\ +Mental health (cases)\ **Figure, psychological distress in cases** @@ -97,7 +97,7 @@ Females in couples can give birth to a (single) child in each simulated year, as
4.1 Family composition module code structure
-Family composition module overview +Family composition module overview This figure illustrates the timeline of the family composition module as defined by the `buildSchedule()` method in the SimPathsModel class. Every year the model conducts union matching to form households and benefit unions. Specifically, the model executes: @@ -144,7 +144,7 @@ Individuals who enter a partnership are matched using either a parametric or non The cohabitation method (in Person class) computes a group of persons to be considered in the union matching process (a map of personsToMatch). -Partnership method +Partnership method @@ -157,7 +157,7 @@ The cohabitation method (in Person class) computes a group of persons to be cons The `UnionMatching` class receives sets of unmatched males and females (passed as unmatched, constructed from personsToMatch) and forms new couples by creating benefit units and households via male.setupNewBenefitUnit(female, true). -UnionMatching +UnionMatching The key method, `evaluateGM()`, implements the global matching procedure as follows: @@ -212,7 +212,7 @@ Females aged 18 to 44 can give birth to a child whenever they are identified in
-fertility module +fertility module _Alignment_ The number of projected births is aligned to the number of newborns supplied by the official projections used for population alignment. The alignment procedure randomly samples fertile women and adjusts the outcome of the fertility process until the target number of newborns has been met. @@ -390,12 +390,12 @@ Although net wealth is not disaggregated in the model, the incidence of homeowne A secondary subjective-wellbeing process adjusts estimates obtained by the primary process to account for the effect of exposure to labour market transitions, such as moving in and out of employment and/or poverty. Specifically, in the SimPaths model, method `Person.healthMentalHM2level()` corresponds to the Step 2 of such a mental health evaluation, as illustrated in the right half of the Figure 1 below: -Mental health (levels)\ +Mental health (levels)\ **Figure 1, psychological distress in levels** The first and second processes for mental health in cases are combined, as illustrated in Figure 2, where processes `HM2CasesFemales` and `HM2CasesMales` correspond to the second process. -Mental health (cases)\ +Mental health (cases)\ **Figure 2, psychological distress in cases** diff --git a/documentation/wiki/user-guide/gui.md b/documentation/wiki/user-guide/gui.md index cc5792fe8..f18e1b7b6 100644 --- a/documentation/wiki/user-guide/gui.md +++ b/documentation/wiki/user-guide/gui.md @@ -3,7 +3,7 @@ # 1. Introduction In this section, we discuss the different components that make up the JAS-mine Graphical User Interface (GUI). -![SimPaths GUI Screenshot](https://raw.githubusercontent.com/centreformicrosimulation/SimPaths/develop/docs/figures/SimPaths%20GUI.png) +![SimPaths GUI Screenshot](https://raw.githubusercontent.com/simpaths/SimPaths/develop/docs/figures/SimPaths%20GUI.png) JAS-mine supports three different types of execution mode:- [interactive mode](https://www.microsimulation.ac.uk/jas-mine/resources/cookbook/start/), [batch mode](https://www.microsimulation.ac.uk/jas-mine/resources/cookbook/start/) and [multi-run mode](https://www.microsimulation.ac.uk/jas-mine/resources/tutorials/run-a-simulation-many-times/). The most common mode for prototyping a JAS-mine project, developing an intuition about how it works and demonstrating it to an audience is the interactive mode. This features a graphical user interface, where model parameters can be set and updated during a simulation run, and pre-determined graphical objects can be displayed to allow for real-time inspection of a number of the model's output quantities. @@ -37,7 +37,7 @@ There are three menu tabs at the top of the JAS-mine: ## 1.2 Simulation Control Pane -![JAS-mine Buttons](https://raw.githubusercontent.com/centreformicrosimulation/SimPaths/develop/docs/figures/SimPaths-Buttons.png) +![JAS-mine Buttons](https://raw.githubusercontent.com/simpaths/SimPaths/develop/docs/figures/SimPaths-Buttons.png) Below the Menu tabs are the simulation control buttons. The user can easily discover the meaning of each of the buttons by hovering the mouse pointer over each button. We describe the actions associated with each button below, ordered from left to right: @@ -56,7 +56,7 @@ The sliding scale on the right labelled **'Simulation speed'** adjusts the real- A JAS-mine model's *[GUI parameters](https://www.microsimulation.ac.uk/jas-mine/resources/cookbook/gui-parameters/)* appear in the parameter boxes below the Simulation Control Pane. One parameter box for each of the '[Model-Collector-Observer](https://www.microsimulation.ac.uk/jas-mine/resources/focus/model-collector-observer/)' manager classes is displayed, as long as there are any variables in each of the manager classes that have the `@GUIparameter` annotation. -![JAS-mine GUI Parameters](https://raw.githubusercontent.com/centreformicrosimulation/SimPaths/develop/docs/figures/SimPaths%20parameters.png) +![JAS-mine GUI Parameters](https://raw.githubusercontent.com/simpaths/SimPaths/develop/docs/figures/SimPaths%20parameters.png) The description of a GUI parameter can be observed by hovering the mouse pointer over the value, upon which a yellow box containing the description appears if it has been defined as an attribute in the `@GUIparameter` annotation where the variable is declared, e.g.: ```java @@ -76,11 +76,11 @@ The graphics do not immediately appear in the GUI when the JAS-mine project's St The settings of a graphical widget can be adjusted by right clicking on it with the mouse pointer, and selecting the appropriate controls that are available for the type of widget. For example, the labels, line-type, colour and appearance of time series plots can be altered while running the simulation as shown below: -![JAS-mine Chart Properties](https://raw.githubusercontent.com/centreformicrosimulation/SimPaths/develop/docs/figures/Chart%20Properties.png) +![JAS-mine Chart Properties](https://raw.githubusercontent.com/simpaths/SimPaths/develop/docs/figures/Chart%20Properties.png) In addition, for a time series plot, it is possible to zoom in to areas of data points by left-clicking and dragging the mouse pointer diagonally downwards and to right in order to select a rectangle of area to enlarge. The left hand side of the figure below shows the rectangle created by dragging the mouse pointer (the mouse pointer is not shown), and the right hand side is the resulting enlarged chart. The user can zoom out again either by dragging the mouse pointer upwards or leftwards, or by right clicking and selecting 'Auto Range -> Both Axes' from the list of options. -![JAS-mine Chart Zoom](https://raw.githubusercontent.com/centreformicrosimulation/SimPaths/develop/docs/figures/SimPaths-Chart-Zoom.png) +![JAS-mine Chart Zoom](https://raw.githubusercontent.com/simpaths/SimPaths/develop/docs/figures/SimPaths-Chart-Zoom.png) Finally, the time series plots can be saved as a PNG file, printed or copied by right clicking on the chart and selecting the relevant option. @@ -88,4 +88,4 @@ Finally, the time series plots can be saved as a PNG file, printed or copied by The output stream is the white coloured window at the bottom of the GUI. It contains the system and debugger out-stream data that would be printed out to the Command Prompt (in Windows), the Terminal (Linux), or in Eclipse if running in batch mode without the GUI. Such output includes any data produced by `System.out.println()` or `System.err.println()` commands in Java, and also information about the creation of database tables when building the project. The stack trace of any exceptions thrown will be printed out. The buttons on top of the output stream window include an option to save the text to file. -![JAS-mine Output Stream](https://raw.githubusercontent.com/centreformicrosimulation/SimPaths/develop/docs/figures/Output%20stream.png) \ No newline at end of file +![JAS-mine Output Stream](https://raw.githubusercontent.com/simpaths/SimPaths/develop/docs/figures/Output%20stream.png) \ No newline at end of file diff --git a/documentation/wiki/user-guide/single-runs.md b/documentation/wiki/user-guide/single-runs.md index 46456b873..d2d66fce4 100644 --- a/documentation/wiki/user-guide/single-runs.md +++ b/documentation/wiki/user-guide/single-runs.md @@ -1,15 +1,15 @@ # Single Runs -1. Install the [SimPaths executable](https://github.com/centreformicrosimulation/SimPaths/releases) -2. [Request access to the data](https://github.com/centreformicrosimulation/SimPaths/wiki/2.Input-data). +1. Install the [SimPaths executable](https://github.com/simpaths/SimPaths/releases) +2. [Request access to the data](https://github.com/simpaths/SimPaths/wiki/2.Input-data). 3. Run the app. In the pop-up menu, select option number 4 and click "Next." - ![image](https://github.com/centreformicrosimulation/SimPaths/assets/56582427/c9042177-3fa1-472c-bfe5-b699449810d4) + ![image](https://github.com/simpaths/SimPaths/assets/56582427/c9042177-3fa1-472c-bfe5-b699449810d4) 4. Allow a few minutes for the database to be built. 5. You should now see the GUI. - ![image](https://github.com/centreformicrosimulation/SimPaths/assets/56582427/0ef65dad-5969-4b5e-9ada-bbb968dd380b) + ![image](https://github.com/simpaths/SimPaths/assets/56582427/0ef65dad-5969-4b5e-9ada-bbb968dd380b) 6. Click the "Build simulation model" button, and when the process finishes, click the "Start simulation" button. 7. You have now successfully run the simulation. Analyse real-time output and modify model parameters if desired. diff --git a/documentation/wiki/validation/index.md b/documentation/wiki/validation/index.md index 1ba2c9937..efbae31c6 100644 --- a/documentation/wiki/validation/index.md +++ b/documentation/wiki/validation/index.md @@ -85,7 +85,7 @@ These should be run **after executing *SimPaths***, as they rely on a number of Before running these scripts, complete the following preparatory steps: - **a. Obtain simulated output from *SimPaths*** - Ensure that the most recent simulated output is available. See [Section 2](https://github.com/centreformicrosimulation/SimPaths/wiki/2.-Running-SimPaths) to run SimPaths and obtain the simulation outputs. + Ensure that the most recent simulated output is available. See [Section 2](https://github.com/simpaths/SimPaths/wiki/2.-Running-SimPaths) to run SimPaths and obtain the simulation outputs. - **b. Set up the file structure** Place the downloaded do-files in a **simulation validation** folder in a subfolder called *do_files*. diff --git a/mkdocs.yml b/mkdocs.yml index 1a9023823..a7b421023 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,9 +2,9 @@ site_name: SimPaths Documentation site_description: >- An open-source microsimulation framework for modelling individual and household life course events across the UK and Europe. -site_url: https://centreformicrosimulation.github.io/SimPaths/ -repo_url: https://github.com/centreformicrosimulation/SimPaths -repo_name: centreformicrosimulation/SimPaths +site_url: https://simpaths.github.io/SimPaths/ +repo_url: https://github.com/simpaths/SimPaths +repo_name: simpaths/SimPaths docs_dir: documentation/wiki @@ -82,7 +82,7 @@ markdown_extensions: extra: social: - icon: fontawesome/brands/github - link: https://github.com/centreformicrosimulation/SimPaths + link: https://github.com/simpaths/SimPaths name: GitHub - icon: fontawesome/solid/globe link: https://www.microsimulation.ac.uk/