Skip to content

Activity alignment process overview

Jump to bottom
Mariia Var edited this page Oct 21, 2025 · 11 revisions

The Activity Alignment process in SimPaths is used to calibrate the labour supply model so that simulated employment rates match their target rates for each subgroup of benefit units.

The alignment dynamically adjusts certain utility coefficients in the labour supply model — specifically those linked to the fixed costs of work participation — until the simulated share of employed individuals aligns with the target employment share defined in Parameters.

1. Main Class: ActivityAlignmentV2

  • Implements: IEvaluation
  • Purpose: Encapsulates the alignment logic for employment calibration by defining the function f(x) = target - simulated(x), where x is a utility adjustment coefficient. In the current version of SimPathsEU, this corresponds to a fixed cost associated with entering employment.

ActivityAlignmentV2 operates at the subgroup level (e.g., single males, couples, females with dependents).
For each subgroup, it:

  1. Retrieves the target employment share from input data.
  2. Computes the simulated employment share given current utility parameters.
  3. Returns the difference between the two (target - simulated).

This function is then passed to the root-finding algorithm (RootSearch), which iteratively adjusts the fixed-cost coefficient until convergence — i.e., until the simulated share matches the target within tolerance (|f(x)| < tol).

2. Alignment Mechanism

The utility of employment is represented by a set of regression coefficients in the labor supply utility function.
Among these coefficients are fixed-cost terms — representing the (dis)utility or setup cost associated with entering employment — these coefficients the alignmnet process adjusts.

These fixed costs differ by gender, e.g.:

  • AlignmentFixedCostMen
  • AlignmentFixedCostWomen

The alignment process modifies these coefficients to shift individuals’ propensity to work up or down — thereby changing the aggregate employment rate.

For example: if the simulated employment rate of single females is below the empirical target,
the model reduces the fixed cost term (AlignmentFixedCostWomen) to make working relatively more attractive.

Step-by-Step Process

  1. evaluate() receives a proposed adjustment value (x) from the root-search algorithm.
  2. adjustCoefficients() applies this adjustment to the specified utility coefficients.
  3. The model recalculates labor supply and income using updateLabourSupplyAndIncome().
  4. computeSimulatedShare() measures the resulting employment rate.
  5. The difference between target and simulated rates is returned to RootSearch.
  6. RootSearch repeats the process, updating x until the difference is within the defined tolerance.

3. Subgroup Classification

The ActivityAlignmentV2 class determines subgroup membership via the matchesSubgroup() method, based on the following criteria:

  • Occupancy: e.g., couple, single male, single female
  • At-risk-of-work flag: Person.atRiskOfWork()
  • Adult-child flag: Person.getAdultChildFlag()

This ensures that each benefit unit is correctly assigned to a single subgroup (e.g., female adult child, male with dependent, etc.).

Each subgroup calls activityAlignment(...) with its own configuration:

Method Subgroup Coefficient Adjusted OccupancyExtended Flag
activityAlignmentSingleMales() Single males AlignmentFixedCostMen Single_Male
activityAlignmentSingleACMales() Adult-child males AlignmentFixedCostMen Male_AC
activityAlignmentSingleFemales() Single females AlignmentFixedCostWomen Single_Female
activityAlignmentSingleACFemales() Adult-child females AlignmentFixedCostWomen Female_AC
activityAlignmentCouples() Couples AlignmentFixedCostMen, AlignmentFixedCostWomen Couple
activityAlignmentMaleWithDependents() Males with dependents AlignmentFixedCostMen Male_With_Dependent
activityAlignmentFemaleWithDependents() Females with dependents AlignmentFixedCostWomen Female_With_Dependent

Each call performs the following steps:

  1. Retrieves the current adjustment from the time-series parameters.
  2. Constructs an ActivityAlignmentV2 instance for the subgroup.
  3. Runs the root-search procedure until convergence.
  4. Stores the resulting adjustment back into the model parameters.

4. Process Flow Summary

      ┌──────────────────────────────┐
      │       Start Alignment        │
      │       (per subgroup)         │
      └───────────────┬──────────────┘
                      │
          ┌───────────▼────────────┐
          │ Instantiate            │
          │ ActivityAlignmentV2    │
          │ (define subgroup &     │
          │  regressorsToModify)   │
          └───────────┬────────────┘
                      │
          ┌───────────▼────────────┐
          │ Initialize RootSearch  │
          │ with initial Δ₀(utility│
          │  adjustment guess)     │
          └───────────┬────────────┘
                      │
             ┌────────▼────────┐
             │ evaluate(Δᵢ):   │ <---------------------------------------┐
             │  • Apply Δᵢ to  │                                         │
             │    coefficients │                                         │
             │  • Recompute    │                                         │
             │    labor supply │                                         │
             │  • Compute f(Δᵢ)│                                         │
             │    = target −   │                                         │
             │      simulated  │                                         │
             └────────┬────────┘                                         │
                      │                                                  │
          ┌───────────▼────────────┐                                     │
          │ RootSearch             │            NO            ┌──────────┘─────────┐
          │────────────────────────│ -----------------------> │ adjust Δᵢ₊₁        │
          │ checks if |f(Δᵢ)|      │    iteration continues   │ using root finding │
          │ < tolerance            │         (Δᵢ → Δᵢ₊₁)      └────────────────────┘
          │ Converged?             │ 
          └───────────┬────────────┘
                      │YES
                      │
            ┌─────────▼─────────┐
            │ Save final Δ*     │
            └─────────┬─────────┘
                      │
          ┌───────────▼───────────┐
          │ Alignment Complete    │
          │ for the given subgroup│
          └───────────────────────┘

Occupancy groups (group_code)

group_code Required At-Risk Flags on BU adultchildflag Description
couple bu_maleAtRisk == 1 and bu_femaleAtRisk == 1 - Couple benefit unit where both the male and female are “at risk” (in the labour-market risk set).
male_wdep bu_maleAtRisk == 1 and bu_femaleAtRisk != 1 - Couple BU where the male is at risk and the female partner is not at risk (female is a dependent partner).
female_wdep bu_maleAtRisk != 1 and bu_femaleAtRisk == 1 - Couple BU where the female is at risk and the male partner is not at risk (male is a dependent partner).
smale (not used) adultchildflag == 0 Single male benefit unit (not an adult child in a parental home).
sfemale (not used) adultchildflag == 0 Single female benefit unit (not an adult child in a parental home).
male_AC (not used) adultchildflag == 1 Male adult child benefit unit (male in parental home flagged as adult child).
female_AC (not used) adultchildflag == 1 Female adult child benefit unit (female in parental home flagged as adult child).

Clone this wiki locally