Visualize PropertyLayers

[EwoutH]

This PR adds support for visualizing PropertyLayers in the Matplotlib-based space visualization component. It allows users to overlay PropertyLayer data on top of the existing grid and agent visualizations, or on its own.

It introduces a new propertylayer_portrayal parameter to customize the appearance of PropertyLayers and refactors the existing space visualization code for better modularity and flexibility.

Motive

The PropertyLayer is becoming a key feature in Mesa, so it should be visualized easily. This feature enables users to easily visualize multiple layers of data simultaneously, such as environmental factors or agent properties, alongside the agents themselves.

Implementation

• Added a new propertylayer_portrayal parameter to the make_space_matplotlib function.
• Implemented a draw_property_layers function to render PropertyLayer data using Matplotlib's imshow.
• Modified the _draw_grid function to incorporate PropertyLayer visualization before drawing agents.
• Added support for both color-based and colormap-based PropertyLayer rendering.
• Implemented alpha blending for PropertyLayer visualization to allow overlaying multiple layers.
• Added colorbar support for PropertyLayer visualization.

Usage Examples

You can visualize multiple PropertyLayers ("grass" and "temperature" in this case) along with agents in a grid space:

def agent_portrayal(agent):
    return {"color": "red", "shape": "o", "size": 20}

propertylayer_portrayal = {
    "grass": {
        "colormap": "Greens",
        "alpha": 1,
    },
    "temperature": {
        "colormap": "coolwarm",
        "alpha": 0.333,
        "vmin": 0,
        "vmax": 100
    },
}

model = ExampleModel(10, 10)
page = SolaraViz(
    model,
    [make_space_matplotlib(agent_portrayal, propertylayer_portrayal)],
)

You can also use a single color for a PropertyLayer. Here we render the "cell_layer" PropertyLayer using shades of black, with the highest value having 0% opacity and the lowest value having 100% opacity. For Game of Life that means alive cells are fully black, and dead cells transparent.

propertylayer_portrayal = {
    "cell_layer": {
        "color": "Black",
        "alpha": 1,
        "colorbar": False,
    },
}

Any matplotlib color is valid. The highest value will have that color with 0% opacity, the lowest with 100% opacity (which can again be scaled with modifying vmin and vmax).

Additional Notes

• Currently supported spaces: Grid and standalone PropertyLayers.
  • ContinuousSpace, NetworkGrid, and VoronoiGrid can be added in future PR(s).
• Future work could include adding support for additional space types and improving the efficiency of rendering for large grids.
• The PR includes updates to handle different sizes between the PropertyLayer and the grid space, issuing warnings when there's a mismatch.
• Colorbar display can be toggled using the colorbar parameter in the portrayal dictionary.
• The coordinate system has been validated to ensure consistent axis directions between PropertyLayers and the grid space.
• A demo using the Game of Life model has been implemented in a separate PR (GoL_fast: Visualize the Game of Life cells using the PropertyLayer mesa-examples#214) to showcase these new visualization capabilities.

TODO

• Scale colors over alpha (aside from colormap)
• Add switch for colorbars and fix warning
• Validate coordinate system
  • Handle different sizes (just warn)
  • Axis in same direction
• Demo GOL (GoL_fast: Visualize the Game of Life cells using the PropertyLayer mesa-examples#214)
• Add tests
• Write up PR

Closes #2138.

[EwoutH]

This is ready for a first round of review, API wise its done. Any conceptual, feature or API feedback is welcome. If no major things come up, I will finish the tests and such.

The GoL example is also available here: projectmesa/mesa-examples#214

[EwoutH]

Implemented the last features (turning color bars on and off), validated the PropertyLayer coordinate system was visualized on the same axis as the Agent one, and updated the PR description.

I have no idea what for tests to add, suggestions are welcome.

Ready for review.

[EwoutH]

Going to merge this, it breaks nothing and adds a new feature.

Post-merge review still appreciated!

[rht]

Going to merge this, it breaks nothing and adds a new feature.

This is not fine. You are breaking the convention of a review needed into a new feature that is not experimental. This is definitely not fair to other developers who have waited for a long time even for a review, e.g. @wang-boyu with the recent Mesa-Geo stuff, even though he is the lead maintainer on the repo.

[EwoutH]

It’s a valid concern. I wanted to include it in the beta, so users could start testing it and delivering feedback, and updating example models (like projectmesa/mesa-examples#214). I thought I had an approval on the API for this PR and #2341 from @quaquel.

@projectmesa/maintainers I would like your perspective on how to handle cases like this, for if they happen in the future.

[rht]

Either of:

• Why pass an entire model instead of just the layers?
• Why not use the space argument and access it from the model instead?

[rht]

Edit: s/Why not use the space/Why not remove the space/

[EwoutH]

Thanks for the review and the questions, I will try to look into them soon.

Also feel free to open a PR if you already have concrete solutions in mind.

Edit: Yeah I now remind, there are some inconsistencies between the draw functions here. When I add support for other spaces I will try to address these.