Write Trip Matrices

Write open matrix (OMX) trip matrices for assignment. Reads the trips table post preprocessor and run expressions to code additional data fields, with one data fields for each matrix specified. The matrices are scaled by a household level expansion factor, which is the household sample rate by default, which is calculated when households are read in at the beginning of a model run. The main interface to write trip matrices is the write_trip_matrices function. This function is registered as an Inject step in the example Pipeline.

Structure

• Core Table: trips

• Result: omx trip matrices

• Skims Keys: origin, destination

This model generates only True or False outcomes, and is structured as a binary logit model.

Park-and-Ride Legs

Each entry in MATRICES[].tables can specify origin and destination columns; they default to origin and destination. This allows a trip using Park-and-Ride Lot Choice to contribute drive and transit legs through pnr_zone_id. Entries with the same name within one output file accumulate into the same OMX matrix.

For example, the following fragment routes outbound drive access to the lot and outbound transit from the lot to the destination, and adds them to the existing auto and transit output demand matrices:

MATRICES:
  - file_name: trip_matrices.omx
    tables:
      - name: auto
        data_field: sov_auto
      - name: transit
        data_field: walk_transit
      - name: auto
        data_field: pnr_outbound
        origin: origin
        destination: pnr_zone_id
      - name: transit
        data_field: pnr_outbound
        origin: pnr_zone_id
        destination: destination
      - name: auto
        data_field: pnr_inbound
        origin: pnr_zone_id
        destination: destination
      - name: transit
        data_field: pnr_inbound
        origin: origin
        destination: pnr_zone_id

Before writing matrices, use the preprocessor to map the final tour lot onto the trips table by tour_id and create the data fields to aggregate. In this example, pnr_outbound is a count or weight for the applicable outbound park-and-ride trips and zero for other trips. It must check actual mode use and a valid lot, since a candidate lot alone does not imply park-and-ride use. Create corresponding inbound fields and entries for destination-side origin to lot (transit), then lot to home-side destination (auto). Implementations with intermediate stops must define which trips use each portion of the path.

These column names are illustrative, not automatically generated fields. The writer does not split trips automatically. Supply endpoint columns in a consistent zone system suitable for the output domain; for two-zone outputs, land-use TAZ mappings are used when conversion is needed. Household expansion weights apply to these entries as they do to other matrices.

Configuration

settings activitysim.abm.models.trip_matrices.WriteTripMatricesSettings

Bases: PydanticReadable

Settings for the write_trip_matrices component.

Fields:

• CONSTANTS (dict[str, Any])

• HH_EXPANSION_WEIGHT_COL (str)

• MATRICES (list[MatrixSettings])

• SAVE_TRIPS_TABLE (bool)

• preprocessor (PreprocessorSettings | None)

• source_file_paths ()

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

field HH_EXPANSION_WEIGHT_COL: str = 'sample_rate'

Column represents the sampling rate of households

field MATRICES: list[MatrixSettings] = []

field SAVE_TRIPS_TABLE: bool = False

Save trip tables

field preprocessor: PreprocessorSettings | None = None

Examples

• Prototype MTC

• Prototype ARC

Implementation

activitysim.abm.models.trip_matrices.write_trip_matrices(state: State, network_los: Network_LOS, trips: DataFrame, model_settings: WriteTripMatricesSettings | None = None, model_settings_file_name: str = 'write_trip_matrices.yaml') → None

Write trip matrices step.

Adds boolean columns to local trips table via annotation expressions, then aggregates trip counts and writes OD matrices to OMX. Save annotated trips table to pipeline if desired.

Writes taz trip tables for one and two zone system.

For one zone system, uses the land use table for the set of possible tazs. For two zone system, uses the taz skim zone names for the set of possible tazs.