Telecommute Status#

ActivitySim telecommute representation consists of two long term submodels - a person work_from_home model and a person telecommute_frequency model. The work from home model predicts if a worker works exclusively from home, whereas the telecommute frequency model predicts number of days in a week a worker telecommutes, if they do not exclusively work from home. However, neither of them predicts whether a worker telecommutes or not on the simulation day. This telecommute status model extends the previous two models to predict for all workers whether they telecommute on the simulation day.

A simple implementation of the telecommute status model can be based on the worker’s telecommute frequency. For example, if a worker telecommutes 4 days a week, then there is a 80% probability for them to telecommute on the simulation day. The telecommute status model software can accommodate more complex model forms if needed.

There have been discussions about where to place the telecommute status model within the model sequence, particularly regarding its interation with the Coordinated Daily Activity Pattern (CDAP) model. Some have proposed expanding the CDAP definition of the “Mandatory” day pattern to include commuting, telecommuting and working from home, and then applying the telecommute status model to workers with a “Mandatory” day pattern. While this idea had merit, it would require re-defining and re-estimating CDAP for many regions, which presents practical challenges.

During Phase 9B development, the Consortium collaboratively reached a consensus on a preferred design for explicitly modeling telecommuting. It was decided that the existing CDAP definitions would remain unchanged. The new design introduces the ability to model hybrid workers—those who work both in-home and out-of-home on the simulation day. To support this, the Consortium recommended adding two new models: a Telecommute Arrangement model and an In-Home Work Activity Duration model.

As of August 2025, these two models remain at the design stage and have not yet been implemented. Once deployed, they will supersede the current telecommute status model, which will no longer be needed. In the interim, the telecommute status model can be used to flag telecommuters in the simulation.

The main interface to the telecommute status model is the telecommute_status function. This function is registered as an Inject step in the example Pipeline.

Structure#

  • Configuration File: telecommute_status.yaml

  • Core Table: persons

  • Result Table: is_telecommuting

Configuration#

settings activitysim.abm.models.telecommute_status.TelecommuteStatusSettings#

Bases: LogitComponentSettings

Settings for the telecommute_status component.

Config:

  • extra: str = forbid

Fields:
Validators:

  • update_sharrow_skip » all fields

field CHOOSER_FILTER_COLUMN_NAME: str = 'is_worker'#

Column name in the dataframe to represent worker.

Validated by:

  • update_sharrow_skip

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”.

Validated by:

  • update_sharrow_skip

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

Named constants usable in the utility expressions.

Validated by:

  • update_sharrow_skip

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

Logit model mathematical form.

  • “MNL”

    Multinomial logit model.

  • “NL”

    Nested multinomial logit model.

Validated by:

  • update_sharrow_skip

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:

  • update_sharrow_skip

field SPEC: Path [Required]#

Utility specification filename.

This is sometimes alternatively called the utility expressions calculator (UEC). It is a CSV file giving all the functions for the terms of a linear-in-parameters utility expression.

Validated by:

  • update_sharrow_skip

field TELECOMMUTE_ALT: int [Required]#

Value that specifies if the worker is telecommuting on the simulation day.

Validated by:

  • update_sharrow_skip

field annotate_households: PreprocessorSettings | None = None#

Annotate households output tables with additional columns.

These settings are used to add additional columns to the output tables after the logit model is run. They are typically used to add additional attributes that are derived from the model results.

Validated by:

  • update_sharrow_skip

field annotate_persons: PreprocessorSettings | None = None#

Annotate persons output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_tours: PreprocessorSettings | None = None#

Annotate tours output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_trips: PreprocessorSettings | None = None#

Annotate trips output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_vehicles: PreprocessorSettings | None = None#

Annotate vehicles output tables with additional columns.

Validated by:

  • update_sharrow_skip

field compute_settings: ComputeSettings = ComputeSettings(sharrow_skip=False, fastmath=True, use_bottleneck=None, use_numexpr=None, use_numba=None, drop_unused_columns=True, protect_columns=[], performance_log=None)#

Sharrow settings for this component.

Validated by:

  • update_sharrow_skip

field preprocessor: PreprocessorSettings | list[PreprocessorSettings] | None = None#

Chooser preprocessor settings.

This is a set of expressions to be evaluated on the choosers before the logit model is run. It is used to prepare the choosers for the logit model by adding columns that are used in the utility expressions.

Validated by:

  • update_sharrow_skip

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.

Validated by:

  • update_sharrow_skip

classmethod nests_are_for_nl(nests, values)#

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

validator update_sharrow_skip  »  all fields#

Examples#

Implementation#

activitysim.abm.models.telecommute_status.telecommute_status(state: State, persons_merged: DataFrame, persons: DataFrame, model_settings: TelecommuteStatusSettings | None = None, model_settings_file_name: str = 'telecommute_status.yaml', trace_label: str = 'telecommute_status') → None#

This model predicts whether a person (worker) telecommutes on the simulation day. The output from this model is TRUE (if telecommutes) or FALSE (if does not telecommute).