datacollector: Allow collecting data from Agent (sub)classes

[EwoutH]

Enhanced Mesa's DataCollector to allow collecting data from Agent (sub)classes, providing more flexible and granular data collection capabilities.

Motive

To enable more comprehensive data collection in multi-agent simulations, allowing researchers to track attributes and behaviors specific to different agent types, including custom Agent subclasses.

Implementation

• Modified DataCollector class to accept agenttype_reporters parameter
• Added _new_agenttype_reporter method for handling agent-type-specific reporters
• Updated collect method to handle agent-type-specific data collection
• Added get_agenttype_vars_dataframe method for retrieving agent-type-specific data
• Updated Model class to support agenttype_reporters in initialize_data_collector
• Added support for collecting data from all Agent subclasses, not just predefined agent types
• Updated docstrings and module-level documentation
• Added comprehensive unit tests for the new functionality

Usage Examples

class MyModel(Model):
    def __init__(self):
        super().__init__()
        self.datacollector = DataCollector(
            agent_reporters={"life_span": "life_span"},
            # The new agenttype_reporters argument
            agenttype_reporters={
                Wolf: {"sheep_eaten": "sheep_eaten"},
                Sheep: {"wool": "wool_amount"},
                Animal: {"energy": "energy"}  # Collects from all animals
            }
        )

# Retrieve data for a specific agent type
wolf_data = model.datacollector.get_agenttype_vars_dataframe(Wolf)
# Retrieve data for all Animal subclasses, which are in this case all Wolf and Sheep
animal_data = model.datacollector.get_agenttype_vars_dataframe(Animal)

Additional Notes

• Backward compatible with existing DataCollector usage
• Supports collecting data from custom Agent subclasses and superclasses

Part of #348.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 +1.3% [+0.1%, +2.5%]	🔵 +0.2% [-0.1%, +0.5%]
BoltzmannWealth	large	🔵 -0.3% [-0.9%, +0.2%]	🔵 -1.4% [-3.6%, +1.8%]
Schelling	small	🔵 +0.1% [-0.3%, +0.4%]	🔵 -0.4% [-0.6%, -0.2%]
Schelling	large	🔵 +0.1% [-0.6%, +0.8%]	🔵 -2.1% [-3.4%, -0.8%]
WolfSheep	small	🔵 +0.9% [+0.6%, +1.1%]	🔵 +0.0% [-0.2%, +0.3%]
WolfSheep	large	🔵 -3.0% [-4.1%, -1.7%]	🟢 -6.4% [-7.6%, -5.3%]
BoidFlockers	small	🔵 +1.0% [+0.3%, +1.5%]	🔵 -0.2% [-0.9%, +0.5%]
BoidFlockers	large	🔵 +0.8% [+0.3%, +1.2%]	🔵 +0.5% [-0.3%, +1.2%]

[rht]

What about the case for e.g. in Epstein civil violence, you want to collect based on citizens that are jailed, which is not based on type?

[EwoutH]

This PR doesn't fix everything, we clearly need a new DataCollector. But it's a minimally invasive, fully backwards compatible extension to the current DataCollector that everybody knows. It's even backportable to Mesa 2.x.

In Epstein civil violence, you can log if agents are jailed or not and filter afterwards. Not ideal, but workable.

Of course I'm open for other suggestions for backwards compatible alternatives.

[rht]

The code path has been well tested with model reporter and agent reporter. Also, better than nothing. I'm fine with this PR.

[quaquel]

There are a few lines currently not covered by the tests, but otherwise, this seems fine. It solves a long-standing open issue in a backward-compatible way. It makes sense to add it while we continue work on building the foundations for a better datacollector.

[EwoutH]

Added some additional tests.

I consciously named it agenttype_reporters, to leave room for future other arguments like agentset_reporters or custom_agent_reporters.

This functionality might even be able to be implemented more elegantly using more existing code.

But I think API is solid, and there are distinct use cases for it. One huge advantage of collecting by type, it that you can ensure all agents have those attributes and methods you’re collecting. It also elegantly using the pre-existing model.agent_by_types duct, which is a very fast way to get these agent groups (since select can be an expensive operation).

[EwoutH]

In 86b184d and 3dbb5b6 I updated this feature to allow collecting from any Agent (sub)class, so also a class like Animals, which is not present in model.agents_by_type but is a valid Agent (sub)class. It even allows inputting Agent itself, but that's ofcourse redundant with the agent_reporters.

        self.datacollector = DataCollector(
            agenttype_reporters={
                Sheep: {"wool": "wool_amount"},
                Animal: {"energy": "energy"}  # Collects from all animals
            }
        )

I would love some final reviews on this (also from @Corvince).

[quaquel]

do we need this part about assumptions. All this is is in Model. Why not say: "the DataCollector is designed to work with Model or any subclass thereof?

[quaquel]

2 minor remaining comments but otherwise seems good to go.

[EwoutH]

Thanks for reviewing!

I'm merging to keep moving this forward, but @Corvince still I would really love to hear your thoughts on the API.