Work from Home

Telecommuting is defined as workers who work from home instead of going to work. It only applies to workers with a regular workplace outside of home. The telecommute model consists of two submodels - this work from home model and a person telecommute_frequency model. This model predicts for all workers whether they usually work from home.

The work from home model includes the ability to adjust a work from home alternative constant to attempt to realize a work from home percent for what-if type analysis. This iterative single process procedure takes as input a number of iterations, a filter on the choosers to use for the calculation, a target work from home percent, a tolerance percent for convergence, and the name of the coefficient to adjust. An example setup is provided and the coefficient adjustment at each iteration is: new_coefficient = log( target_percent / current_percent ) + current_coefficient.

The main interface to the work from home model is the work_from_home function. This function is registered as an Inject step in the example Pipeline.

Structure

• Configuration File: work_from_home.yaml

• Core Table: persons

• Result Table: work_from_home

Configuration

settings activitysim.abm.models.work_from_home.WorkFromHomeSettings

Bases: LogitComponentSettings

Settings for the work_from_home component.

Fields:

• CHOOSER_FILTER_COLUMN_NAME (str)

• COEFFICIENTS (pathlib.Path | None)

• CONSTANTS (dict[str, typing.Any])

• DEST_CHOICE_COLUMN_NAME (str)

• LOGIT_TYPE (Literal['MNL', 'NL'])

• NESTS (activitysim.core.configuration.logit.LogitNestSpec | None)

• SPEC (str)

• WORK_FROM_HOME_ALT (int)

• WORK_FROM_HOME_CHOOSER_FILTER (str)

• WORK_FROM_HOME_COEFFICIENT_CONSTANT (float)

• WORK_FROM_HOME_ITERATIONS (int)

• WORK_FROM_HOME_TARGET_PERCENT (float)

• WORK_FROM_HOME_TARGET_PERCENT_TOLERANCE (float)

• preprocessor (activitysim.core.configuration.base.PreprocessorSettings | None)

• sharrow_skip (bool)

• source_file_paths (list[pathlib.Path])

Validators:

• nests_are_for_nl » NESTS

field CHOOSER_FILTER_COLUMN_NAME: str = 'is_worker'

Column name in the dataframe to represent worker.

field COEFFICIENTS: Path | None = None

Coefficients filename.

This is a CSV file giving named parameters for use in the utility expression. If it is not provided, then it is assumed that all model coefficients are given explicitly in the SPEC as numerical values instead of named parameters. This is perfectly acceptable for use with ActivitySim for typical simulation applications, but may be problematic if used with “estimation mode”.

field CONSTANTS: dict[str, Any] = {}

Named constants usable in the utility expressions.

field DEST_CHOICE_COLUMN_NAME: str = 'workplace_zone_id'

Column name in persons dataframe to specify the workplace zone id.

field LOGIT_TYPE: Literal['MNL', 'NL'] = 'MNL'

Logit model mathematical form.

• “MNL”

  Multinomial logit model.

• “NL”

  Nested multinomial logit model.

field NESTS: LogitNestSpec | None = None

Nesting structure for a nested logit model.

The nesting structure is specified heirarchically from the top, so the value of this field should be the “root” level nest of the nested logit tree, which should contain references to lower level nests and/or the actual alternatives.

For example, this YAML defines a simple nesting structure for four alternatives (DRIVE, WALK, WALK_TO_TRANSIT, DRIVE_TO_TRANSIT) with the two transit alternatives grouped together in a nest:

NESTS:
  name: root
  coefficient: coef_nest_root
  alternatives:
    - DRIVE
    - WALK
    - name: TRANSIT
      coefficient: coef_nest_transit
      alternatives:
      - WALK_TO_TRANSIT
      - DRIVE_TO_TRANSIT

Validated by:

• nests_are_for_nl

field SPEC: str = 'work_from_home.csv'

Filename for the accessibility specification (csv) file.

field WORK_FROM_HOME_ALT: int [Required]

Value that specify if the person is working from home

field WORK_FROM_HOME_CHOOSER_FILTER: str = None

Setting to filter work from home chooser.

field WORK_FROM_HOME_COEFFICIENT_CONSTANT: float = None

Setting to set the work from home coefficient.

field WORK_FROM_HOME_ITERATIONS: int = 1

Setting to specify the number of iterations.

field WORK_FROM_HOME_TARGET_PERCENT: float = None

Setting to set work from target percent.

field WORK_FROM_HOME_TARGET_PERCENT_TOLERANCE: float = None

Setting to set work from home target percent tolerance.

field preprocessor: PreprocessorSettings | None = None

Setting for the preprocessor.

field sharrow_skip: bool = False

Setting to skip sharrow.

field source_file_paths: list[Path] = None

A list of source files from which these settings were loaded.

This value should not be set by the user within the YAML settings files, instead it is populated as those files are loaded. It is primarily provided for debugging purposes, and does not actually affect the operation of any model.

validator nests_are_for_nl  »  NESTS

Checks that nests are provided if (and only if) LOGIT_TYPE is NL.

Examples

• Prototype SEMCOG

• Prototype MWCOG

Implementation

activitysim.abm.models.work_from_home.work_from_home(state: State, persons_merged: DataFrame, persons: DataFrame, model_settings: Optional[WorkFromHomeSettings] = None, model_settings_file_name: str = 'work_from_home.yaml', trace_label: str = 'work_from_home') → None

This model predicts whether a person (worker) works from home. The output from this model is TRUE (if works from home) or FALSE (works away from home). The workplace location choice is overridden for workers who work from home and set to -1.