Add advanced customization options for agent visualization

[EwoutH]

This PR builds on #2242 by @rmhopkins4.

This allows more visualisation options for agents, by allowing specifying edgecolor, linewidth and alpha in the agent_portrayal.

Implementation

• Refactored the _get_agent_data function to handle new visualization parameters (edge colors, line widths, alpha).
• Implemented backward compatibility for old keyword arguments using a translation dictionary.
• Updated _draw_continuous_space and _draw_voronoi functions to use the new agent data format.
• Improved code reusability by centralizing agent data retrieval logic.
• Ensured consistency in visualization across different space types (grid, continuous, Voronoi).

Usage Examples

Users can now specify additional properties in their agent portrayal function. For example, display agents with red fill, black edges, and partial transparency.

agent_portrayal = {
        "shape": "^",
        "color": "red",
        "size": 20,
        "edgecolor": "black",
        "linewidth": 2,
        "alpha": 0.7
    }

Another example, dependent on the state of the Agent:

def agent_portrayal(agent):
    return {
        "c": "white" if agent.isAlive else "black",
        "s": 45,
        "marker": "*",
        "edgecolors": "purple",
        "linewidths": 0.5,
        "alpha": 0.5,
    }

Additional notes

• This change maintains backward compatibility with existing agent portrayal implementations.
• The new visualization options are available for all space types (grid, continuous, Voronoi).
• Future work could include extending these options to network visualizations and adding more advanced styling capabilities.

[quaquel]

I like the API idea a lot. No time to review in detail atm.

[EwoutH]

I have to fix a few small things, but API wise it's ready. I rebased the PR on the latest main.

[Corvince]

Huh, I somehow missed this PR. Less code, more options sounds good!

[EwoutH]

Thanks!

Only now I completely forgot what small things I still needed to fix 😅.

[quaquel]

This won't work. This method is for plotting the experimental Voronoi space.

The _get_agent_data method presupposes an old style space because it does for agents, pos in space.coord_iter():.

[quaquel]

See my remark about how this changes _draw_voronoi (which is a new style experimental space).

[quaquel]

@EwoutH, with all the refactoring, how do you want to proceed with this? I had a quick look and have some ideas on how to provide this functionality within the refactored code-base. The tricky part is that linewidth and edge color can be provided at the agent level (currently not supported) or at the level of a single ax.scatter command (currently already supported). alpha is already supported via some **kwargs magic.

[EwoutH]

alpha was by far the most important in this PR, the rest was "bijvangst". So maybe we can document how alpha works (or support it better if needed), and leave the rest be for now.

I'm not attached to this PR at all.

[quaquel]

alpha was by far the most important in this PR, the rest was "bijvangst". So maybe we can document how alpha works (or support it better if needed), and leave the rest be for NWO .

To be clear: support for alpha did not exist before #2430, which added **space_drawing_kwargs. You can now do draw_space(model.grid, my_agent_portrayal, alpha=0.5) and then all ax.scatter calls will use an alpha of 0.5. What is currently not supported is using alpha for each agent separately. According to the docs of matplotlib, this should not even work... but it does.

The ax.scatter docs say:

alpha: float, default: None

but alpha array-like of float also works. I'll put in a new PR to support this.

[EwoutH]

Interesting, notified them upstream:

• [Doc]: ax.scatter alpha also supports an array-like of floats matplotlib/matplotlib#29101

[quaquel]

superseded by #2468