Step 4 - Trip Generation

Trip generation proceeds in two parts:

Trips by zone

This script estimates trip generation for home-based and non-home-based trip generators separately, combines the results, and stores trip generation estimates as well as household cross-classification results in HDF arrays that can be read using emma.lba.openLbArray_HDF.

Home-based productions are stratified by household type.
  • Read estimates of households in each zone across 4 dimensions

    • HH size (1, 2, 3, 4+)

    • Number of workers (0, 1, 2, 3+)

    • Income group (1, 2, 3, 4)

    • Vehicle ownership (0, 1, 2, 3+)

  • Read trip generation rates and seed data for household cross-classification

  • Cross-classify households into 256 HH types using iterative proprtional fitting (see emma.ipf)

Attractions are estimated based on destination activities (jobs by type, school enrollments, etc.)

Non-home-based productions are estimated based on household variables but redistributed to match the spatial allocation implied by non-home generators.

This script needs to be run for each land use configuration. Results are stored in the “lu” folder corresponding to each land use configuration. Results generated include:

  • hh_by_type_sum.csv: csv

    Summary table of households by type by focus and window area inclusion (for high-level QA of results).

  • trip_gen_summary.csv: csv

    Summary table of trips by purpose and end by focus and window area inclusion.

  • trips_by_zone.csv: csv

    TAZ-level tabulation of trips by purpose and end.

  • HHs_by_type_taz.h5: LbArray

    Cross-classified households by type in each TAZ.

  • trips_by_taz.h5: LbArray

    Trip productions and attractions by purpose and household type in each TAZ.

Trips by block (in window)

This script estimates block-level trips by household type and non-home activities based on TAZ-level trip estimates and block-level activity estimates. This is accomplished in 3 major steps:

  1. Estimate activity-based block trip generation propensity by purpose

    • Propensities are estimated such that every block has an extremely small starting propensity, and this grows based on block activities. This is to alleviate potential discontinuities between block-level and TAZ-level activity estimates.

      • Home-based propensity is informed by HH types

      • Non-home-based propensity is informed by job types and enrollments

  2. Normalize the activity-based propensities such that they sum to 1.0 within each TAZ.

    • Summarize the activity-based propensities to yield the total trip-making propensity for each TAZ. The resultsing score is the total trip gen propensity (either for P’s or A’s) by purpose.

    • Normalize block-level, activity-specific propensities based on its parent TAZ’s total trip-making propensity. When each block’s trip total is estimated, these normalized shares determine trips by activity type.

  3. Multiply TAZ-level trip estimates by purpose and trip-end to block- level, activity-based normalized propensities. This yields activity- based trips by block.

Results generated include (for “window” area only):
  • trips_by_block.csv: csv

    Block-level tabulation of trips by purpose and end.

  • HHs_by_type_block.h5: LbArray

    Cross-classified households by type in each block.

  • trips_by_block.h5: LbArray

    Trip productions and attractions by purpose and household type in each block.

Functions

The following functions are referenced in this script, from the wsa.trip_gen (or tg) submodule:

wsa.tg.readTAZs(lu_config, taz_table='MAPC_TAZ_data.xlsx', taz_sheet='Zdata', taz_id='TAZ', zones_in_model='input\\model_area_zones.csv', zim_id='ID')

Reads zone input tables from default locations.

Parameters

  • lu_config (String) –

  • taz_table (String, default="MAPC_TAZ_data.xlsx") –

  • taz_sheet (String, default="Zdata") –

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

  • zones_in_model (String, default="inputmodel_area_zones.csv") –

  • zim_id (String, default="ID") – The field that identifies each TAZ in zones_in_model.

Returns

taz_df – TAZ records from taz_table filtered by values in zones_in_model

Return type

pd.DataFrame

wsa.tg.readBlocks(lu_config, block_hh_table='Household_Types_by_Block.csv', block_emp_table='Jobs_Enroll_by_Block.csv', hh_id_field='block_id', emp_id_field='block_id', window_blocks='input\\window_blocks.csv', wb_id='GEOID10')

Reads block input tables from default locations.

Parameters

  • lu_config (String) –

  • block_hh_table (String, default="Household_Types_by_Block.csv") –

  • block_emp_table (String, default="Jobs_Enroll_by_Block.csv") –

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

  • hh_field (String, default="Households") –

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

  • emp_act_field (String, default="tot_emp") –

  • window_blocks (String, default="window_blocks.csv") –

  • wb_id (String, default="GEOID10") –

Returns

  • hh_df (pd.DataFrame) – Block-level households by type. Rows reflect only the blocks listed in window_blocks.

  • nh_df (pd.DataFrame) – Block-level non-home activities. Rows reflect only the blocks listed in window_blocks.

  • wb_df (pd.DataFrame) – Block ids with TAZ ids. Rows reflect only the blocks listed in window_blocks.

wsa.tg.relabel(row, column, value_dict)

Supporting funciton to replace values based on a dictionary lookup. Called from DataFrame.apply().

Parameters

  • row (Iterable) – A row in a pandas DataFrame

  • column (String) – The column to relabel

  • value_dict ({String: String, ..}) – A dictionary with keys reflecting original value at this row/column location and values reflecting the value to write to this location. If the original value is not in the dictionary, the original value remains in place.

wsa.tg.prepSeed(seed_df)

Convert seed data to a long form data frame. Use when reading in household cross-classification seeds. Transforms the seed from its original format to a long format compatible with later components of the trip-generation process.

Parameters

seed_df (pd.DataFrame) –

Returns

long_seed

Return type

pd.DataFrame

wsa.tg.getSeedByTAZ(taz_id, lookup_df, seed_df, veh_df)

Lookup seed matrices based on the PUMA ID associated with each TAZ. Add the vehicle ownership dimension (not included in seed source) from values provided in a separate data frame.

Parameters

  • taz_id (Numeric) – The taz for which to fetch the appropriate HH cross-classification seed.

  • lookup_df (pd.DataFrame) – A data frame in which taz’s are related to PUMA id’s so that the appropriate seed can be pulled for the provided taz_id.

  • seed_df (pd.DataFrame) – A data frame with seed details by PUMA.

  • veh_df (pd.DataFrame) – A simple data frame with assumed seed values by vehicle ownership categories.

Returns

seed_vo – The seed details for this taz (based on its PUMA location), with vehicle ownership seed estimated from regional averages.

Return type

pd.DataFrame

See also

fetchSeedArray()

wsa.tg.fetchSeedArray(taz_id, lookup_df, long_seed, veh_df)

Convert a seed matrix to a labeled array. The seed matrix is first looked up based on TAZ ID and the lookup data frame.

Parameters

  • taz_id (Numeric) – The TAZ for which to fetch the seed data.

  • lookup_df (pd.DataFrame) – A data frame relating TAZs to PUMA ID’s.

  • long_seed (pd.DataFrame) – A long-form data frame with IPF seed values for a PUMA

  • veh_df (pd.DataFrame) – A data frame with generalize vehicle ownership seed shares.

Returns

seed_array

Return type

LbArray

See also

getSeedByTAZ()

wsa.tg.dfToLabeledArray_tg(tg_df, ref_array, dims, act_col, block_id='block_id', excl_labels='-', levels=['block_id', 'TAZ', 'INWINDOW', 'INFOCUS'])

Convert a data frame of block-level activities to a labeled array. Fill in label values based on a reference array (taz activities, e.g.) and enrich and align axes for clean downstream operations.

Parameters

  • tg_df (pd.DataFrame) – A data frame with block-level activity data. WARNING! The data frame is modified in-place (NaN values are replaced by labels)

  • ref_array (LbArray) – A labeled array with activities by TAZ. This provdes the basic form for the block-level array returned by the function.

  • dims ([String,..]) – Axis names in ref_array corresponding to activity dimensions.

  • act_col (String) – The column in tg_df that contains activity value estimates.

  • block_id (String, default="block_id") – The column in`tg_df` that identifies each block.

  • excl_labels (String or [String,..], default="-") – A collection of labels (in any axis) whose values are dropped when casting the block-level array returned by the function.

  • levels ([String,..], default=["block_id", "TAZ", "INWINDOW", "INFOCUS"]) – The names of columns in tg_df that will be used to add levels to the block-level array returned by the function. These keep intact block-level nesting information.

Returns

act_array – A block level array of activity data (based on tg_df) whose axis labels align with those in ref_array.

Return type

LbArray

wsa.tg.calcPropensity_HB(prop_array, hh_propensity_dict, end_axis='End', prod_label='P')

A function to calculate trip-making propensities for home-based trip generators. Home-based trip-making propensity is estimated based on household types in each block and their respective generalized trip-making propensity factors.

Parameters

  • prop_array (LbArray) – A labeled array, assumed to be initialized to 1.0 and having axes with labels corresponding to those named in hh_propensity_dict.

  • hh_propensity_dict (Dict) – A nested dictionary whose keys correspond to axis names in prop_array and whose values are dictionaries of labels that are members of the named axis and propensity weights.

  • end_axis (String, default="End") – prop_array is assumed to cover all potential trips (home-based or otherwise) and both trip ends. This function only updates the

  • prod_label (String, default="P") –

Returns

prods – An estimate of productions propensity for different household types.

Return type

LbArray

See also

calcPropensity_NH(), normalizePropensity(), applyTAZTrips()

wsa.tg.calcPropensity_NH(nh_df, lbl_col, act_col, purposes, propensities, base_prop, wb_df, block_id='block_id', wb_block_id='block_id', levels=['block_id', 'TAZ', 'INFOCUS', 'INWINDOW'], logger=None)

A function to calculate raw block-level trip-making propensities for non-home trip generators, by purpose. Non-home trip-making propensity is estimated based on various non-home activities in each block and their respective generalized trip-making propensity factors.

Parameters

  • nh_df (pd.DataFrame) – A data frame of non-home activities by block.

  • lbl_col (String) – The column in nh_df that identifies each block’s activity by type.

  • act_col (String) – The column in nh_df that stores the number of each activity.

  • purposes ([String,..]) – The purposes for which trip propensities are estimated.

  • propensities ({String: {String: {String: [numeric,..]}}}) – A nested dictionary of trip-making propensities. At the outer level, keys are trip purposes; at the middle level, keys are axis names; at the inner level, keys are axis labels and values are propensity weights.

  • base_prop (numeric) – A baseline trip-making propensity. This is a small value that ensures all blocks have a nominal trip-making potential. Blocks with activities will have significantly higher propensities based on the number of activities and the propensities dictionary.

  • block_id (String, default="block_id") – The column in nh_df that uniquely identifies each block.

  • wb_df (pd.DataFrame) – The data frame listing the blocks in the window area with their TAZ parentage.

  • wb_block_id (String, default="block_id") – The column in wb_df that uniquely identifies each block.

  • levels ([String,..], default=["block_id", "TAZ", "INFOCUS", "INWINDOW"]) – A list of column names in nh_df that defined indexing levels.

Returns

nh_array – A labeled array with an axis storing block information (with levels recorded in a multi-index) and an axis differentiating trip propensities by purpose.

Return type

LbArray

See also

calcPropensity_HB(), normalizePropensity(), applyTAZTrips()

wsa.tg.normalizePropensity(block_prop_array, block_axis, taz_level='TAZ', block_level='block_id', ends=['P', 'A'], purposes=['HBW', 'HBO', 'HBSch', 'NHB'])

Estimate each block’s share of total TAZ trip-making by activty type.

Parameters

  • block_prop_array (LbArray) – An array of total estimated trip-making propensity by block and activity type. Assumed to have axes “Purpose” and “End”.

  • block_axis (LbAxis) – The axis in block_prop_array that identifies each block. Assumed to be a MultiIndex object with one level identifying blocks and the other identifying TAZs.

  • taz_level (String, default="TAZ") – The name of the level in block_axis that identifies the TAZ each block is in.

  • block_level (String, default="block_id") – The name of the level in block_axis that uniquely identifes each block.

  • ends ([String,..], default=["P", "A"]) – The names of values in the End axis of block_prop_array.

  • purposes ([String,..], default=["HBW", "HBO", "HBSch", "NHB"]) – The names of values in the Purpose axis of block_prop_array.

Returns

block_prop_array is updated inplace, such that its raw propensity estimates are normalized into shares of total TAZ-level trip-making.

Return type

None

See also

calcPropensity_HB(), calcPropensity_NH(), applyTAZTrips()

wsa.tg.applyTAZTrips(taz_trips_array, taz_axis, taz_level, block_prop_array, block_axis, block_level, ends=['P', 'A'], purposes=['HBW', 'HBO', 'HBSch', 'NHB'])

Multiply normalized trip-making propensities at block level by total trip estimates (by purpose) at TAZ level.

Parameters

  • taz_trips_array (LbArray) – A labeled array with trip estimates by TAZ, purpose, and end (production vs. attraction)

  • taz_axis (LbAxis) – The axis in taz_trips_array that identifies each TAZ.

  • taz_level (String) – The name of the level in taz_axis that uniquely identifies each TAZ.

  • block_prop_array (LbArray) – A labeled array with normalized trip-making propensities by block, activity, purpose, and end.

  • block_axis (LbAxis) – The axis in block_prop-array that identifies each block by its TAZ perentage (assumed to use the same name as taz_level)

  • block_level (String) – The name of the level in block_axis that uniquely identifies each block.

  • ends ([String,..], default=["P", "A"]) – The values in the End axis of both taz_trips_array and block_prop_array.

  • purposes ([String,..], default=["HBW", "HBO", "HBSch", "NHB"]) – The values in the Purpose axis of both taz_trips_array and block_prop_array.

Returns

block_prop_array is modified in place such that its normalized shares of TAZ-level trip-making are multiplied by total trips in each corresponding TAZ to yield total trips at the block level, by activity

Return type

None

See also

calcPropensity_HB(), calcPropensity_NH(), normalizePropensity()