Skip to content

Analysis Tools

The analysis tools let your assistant work with the results of a simulation, much like the Analyzer in the web interface: where does traffic jam, which trips are affected, and how does a changed scenario perform compared to the original. They only read data and never change simulations or scenarios.

Examples:

  • "How did simulation 5 go? Were there collisions or teleports?"
  • "Where does it jam most in simulation 5? Name the five worst streets."
  • "Which vehicles lost the most time, and which ones never reached their destination?"
  • "Compare simulation 6 with simulation 5 and show me which streets got worse."

What you need

Analysis tools work with the simulation ID that running a simulation returns, for example "simulation 5".

One run or all runs. A simulation can have several runs.

You ask for What the assistant analyzes
A simulation All successful runs together. Values are the mean over the runs and the spread between the runs is reported as well.
A simulation with only one successful run That run.
A specific run (for example "run 101") Only that run.

A simulation that is still running is not analyzed; the assistant tells you to wait. The aggregate of several runs needs at least two successful runs.

Outputs. What can be analyzed depends on the outputs that were written when the simulation ran:

Output Needed for
Edge data (mean data) Congestion hotspots, edge results, comparison of edges
Trips (trip information) Trip statistics, individual trips, comparison of trip figures
Vehicle routes Routes of vehicles

The trip information output is optional; ask the assistant to include it when it starts a simulation. The tool analyzer__get_simulation_results shows which outputs a simulation has, and the assistant tells you when an output is missing.

Overview of a simulation

Tool What it does
analyzer__get_simulation_results Starting point: which outputs the simulation has, its runs and their key figures (vehicles, teleports, collisions, mean speed, mean time loss and more). For several runs also the mean and the spread of the key figures.

Congestion

Tool What it does
analyzer__find_congestion_hotspots Finds the edges with the worst congestion, with street name and position.
analyzer__get_edge_results Shows the measured traffic of specific edges, selected by edge ID, street name or area.

An edge is a street section between two junctions. For every edge the following measures are available:

Measure Meaning
Time loss Time lost in seconds compared to driving at the ideal speed.
Travel time Time in seconds that vehicles needed for the edge.
Density Vehicles per kilometer.
Occupancy Share of the edge that is occupied by vehicles, in percent.
Relative speed Mean speed as a share of the speed limit. 1 means free flow, a low value means slow traffic.
Traffic volume Vehicles per hour.
Entered and left Number of vehicles that entered and left the edge.

Hotspots can be sorted by any of the measures. Each result contains the street name, the position (latitude and longitude of the middle of the edge), the number of lanes and the speed limits of the edge. Edges that no vehicle entered are left out by default, so that the list shows streets with real traffic.

Trips

Tool What it does
analyzer__get_trip_statistics Shows distributions of duration, time loss, waiting time and route length, optionally per vehicle class, vehicle type or kind (vehicle, person).
analyzer__find_trips Finds individual trips, for example those with the highest time loss or vehicles that did not finish.
analyzer__get_vehicle_routes Shows the routes of given vehicles as edges and street names.

Statistics contain count, mean, median, 90th and 95th percentile and maximum. Trips that were still under way when the simulation ended are counted as uncompleted and are not part of the distributions, because their values are only partial. They are interesting on their own: they often are vehicles that got stuck. Ask for them with "trips that did not finish".

For several runs, each trip is averaged over the runs. The spread between the runs is therefore not part of the distributions; use the analysis of a single run if you need the exact values of one run.

Routes can differ between runs, so for a simulation with several runs the assistant has to pick one run for analyzer__get_vehicle_routes.

Comparing variants

Tool What it does
analyzer__compare_simulations Compares a variant with a baseline: key figures and the edges that got worse or better.

A comparison shows how key figures changed, for example mean time loss, mean duration or the number of unfinished trips, and lists the edges whose traffic got worse and those that got better, with street name and position. The comparison measure can be time loss, travel time, density, occupancy or relative speed.

Both sides use all their successful runs. If both simulations have at least two runs, each edge change comes with a value that shows whether the change is larger than the variation between runs. Values above about 2 (or below -2) point to a real change; small values mean that the difference may be random.

Edges are matched by their ID, so the two scenarios should share their road network, for example a duplicated scenario with changed speed limits. The assistant tells you if the networks differ strongly.

The network

Tool What it does
analyzer__get_network_summary Shows the size of the road network: edges, lanes, junctions, traffic lights, total length, how the length splits over speed limits, and the bounds of the area.

Good to know

  • Limits: a result contains at most 500 rows and says how many rows matched. Ask for more specific selections if the list is truncated.
  • Large results: very large result files are refused. Use the ZIP export to get all outputs in that case.
  • Units: seconds, meters, meters per second and degrees. Speeds and speed limits are given in meters per second; multiply by 3.6 for kilometers per hour.