diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md index 59bfc4cdc..6a1320a3d 100644 --- a/docs/developer-guide/index.md +++ b/docs/developer-guide/index.md @@ -15,7 +15,7 @@ New developers of SimPaths are strongly recommended to familiarise themselves wi *** -# 1. Guiding principles +## 1. Guiding principles
Clarity A clear distinction is made in JAS-mine between objects with a modelling content, which specify the structure of the simulation, and objects which perform useful but auxiliary tasks, from enumerating categorical variables to building graphical widgets, from creating filters for the collection of agents to computing aggregate statistics to be saved in the output database. @@ -42,7 +42,7 @@ Transparent coding for transparent modelling is achieved by *** -# 2. Architecture +## 2. Architecture SimPaths shares with all JAS-mine projects some architectural choices.
diff --git a/docs/index.md b/docs/index.md index 6c73be460..6e350a1b3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,7 @@ hide: ## About SimPaths -SimPaths builds upon **JAS-mine**, an open-source Java platform designed for discrete-event simulations. Models currently exist for the **UK, Greece, Hungary, Italy, and Poland**. This documentation primarily covers the **UK model**. +SimPaths builds upon **JAS-mine**, an open-source Java platform designed for discrete-event simulations. Models currently exist for the **UK, Greece, Hungary, Italy, and Poland**.
šŸ‡¬šŸ‡§ United Kingdom diff --git a/docs/overview/parameterisation.md b/docs/overview/parameterisation.md index 4f35084a7..f951f7b8c 100644 --- a/docs/overview/parameterisation.md +++ b/docs/overview/parameterisation.md @@ -10,7 +10,7 @@ The most recent parametrisation of the model is [stored on Github](https://githu -# 1. Description of the tax and benefit system display +## 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). @@ -18,7 +18,7 @@ To learn more about UKMOD, visit [UKMOD's website](https://www.microsimulation.a -# 2. Model parameters +## 2. Model parameters Source: [Github](https://github.com/centreformicrosimulation/SimPaths/tree/develop/input). diff --git a/docs/overview/simulated-modules.md b/docs/overview/simulated-modules.md index 49bd9db4b..b16eaa480 100644 --- a/docs/overview/simulated-modules.md +++ b/docs/overview/simulated-modules.md @@ -1,6 +1,6 @@ # Simulated Modules -# 1. Ageing +## 1. Ageing The first simulated process in each period increments the age of each simulated person by one year. Any dependent child that reaches an exogenously assumed ā€œage of independenceā€ (18 years-of-age in the parameterization for the UK) is extracted from their parental benefit unit and allocated to a new benefit unit. Individuals are then subject to a risk of death, based on age, gender and year specific probabilities that are commonly reported as components of official population projections. Death is simulated at the individual level but omitting single parent benefit units (to avoid the creation of orphans). @@ -17,7 +17,7 @@ Individuals who have recently attained the assumed age of independence and were -# 2. Education +## 2. Education The education module determines transitions into and out of student status. Students are assumed not to work and therefore do not enter the labour supply module. Individuals who leave education have their level of education re-evaluated and can become employed.
@@ -38,7 +38,7 @@ Individuals who cease to be students are assigned a level of education based on -# 3. Health +## 3. Health The health module projects an individualā€™s health status, comprising both self-rated general health and mental health metrics (based on a clinically validated measure of psychological distress using a Likert scale and a caseness indicator), and determines whether an individual is long-term sick or disabled (in which case, he/she is not at risk of work and may require social care). @@ -85,7 +85,7 @@ The baseline measures of the level and caseness of psychological distress descri
-# 4. Family composition +## 4. Family composition The family composition module is the principal source of interactions between simulated agents in the model. The module projects the formation and dissolution of cohabiting relationships and fertility. Where a relationship forms, then spouses are selected via a matching process that is designed to reflect correlations between partnersā€™ characteristics observed in survey data. The proportion of the population in a cohabiting relationship is, by default, aligned to the population aggregate in the years for which observational data is available, to account for changes in household structure introduced by the population alignment. @@ -225,7 +225,7 @@ The number of projected births is aligned to the number of newborns supplied by
-# 5. Social care +## 5. Social care The social care module projects provision and receipt of social care activities for people in need of help due to poor health or advanced age. The module is designed to distinguish between formal and informal social care, and the social relationships associated with informal care. The social care module accounts for the time cost incurred by care providers with respect to informal care, and the financial cost incurred by care receivers with respect to formal care. _Receipt of social care_ @@ -252,7 +252,7 @@ Specifically, the model distinguishes between four population subgroups with res -# 6 Investment income +## 6. Investment income The investment income module projects income from investment returns and (private) pensions. The approach taken to project these measures of income depends upon the model variant considered for analysis. Where consumption/savings decisions are simulated using a structural behavioural framework, then asset income is projected based on accrued asset values and exogenously projected rates of return. Alternatively, computational burden of model projections can be economised by proxying non-labour income without explicitly projecting asset holdings. @@ -277,7 +277,7 @@ $r_{dl,t} + (r_{du,t} - r_{dl,t}) \phi_{i,t}$ otherwise where $i$ denotes the benefit unit and $t$ denotes time. $1 \ge \phi_{i,t} \ge 0$ denotes the (bounded) ratio of benefit unit debt to full-time potential earnings. Assuming $r_{du,t} \ge r_{dl,t}$ reflects a ā€˜soft constraintā€™ where interest rates increase with indebtedness. -# 7. Labour income +## 7. Labour income The labour income module projects potential (hourly) wage rates for each simulated adult in each year and their associated labour activity. Given potential wage rates, hours of paid employment by all adult members of a benefit unit are generated. Labour (gross) income is then determined by multiplying hours worked by the wage rate. _Wage rates_ @@ -343,7 +343,7 @@ _Alignment_ When the default specification of SimPaths for projecting labour supply is used, the estimated utility of single men, single women, and couples is adjusted to align the aggregate employment rate to the employment rate observed in the data in the validation period. The final adjustment value is used in the subsequent periods, for which no data is available. This procedure accounts for the existence of unemployment in the real economy and the fact that labour supply decisions simulated using the random utility model assume no constraints on labour demand in the economy. -# 8. Disposable income +## 8. Disposable income Disposable income is simulated by matching each simulated benefit unit in each projected period with a donor benefit unit reported by a tax-benefit reference database, following the procedure described by [van de Ven et al. (2022)](https://www.iser.essex.ac.uk/wp-content/uploads/files/working-papers/cempa/cempa3-22.pdf). The database stores details of taxes and benefits alongside associated demographic and private income characteristics for a sample of benefit units. This database could be populated from a wide range of sources. The approach was originally formulated to draw upon output data derived from the UK version of EUROMOD (UKMOD), and then extended to accommodate projections from any EUROMOD country. The matching procedure for benefit units applies coarsened exact matching over a number of discrete-valued characteristics, followed by nearest-neighbour matching on a set of continuous variables. The nearest neighbour matching is performed with respect to Mahalanobis distance measures evaluated over multiple continuous valued characteristics. @@ -356,7 +356,7 @@ Finally, adjustments to account for public subsidies for the costs of (formal) s -# 9. Consumption +## 9. Consumption Given disposable income and household demographics, the consumption module projects measures of benefit unit expenditure. Where the model projects wealth, then a simple accounting identity is used to track the evolution of benefit unit assets through time. A regression-based homeownership process predicts if the primary residence is owned by either of the responsible adults in a benefit unit, in which case the benefit unit is considered to own its home. _Non-discretionary expenditure_ @@ -385,7 +385,7 @@ Although net wealth is not disaggregated in the model, the incidence of homeowne -# 10. Mental health +## 10. Mental health 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: @@ -401,6 +401,6 @@ The first and second processes for mental health in cases are combined, as illus -# 11 Statistical display +## 11. Statistical display At the end of each simulated year, SimPaths generates a series of year specific summary statistics. All of these statistics are saved for post-simulation analysis, with a subset of results also reported graphically as the simulation proceeds. diff --git a/docs/research/index.md b/docs/research/index.md index 6726347a4..3ed9994cb 100644 --- a/docs/research/index.md +++ b/docs/research/index.md @@ -1,13 +1,13 @@ # Research -# 1 SimPaths reference paper +## 1. SimPaths reference paper If you use SimPaths or derived work, please cite: Bronka P, van de Ven J, Kopasker D, Katikireddi SV, Richiardi M (2025). [SimPaths: an open-source microsimulation model for life course analysis](https://microsimulation.pub/articles/00318). *International Journal of Microsimulation*, 18(1): 95-133. -# 2 Further references +## 2. Further references - van de Ven J, Bronka P, Richiardi M (2025). [Welfare effects of social care policies](https://www.microsimulation.ac.uk/publications/publication-588564/). CeMPA WP 5/25. - van de Ven J, Bronka P, Richiardi M (2024). [The life course effects of care](https://www.microsimulation.ac.uk/publications/publication-578383/). CeMPA WP 7/24. diff --git a/docs/validation/index.md b/docs/validation/index.md index 9ac93da4a..1ba2c9937 100644 --- a/docs/validation/index.md +++ b/docs/validation/index.md @@ -1,6 +1,6 @@ # Model Validation -# 1. Introduction +## 1. Introduction This section explains the current procedures implemented to validate the SimPaths' inputs and outputs. @@ -18,7 +18,7 @@ At present, validation is organised into three main steps: *To be completed.* -# 2. Obtaining the validation scripts +## 2. Obtaining the validation scripts Validation procedures are currently executed in **Stata**. The corresponding do-files are located in the *validation* subfolder on the `develop` branch of the *SimPaths* GitHub repository. @@ -37,12 +37,12 @@ You can access these files in one of three ways: Each method gives you the same file contents; the difference is whether you download just one file, a snapshot of the branch, or the entire version-controlled repository. -# 3. Running the validation scripts +## 3. Running the validation scripts Once you have obtained the relevant validation files, the next step is to run them in **Stata**. This section explains how to set up your working environment, what data are required, and how to execute the validation do-files for each stage of validation. -## 3.1 Validating regression estimates +### 3.1 Validating regression estimates These do-files are contained in the subfolder *01_estimate_validation*. Before running these scripts, four preparatory steps are required: @@ -77,7 +77,7 @@ Before running these scripts, four preparatory steps are required: Once these steps have been completed, you can straightforwardly run the do-files to produce the validation plots. -## 3.2 Validating the simulated output +### 3.2 Validating the simulated output The do-files for validating the simulated output are contained in the subfolder *02_simulation_validation*. These should be run **after executing *SimPaths***, as they rely on a number of *.csv* files produced by the model. diff --git a/mkdocs.yml b/mkdocs.yml index 026339d47..f172ddd34 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -116,7 +116,7 @@ nav: - Modifying Tax-Benefit Settings: user-guide/tax-benefit-parameters.md - Uncertainty Analysis: user-guide/uncertainty-analysis.md - - Development: + - Developer Guide: - developer-guide/index.md - Working in GitHub: developer-guide/working-in-github.md - JAS-mine Architecture: