simcronomicon.visualization package

Submodules

simcronomicon.visualization.plot_status_summary module

simcronomicon.visualization.plot_status_summary.plot_status_summary_from_hdf5(output_hdf5_path, status_type=None)

Plot the normalized status summary (density) over time from a simulation HDF5 output file.

This function reads the simulation status summary from the specified HDF5 file, normalizes each status by the total population, and plots the density of each status (or a subset of statuses) over simulation timesteps.

Parameters:

  • output_hdf5_path (str) – Path to the HDF5 file containing simulation results.

  • status_type (str or list of str or None, optional) – If None (default), plot all status types. If str, plot only the specified status type. If list of str, plot only the specified status types.

Raises:

  • ValueError – If the HDF5 file contains no status data or if the total population is zero. If an invalid status_type is provided.

  • TypeError – If status_type is not None, str, or list of str.

Returns:

Displays a matplotlib plot of the status densities over time.

Return type:

None

simcronomicon.visualization.plot_scatter module

simcronomicon.visualization.plot_scatter.plot_agents_scatter(output_hdf5_path, town_graph_path, time_interval=None)

Visualize the movement and status of agents over time on a map using simulation output using Plotly and OpenStreetMap.

Parameters:

  • output_hdf5_path (str) – Path to the HDF5 file containing simulation results.

  • town_graph_path (str) – Path to the .graphmlz file containing the town graph.

  • time_interval (tuple or list of int, optional) – (start, end) timestep range to visualize. If None, visualize all timesteps.

Returns:

Displays an Plotly map with a time slider showing agent locations and statuses over time.

Return type:

None

Notes

  • Each status is represented by a random color (A colormap parameter is a to-be-implemented)

  • Requires internet connection for OpenStreetMap tiles

simcronomicon.visualization.plot_scatter.plot_place_types_scatter(town_graph_path, town_config_path, colormap=None)

Visualizes nodes from a .graphmlz town graph file as colored points with colors representing different place types (e.g., accommodation, commercial, education), using Plotly and OpenStreetMap..

Parameters:

  • town_graph_path (str) – Path to the .graphmlz file containing the town graph with node coordinates and place_type classifications.

  • town_config_path (str) – Path to the .json file containing town metadata with ‘epsg_code’ for coordinate conversion and ‘place_types’ list defining valid place types.

  • colormap (dict, optional) – Custom color mapping {‘place_type’: ‘#HEXCOLOR’}. If None, uses defaults. Custom colors override defaults for matching place types.

Returns:

Displays an interactive Plotly scatter map with colored points, legend, and hover information showing node IDs.

Return type:

None

Raises:

  • AssertionError – If file extensions are incorrect (.graphmlz and .json required).

  • KeyError – If town_config_path doesn’t contain required ‘epsg_code’ field.

  • ValueError – If colormap doesn’t provide colors for all place types defined in town_config_path’s ‘place_types’ list.

  • FileNotFoundError – If specified file paths don’t exist.

Notes

  • Default colors provided for: accommodation, commercial, religious, education, workplace, healthcare_facility

  • Nodes with undefined place types are colored gray (#CCCCCC)

  • Requires internet connection for OpenStreetMap tiles

Module contents