At-work Subtours Frequency#

The at-work subtour frequency model selects the number of at-work subtours made for each work tour. It also creates at-work subtours by adding them to the tours table in the data pipeline. These at-work sub-tours are travel tours taken during the workday with their origin at the work location, rather than from home. Explanatory variables include employment status, income, auto ownership, the frequency of other tours, characteristics of the parent work tour, and characteristics of the workplace zone.

Choosers: work tours Alternatives: none, 1 eating out tour, 1 business tour, 1 maintenance tour, 2 business tours, 1 eating out tour + 1 business tour Dependent tables: household, person, accessibility Outputs: work tour subtour frequency choice, at-work tours table (with only tour origin zone at this point)

The main interface to the at-work subtours frequency model is the atwork_subtour_frequency function. This function is registered as an Inject step in the example Pipeline.

Structure#

  • Configuration File: atwork_subtour_frequency.yaml

  • Core Table: tours

  • Result Field: atwork_subtour_frequency

Configuration#

settings activitysim.abm.models.atwork_subtour_frequency.AtworkSubtourFrequencySettings#

Bases: LogitComponentSettings

Settings for the atwork_subtour_frequency component.

Fields:
Validators:

  • nests_are_for_nl » NESTS

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

field preprocessor: PreprocessorSettings | None = None#

Setting for the preprocessor.

field sharrow_skip: bool = False#

Skip sharrow when evaluating this component.

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#

Implementation#

activitysim.abm.models.atwork_subtour_frequency.atwork_subtour_frequency(state: State, tours: DataFrame, persons_merged: DataFrame, model_settings: Optional[AtworkSubtourFrequencySettings] = None, model_settings_file_name: str = 'atwork_subtour_frequency.yaml', trace_label: str = 'atwork_subtour_frequency') → None#

This model predicts the frequency of making at-work subtour tours (alternatives for this model come from a separate csv file which is configured by the user).