Revised income estimates

.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(xargs -I {} wc -l {})",
+      "Bash(mvn clean *)",
+      "Bash(python -c \"import docx; print\\('python-docx available'\\)\")",
+      "Bash(python3 -c \"import docx; print\\('ok'\\)\")",
+      "Bash(where py *)",
+      "Bash(py --version)",
+      "Bash(py -c \"import docx; print\\('ok'\\)\")",
+      "Bash(py -m pip install python-docx -q)",
+      "Bash(py generate_review.py)",
+      "Bash(pip show *)",
+      "PowerShell(Get-Command *)"
+    ]
+  }
+}

.github/workflows/SimPathsBuild.yml

@@ -16,33 +16,33 @@ jobs:
   build:
     runs-on: [ ubuntu-latest ]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up JDK 19
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: '19'
         distribution: 'temurin'
     - name: Build with Maven
       run: mvn -B package --file pom.xml
-    - uses: actions/upload-artifact@v4
+    - uses: actions/upload-artifact@v7
       with:
         name: simpaths_jars
         path: ./*.jar
 
   run-integration-tests:
     runs-on: [ ubuntu-latest ]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up JDK 19
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: '19'
         distribution: 'temurin'
     - name: Run integration tests
       run: mvn verify
     - name: Upload Actual CSVs for Inspection
       if: failure()  # This ensures it only runs when the tests fail
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v7
       with:
         name: actual-simulation-results
         path: output/INTEGRATION_TESTS/csv/
@@ -51,43 +51,43 @@ jobs:
     needs: build
     runs-on: [ ubuntu-latest ]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up JDK 19
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           java-version: '19'
           distribution: 'temurin'
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: simpaths_jars
           path: .
       - name: Do one full Setup and Run with SimPathsStart (mimicking GUI run)
         run: java -jar singlerun.jar -c UK -s 2019 -g false --rewrite-policy-schedule
       - name: Check input db exists
         id: check_file
-        uses: thebinaryfelix/check-file-existence-action@1.0.0
+        uses: thebinaryfelix/check-file-existence-action@2.0.0
         with:
           files: 'input/input.mv.db, input/EUROMODpolicySchedule.xlsx, input/DatabaseCountryYear.xlsx'
 
   run-simpaths-persist-root:
     needs: build
     runs-on: [ ubuntu-latest ]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up JDK 19
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: '19'
         distribution: 'temurin'
-    - uses: actions/download-artifact@v4
+    - uses: actions/download-artifact@v8
       with:
         name: simpaths_jars
         path: .
     - name: Setup run
       run: java -jar multirun.jar -DBSetup -config test_create_database.yml
     - name: Check input db exists
       id: check_file
-      uses: thebinaryfelix/check-file-existence-action@1.0.0
+      uses: thebinaryfelix/check-file-existence-action@2.0.0
       with:
         files: 'input/input.mv.db, input/EUROMODpolicySchedule.xlsx, input/DatabaseCountryYear.xlsx'
     - name: Do two runs with persistence to root database
@@ -97,21 +97,21 @@ jobs:
     needs: build
     runs-on: [ ubuntu-latest ]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     - name: Set up JDK 19
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: '19'
         distribution: 'temurin'
-    - uses: actions/download-artifact@v4
+    - uses: actions/download-artifact@v8
       with:
         name: simpaths_jars
         path: .
     - name: Setup run
       run: java -jar multirun.jar -DBSetup -config test_create_database.yml
     - name: Check input db exists
       id: check_file
-      uses: thebinaryfelix/check-file-existence-action@1.0.0
+      uses: thebinaryfelix/check-file-existence-action@2.0.0
       with:
         files: 'input/input.mv.db, input/EUROMODpolicySchedule.xlsx, input/DatabaseCountryYear.xlsx'
     - name: Do two runs with no persistence

.github/workflows/deploy-docs.yml

@@ -23,12 +23,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.x'
 
@@ -39,10 +39,10 @@ jobs:
         run: mkdocs build --strict
 
       - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: site/
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/publish-javadoc.yml

@@ -15,10 +15,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v6
 
       - name: Set up JDK 19
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v5
         with:
           java-version: '19'
           distribution: 'temurin'

.gitignore

@@ -246,3 +246,5 @@ input/EUROMODoutput/baseline/*
 
 # IntelliJ
 .idea/
+
+input/InitialPopulations/original/*

CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Important: Directory Path Contains Spaces
+
+The project root is `C:\MyFiles\99 DEV ENV\JAS-MINE\SimPaths`. The path contains spaces, so always wrap paths in double quotes in shell/Bash commands, e.g.:
+
+```bash
+cd "C:\MyFiles\99 DEV ENV\JAS-MINE\SimPaths"
+mvn -f "C:\MyFiles\99 DEV ENV\JAS-MINE\SimPaths\pom.xml" compile
+```
+
+## Build & Run Commands
+
+```bash
+# Compile only
+mvn compile
+
+# Run unit tests (excludes integration tests)
+mvn test
+
+# Run a single test class
+mvn test -Dtest=MahalanobisDistanceTest
+
+# Run a single test method
+mvn test -Dtest=PersonTest#methodName
+
+# Run integration tests (requires pre-built JARs)
+mvn failsafe:integration-test
+
+# Build shaded JARs (produces singlerun.jar and multirun.jar in project root)
+mvn package
+
+# Run simulation headless via multirun.jar (uses config/default.yml)
+java -jar multirun.jar -config config/default.yml
+
+# Run database setup only
+java -jar multirun.jar -DBSetup -config config/default.yml
+
+# Run with GUI (single run)
+java -jar singlerun.jar
+```
+
+Java 19 is required (configured in pom.xml). Dependencies are pulled from Maven Central and JitPack (for JAS-mine).
+
+## Architecture Overview
+
+SimPaths is a **dynamic microsimulation model** built on the [JAS-mine](https://github.com/jasmineRepo) simulation framework. It projects individual and household life histories year-by-year across domains: labour market, health, demographics, social care, and taxes/benefits.
+
+### Simulation entity hierarchy
+
+```
+Household          — groups BenefitUnits sharing a dwelling (parent–adult-child links)
+  └─ BenefitUnit  — the tax/benefit assessment unit (couple or single + dependent children)
+       └─ Person  — the individual agent (all life-course state is stored here)
+```
+
+All three are JPA `@Entity` classes persisted via Hibernate/H2. Each carries a `PanelEntityKey` (id + simulation_time + simulation_run).
+
+### Simulation lifecycle
+
+`SimPathsModel` (extends `AbstractSimulationManager`) owns the main simulation loop. Each year it fires ordered events that update entities via `EventListener.onEvent()`. The sequence covers: mortality → union formation/dissolution → fertility → education → labour market → taxes/benefits → health → social care → statistics collection.
+
+### Key classes to know
+
+| Class | Role |
+|---|---|
+| `SimPathsModel` | Orchestrates yearly event schedule; holds all population lists |
+| `SimPathsStart` | Entry point for single runs (GUI or headless) |
+| `SimPathsMultiRun` | Entry point for multi-run / sensitivity analysis |
+| `SimPathsCollector` | Collects and exports output statistics each year |
+| `Parameters` | Static store for all model parameters and regression coefficients loaded from Excel |
+| `ManagerRegressions` | Routes regression evaluation calls to the correct JAS-mine regression objects |
+| `Person` / `BenefitUnit` | Core simulation agents — most behavioural logic lives here |
+
+### Tax-benefit imputation (`model/taxes/`)
+
+Tax and benefit outcomes are not calculated analytically. Instead, the model uses **statistical matching**: simulated households are matched to a pre-built donor database derived from EUROMOD/UKMOD output. `TaxDonorDataParser` builds this database; `DonorTaxImputation` performs the matching using a nearest-neighbour key function (`KeyFunction1`–`KeyFunction4`).
+
+### Intertemporal optimisation (`model/decisions/`)
+
+An optional backward-induction module solves for optimal lifetime consumption and labour supply. `ManagerSolveGrids` runs the solution over a multi-dimensional state-space grid (age, health, education, pension, region, etc.). `ManagerPopulateGrids` sets up the grid geometry. This is computationally expensive and disabled by default (`enableIntertemporalOptimisations: false`).
+
+### Regression system
+
+All behavioural equations are estimated externally and loaded at startup from Excel files in `input/`. `Parameters` loads them via JAS-mine's `ExcelAssistant`/`MultiKeyCoefficientMap`. `RegressionName` (enum) names every equation; `ManagerRegressions` dispatches calls by type (linear, probit, ordered probit, multinomial logit, etc.).
+
+### Alignment
+
+Several demographic processes are aligned to external targets (ONS projections, LFS shares) via `ActivityAlignmentV2`, `FertilityAlignment`, `PartnershipAlignment`, `InSchoolAlignment`, `SocialCareAlignment`. Alignment factors are exported to `AlignmentAdjustmentFactors1.csv` each run.
+
+### Configuration
+
+Runs are configured via YAML files in `config/`. `default.yml` documents all available keys with their defaults. CLI flags override YAML values. `SimPathsMultiRun` reads the YAML and reflectively sets fields on `SimPathsModel`, `SimPathsCollector`, and `Parameters`.
+
+### Output
+
+Output is written to `output/<run-timestamp>/csv/` by `SimPathsCollector`. Key files:
+- `Statistics1.csv` — income distribution (Gini, percentiles, S-Index)
+- `Statistics2.csv` — demographic validation (partnership, employment, health by age/gender)
+- `EmploymentStatistics.csv`, `HealthStatistics.csv` — domain-specific time series
+- `AlignmentAdjustmentFactors1.csv` — alignment diagnostics
+
+### Integration tests
+
+`RunSimPathsIntegrationTest` runs the full simulation end-to-end using the built JARs and compares CSV output against reference files in `src/test/java/simpaths/integrationtest/expected/`. If a substantive change shifts the output, update the expected files and commit them.
+
+## Domain Knowledge
+
+This section records design principles and non-obvious rationale accumulated through development. Update it as new insights emerge.
+
+### Price levels: SimPaths vs. the tax donor database
+
+All SimPaths financial variables are stored in **real 2015 prices** (`BASE_PRICE_YEAR`). The tax donor database, however, is denominated in **nominal prices of the respective policy year**.
+
+Tax donor matching therefore requires a two-step price bridge:
+1. Inflate SimPaths income to policy-year prices before matching.
+2. Deflate the imputed financial values from the matched donor record back to 2015 prices.
+
+The default uprating series is `TimeSeriesVariable.Inflation`, sourced from the `inflation` worksheet in `input/economic_time_series.xlsx`. An alternative option (added 2026-04) allows wage growth to be used instead of price growth for the initial matching step, controlled via a config flag.