Analyzing Simulation Output

Simulation outputs can be analyzed and plotted with various tools. In this article, the analysis with FalconSQL/Plotly is used as an example.

How to plot simulation output data with FalconSQL/Plotly

FalconSQL and Plotly require data stored in a database.

  1. Go to https://plotly.com/chart-studio-help/database-connectors/personal-login/. This site includes download links, installation instructions, and documentation on how to use Falcon SQL.

  2. Once your database is connected to Falcon SQL (in the Connection tab), you can submit SQL queries (in the Query tab) to extract and visualize the desired data.

  3. After the query ran successfully, the extracted attributes are available in the Chart tab. Click "Trace" to generate a new plot. You can generate multiple traces to visualize and compare different data.

  4. In the Export tab, click "Upload chart". You will be directed a Chart Studio Plotly site in your web browser, where you can create, edit, and share a dashboard that contains your diagrams.

  5. Below is an example of visualization using simulation data that was stored in a PostgreSQL database. The simulation time was 24 hours and agents were able to travel on foot and by bike. The query submitted to Falcon SQL was:

    SELECT CAST(TRUNC(EXTRACT(HOUR FROM "Citizen"."DateTime")) AS INTEGER) AS "hr:DateTime",
SUM((CASE WHEN ("Citizen"."ModalityCount" = 1) THEN "Citizen"."ModalityCount" ELSE NULL END)) AS "sum:Calc_walk",
SUM((CASE WHEN ("Citizen"."ModalityCount" = 3) THEN "Citizen"."ModalityCount" ELSE NULL END)) AS "sum:Calc_cycle"
FROM "mars"."Citizen" "Citizen"
GROUP BY 1

    Using the data that was returned from the database, the following diagram was generated: Barchart for walking and cycling The chart shows the number of walking and cycling agents per hours for the duration of the 24-hour simulation time.

How to plot simulation output data with Tableau

Tableau can take your simulation's output data via a csv file or a database connection. Tableau is a useful tool for analyzing and aggregating data as well as creating custom functions to process data as needed.

  1. Download and install Tableau.

    ​ Note: Students can use this link to obtain the free education version: https://www.tableau.com/academic/students.

  2. Open Tableau and select your data source (csv or database connection).

  3. Tableau offers online tutorials and documentation: https://help.tableau.com/current/pro/desktop/en-us/gettingstarted_overview.htm.

How to create a map of agent density per tick (heat map)

MARS offers a Python-based tool/script that can be used to generate heat maps of agents per simulation tick. Simulation output data needs to be available in a csv file. Per default, the script is in the directory Analysis (if you cannot find it, please ask a MARS representative).

  1. In a terminal, navigate to the folder where the script is located. Note: Python needs to be installed on your system and added to your system's path variable to be able to run the script from the terminal.

  2. Execute the script by entering the following parameters:

    csvtoasc.py <path_to_file_without_file_extension> <grid_cell_size> <column_name_of_longitude> <column_name_of_latitude>

    <path_to_file_without_file_extension>: can be absolute or relative. Please do not include the file extension. Example: Citizen

    <grid_cell_size>: this is a number that specifies the size of a single grid cell (in degrees) of the heat map you wish to generate. Example: 0.25

    ​ Note: for more information on degrees and geocoordinates and how they are processed in MARS, please see TODO: add link to article about geocoordinates

    <column_name_of_longitude>: the name of the column in the output csv file from which longitude data should be retrieved. This value depends on your csv file. Example: Long

    <column_name_of_latitude>: the name of the column in the output csv file from which latitude data should be retrieved. This value depends on your csv fiile. Example: Lat

  3. The script generates a folder in the working directory and stores an asc file per tick inside the folder.

  4. You can load the asc files into QGIS (e.g., via drag-and-drop) to visualize them.

  5. OpenStreetMap data (or the layer data from your model) can be layered below the heat maps to show where on the map (and at what time of the simulation) agents were positioned. Below is an example of three heatmaps showing the difference in agent density during three different simulation ticks:

    Morning noon evening
    morning noon evening