Creator

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

Creates and connects actors and locations.

create(df, location_designers, actor_class=<class 'pop2net.actor.Actor'>, actor_class_attr=None, actor_class_dict=None, n_actors=None, sample_level=None, sample_weight=None, replace_sample_level_column=True, clear=False, delete_magic_actor_attributes=True, return_elements=False)[source]

Creates actors and locations based on a given dataset.

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

Parameters:

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

  • actor_class (type[p2n.Actor]) – The class from which the actor instances are created.

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

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

  • 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 actors 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_actor_attributes (bool) – If True, all magic actor attributes will be removed after the creation of the location instances.

Returns:

A list of actors and a list of locations.

Return type:

tuple

create_actors(actor_class=None, actor_class_attr=None, actor_class_dict=None, df=None, n=None, clear=False)[source]

Creates actors from a pandas DataFrame.

Creates one actor-instance of the given actor-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 actors without any additional attributes are created.

Parameters:

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

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

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

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

Returns:

A list of actors.

create_actors_from_id_list(id_list, id_attr_name, actor_class)[source]

Create actors based on a list of ids.

Extracts unique IDs and creates one actor instance for each unique ID.

Parameters:

  • id_list (list) – A list that contains IDs.

  • id_attr_name (str) – The name of the attribute that will be added to each actor instance and contains the ID from the list.

  • actor_class (None | type[p2n.Actor]) – The class from which the actor instances are created.

Returns:

None

create_actors_from_pandas_edgelist(df, id_attr_name, actor_class=None)[source]

Create actors based on a pandas edge list.

Extracts unique IDs from an edge list stored in a pandas dataframe and creates one actor instance for each unique ID.

Parameters:

  • df (pd.DataFrame) – DataFrame containing the edge list. Must include the columns “source” and “target”, which store node identifiers.

  • id_attr_name (str) – The name of the attribute that will be added to each actor instance and contains the ID from the edge list.

  • actor_class (None | type[p2n.Actor]) – The class from which the actor instances are created.

Returns:

None

create_locations(location_designers, actors=None, clear=False, delete_magic_actor_attributes=True)[source]

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

Parameters:

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

  • actors (list | p2n.ActorList) – A list of actors.

  • 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_actor_attribtues (book) – If True, all magic actor attributes will be removed after the creation of the location instances.

Returns:

A list of locations.

Return type:

p2n.LocationList

create_locations_from_pandas_edgelist(df, id_attr_name, location_cls=None, location_label=None, weighted=False)[source]

Create connections (“locations”) between actors based on a pandas edge list.

Each row in the dataframe represents an edge between two actors, identified by their node IDs. The method resolves these IDs to actor instances and creates a connection between them.

Parameters:

  • df (pd.DataFrame) – DataFrame containing the edge list. Must include the columns “source” and “target”, which store node identifiers. If weighted=True, it must also include a “weight” column.

  • id_attr_name (str) – Name of the actor attribute that stores the node ID used to match actors with the “source” and “target” values.

  • location_cls (type | None, optional) – Class used to instantiate the location/connection object. If None, a default location class is used.

  • location_label (str | None, optional) – Optional label assigned to the created location.

  • weighted (bool, optional) – If True, edge weights are read from the “weight” column in df. If False, all connections are created with a default weight of 1.

Returns:

None

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_actors(columns=None, drop_agentpy_columns=True)[source]

Returns the latest created population of actors 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 actor and one column for each actor attribute.

Return type:

pd.DataFrame