Creator

class pop2net.creator.Creator(model, seed=None)[source]

Creates and connects agents and locations.

create(df, location_designers, agent_class=<class 'pop2net.agent.Agent'>, agent_class_attr=None, agent_class_dict=None, n_agents=None, sample_level=None, sample_weight=None, replace_sample_level_column=True, clear=False, delete_magic_agent_attributes=True)[source]

Creates agents and locations based on a given dataset.

Combines the Creator-methods draw_sample(), create_agents() and create_locations().

Parameters:

  • df (pd.DataFrame) – A data set with individual data that forms the basis for the creation of agents. Each row is (potentially) translated into one agent. Each column is translated into one agent attribute.

  • agent_class (type[p2n.Agent]) – The class from which the agent instances are created.

  • location_designers (list) – A list of classes from which the location instances are created.

  • n_agents (Optional[int], optional) – The number of agents that will be created. If n_agents is set to None, each row of df is translated into exactly one agent. Otherwise, rows are randomly drawn (with replacement, if n_agents > len(df)) from df until the number of agents created equals n_agents.

  • sample_level (Optional[str], optional) – If sample_level is None, the rows are sampled individually. Otherwise the rows are sampled as groups. sample_level defines which column of df contains the group id.

  • sample_weight (Optional[str]) – The column of df in which should be used as probability weight during sampling.

  • replace_sample_level_column (bool) – Should the original values of the sample level be overwritten by unique values after sampling to avoid duplicates?

  • clear (bool) – Should the agents and locations already included in the model be removed?

  • delete_magic_location_attributes (bool) – If True, all magic location attributes will be removed after the creation of the location instances.

  • delete_magic_agent_attributes (bool) – If True, all magic agent attributes will be removed after the creation of the location instances.

Returns:

A list of agents and a list of locations.

Return type:

tuple

create_agents(agent_class=<class 'pop2net.agent.Agent'>, agent_class_attr=None, agent_class_dict=None, df=None, n=None, clear=False)[source]

Creates agents from a pandas DataFrame.

Creates one agent-instance of the given agent-class for each row of the given df, if df is not None. All columns of the df are added as instance attributes containing the row-specific values of the specific column. If df is None and n is not None, n default agents without any additional attributes are created.

Parameters:

  • agent_class – A class to instantiate all agents with. Every column in the DataFrame will result in an attribute of the agents.

  • df (Optional[DataFrame]) – The DataFrame from which the agents should be created from.

  • n (Optional[int]) – The number of agents that should be created. Defaults to None.

  • clear (bool) – Should the agents already included in the model be removed?

Return type:

AgentList

Returns:

A list of agents.

create_locations(location_designers, agents=None, clear=False, delete_magic_agent_attributes=True)[source]

Creates location instances and connects them with the given agent population.

Parameters:

  • location_designers (list) – A list of LocationDesigner classes.

  • agents (list | p2n.AgentList) – A list of agents.

  • clear (bool) – Should the locations already included in the model be removed?

  • delete_magic_location_attributes (bool) – If True, all magic location attributes will be removed after the creation of the location instances.

  • delete_magic_agent_attribtues (book) – If True, all magic agent attributes will be removed after the creation of the location instances.

Returns:

A list of locations.

Return type:

p2n.LocationList

draw_sample(df, n=None, sample_level=None, sample_weight=None, replace_sample_level_column=True)[source]

Draw a sample from a dataframe.

Parameters:

  • df (pandas.DataFrame) – a pandas DataFrame

  • n (int) – Target size of the final sample. If this is higher the size of the input DataFrame, the sampling will occure with replacement. Without otherwise. If n is set to None, df is returned as it is.

  • sample_level (str, optional) – A variable the specifies sample units, i.e. rows that should always

  • instance (be sampled together. For) – Defaults to None.

  • households. (a household ID to sample by) – Defaults to None.

  • sample_weight (str, optional) – The column of df which should be used as probability weight. Defaults to None.

  • replace_sample_level_column (bool) – Should the original values of the sample level be overwritten by unique values after sampling to avoid duplicates?

Return type:

DataFrame

Returns:

A pandas DataFrame.

get_df_agents(columns=None, drop_agentpy_columns=True)[source]

Returns the latest created population of agents as a dataframe.

Parameters:

  • columns (list | None) – A list of column names that sould be kept. All other columns are deleted.

  • drop_agentpy_columns (bool) – Deletes some columns created by AgentPy.

Raises:

Pop2netException – _description_

Returns:

A dataframe which contains one row for each agent and one column for each agent attribute.

Return type:

pd.DataFrame