polaris.analyze.result_kpis.ResultKPIs

Contents

polaris.analyze.result_kpis.ResultKPIs#

class polaris.analyze.result_kpis.ResultKPIs(inputs: PolarisInputs, cache_dir: Path, population_scale_factor: float, include_kpis: Tuple[KPITag, ...], exclude_kpis: Tuple[KPITag, ...] = (KPITag.HIGH_MEMORY, KPITag.BROKEN))#

Bases: object

This class provides an easy way to extract relevant metrics for a single simulation run of POLARIS. The easiest way to generate an instance is via the factory method from_iteration which takes the path to the outputs of a simulation run (or a ConvergenceIteration())

from polaris.analyze.result_kpi import ResultKPIs

kpis = ResultKPIs.from_iteration(ref_project_dir / f"{city}_iteration_2")

Metric comparison plots can then be generated in a notebook using:

results = KpiComparator()
results.add_run(kpis, 'an-arbitrary-label')
results.plot_mode_share()
results.plot_vmt()
results.plot_vmt_by_link_type()

Any number of runs can be added using add_run up to the limit of readability on the generated plots.

__init__(inputs: PolarisInputs, cache_dir: Path, population_scale_factor: float, include_kpis: Tuple[KPITag, ...], exclude_kpis: Tuple[KPITag, ...] = (KPITag.HIGH_MEMORY, KPITag.BROKEN))#

Methods

__init__(inputs, cache_dir, ...[, exclude_kpis])

available_metrics()

Return a dictionary of available metrics that can be computed

cache_all_available_metrics([verbose, ...])

Cache available metrics into a KPI cache directory

cached_metrics()

Obtain a set of cached metrics for the KPI object

close()

Close access to the KPI cache database

from_args(files, iteration_dir[, ...])

Create a KPI object using a detailed set of arguments.

from_dir(iteration_dir, **kwargs)

Create a KPI object from a given directory.

from_iteration(iteration, **kwargs)

Create a KPI object from a ConvergenceIteration object.

get_cached_kpi_value(kpi_name[, skip_cache, ...])

Get the cached value of a metric

get_kpi_value(kpi_name)

Compute a metric that is requested, if defined

has_cached_kpi(kpi_name)

Check if KPI is cached

metric_activity_distances()

Metric provides activity distances and travel times by activity type

metric_activity_duration_distribution()

Metric provides the activity duration distribution for all activity purposes in the simulation

metric_activity_rate_distribution()

Metric provides the activity rate distribution of all activity purposes in the simulation

metric_activity_start_distribution()

Metric provides the activity start distribution of all activity purposes in the simulation

metric_activity_start_time_distributions()

Metric provides the activity start time distribution of vehicle trips in simulation

metric_average_vehicle_ownership()

Metric retrieves the average household vehicle ownership from the synthetic population in the output

metric_avo_by_tnc_operator()

Metric provides the average vehicle occupancy (AVO) achieved by each TNC oeprator when serving the demand in simulation

metric_calibration_act_gen()

Metric provides calibration comparison between simulated activities and target activities by person type and activity type

metric_calibration_act_gen_planned()

Metric provides calibration comparison between planned number of activities and target activities by person type and activity type - primarily used for debugging

metric_calibration_boardings()

Metric provides the calibration comparison of boarding counts by transit agency and transit mode

metric_calibration_destination()

Metric provides the calibration comparison of trip distances by activity type in simulation and that found in data, and also shows the validation travel times achieved in simulation compared to that found in data

metric_calibration_mode_share()

Metric provides calibration comparison of executed mode shares by trip purpose in simulation and target for the region

metric_calibration_mode_share_planned()

Metric provides calibration comparison of planned mode shares by trip purpose in simulation and target for the region

metric_calibration_timing()

Metric provides calibration comparison of trip start times by activity purposein simulation and target for the region

metric_calibration_timing_planned()

Metric provides calibration comparison of planned trip start times by activity purpose in simulation and target for the region - primarily used for debugging

metric_count_validation()

Metric provides the data comparing simulation link counts to those observed in data

metric_county_to_county_demand()

Metric provides a matrix of county to county demand aggregated using the County table in Supply

metric_distance_by_act_type()

Metric provides average trip distance by activity type

metric_escooter_utilization_at_garage()

Metric provides the e-scooter utilization when they are available at garages to use after parking a vehicle

metric_ev_charging()

Metric provides an aggregate summary of electric vehicle (EV) charging such as energy, waiting time, charging time, cost of charging, and number of charging events by EV type, charging station type, and whether residential charging was available

metric_ev_consumption()

Metric provides electric vehicle (EV) consumption while in operation such as distance, energy used, and average Wh per mile by trip mode

metric_executed_activity_mode_share_by_income()

Metric provides the executed mode share by income quintiles

metric_executed_modes()

Metric provides summary of executed modes AFTER dynamic traffic assignment

metric_file_sizes()

Metric provides the size of generated SQLite and H5 files

metric_flow_density_fd()

Metric provides the fundamental diagram by link types in the simulation

metric_freight_distance_distribution()

Metric provides freight distance distribution by freight mode, trip purpose, and trip type

metric_freight_mode_share()

Metric provides the aggregate freight mode share by shipment mode

metric_freight_mode_trade_type(**kwargs)

Metric provides the freight movements by trade type

metric_freight_shipping_cost()

Metric provides the total shipment costs by shipment mode

metric_freight_trip()

Metric provides freight trip summary

metric_gaps()

Metric provides the routing gaps from the run

metric_garage_access_w_escooters()

Metric provides e-scooter utilization, demand, and access time observed at garages

metric_mode_shares()

Metric provides the aggregate mode shares by trip purposes of HBW, HBO, NHB, and total

metric_network_gaps_by_hour()

Metric provides the network gaps from routing aggregated by time of day (in hours)

metric_network_gaps_by_link_type()

Metric provides the network gaps from routing aggregated by link type

metric_num_hh()

Metric provides number of households simulated in iteration

metric_num_hh_by_hh_size()

Metric provides number of households by household size

metric_num_persons_by_age_band_10()

Metric provides persons by age 10-year age bands

metric_num_persons_by_age_band_5()

Metric provides persons by age 5-year age bands

metric_parking_delay_stats()

Metric provides the aggregate delay statistics observed around parking infrastructure

metric_parking_share()

Metric provides the share of parking simulated between garage and on-street parking locations

metric_parking_stats()

Metric provides aggregate parking statistics such as revenue, demand, and number of e-scooter trips made by parking type and time of day

metric_parking_utilization()

Metric provides the temporal utilization of parking for various parking types separated by area types

metric_planned_activity_start_time_distributions()

"Metric provides the planned activity start time distribution for all modes

metric_planned_modes()

Metric provides summary of planned modes BEFORE dynamic traffic assignment

metric_planned_rmse_vs_observed()

Metric provides the root mean squared error for calibration procedures between planned and executed values of activity counts, mode shares, and trip start time choice

metric_polaris_exe()

Metric provides the GIT branch, SHA, build date, and URL of the POLARIS executable used to generate the outputs

metric_population()

Metric provides population summary simulated

metric_rmse_vs_observed()

Metric provides the root mean squared errors for calibration procedures such as activity, mode, boardings, trip distance, and trip start time

metric_road_pricing()

Metric provides the tolls collected from various vehicle sources (such as personally-owned, TNC, freight)

metric_skim_stats()

Metric provides the skim statistics for highway and transit skims generated in the iteration such as min, max, and average travel time, cost, etc.

metric_sov_parking_access_time()

Metric provides the parking access time simulated for personally-owned auto-based trips

metric_spatial_trips()

Metric provides trips by origin and destination across various aggregation for spatial mapping

metric_summary()

Metric that captures the summary of the iteration such as number of vehicles in network, run time, memory usage.

metric_tnc_request_stats()

Metric provides a summary of all TNC requests made during simulation such as time to assign, pickup time, dropoff time, travel time, travel distance group by TNC operators, service modes such as TAXI and First-Mile-Last-Mile (FMLM), and assignment status

metric_tnc_stats()

Metric provides the aggregate TNC operator level stats such as trips served, revenue, charging trips by operator

metric_tnc_trip_stats()

Metric provides a summary of all TNC vehicle trips made during simulation such as vehicle miles traveled (VMT), vehicle hours traveled (VHT) and grouped by TNC operator, various legs of operation (pickup, dropoff, charging), and whether vehicle was occupied or unoccupied

metric_traffic_cumulative_gap()

BROKEN: Metric provides the cumulative gap

metric_transit_boardings()

Metric provides the boardings and alightings by each transit agency and GTFS mode (such as bus, rail, metro, etc.)

metric_transit_experience()

Metric provides the aggregate transit experience as processed from multimodal paths in the simulation to provide travel time, transfers, walk time, bike time, cost, etc.

metric_trip_costs()

"Metric provides the cost experienced when making trips in the simulation such as monetary (operating), toll, and time costs by mode and trip type

metric_trip_length_distribution()

Metric provides an aggregate distribution of trip distances by mode and trip type

metric_tts()

Metric provides total travel time for all trips in simulation

metric_validation_speed()

Metric provides the validation of speeds simulated by link type and time period while comparing to data provided

metric_vehicle_technology(**kwargs)

Metric provides the summary of vehicle technology owned by various POLARIS agents (such as households, freight operators, TNC, and transit)

metric_vmt_vht()

Metric provides the aggregate vehicle miles traveled (VMT), vehicle hours traveled (VHT), average speed, and count by all modes in simulation

metric_vmt_vht_by_link()

Metric provides the vehicle miles traveled (VMT), vehicle hours traveled (VHT), and average speed in AM, PM, and Off-Peak periods by link type

network_gaps_by_x(x)

Utility function used by metrics to aggregate network gaps by x

one_value(conn, query[, default])

Provide one value from a SQL query evaluated on a connection or return a default

Attributes

result_time_step

result_time_step = 3600#
__init__(inputs: PolarisInputs, cache_dir: Path, population_scale_factor: float, include_kpis: Tuple[KPITag, ...], exclude_kpis: Tuple[KPITag, ...] = (KPITag.HIGH_MEMORY, KPITag.BROKEN))#
classmethod from_iteration(iteration: ConvergenceIteration, **kwargs)#

Create a KPI object from a ConvergenceIteration object.

Parameters:

iteration (ConvergenceIteration) – Iteration object for which a KPI object is created

classmethod from_dir(iteration_dir: Path, **kwargs)#

Create a KPI object from a given directory.

Parameters:

iteration_dir (Path) – Iteration directory for which a KPI object is created

classmethod from_args(files: PolarisInputs, iteration_dir: Path, cache_name: str = 'kpi.cache', clear_cache=False, exit_if_no_cache=False, population_scale_factor=None, include_kpis: Tuple[KPITag, ...] = (KPITag.SYSTEM, KPITag.POPULATION, KPITag.ACTIVITIES, KPITag.TRIPS, KPITag.TNC, KPITag.TRAFFIC, KPITag.TRANSIT, KPITag.VEHICLES, KPITag.CALIBRATION, KPITag.VALIDATION, KPITag.CONVERGENCE, KPITag.GLOBAL, KPITag.PARKING, KPITag.FREIGHT), exclude_kpis: Tuple[KPITag, ...] = (KPITag.HIGH_MEMORY, KPITag.BROKEN))#

Create a KPI object using a detailed set of arguments.

cache_all_available_metrics(verbose=False, metrics_to_cache=None, skip_cache=False)#

Cache available metrics into a KPI cache directory

Parameters:

  • verbose (bool) – Optional, Enable verbose logging

  • metrics_to_cache – Optional, A list of metrics to cache if not all available metrics

  • skip_cache (bool) – Optional, Skip using the cache directory and generate metrics

classmethod available_metrics()#

Return a dictionary of available metrics that can be computed

close()#

Close access to the KPI cache database

get_kpi_value(kpi_name)#

Compute a metric that is requested, if defined

Parameters:

kpi_name – Name of the metric to be retrieved

get_cached_kpi_value(kpi_name, skip_cache=False, force_cache=False)#

Get the cached value of a metric

Parameters:

  • kpi_name – Name of the metric to be retrieved

  • skip_cache (bool) – Optional, skip cache and compute the metric before retrieval

  • force_cache (bool) – Optional, force only the use of a stored value and skip if it does not exist

has_cached_kpi(kpi_name)#

Check if KPI is cached

Parameters:

kpi_name – String name of metric to check if cached

cached_metrics()#

Obtain a set of cached metrics for the KPI object

metric_summary()#

Metric that captures the summary of the iteration such as number of vehicles in network, run time, memory usage.

metric_file_sizes()#

Metric provides the size of generated SQLite and H5 files

metric_polaris_exe()#

Metric provides the GIT branch, SHA, build date, and URL of the POLARIS executable used to generate the outputs

metric_gaps()#

Metric provides the routing gaps from the run

static one_value(conn, query, default=0)#

Provide one value from a SQL query evaluated on a connection or return a default

Parameters:

  • conn – SQLite connection to a database

  • query – String SQL query to be evaluated

  • default (int) – Optional, default value returned if query evaluates to None

metric_population()#

Metric provides population summary simulated

metric_num_persons_by_age_band_5()#

Metric provides persons by age 5-year age bands

metric_num_persons_by_age_band_10()#

Metric provides persons by age 10-year age bands

metric_num_hh()#

Metric provides number of households simulated in iteration

metric_num_hh_by_hh_size()#

Metric provides number of households by household size

metric_tts()#

Metric provides total travel time for all trips in simulation

metric_distance_by_act_type()#

Metric provides average trip distance by activity type

metric_planned_modes()#

Metric provides summary of planned modes BEFORE dynamic traffic assignment

metric_executed_modes()#

Metric provides summary of executed modes AFTER dynamic traffic assignment

metric_mode_shares()#

Metric provides the aggregate mode shares by trip purposes of HBW, HBO, NHB, and total

metric_executed_activity_mode_share_by_income()#

Metric provides the executed mode share by income quintiles

metric_activity_start_distribution()#

Metric provides the activity start distribution of all activity purposes in the simulation

metric_activity_rate_distribution()#

Metric provides the activity rate distribution of all activity purposes in the simulation

metric_activity_duration_distribution()#

Metric provides the activity duration distribution for all activity purposes in the simulation

metric_vmt_vht()#

Metric provides the aggregate vehicle miles traveled (VMT), vehicle hours traveled (VHT), average speed, and count by all modes in simulation

metric_ev_charging()#

Metric provides an aggregate summary of electric vehicle (EV) charging such as energy, waiting time, charging time, cost of charging, and number of charging events by EV type, charging station type, and whether residential charging was available

metric_ev_consumption()#

Metric provides electric vehicle (EV) consumption while in operation such as distance, energy used, and average Wh per mile by trip mode

Metric provides the vehicle miles traveled (VMT), vehicle hours traveled (VHT), and average speed in AM, PM, and Off-Peak periods by link type

metric_flow_density_fd()#

Metric provides the fundamental diagram by link types in the simulation

metric_activity_distances()#

Metric provides activity distances and travel times by activity type

metric_vehicle_technology(**kwargs)#

Metric provides the summary of vehicle technology owned by various POLARIS agents (such as households, freight operators, TNC, and transit)

metric_tnc_request_stats()#

Metric provides a summary of all TNC requests made during simulation such as time to assign, pickup time, dropoff time, travel time, travel distance group by TNC operators, service modes such as TAXI and First-Mile-Last-Mile (FMLM), and assignment status

metric_tnc_trip_stats()#

Metric provides a summary of all TNC vehicle trips made during simulation such as vehicle miles traveled (VMT), vehicle hours traveled (VHT) and grouped by TNC operator, various legs of operation (pickup, dropoff, charging), and whether vehicle was occupied or unoccupied

metric_tnc_stats()#

Metric provides the aggregate TNC operator level stats such as trips served, revenue, charging trips by operator

metric_avo_by_tnc_operator()#

Metric provides the average vehicle occupancy (AVO) achieved by each TNC oeprator when serving the demand in simulation

metric_road_pricing()#

Metric provides the tolls collected from various vehicle sources (such as personally-owned, TNC, freight)

metric_transit_boardings()#

Metric provides the boardings and alightings by each transit agency and GTFS mode (such as bus, rail, metro, etc.)

metric_transit_experience()#

Metric provides the aggregate transit experience as processed from multimodal paths in the simulation to provide travel time, transfers, walk time, bike time, cost, etc.

network_gaps_by_x(x)#

Utility function used by metrics to aggregate network gaps by x

Parameters:

x – aggregation criteria such as ‘link_type’ or ‘hour’

Metric provides the network gaps from routing aggregated by link type

metric_network_gaps_by_hour()#

Metric provides the network gaps from routing aggregated by time of day (in hours)

metric_skim_stats()#

Metric provides the skim statistics for highway and transit skims generated in the iteration such as min, max, and average travel time, cost, etc.

metric_count_validation()#

Metric provides the data comparing simulation link counts to those observed in data

metric_rmse_vs_observed()#

Metric provides the root mean squared errors for calibration procedures such as activity, mode, boardings, trip distance, and trip start time

metric_planned_rmse_vs_observed()#

Metric provides the root mean squared error for calibration procedures between planned and executed values of activity counts, mode shares, and trip start time choice

metric_calibration_act_gen()#

Metric provides calibration comparison between simulated activities and target activities by person type and activity type

metric_calibration_act_gen_planned()#

Metric provides calibration comparison between planned number of activities and target activities by person type and activity type - primarily used for debugging

metric_calibration_mode_share()#

Metric provides calibration comparison of executed mode shares by trip purpose in simulation and target for the region

metric_calibration_mode_share_planned()#

Metric provides calibration comparison of planned mode shares by trip purpose in simulation and target for the region

metric_calibration_timing()#

Metric provides calibration comparison of trip start times by activity purposein simulation and target for the region

metric_calibration_timing_planned()#

Metric provides calibration comparison of planned trip start times by activity purpose in simulation and target for the region - primarily used for debugging

metric_calibration_destination()#

Metric provides the calibration comparison of trip distances by activity type in simulation and that found in data, and also shows the validation travel times achieved in simulation compared to that found in data

metric_calibration_boardings()#

Metric provides the calibration comparison of boarding counts by transit agency and transit mode

metric_validation_speed()#

Metric provides the validation of speeds simulated by link type and time period while comparing to data provided

metric_trip_length_distribution()#

Metric provides an aggregate distribution of trip distances by mode and trip type

metric_trip_costs()#

“Metric provides the cost experienced when making trips in the simulation such as monetary (operating), toll, and time costs by mode and trip type

metric_activity_start_time_distributions()#

Metric provides the activity start time distribution of vehicle trips in simulation

metric_planned_activity_start_time_distributions()#

“Metric provides the planned activity start time distribution for all modes

metric_county_to_county_demand()#

Metric provides a matrix of county to county demand aggregated using the County table in Supply

metric_average_vehicle_ownership()#

Metric retrieves the average household vehicle ownership from the synthetic population in the output

metric_traffic_cumulative_gap()#

BROKEN: Metric provides the cumulative gap

metric_spatial_trips()#

Metric provides trips by origin and destination across various aggregation for spatial mapping

metric_sov_parking_access_time()#

Metric provides the parking access time simulated for personally-owned auto-based trips

metric_parking_share()#

Metric provides the share of parking simulated between garage and on-street parking locations

metric_escooter_utilization_at_garage()#

Metric provides the e-scooter utilization when they are available at garages to use after parking a vehicle

metric_parking_utilization()#

Metric provides the temporal utilization of parking for various parking types separated by area types

metric_garage_access_w_escooters()#

Metric provides e-scooter utilization, demand, and access time observed at garages

metric_parking_stats()#

Metric provides aggregate parking statistics such as revenue, demand, and number of e-scooter trips made by parking type and time of day

metric_parking_delay_stats()#

Metric provides the aggregate delay statistics observed around parking infrastructure

metric_freight_mode_share()#

Metric provides the aggregate freight mode share by shipment mode

metric_freight_shipping_cost()#

Metric provides the total shipment costs by shipment mode

metric_freight_mode_trade_type(**kwargs)#

Metric provides the freight movements by trade type

metric_freight_trip()#

Metric provides freight trip summary

metric_freight_distance_distribution()#

Metric provides freight distance distribution by freight mode, trip purpose, and trip type

Contents