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)[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_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

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