scml-vis

A simple visualiser for SCML worlds and tournaments. You can watch a demo on YouTube

Screenshots

Main Features

• Displays any world/tournament run using the SCML package
• Allows filtering using worlds, agent types, and agent instances
• Shows world statistics, agent type and instance statistics and contract statistics as functions of simulation step/time

Requirements

• scml-vis requires Python 3.8 or above.
• scml-vis can visualize worlds created by scml 0.4.2 or later (simulations created using older versions of scml can be visualized in most cases but are not officially supported).

Installation

With pip:

python3 -m pip install scml-vis

With pipx:

python3 -m pip install --user pipx
pipx install scml-vis

Usage

The visualizer can be run using any of the following commands:

scmlv
scmlvis
scml-vis

Hereafter we will use the shorter version.

• To visualize any of the recently run worlds and tournaments just run:

   scmlv show

  This will open your browser and allow you to choose a world or a tournament to display.

  • If this is the first time you visualize logs in this folder, you will be asked to compile visualization data
  • If visualization data is available (or your pressed the compile visualization data button), you can now start visualizing the logs

• To visualize the logs in a specific folder, you can directly pass the folder as in:

  scmlv show -f path-to-your-folder

• It is also possible to just compile visualization data without running the visualizer using:

  scmlv compile path-to-your-folder

• The visualizer creates a database that it uses to create all the figures you see. You can directly explore this database using:

  scmlv explore path-to-your-folder

  This will open a datasette page allowing you to explore this database This dataset will contain 8 tables describing everything that was logged in the world or tournament. Please consult datasette documentation for all the ways you can interact with this dataset.

Available visualizations

To visualize your logs, you need to follow three steps:

1. Filter the dataset using the Data Selection section of the sidebar.
2. Choose the family of figures you would like to show from the Figure Selection dropdown in the sidebar. Currently we provide Time-series, Tables and others that are always available as well as Networks that are only available when you visualize a single world or filter the tournament to focus on a single world.
3. Choose the specific graph you want to see from the family selected in the previous step.

You can watch a demo of this process here

TODO List (Good Ideas for PRs)

• Show negotiation logs (i.e. negotiation results)
• Display all contracts (i.e. in a table) based on selection criteria
• Zoom on negotiation details (i.e. exchanged offers)
• Add dynamic figures using plotly/altair
• Add networkx like graphs of contracts / negotiations / offers
• Allow starting the app without specifying a folder.
• Add new figure types that do not have time/step in the x-axis.
• Correcting the placement of weights on edges in network views.
• Adding a graph showing negotiation history in the ufun-space of negotiators (will require a change in the scml package).
• Add saving and loading of the visualizer's state (i.e. what is visible).
• Resolving the strange behavior of CI bands in plotly in some cases.