Joint Tour Participation#

In the joint tour person participation model, each eligible person sequentially makes a choice to participate or not participate in each joint tour. Since the party composition model determines what types of people are eligible to join a given tour, the person participation model can operate in an iterative fashion, with each household member choosing to join or not to join a travel party independent of the decisions of other household members. In the event that the constraints posed by the result of the party composition model are not met, the person participation model cycles through the household members multiple times until the required types of people have joined the travel party.

This step also creates the joint_tour_participants table in the pipeline, which stores the person ids for each person on the tour.

The main interface to the joint tour participation model is the joint_tour_participation function. This function is registered as an Inject step in the example Pipeline.

Structure#

Configuration File: joint_tour_participation.yaml
Core Table: tours
Result Field: number_of_participants, person_id (for the point person)

Configuration#

settings activitysim.abm.models.joint_tour_participation.JointTourParticipationSettings#

Bases: LogitComponentSettings

Settings for the joint_tour_participation 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 annotate_persons: PreprocessorSettings | None = None#: Instructions for annotating the persons table.

field participation_choice: str = 'participate'#

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.joint_tour_participation.joint_tour_participation(state: State, tours: DataFrame, persons_merged: DataFrame, model_settings: Optional[JointTourParticipationSettings] = None, model_settings_file_name: str = 'joint_tour_participation.yaml', trace_label: str = 'joint_tour_participation') → None#: Predicts for each eligible person to participate or not participate in each joint tour.

activitysim.abm.models.joint_tour_participation.participants_chooser(state: State, probs: DataFrame, choosers: DataFrame, spec: DataFrame, trace_label: str) → tuple[Series, Series]#

custom alternative to logit.make_choices for simulate.simple_simulate

Choosing participants for mixed tours is trickier than adult or child tours becuase we need at least one adult and one child participant in a mixed tour. We call logit.make_choices and then check to see if the tour statisfies this requirement, and rechoose for any that fail until all are satisfied.

In principal, this shold always occur eventually, but we fail after MAX_ITERATIONS, just in case there is some failure in program logic (haven’t seen this occur.)

The return values are the same as logit.make_choices

Parameters:

probspandas.DataFrame: Rows for choosers and columns for the alternatives from which they are choosing. Values are expected to be valid probabilities across each row, e.g. they should sum to 1.
chooserspandas.dataframe: simple_simulate choosers df
specpandas.DataFrame: simple_simulate spec df We only need spec so we can know the column index of the ‘participate’ alternative indicating that the participant has been chosen to participate in the tour
trace_labelstr

Returns:

choices, rands: choices, rands as returned by logit.make_choices (in same order as probs)