XBorder PR

[mxndrwgrdnr]

I. Background

This branch was cloned from develop so that the codebase can be edited/updated without interfering with the working version of the XBorder code that lives in develop.

To Discuss:

• Which changes belong in SANDAG/ABM/src/asim_cross_border/extensions/ and which changes should/must remain here in core//abm/?
• Of the latter, which changes should be included in PR, and which should not?

To Do:

• Add docstrings to new methods/modules
• Create XBorder example and add it to tests.

Goals:

• After merge into master, submit second PR to merge changes to the main (upstream) ActivitySim fork.

II. Detail

Brand new model steps:

• tour_scheduling_probabilistic
  • WHAT: Probabilistic alternative to logit-based tour scheduling
  • WHY: Survey data is often too sparse to properly estimate a multinomial logistic regression model for tour scheduling. A probabilistic approach solves this problem by allowing the user to provide a probability lookup table instead of a logit specification.
  • HOW: This new step is modeled after the existing "trip_scheduling" model, which already uses a probability lookup table to assign departure times. Rather than replicating this code in a new model, the probabilistic assignment logic that the new steps have in common was consolidated into a new abm/models/util/ module called probabilistic_scheduling.py. This approach has the added benefit of streamlining the "trip_scheduling" code.
  • COMPATIBILITY: All new model steps are fully backwards compatible with existing ActivitySim implementations.
  • RECOMMENDATION: ActivitySim PR
• tour_od_choice
  • WHAT: Jointly modeled tour origin and destination choice
  • WHY: Currently ActivitySim depends upon the existence of a hard-coded "home_zone_id" column in the households table. However, synthetic population data may not always have residential location assignments (e.g. a synthetic population based on aggregate travel demand). In fact, many potential ActivitySim users may not have access to a synthetic population at all. By allowing agents to choose a tour origin at the same time as they choose a tour destination, we can greatly relax the input data requirements and broaden the scope of analyses that are possible with ActivitySim.
  • HOW: This model works much like the other location choice models in ActivitySim, except the table of alternatives is comprised of origin-destination pairs rather than just destinations. The alternatives a created dynamically by merging the land use table against itself and allowing the user to specify a subset of zones to be used as tour origins.
  • COMPATIBILITY: All new model steps are fully backwards compatible with existing ActivitySim implementations.
  • RECOMMENDATION: ActivitySim PR
• reassign_tour_purpose_by_poe
  • WHAT: Update tour purpose after tour origin has been assigned.
  • WHY: As mentioned above, when a synthetic population is derived from aggregate travel demand data, the households may not have residential locations, but they may have tour purposes derived from an observed probability distribution. In this case, the tour OD choice model can be segmented by tour purpose. This model allows the system to update the tour purposes after the tour origin has been chosen in order to ensure that the distribution of tour purposes at the tour origin matches the observed marginal distributions.
  • HOW: A simple monte carlo simulation is performed based on a user defined exogenous probability distribution of tour purposes for each tour origin.
  • COMPATIBILITY: All new model steps are fully backwards compatible with existing ActivitySim implementations.
  • RECOMMENDATION: example_sandag_xborder/extensions

Brand new modules:

• abm/models/util/trip.py
  • WHY: Currently, the code to generate the ActivitySim "trips" table is spread across multiple modules. The stop_frequency step first instantiates the table, and then trip_destination augments it with origin and destination columns that are inherited from the parent tour. The trip.py module provides a more intuitive home in the code base for this code, and consolidates it under a single module: initialize_from_tours(). By isolating the trips initialization process in this way, it also makes it possible to initialize trips from within any number of arbitrary model steps. This in turn allows the user to compute trip-level metrics (e.g. trip mode choice logsums) for use in a model step that precedes "stop_frequency".
  • COMPATIBILITY: As seen here, the "trips" table will still be instantiated in the "stop_frequency" model, making this change fully backwards compatible with all existing ActivitySim implementations.
  • RECOMMENDATION: ActivitySim PR
• abm/models/util/tour_od.py
  • WHY: Much like the location_choice.py models ("workplace_location_choice" and "school_location_choice") rely on the tour_destination.py submodule to do their heavy lifting, tour_od.py helps to keep the "tour_od_choice" model step definition code to a minimum.
  • COMPATIBILITY: The "tour_od.py" module is only used by the "tour_od_choice" model, so this change is completely backwards compatible will all existing ActivitySim implementations.
  • RECOMMENDATION: ActivitySim PR
• abm/models/util/probabilistic_scheduling.py
  • WHY: As explained above, this module consolidates the probabilistic departure time assignment that is common between the "trip_scheduling" model and the new "tour_scheduling_probabilistic" model.
  • COMPATIBILITY: Fully backward compatible after replacing this entire 100 line chunk of code with one call to the new module as seen here.
  • RECOMMENDATION: ActivitySim PR

Existing models with substantial changes:

• tour_mode_choice
  • WHAT: pseudo-trip generation and trip mode choice execution
  • WHY: Tour mode choice models are commonly specified to include trip-level mode choice logsum terms. This functionality is currently not supported by ActivitySim and is thus an obstacle for users wishing to convert existing travel demand models over to ActivitySim.
  • HOW: Use the new trip.initialize_from_tours() method to create a table of half-tour trips (one outbound, one inbound) based on the tour origin and destination of each tour for each potential tour mode choice alternative. Then use this table of pseudo-trips to call the "trip_mode_choice" model from within "tour_mode_choice". Save the trip_mode_choice logsums and append them to the tours table.
  • COMPATIBILITY: This new functionality gets triggered by a new tour_mode_choice model configuration parameter. This parameter is completely optional (as seen here), making this change completely backwards compatible will all existing ActivitySim implementations.
  • RECOMMENDATION: ActivitySim PR
• stop_frequency
  • WHAT: As described above, this change moves the trips initialization code to abm/models/util/trip.py
  • WHY: Code legibility and extensibility. Trips can now be initialized by any model step.
  • HOW: The stop_frequency.py module now just calls the abm/models/util/trip.py module here.
  • COMPATIBILITY: Fully backwards compatible.
  • RECOMMENDATION: ActivitySim PR
• trip_destination
  • WHAT: As described above, trip OD instantiation is moved from here to here.
  • WHY: Code legibility and extensibility. Trips can now be initialized by any model step.
  • HOW: The "trip_destination" model now only initializes trip ODs if called from within "trip_purpose_and_destination" as described in the comment here.
  • COMPATIBILITY: Fully backward compatible.
  • RECOMMENDATION: ActivitySim PR
• trip_scheduling
  • WHAT: 1) stop duration scheduling mode; and 2) inbound scheduling constraint updating
  • WHY: 1) When survey data is too sparse to populate a probability lookup table for all possible departure periods, stop duration probabilities are often used to simulate sequential trip departure times; 2) Under the existing trip scheduling process, it is possible for inbound trips to depart before the last outbound trip of a tour.
  • HOW: 1) A new parameter in the "trip_scheduling" .yaml config and an internal duration probability processing method in the new "probabilistic_scheduling.py" module; 2) Update the tour_earliest constraint after the last outbound trip is scheduled as seen here
  • COMPATIBILITY: 1) The scheduling_mode parameter is completely optional, with the default set to the existing departure-based scheduling mode to ensure complete backwards compatibility; 2) This change is really a bug fix. So although it is fully backwards compatible with existing ActivitySim implementations, new inbound trip departure times are to be expected.
  • RECOMMENDATION: ActivitySim PR

Existing modules with substantial changes:

• pathbuilder.py
  • WHAT: Turn tracing off if certain conditions are met.
  • WHY: When transit paths are filtered here it is rare but possible that no viable transit paths remain. In this case we have to force tracing to be turned off or else a very convoluted series of errors will be generated.
  • HOW: Conditional clauses here, here, and here
  • COMPATIBILITY: This is a bug fix and as such is fully backwards compatible with all existing ActivitySim implementations.
  • RECOMMENDATION: ActivitySim PR

[mxndrwgrdnr]

Docstring progress:

• tour_od_choice.py
• tour_od.py
• tour_scheduling_probabilistic.py
• probabilistic_scheduling.py
• reassign_tour_purpose_by_poe.py
• tour_mode_choice.py
• trip.py
• stop_frequency.py
• trip_destination.py
• trip_scheduling.py
• pathbuilder.py