uxsim.analyzer

Analyzer for a UXsim simulation result. This module is automatically loaded when you import the uxsim module.

Functions

load_font_data([font_path])

Classes

Analyzer(W[, font_pillow, font_matplotlib])

Class for analyzing and visualizing a simulation result.

class uxsim.analyzer.Analyzer(W, font_pillow=None, font_matplotlib=None)

Class for analyzing and visualizing a simulation result.

Create result analysis object.

Parameters:

• W (object) – The world to which this belongs.

• font_pillow (str, optional) – The path to the font file for Pillow. If not provided, the default font for English and Japanese is used.

• font_matplotlib (str, optional) – The font name for Matplotlib. If not provided, the default font for English and Japanese is used.

area_to_pandas(areas, area_names=None, border_include=True)

Compute traffic stats in area and return as pandas.DataFrame.

Parameters:

• areas (list) – The list of areas. Each area is defined as a list of nodes. The items of area can be Node objects or names of Nodes.

• area_names (list, optional) – The list of names of areas.

• border_include (bool, optional) – If set to True, the links on the border of the area are included in the analysis. Default is True.

Return type:

pd.DataFrame

areas2areas_to_pandas(areas, area_names=None)

Compute the area-wise OD-specific stats and return a pandas DataFrame. It analyzes travel stats between areas (set of nodes).

Parameters:

• areas (list) – The list of areas. Each area is defined as a list of nodes. The items of area can be Node objects or names of Nodes.

• area_names (list, optional) – The list of names of areas.

Return type:

pd.DataFrame

basic_analysis()

Analyze basic stats.

basic_to_pandas()

Comutes the basic stats and return as a pandas DataFrame.

Return type:

pd.DataFrame

compute_accurate_traj()

Generate more complete vehicle trajectories for each link by extrapolating recorded trajectories. It is assumed that vehicles are in free-flow travel at the end of the link.

compute_edie_state()

Compute Edie’s traffic state for each link.

compute_mfd(links=None)

Compute network average flow and density for MFD.

cumulative_curves(links=None, figsize=(6, 4))

Plots the cumulative curves and travel times for the provided links.

Parameters:

• links (list or object, optional) – A list of links or a single link for which the cumulative curves and travel times are to be plotted. If not provided, the cumulative curves and travel times for all the links in the network will be plotted.

• figsize (tuple of int, optional) – The size of the figure to be plotted. Default is (6, 4).

Notes

This method plots the cumulative curves for vehicle arrivals and departures, as well as the instantaneous and actual travel times. The plots are saved to the directory out<W.name> with the filename format cumulative_curves_<link.name>.png.

gps_like_log_to_pandas()

Generate GPS-like log (x and y in the coordinate system used for Node) of vehicles and return as a pandas DataFrame.

Return type:

pd.DataFrame

link_analysis_coarse()

Analyze link-level coarse stats: traffic volume, remaining vehicles, free-flow travel time, average travel time, its std.

link_cumulative_to_pandas()

Compute the cumulative counts etc. in links and return as a pandas DataFrame.

Return type:

pd.DataFrame

link_to_pandas()

Converts the link-level analysis results to a pandas DataFrame.

Return type:

pd.DataFrame

link_traffic_state_to_pandas()

Compute the traffic states in links and return as a pandas DataFrame.

Return type:

pd.DataFrame

log_vehicles_to_pandas()

same to vehicles_to_pandas, just for backward compatibility

macroscopic_fundamental_diagram(kappa=0.2, qmax=1, figtitle='', links=None, fname='', figsize=(4, 4))

Plots the Macroscopic Fundamental Diagram (MFD) for the provided links.

Parameters:

• kappa (float, optional) – The maximum network average density for the x-axis of the MFD plot. Default is 0.2.

• qmax (float, optional) – The maximum network average flow for the y-axis of the MFD plot. Default is 1.

• links (list or object, optional) – A list of links or a single link for which the MFD is to be plotted. If not provided, the MFD for all the links in the network will be plotted.

• fname (str) – File name for saving (postfix). Default is “”.

• figsize (tuple of int, optional) – The size of the figure to be plotted. Default is (4, 4).

Notes

This method plots the Macroscopic Fundamental Diagram (MFD) for the provided links. The MFD provides a relationship between the network average density and the network average flow. The plot is saved to the directory out<W.name> with the filename mfd<fname>.png.

mfd_to_pandas(links=None)

Compute the MFD-like stats and return as a pandas DataFrame.

Return type:

pd.DataFrame

network(t=None, detailed=1, minwidth=0.5, maxwidth=12, left_handed=1, tmp_anim=0, figsize=(6, 6), network_font_size=4, node_size=2)

Visualizes the entire transportation network and its current traffic conditions.

Parameters:

• t (float, optional) – The current time for which the traffic conditions are visualized.

• detailed (int, optional) – Determines the level of detail in the visualization. If set to 1, the link internals (cell) are displayed in detail. If set to 0, the visualization is simplified to link-level. Default is 1.

• minwidth (float, optional) – The minimum width of the link visualization. Default is 0.5.

• maxwidth (float, optional) – The maximum width of the link per lane visualization. Default is 12.

• left_handed (int, optional) – If set to 1, the left-handed traffic system (e.g., Japan, UK) is used. If set to 0, the right-handed one is used. Default is 1.

• tmp_anim (int, optional) – If set to 1, the visualization will be saved as a temporary animation frame. Default is 0.

• figsize (tuple of int, optional) – The size of the figure to be plotted. Default is (6, 6).

• network_font_size (int, optional) – The font size for the network labels. Default is 4.

• node_size (int, optional) – The size of the nodes in the visualization. Default is 2.

Notes

This method visualizes the entire transportation network and its current traffic conditions. The visualization provides information on vehicle density, velocity, link names, node locations, and more. The plots are saved to the directory out<W.name> with filenames depending on the detailed and t parameters.

network_anim(animation_speed_inverse=10, detailed=0, minwidth=0.5, maxwidth=12, left_handed=1, figsize=(6, 6), node_size=2, network_font_size=20, timestep_skip=24, file_name=None)

Generates an animation of the entire transportation network and its traffic states over time.

Parameters:

• animation_speed_inverse (int, optional) – The inverse of the animation speed. A higher value will result in a slower animation. Default is 10.

• detailed (int, optional) – Determines the level of detail in the animation. If set to 1, the link internals (cell) are displayed in detail. Under some conditions, the detailed mode will produce inappropriate visualization. If set to 0, the visualization is simplified to link-level. Default is 0.

• minwidth (float, optional) – The minimum width of the link visualization in the animation. Default is 0.5.

• maxwidth (float, optional) – The maximum width of the link visualization in the animation. Default is 12.

• left_handed (int, optional) – If set to 1, the left-handed traffic system (e.g., Japan, UK) is used. If set to 0, the right-handed one is used. Default is 1.

• figsize (tuple of int, optional) – The size of the figures in the animation. Default is (6, 6).

• node_size (int, optional) – The size of the nodes in the animation. Default is 2.

• network_font_size (int, optional) – The font size for the network labels in the animation. Default is 20.

• timestep_skip (int, optional) – How many timesteps are skipped per frame. Large value means coarse and lightweight animation. Default is 8.

• file_name (str, optional) – The name of the file to which the animation is saved. It overrides the defauld name. Default is None.

Notes

This method generates an animation visualizing the entire transportation network and its traffic conditions over time. The animation provides information on vehicle density, velocity, link names, node locations, and more. The generated animation is saved to the directory out<W.name> with a filename based on the detailed parameter.

Temporary images used to create the animation are removed after the animation is generated.

network_fancy(animation_speed_inverse=10, figsize=6, sample_ratio=0.3, interval=5, network_font_size=0, trace_length=3, speed_coef=2, file_name=None, antialiasing=True)

Generates a visually appealing animation of vehicles’ trajectories across the entire transportation network over time.

Parameters:

• animation_speed_inverse (int, optional) – The inverse of the animation speed. A higher value will result in a slower animation. Default is 10.

• figsize (int or tuple of int, optional) – The size of the figures in the animation. Default is 6.

• sample_ratio (float, optional) – The fraction of vehicles to be visualized. Default is 0.3.

• interval (int, optional) – The interval at which vehicle positions are sampled. Default is 5.

• network_font_size (int, optional) – The font size for the network labels in the animation. Default is 0.

• trace_length (int, optional) – The length of the vehicles’ trajectory trails in the animation. Default is 3.

• speed_coef (int, optional) – A coefficient that adjusts the animation speed. Default is 2.

• file_name (str, optional) – The name of the file to which the animation is saved. It overrides the defauld name. Default is None.

• antialiasing (bool, optional) – If set to True, antialiasing is applied to the animation. Default is True.

Notes

This method generates a visually appealing animation that visualizes vehicles’ trajectories across the transportation network over time. The animation provides information on vehicle positions, speeds, link names, node locations, and more, with Bezier curves used for smooth transitions. The generated animation is saved to the directory out<W.name> with a filename anim_network_fancy.gif.

Temporary images used to create the animation are removed after the animation is generated.

network_pillow(t=None, detailed=1, minwidth=0.5, maxwidth=12, left_handed=1, tmp_anim=0, figsize=6, network_font_size=20, node_size=2, image_return=0)

Visualizes the entire transportation network and its current traffic conditions. Faster implementation using Pillow.

Parameters:

• t (float, optional) – The current time for which the traffic conditions are visualized.

• detailed (int, optional) – Determines the level of detail in the visualization. If set to 1, the link internals (cell) are displayed in detail. If set to 0, the visualization is simplified to link-level. Default is 1.

• minwidth (float, optional) – The minimum width of the link visualization. Default is 0.5.

• maxwidth (float, optional) – The maximum width of the link visualization. Default is 12.

• left_handed (int, optional) – If set to 1, the left-handed traffic system (e.g., Japan, UK) is used. If set to 0, the right-handed one is used. Default is 1.

• tmp_anim (int, optional) – If set to 1, the visualization will be saved as a temporary animation frame. Default is 0.

• figsize (tuple of int, optional) – The size of the figure to be plotted. Default is (6, 6).

• network_font_size (int, optional) – The font size for the network labels. Default is 4.

• node_size (int, optional) – The size of the nodes in the visualization. Default is 2.

Notes

This method visualizes the entire transportation network and its current traffic conditions. The visualization provides information on vehicle density, velocity, link names, node locations, and more. The plots are saved to the directory out<W.name> with filenames depending on the detailed and t parameters.

od_analysis()

Analyze OD-specific stats: number of trips, number of completed trips, free-flow travel time, average travel time, its std, total distance traveled

od_to_pandas()

Compute the OD-specific stats and return as a pandas DataFrame.

Return type:

pd.DataFrame

output_data(fname=None)

Save all results to CSV files. This is obsolute; not all functions are implemented.

plot_vehicle_log(vehname)

Plots the driving link and speed for a single vehicle.

Parameters:

vehname (str) – The name of the vehicle for which the driving link and speed are to be plotted.

Notes

This method visualizes the speed profile and the links traversed by a specific vehicle over time. The speed is plotted on the primary y-axis, and the links are plotted on the secondary y-axis. The plot is saved to the directory out<W.name> with the filename vehicle_<vehname>.png.

plot_vehicles_log(vehnamelist)

Plots the driving link and speed for a single vehicle.

Parameters:

vehname (str) – The name of the vehicle for which the driving link and speed are to be plotted.

Notes

This method visualizes the speed profile and the links traversed by a specific vehicle over time. The speed is plotted on the primary y-axis, and the links are plotted on the secondary y-axis. The plot is saved to the directory out<W.name> with the filename vehicle_<vehname>.png.

print_simple_stats(force_print=False)

Prints basic statistics of simulation result.

Parameters:

force_print (bool, optional) – print the stats regardless of the value of print_mode

show_simulation_progress()

Print simulation progress.

time_space_diagram_density(links=None, figsize=(12, 4), plot_signal=True, xlim=None, ylim=None)

Draws the time-space diagram of traffic density on specified links.

Parameters:

• links (list of link or link, optional) – The names of the links for which the time-space diagram is to be plotted. If None, the diagram is plotted for all links in the network. Default is None.

• figsize (tuple of int, optional) – The size of the figure to be plotted, default is (12,4).

• plot_signal (bool, optional) – Plot the downstream signal red light.

time_space_diagram_traj(links=None, figsize=(12, 4), plot_signal=True, xlim=None, ylim=None)

Draws the time-space diagram of vehicle trajectories for vehicles on specified links.

Parameters:

• links (list of link or link, optional) – The names of the links for which the time-space diagram is to be plotted. If None, the diagram is plotted for all links in the network. Default is None.

• figsize (tuple of int, optional) – The size of the figure to be plotted, default is (12,4).

• plot_signal (bool, optional) – Plot the downstream signal red light.

time_space_diagram_traj_links(linkslist, figsize=(12, 4), plot_signal=True, xlim=None, ylim=None)

Draws the time-space diagram of vehicle trajectories for vehicles on concective links.

Parameters:

• linkslist (list of link or list of list of link) – The names of the concective links for which the time-space diagram is to be plotted.

• figsize (tuple of int, optional) – The size of the figure to be plotted, default is (12,4).

• plot_signal (bool, optional) – Plot the signal red light.

vehicle_groups_to_pandas(groups, group_names=None)

Computes the stats of vehicle group and return as a pandas DataFrame.

Parameters:

• groups (list) – The list of vehicle groups. Each group is defined as a list of vehicle object.

• group_names (list, optional) – The list of names of vehicle groups.

Return type:

pd.DataFrame

vehicle_trip_to_pandas()

Compute the vehicle trip summary and return as a pandas DataFrame.

Returns:

A DataFrame containing the trip summary of the vehicle trip logs, with the columns:

• ’name’: the name of the vehicle (platoon).

• ’orig’: the origin node of the vehicle’s trip.

• ’dest’: the destination node of the vehicle’s trip.

• ’departure_time’: the departure time of the vehicle.

• ’final_state’: the final state of the vehicle.

• ’travel_time’: the travel time of the vehicle.

• ’average_speed’: the average speed of the vehicle.

• ’distance_traveled’: the distance traveled by the vehicle.

Return type:

pd.DataFrame

vehicles_to_pandas()

Compute the detailed vehicle travel logs and return as a pandas DataFrame.

Returns:

A DataFrame containing the travel logs of vehicles, with the columns:

• ’name’: the name of the vehicle (platoon).

• ’dn’: the platoon size.

• ’orig’: the origin node of the vehicle’s trip.

• ’dest’: the destination node of the vehicle’s trip.

• ’t’: the timestep.

• ’link’: the link the vehicle is on (or relevant status).

• ’x’: the position of the vehicle on the link.

• ’s’: the spacing of the vehicle.

• ’v’: the speed of the vehicle.

Return type:

pd.DataFrame