Step 6 - Trip Distribution

This script models trip distribution in five steps:

  1. Creates empty trip tables for each trip purpose. Each table has an axis for each travel mode in addition to From and To axes.

  2. Seeds each purpose’s trip tables using production and attraction estimates produced for each mode by the mode choice model and the weightedInteractions method in emma. In this step, period factors are applied to adjust daily trip estimates down to period estimates.

  3. Setup shadowing - this forges a relationship between the block-level trip table and the TAZ-level trip table. Factors applied to trips at TAZ level are mimicked at the block level. This allows block-level detail to influence mode shares and distribution to reflect travel opportunities beyond the window area.

  4. Apply k factors - these factors adjust the raw mode choice estimates to better match an observed or modeled condition in a specific scenario. A preferred set of factors should be establsihed and used for all other scenarios for meaningful cross-scenario comparisons.

  5. Balance the trip tables using iterative proporational fitting (IPF). The balancing process focuses on total person trip productions and attractions in the selected travel period. Trips by mode can fluctuate during the balancing process.

After the balancing step is complete, results are reported in csv files.

  • trips_by_mode_and_purpose_dist_{period}.csv: csv

    Summarizes trips by mode and pupose to and from the key broad reporting geographies: focus area, window area, remainder area.

  • trip_len_dist_{period}.csv: csv

    A summary of trips, person miles of travel, and average trip length to and from each TAZ. Can be summarized for arbitray collections of TAZs, including built-in groupings for zones in the focus and window areas. When summarizing, average trip length should be calculated based on the sum of person miles of travel divided by the sum of trips.

  • trip_dur_dist_{period}.csv: csv

    Same as trip_len_dist.csv, but focused on trip duration (in minutes).

trip_cost_dist_{period}.csv: csv

Same as trip_len_dist.csv, but focused on trip generalized costs (in dollars).

Functions

The following functions are referenced in this script, from the wsa.distribution submodule:

wsa.distribution.initTripTable(scen, purpose, period, logger=None)

Intialize a trip table for this scenario, purpose, and period. All trip interchanges are intialized to zero (0.0).

Parameters

  • scen (String) –

  • purpose (String) –

  • period (String) –

  • logger (Logger) –

Returns

taz_trip_table, block_trip_table

Return type

(emma.od.Skim, emma.od.Skim)

wsa.distribution.applyKFactors(trip_table, factors, mode_axis='Mode', **crit)

Expand or contract trips in each mode based on factors that would bring modal estimates in closer alignment with an authoritative validation source (CTPS model, e.g.). Factors should not be scenario-specific but applied consistently across all scenarios.

Parameters

  • trip_table (emma.od.Skim) – Trips in this Skim will be factored by mode.

  • factors (array-like 1d) – Factor values to apply. The number and order of factors must correspond to the modes listed in the trip_table’s mode_axis.

  • mode_axis (String, default="Mode") – The name of the axis in trip_table that identifies each mode.

  • **crit (keyword arguments) – Criteria for applying the factors only to specific portions of the trip_table (apply only to zone in the window area, e.g.)

Returns

factor_table

Return type

emma.od.Skim

wsa.distribution.tripEndsByMode(scen, purpose, period_factor, taz_zone_dim='TAZ', block_zone_dim='block_id', mode_dim='Mode', purp_dim='Purpose', end_dim='End', block_taz_level='TAZ', logger=None)

Summarize trips by mode by zone for this purpose (factored into the specified travel period) and return data frames of trips at TAZ and block level for use in distribtion.

TAZ-level trip estimates in the “window” area are patched in from the block-level estimates, over-riding the original TAZ-level estimates for those zones.

Parameters are mostly focused on identifying axis names for trips_by_mode labeled arrays.

Parameters

  • scen (String) –

  • purpose (String) –

  • period_factor (numeric) – A factor for this period and purpose by which trip estimates are scaled (for all modes) from daily trips to period trips

  • taz_zone_dim (String, default="TAZ") –

  • block_zone_dim (String, default="block_id") –

  • mode_dim (String, default="Mode") –

  • purp_dim (String, default="Purpose") –

  • end_dim (String, default="End") –

  • block_taz_level (String, default = "TAZ") –

  • logger (Logger, default=None) –

Returns

  • trips_df_taz (pd.DataFrame) – For this scenario, purpose, and travel period, these are the estimates of trips by mode (productions and attractions listed separately) at the TAZ level

  • trips_df_block (pd.DataFrame) – Same as above, with trips summarized at block level.

wsa.distribution.seedTripTable(net_config, purpose, trip_table, trips_df, decay_refs, mode_col='Mode', trips_col='trips', end_col='End', id_col='TAZ', level=None, scale='TAZ', modes=['walk', 'bike', 'driver', 'passenger', 'WAT', 'DAT'], nonmotor_modes=['walk', 'bike'], decay_node='/pdf', logger=None)

Uses origin and destination trip estimates and emma’s weightedInteractions method to seed a trip distribution matrix. Trip estimates are filtered by mode and the resulting seed is scaled such that total trips sum to productions.

Parameters

  • net_config (String) – The net config from which to pull decay skim factors.

  • purpose (String) –

  • trip_table (emma.od.Skim) – An empty H5 file where the trip table is stored. This file’s values will be updated, such that trips by each mode are seeded with values based on the weightedInteractions output.

  • trips_df (pd.DataFrame) – A data frame containing trips by mode and end for this purpose. The trip estimates are used in the weightedInteractions procedure to define modal productions and attractions.

  • decay_refs (dict) – A dictionary with keys reflecting mode names in modes and values relating each node to an hdf skim file in the net_config folder where OD decay factors are stored.

  • mode_col (String, default="Mode") – The column in trips_df that identifies each trip estimate’s mode.

  • trips_col (String, default="trips") – The column in trips_df that identifies the trip estimate.

  • end_col (String, default="End") – The column in trips_df that identifies each trip estimate’s end (production or attraction).

  • id_col (String, default="TAZ") – The column in`trips_df` that identifies the zone for each trip estimate.

  • level (String, default=None) – If a decay skim uses a mult-level index for its zone attribute, specify the level in the index to be used for indexing trips_df when running weightedInteractions.

  • scale (String, default="TAZ") – Some steps vary depending on the current analysis scale (“TAZ” or “block”), so the scale is specified here.

  • modes ([String,..], default=["walk", "bike", "driver", "passenger", "WAT", "DAT"]) –

  • nonmotor_modes ([String,..], default=["walk", "bike"]) – Which modes in modes are nonmotorized modes.

  • decay_node (String, default="/pdf") – Name of the node in decay_ref skim file where decay rates are stored.

  • logger (Logger, default=None) –

Returns

Nothing is returned by the function. Rather, values in trip_table are updated based on the outcomes of the weightedInteractions function.

Return type

None

wsa.distribution.tripTargetsByZone(trips_df, zone_col='TAZ', trips_col='trips', end_col='End', logger=None)

From a data frame of trips by zone, mode, and end, summarize trips by zone for each trip end.

Parameters

  • trips_df (pd.DataFrame) –

  • zone_col (String, default="TAZ") –

  • trips_col (String, default="trips") –

  • end_col (String, default="End") –

  • logger (Logger, default=None) –

Returns

targets_p, targets_a

Return type

1d arrays

wsa.distribution.summarizeTripAttributes(trips, mode, net_config, skim_ref, unit, sum_dims=['From', 'To'], factor=1.0)

A helper function to facilitate summarization of trip table data, such as person miles of travel, average trip length, etc.

Parameters

  • trips (emma.od.Skim) – A matrix of trips by mode for a given travel purpose

  • mode (String) – The mode in the Mode axis of trips to summarize

  • net_config (String) – Sets the source directory from which to pull OD cost data

  • skim_ref (Dict) – A dictionary with mode names as keys and skim file parameters (file, node, axis, label) as values to look up key impedance values (distance, time, e.g.) for trip summarization.

  • unit (String) – The trip units being summarized (“miles”, “minutes”, etc.). The units appear in output column headings.

  • sum_dims ([String,..], default=["From", "To"]) – The dimensions over which to summarize trip data.

  • factor (numeric, default=1.0) – Trip sums may be factored for unit conversion if desired (meters to minutes, time to cost, e.g.).

Returns

trip_sum – A data frame with row for each zone

Return type

DataFrome