Agent List

class Melodie.AgentList(agent_class: Type[AgentGeneric], model: Model)

Bases: BaseAgentContainer, Generic[AgentGeneric]

setup_agents(agents_num: int, params_df: DataFrame | TableBase = None)

Setup agents with a specific number, and initialize their properties from a dataframe if it is provided.

Parameters:

  • agents_num – The number of agents to create.

  • params_df – A pandas DataFrame containing agent properties. Its structure should be consistent with the one used in the set_properties method.

Returns:

None

setup()

The setup method.

If you would like to define custom AgentList, please be sure to inherit this method.

init_agents() → List[AgentGeneric]

Initialize all agents in the container, and call the setup() method :return:

random_sample(sample_num: int) → List[AgentGeneric]

Randomly sample sample_num agents from the container :param sample_num: :return:

filter(condition: Callable[[AgentGeneric], bool])

Filter agents satisfying the condition Callable[[Agent], bool]

Returns:

a list of filtered agents

add(agent: AgentGeneric = None, params: Dict = None) → AgentGeneric

Add an agent :param agent: :param params: :return:

to_list(column_names: List[str]) → List[Dict]

Dump all agent and their properties into a list of dict.

Parameters:

column_names – The property names to be dumped.

Returns:

to_dataframe(column_names: List[str] = None) → DataFrame | TableBase

Store all agent values to dataframe. This method is always called by the data collector.

Parameters:

column_names – property names to store

Returns:

set_properties(props_df: DataFrame | TableBase)

Extract properties from a dataframe, and Each row in the dataframe represents the property of an agent.

For example, if there are 100 agents with id from 0 to 99, and each agent contains properties a: int and b: float, the props_df could be like this:

import random
import pandas as pd

df = pd.DataFrame([{"id": i, "a": 2, "b": random.random()} for i in range(100)])
print(df.head())

The output is(df has 100 rows):

    id  a         b
0    0  2  0.207738
1    1  2  0.236711
2    2  2  0.869793
3    3  2  0.797763
4    4  2  0.900024

For each scenario, same parameter values inside props_df will be assigned to each agents. As an instance, properties b value at agent 0 in both scenario 0 and 1 are both 0.207738.

To set different initial parameters for different scenarios, please add a new column id_scenario. An example of dataframe structure is shown below, and in this case, b of agent 0 in scenario 0 is 0.207738, while in scenario 1 it was 0.778997

    id_scenario  id  a         b
0             0   0  2  0.207738
1             0   1  2  0.236711
2             0   2  2  0.869793
......
100           1   0  2  0.778997
101           1   1  2  0.450674
Parameters:

props_df – pd.DataFrame containing agent initial properties.

Returns:

get_agent(agent_id)

Get an agent from the agent list. If agent unexist, return None.

Parameters:

agent_id – The id of the agent object.

Returns:

An agent object, or None.

method_foreach(method_name, args)

For each agent, execute theirs method method_name with arguments args

Parameters:

  • method_name – Name of method, a str;

  • args – Arguments of a method, a tuple

Returns:

None

vectorize(prop_name)

NotImplemented yet.

Generate an numpy array from this list, where the values come from the property defined by prop_name on each agent.

Parameters:

prop_name – Property name

Returns:

An 1-D Numpy array

remove(agent)

Remove an agent from the AgentList

Parameters:

agent

Returns: