Step 7 - TNC Trips

This script estimates the number of TNC trips by TAZ based on a trip table, modal skims (to understand costs by the estimated mode and estimate costs for a potential TNC trip), and alpha values. The probability for taking a TNC trip given its generalized cost must exceed the probability of taking the same trip by the original estimated mode by a factor that exceeds the alpha value set for that mode and travel purpose.

This is a post-processing step that ingests ouptuts from previous steps to provide insight into the number of TNC trips made and what those trips imply for mode shifts.

TNC trip cost parameters are specified as global parameters: TNC_BASE_FARE, TNC_SERVICE_FEE, TNC_COST_PER_MILE.

Alpha values may be calculated when the script is run to calibrate them to targets for aggregate TNC trips by purpose and mode replaced. Once calibrated to a base condition, the same values should be run for alternative scenarios or alternative TNC cost constructions to gauge the impact on TNC utilization.

The script summarizes TNC estimates in two csv tables:

  • TNC_flow_summary_{period}.csv: csv

    Reports TNC trips by purpose and mode replaced for generalized reporting geographies (focus, window, and remainder areas). Summarizes TNC trips, total trips (in the original trip tables), and percent switchted to TNC.

  • TNC_zone_summary_{period}.csv: csv

    Similar to TNC_flow_summary, but broken down on a TAZ-by-TAZ basis.

Functions

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

wsa.TNC.fetchTNCSeed(excel_file, named_range='ipf_seed', purp_col='Purpose', modes=['Walk', 'Bike', 'Transit', 'Driver', 'Passenger'])

Read an IPF seed for estimating regional TNC trips by mode and purpose targets from an excel file. Return the seed as a labeled array.

Parameters

  • excel_file (String) – Path to the excel file with the IPF seed information

  • named_range (String, default="ipf_seed") – A named range in excel_file where seed data may be found.

  • purp_col (String, default="Purpose") – The column heading in the ipf seed range that identifies trip purpose

  • modes ([Syring,..], default=["Walk", "Bike", "Transit", "Driver", "Passenger"]) – The column headings in the ipf seed range that identify travel modes

Returns

seed_array – A labeled array with seeds in two dimensions: Purpose and Mode

Return type

LbArray

wsa.TNC.fetchTNCModeTargets(excel_file, named_range='mode_targets', modes=['Walk', 'Bike', 'Transit', 'Driver', 'Passenger'])

Read a set of modal targets from an excel file reflecting the total TNC trips switched from various modes. These are used in an IPF process to set mode and purpose-specific control totals and setting TNC probability alpha values.

Parameters

  • excel_file (String) – Path to the excel file with the modal target information

  • named_range (String, default="mode_targets") – A named range in excel_file where the targets are found. The range is assumed to consist of a single row, with values ordered in direct correspondence to modes

  • modes ([String,..], default=["Walk", "Bike", "Transit", "Driver", "Passenger"]) – The modes included in the named_range value set. Listed in order shown in the excel file.

Returns

targets – A series of modal targets with mode names as the index.

Return type

pd.Series

wsa.TNC.estimateAlphas(trip_table, tnc_ratio_skim, targets_array, mode, purpose)

Given labeled arrays with trip estimates and TNC probability ratios, determine the probability ratio needed to attain a targeted number of trips for a given mode and purpose.

Parameters

  • trip_table (LbArray) – A labeled array with trips estimated for each OD pair for this mode and purpose.

  • tnc_ratio_skim (LbArray) – A labeled array with TNC probabilty estimates for each OD pair for this mode and purpose.

  • targets_array (LbArray) – A labeled array with targets for TNC trip substitutions given this mode and purpose.

  • mode (String) – The current travel mode whose trips could be candidates for TNC substituation.

  • purpose (String) – The purpose of travel.

Returns

alpha – The TNC probability ratio needed to substitute the targeted number of trips for this mode and purpose. Once established, it should remain the same for other scenarios for cross-scenario comparisons.

Return type

Float

wsa.TNC.initTNCCostArray(scen, purpose, period, hdf_store=None, node_path=None, name=None, overwrite=False, logger=None)

Initialize a new Skim object to record TNC cost components and estimated TNC total costs and trip probabilities.

Parameters

  • scen (String) –

  • purpose (String) –

  • period (String) –

  • hdf_store (String, default=None) –

  • node_path (String, default=None) –

  • name (String, default=None) –

  • Boolean, default=False (overwrite;) –

  • logger (Logger, default=None) –

Returns

Return type

Skim

wsa.TNC.initTNCRatioArray(scen, purpose, period, hdf_store=None, node_path=None, name=None, overwrite=False, logger=None)

Initialize a new Skim object to record modal trip probabilities and TNC trip probability ratios.

Parameters

  • scen (String) –

  • purpose (String) –

  • period (String) –

  • hdf_store (String, default=None) –

  • node_path (String, default=None) –

  • name (String, default=None) –

  • Boolean, default=False (overwrite;) –

  • logger (Logger, default=None) –

Returns

Return type

Skim

wsa.TNC.estimateTNCCosts(auto_skim, purpose, tnc_cost_skim, value_of_time, tnc_base_fare, tnc_service_fee, tnc_cost_per_mile, tnc_decay_mu, tnc_decay_sigma, imp_axis='Impedance', time_label='TravelTime', dist_label='Distance', logger=None)

Estimate TNC cost components. Pulls data for estimates of auto trip durations and distances, calculates TNC estimated costs (time and money) using global cost params. Estimates TNC decay factors for each potential OD pair.

Parameters

  • auto_skim (Skim) – A skim with time and distance impedances for traveling by car. These are used to estimate TNC travel costs.

  • purpose (String) –

  • tnc_cost_skim (String) – A labeled array that will holds the dimensions of TNC costs and the final generalized cost estimate for TNCs for all OD pairs.

  • value_of_time (Numeric) – A factor to convert between time and monetary units, expressed as dollars per hour.

  • tnc_base_fare (Numeric) –

  • tnc_service_fee (Numeric) –

  • tnc_cost_per_mile (Numeric) –

  • tnc_decay_mu ({"minutes": Numeric, "dollars": Numeric}) – A parameter in the lognormal decay expression used to estimate TNC trip propensities, mu varies for cost-based or time-based analyses. The mu values are therefor provided in a dictionary.

  • tnc_decay_sigma (Numeric) – A parameter in the lognormal decay expression used to estimate TNC trip propensities, sigma varies for cost-based or time-based analyses. The sigma values are therefor provided in a dictionary.

  • imp_axis (String, default="Impedance") – The name of the axis in auto_skim along which to find various impedances

  • time_label (String, default="TravelTime") – The impedance axis label where OD travel time estimates are stored.

  • dist_label (String, default="Distance") – The impedance axis label where OD distance estimates are stored.

  • logger (Logger) –

Returns

Return type

None - the tnc_cost_skim is modified in place.

wsa.TNC.estimateTNCProb(net_config, purpose, tnc_ratio_skim, tnc_cost_skim, decay_refs, mode_dict, mode_impedances, use_units='Dollars', all_purposes=['HBW', 'HBO', 'HBSch', 'NHB'], logger=None)

Estimate probability ratios for TNC trips. Pulls data for mode- and purpose-specific decay, calculates modal cdf, and creates probability ratio of modal cdf over tnc cdf.

Parameters

  • net_config (String) –

  • purpose (String) –

  • tnc_ratio_skim (Skim) –

  • tnc_cost_skim (Skim) –

  • decay_refs (dict) – A dictionary whose keys corespond to mode names in the emma analysis and whose values are strings identifying the name of the hdf file containing OD decay factor estimates for that mode.

  • mode_dict (dict) – A dictionary whose keys corespond to mode names in the emma analysis and whose values are strings identifying the general mode referred to in the decay_specs input file.

  • mode_impedances (dict) – A dictionary whose keys correspond to mode names in the emma analysis and whose values are tuples of strings. Each tuple specifies details for obtaining mode-specific costs from a skim file, providing the hdf node path, axis, label, and units of analysis.

  • use_units (String, default="Dollars") – If “Dollars”, the TNC decay in dollars is always referenced; if “Minutes”, the TNC decay in minutes is always referenced; if “align”, the TNC decay referened varies based on the units used for each mode’s generalized costs.

  • all_purposes ([String,..], default=["HBW", "HBO", "HBSch", "NHB"]) –

  • logger (Logger) –

Raises

ValueError – If use_units is not recognized - use “Dollars”, “Minutes”, or “Align”

Returns

Return type

None - the tnc_ratio_skim is modified in place.

wsa.TNC.applyTNCProbRatio(trip_table, tnc_ratio_skim, alpha, hdf_store=None, node_path=None, name=None, overwrite=False, logger=None)

Estimate which trips in a trip table would switch from the estimated mode to TNC, based on the TNC probability ratio (TNC utility relative to the estimated mode). Trips between OD pairs with TNC probability ratios above a set target (alpha) are assumed to switch to TNC.

Parameters

  • trip_table (emma.od.Skim) – A skim with trips by mode distributed from origin to destination zones.

  • tnc_ratio_skim (emma.od.Skim) – A skim with TNC probability ratios

  • alpha (Numeric or [Numeric, ..], default=2.0) – OD pairs with TNC probability ratios above this value are assumed to swith to TNC. A single alpha may be provided or a list of alphas corresponding to the number of modes in the Mode axis of trip_table to allows thresholds to vary by mode.

  • hdf_store (String, default=None) –

  • node_path (String, default=None) –

  • name (String, default=None) –

  • overwrite (Boolean, default=False) –

  • logger (Logger, default=None) –

Returns

tnc_table

Return type

Skim

See also

estimateTNCProb()