AgentList

class MelodieInfra.core.agent_list.BaseAgentContainer

The base class that contains agents

new_id() → int: Create a new auto-increment ID

all_agent_ids() → List[int]: Get id of all agents.

to_list(column_names: List[str] | None = None) → List[Dict]

Convert all agent properties to a list of dict.

Parameters:: column_names – property names

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

agents: A list of Agent, the actual data structure storing agents.

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

Setup agents with specific number, and initialize their property by a dataframe if a dataframe is passed.

Parameters:: agents_num – A integer.

:param params_df : A pandas dataframe whose specification is the same as the argument of set_properties :return:

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 = None, params: Dict | None = 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) → pd.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: pd.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  2  0.207738
  1  2  0.236711
  2  2  0.869793
  3  2  0.797763
  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  2  0.207738
           0   1  2  0.236711
           0   2  2  0.869793
......
         1   0  2  0.778997
         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: