Proposal: Agent selection method

[EwoutH]

A built-in method for agent selection and filtering could help in many situations to select an appropriate subset of agents. This feature request proposes the introduction of a versatile Model method, named select_agents. This function will allow users to select agents based on a combination of attributes, agent types, and functional filters, with the flexibility of specifying the number of agents to select.

This proposal is inspired by the various variants of the n-of functions in NetLogo and @rht smart idea in #1894 (comment).

Functionality Overview:
The select_agents function is designed to be highly flexible and adaptable to various modeling scenarios. Its key features include:

1. Optional Quantity of Agents (n):

   • n (Optional): An integer specifying the desired number of agents to select. If not specified, all agents meeting the criteria will be selected.

2. Criteria-Based Sorting (sort and direction):

   • sort (Optional): A list of attribute names to sort agents. It defines the criteria for selection.
   • direction (Optional): Accompanying sort, this list specifies the sorting direction ('lowest' or 'highest') for each criterion.

3. Agent Filtering (filter):

   • filter (Optional): A lambda function or callable that applies additional conditions to filter agents. It allows for complex logical expressions to refine the selection.

4. Type-Based Filtering (agent_type):

   • agent_type (Optional): A class or list of classes specifying the type(s) of agents to be included in the selection. This ensures that only agents of certain types or subclasses are considered.
   • This feature depends on Native support for multiple agent types #1894.

5. Flexible Size Handling (up_to):

   • up_to (Optional): A boolean that, when True, allows the function to return up to n agents, preventing errors if n exceeds the available agent count. It defaults to True for convenience.

Usage Scenarios:

1. Selecting a Specific Number of Agents:

   • To select a specific number of agents randomly:

     select_agents(n=10)

2. Complex Multi-Criteria Selection:

   • Select agents based on multiple attributes, like 'wealth' and 'age':

     select_agents(n=5, sort=['wealth', 'age'], direction=['highest', 'lowest'])

3. Selection with Functional Filtering:

   • Apply a condition, such as selecting agents with 'energy' above a certain threshold:

     select_agents(filter=lambda agent: agent.energy >= 5)

4. Type-Specific Selection:

   • Choose agents only of a specific subclass, like SpecificAgentClass:

     select_agents(agent_type=SpecificAgentClass)

[EwoutH]

In the future, a very similar API could be constructed for the PropertyGrid (#1898) to select grid cells. Keeps is nice and consistent.

[EwoutH]

For some more context, aside from NetLogo's n-of this also aligns with AgentPy's AgentList.select().

[Corvince]

Love the idea. For the implementation we can do this in small steps if more manageable. I mean we don't need to implement all the functions directly

[EwoutH]

@jackiekazil @tpike3 I would like to discuss and potentially implement this before moving on the PropertyLayer (#1898), since this is a more generalized solution for a problem that I specifically solve in that PR. So if we can implement this, it would make especially the _PropertyGrid in #1898 a lot simpler.

So my specific questions are:

1. Do you agree a built-in agent selection method is useful for Mesa?
2. Do you agree it should be a model method?
3. What do you think of the current proposed API?

   select_agents(n, sort, direction, filter, agent_type, up_to)

---

One thing I'm thinking of is merging the sort and direction parameters and using a list of tuples.

So instead of:

select_agents(n=5, sort=['wealth', 'age'], direction=['highest', 'lowest'])

It would be:

select_agents(n=5, sort=[('wealth', 'highest'), ('age', 'lowest')])

What would you prefer?

[tpike3]

This would be great!

• I ask we don't use lambda for filtering :) and do a callable function.
• We will also need some way to handle agent types and a default to if there is only one agent type or randomly select some n from different agent types. But I suppose this will al be part of Native support for multiple agent types #1894

[EwoutH]

I ask we don't use lambda for filtering :) and do a callable function.

Shall we allow both?

We will also need some way to handle agent types and a default to if there is only one agent type

I see it as as long as you don't change the default (agent_type=None), it just returns all agents from all types, if there is one class or more.

[EwoutH]

Closing this as solved!

• An initial attempt was made in Add select_agents method to Model #1911
• It was implemented as part of the AgentSet in Introduce AgentSet class #1916