Employment Module

This module simulates labor force transitions for persons in the synthetic population. It applies estimated models to determine which individuals enter or exit the workforce, updates employment status and earnings, and provides household-level employment and income summaries.

  • Supports calibration and simultaneous calibration procedures.

  • Relies on estimated logit models for labor force transitions.

Module function

Module configuration options: EmploymentModuleConfig

demos.models.employment.employment(persons)[source]

Simulate labor force transitions for eligible persons.

This step applies estimated models to determine which unemployed persons become employed and which employed persons exit the workforce. Only persons aged 18 or older are considered. The function updates the worker and earning columns in the persons table.

Parameters:

persons (orca.Table) – The persons table containing individual-level attributes.

Notes

  • Requires the persons table with columns: age, worker, earning.

  • Modifies persons.worker and persons.earning in place.

  • Uses module configuration from the TOML config file.

  • Triggers caching of the income_dist table for income assignment.

Example

This step is executed as part of the annual simulation loop:

orca.run([‘employment’], iter_vars=[…])

Orca Columns

demos.models.employment.new_earning(persons, income_dist)[source]

Compute new earnings for persons entering the workforce.

For each eligible person, samples income from a lognormal distribution parameterized by age and education group, using the cached income_dist table.

Parameters:

  • persons (orca.Table) – The persons table.

  • income_dist (orca.Table) – Table with income distribution parameters.

Returns:

Sampled earnings for each person.

Return type:

pandas.Series

demos.models.employment.income_dist(persons)[source]

Compute and cache income distribution parameters by age and education group.

This table is used to sample earnings for new workers in the employment model.

Parameters:

persons (orca.Table) – The persons table.

Returns:

DataFrame with columns: age_group, education_group, data_mean, data_std, mu, sigma.

Return type:

pandas.DataFrame

demos.models.employment.hh_workers(persons)[source]

Compute the number of workers per household.

Parameters:

persons (orca.Table) – The persons table.

Returns:

Categorical summary: “none”, “one”, or “two or more” workers per household.

Return type:

pandas.Series

demos.models.employment.income(persons)[source]

Aggregate household income from person-level earnings.

Parameters:

persons (orca.Table) – The persons table.

Returns:

Total income per household.

Return type:

pandas.Series

Notes

This is for HOUSEHOLDS table

Other Functions

demos.models.employment.sample_income(mean, std)[source]

Draw samples from a lognormal distribution.

Parameters:

  • mean (float or array-like) – The mean(s) of the underlying normal distribution.

  • std (float or array-like) – The standard deviation(s) of the underlying normal distribution.

Returns:

Sample(s) from the lognormal distribution.

Return type:

float or np.ndarray

demos.models.employment.run_and_calibrate_in_workforce_model(persons, calibration_procedure)[source]

Run the ‘enter_labor_force’ estimated model for eligible persons.

Parameters:

  • persons (pandas.DataFrame) – DataFrame of persons with required model variables.

  • calibration_procedure (CalibrationConfig or None) – Calibration procedure to apply, if any.

Returns:

Model predictions for each eligible person (0 = remain unemployed, 1 = become employed).

Return type:

pandas.Series

demos.models.employment.run_and_calibrate_out_workforce_model(persons, calibration_procedure)[source]

Run the ‘exit_labor_force’ estimated model for eligible persons.

Parameters:

  • persons (pandas.DataFrame) – DataFrame of persons with required model variables.

  • calibration_procedure (CalibrationConfig or None) – Calibration procedure to apply, if any.

Returns:

Model predictions for each eligible person (0 = remain employed, 1 = become unemployed).

Return type:

pandas.Series

demos.models.employment.run_simultaenous_calibration(persons, simultaneous_calibration_config)[source]

Run simultaneous calibration for both ‘enter’ and ‘exit’ labor force models.

Parameters:

  • persons (pandas.DataFrame) – DataFrame of persons with required model variables.

  • simultaneous_calibration_config (SimultaneousCalibrationConfig) – Configuration for simultaneous calibration.

Returns:

Predictions for entering and exiting the workforce.

Return type:

tuple of pandas.Series