Simulating exposure-related behaviors using agent-based models embedded with needs-based artificial intelligence

Exposure to a chemical is a critical consideration in the assessment of risk, as it adds real-world context to toxicological information. Descriptions of where and how individuals spend their time are important for characterizing exposures to chemicals in consumer products and in indoor environments. Herein we create an agent-based model (ABM) that simulates longitudinal patterns in human behavior. By basing the ABM upon an artificial intelligence (AI) system, we create agents that mimic human decisions on performing behaviors relevant for determining exposures to chemicals and other stressors. We implement the ABM in a computer program called the Agent-Based Model of Human Activity Patterns (ABMHAP) that predicts the longitudinal patterns for sleeping, eating, commuting, and working. We then show that ABMHAP is capable of simulating behavior over extended periods of time. We propose that this framework, and models based on it, can generate longitudinal human behavior data for use in exposure assessments.

The current version of ABMHAP requires the user to input parameters that describe the longitudinal variation in behavior of a single individual.
The current version of ABMHAP is written in Python version 3.5.3. More information on the Python programming language may be found here. The Python libraries that must be installed in order for ABMHAP to run are listed below. Disclaimer The United States Environmental Protection Agency through its Office of Research and Development has developed this software. The code is made publicly available to better communicate the research. All input data used for a given application should be reviewed by the researcher so that the model results are based on appropriate data for any given application. This model is under continued development. The model and data included herein do not represent and should not be construed to represent any Agency determination or policy.

Setting the input parameters
In order to run ABMHAP, the user must set the following types of input parameters in \run\main_params.py: 1. input parameters that govern the general logistics of the simulation 2. input parameters that govern the the length of simulation duration 3. input parameters that define the behavior of the agent For illustrative purposes, what follows is a demonstration of how to parametrize a run for ABMHAP.
The below code does the following: • informs the algorithm to not print the output to the screen • informs the algorithm to not plot the output • informs the algorithm to not save the output to a file • should the output file be saved, sets the output file to \some_directory\outputfile.csv The user must set the input parameters that govern the general logistics of the simulation: The following code shows how to set ABMHAP to run starting on Sunday, Day 0 starting from 16:00 and ending on Monday, Day 7 at 0:00. It's recommended that the user start running the code on a Sunday or Saturday at 16:00 in order to minimize potential activity conflicts at initiation.
The user must set the input parameters dealing with the duration of the simulation: The user must set the input parameters dealing with when in the simulation year the simulation should start: # start the simulation on Sunday, Day 0 at 16:00 t_start = WINTER * SEASON_2_MIN + 0 * WEEK_2_MIN \ + SUNDAY * DAY_2_MIN + 16 * HOUR_2_MIN where the following constants are useful in assigning input parameters that define the start time of the simulation: The user must set the input parameters that govern the behavior of the agent. The input parameters will govern the agent's behavior for the following activities. In order to set the eat breakfast behavior, the user must set the mean and standard deviation for the start time and duration for the eat breakfast activity. The agent's behavior for eating breakfast is set as follows: In order to set the eat lunch behavior, the user must set the mean and standard deviation for the start time and duration for the eat lunch activity. The agent's behavior for eating lunch is set as follows: # set the mean start time to be 12:000 lunch_start_mean = np.array( [12 * HOUR_2_MIN] ) # set the standard deviation of start time to be 15 minutes lunch_start_std = np.array ( [15] ) # set the mean duration to be 30 minutes lunch_dt_mean = np.array ( [30] ) # set the standard deviation of duration to be 10 minutes lunch_dt_std = np.array ( [10] ) In order to set the eat dinner behavior, the user must set the mean and standard deviation for the start time and duration for the eat dinner activity. The agent's behavior for eating dinner is set as follows: The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08 # set the standard deviation of duration to be 5 minutes dinner_dt_std = np.array ( [5] ) In order to set the work behavior, the user must set the mean and standard deviation for the start time and end time for the work activity. The agent's behavior for working is set as follows: # set the mean start time to be 9:00 work_start_mean = np.array( [9 * HOUR_2_MIN] ) # set the standard deviation of start time to be 15 minutes work_start_std = np.array ( [15] ) The user must set the agent's employment status. The agent's employment status is set as follows: # an agent-based model module for functionality dealing with occupation import occupation # set the job identifier (job id) as standard job if the agent # is supposed to work job_id = occupation.STANDARD_JOB # OR set the job identifier (job id) as not having a job if the agent # is NOT supposed to work job_id = occupation.NO_JOB In order to set the commute to work behavior, the user must set the mean and standard deviation for the duration of the commute to work activity. The agent's behavior for commuting to work is set as follows: # set the mean duration to be 30 minutes commute_to_work_dt_mean = np.array ( [30] ) # set the standard deviation to be 10 minutes commute_to_work_dt_std = np.array ( [10] ) In order to set the commute from work behavior, the user must set the mean and standard deviation for the duration of the commute from work activity. The agent's behavior for commuting from work is set as follows:

Running the simulation
After defining all of the parameters in the file \run\main_params.py, the code is run by doing the following: 1. go to the \run directory.
2. enter python main.py into the terminal (or command line)

press enter (or return)
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08

Interpreting the output
ABMHAP outputs the record of the activities that the agent did during the simulation. This record is called an activity diary. An activity diary is a chronological record contains the following information about each activity: day, start time, end time, duration, and location.
Below is an example of the output of ABMHAP. where day, start, end, dt, act, and loc represent the day the activity starts, the start time of the activity (in hours), the end time of the activity (in hours), the duration of the activity (in hours), the activity identifier, and the location identifier, respectively. In the results, the time of day 16:30 is represented as 16.5.
The following table is an interpretation of the example output shown above. In the table, the duration is expressed in minutes.

Source Directory
These files are the key modules that are used to create the ABMHAP algorithm. Contents:

activity module
This module contains code that governs the activities that the agent performs in order to satisfy its needs.
This module contains the following class: activity.Activity.
Module author: Dr. Namdi Brandon class activity.Activity Bases: object An activity enables a person.Person to address its satiation ( ). This class's purpose is to encapsulate general capabilities that specific instances of activity will derive from.

Variables
• category (int) -an unique identifier naming the type of activity.
• t_end (int) -the end time of the activity [universal time, seconds] • t_start (int) -the start time of the activity [universal time, seconds] • dt (int) -the duration of the activity [seconds]

advertise(the_need, dt)
Calculates the advertised score of doing an activity. Let Ω be the set of all needs addressed by the activity. The score is calculated by doing the following where ( ) is the weight function for the particular need.

Parameters
• the_need (need.Need) -the primary need associated with the respective activity • dt (int) -the duration ∆ of doing the activity [seconds] Returns score the score of the advertisement

Return type float
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08 advertise_interruption() Advertise the score if this activity interrupts another activity.
Note: This function should be overloaded in derived classes.
Returns score the advertised score Return type float

end(p)
This function handles some of the common logistics in ending a specific activity assuming the activity ends without interruption.
Currently the function does the following: Parameters p (person.Person) -the person whose activity is ending.
Returns None

halt(p)
This function handles some of the common logistics in ending a specific activity due to an interruption.
Currently the function does the following: Parameters p (person.Person) -The person whose activity is being interrupted.
Returns None print_id() This function represents the activity category as a string.
Return msg The string representation of the category Return type str start() This function starts a specific activity.
Note: This function is meant to be overloaded by derived activity classes.
Returns None toString() This function represents the activity object as a string.
Return msg The string representation of the activity object Return type str Release 2017.08

asset module
This module contains code that governs objects that enable access to activities (activity.Activity) that an agent may use in order to address a need.
This module contains the following class: asset.Asset.
Module author: Dr. Namdi Brandon class asset.Asset Bases: object An asset is an object that allows the agent to perform an activity. Each asset contains a list Activities that an agent can use to perform actions.

Variables
• activities (dict) -This is a dictionary of all the activities associated with this asset.
• category (int) -This indicates the type of asset.
• id (int) -This is an identifier number for the asset.
• 'location' (location.Location) -This is the location of the asset.
• max_users (int) -This indicates the maximum number of users that can simultaneously access the asset.
• num_users (int) -This is the current number of users for the asset.
• status (int) -This is the state of the asset.

free()
This function changes the state of an asset once it is freed by a Person by doing the following: 1.Decreases the number of users of the asset by 1 2.If the number of users is zero, the status of the asset is set to idle (state.IDLE) Returns None

initialize(people)
This function initializes the asset at the beginning of the simulation.
Note: This function is meant to be overridden

bio module
This module contains information about a person.Person's biology.
This module contains the following class: bio.Bio. Returns None

toString(do_decimal=False)
This function represents the bio.Bio object as a string.

bio module 13
The Returns None update_sleep_end_univ(time_of_day, t_univ) This function sets the end time for sleep in terms of universal time.

Parameters
• time_of_day (int) -the current time of day [minutes] • t_univ (int) -the universal time [minutes] Returns None update_sleep_start() This function samples the sleep start time distribution and sets the start time.
Returns None update_sleep_start_univ(time_of_day, t_univ) This function sets the start time for sleep in terms of universal time.

Parameters
• time_of_day (int) -the current time of day [minutes] • t_univ (int) -the universal time [minutes] Returns None update_time_univ(time_of_day, t_univ, t) This function updates a time , which represents sleep start time or end time, to be in the next occurrence

Parameters
• time_of_day (int) -the current time of day [minutes] • t_univ (int) -the universal time [minutes] • t (int) -the time to be set[minutes, time of day] Return out the time of the next event in universal time Return type int

commute module
This module contains about activities associated with commuting to and from work. This class is an activity.Activity that gives a person.Person the ability to commute to/ from work/ school and satisfy the need Travel travel.Travel. Release 2017.08 Returns None class commute.Commute_From_Work Bases: commute.Commute This class allows for the activity: commuting from work.

advertise(p)
This function calculates the score of an activities advertisement advertise the score to commute.
1.calculate advertisement only if the person is located at work (off-site) 2.calculate the score  Returns None Release 2017.08

start(p)
This handles the start of the commute activity.
If the current location of person is at home, the person is going to work, so set the location to location.OFF_SITE If the current location of the person is off site, the person is going back home, so set the location to location.HOME This class allows for the activity: commute to work

advertise(p)
This function calculates the score of an activities advertisement advertise the score to commute.
1.calculate advertisement only if the person is located at work (off-site) 2.calculate the score

start(p)
This function handles the start of the commute to work activity. If the current location of person is at home, the person is going to work, so set the location to workplace location (location.OFF_SITE)

Parameters p (person.Person) -the person of interest
Returns None

start_commute(p)
This function sets the variables pertaining to starting the commute to work activity.

diary module
This module contains code that governs the activity-diaries. Each activity diary contains dataframes that store the activity-diaries for each person. The activity-diaries are the output of the Agent-Based Model of Human Activity Patterns (ABMHAP) simulation.
This module contains class diary.Diary.
Module author: Dr. Namdi Brandon Returns a tuple containing the following: the array indices for each activity grouping, the activity diaries in a numerical format, the activity diary in a string format, and the column names for each data type Each diary is a tuple that contains the following: 1.the day number of the start of the activity 2.the (start-time, end-time) for the activity event 3.the activity code for the activity event 4.the location of the event get_day_end(day_start, start, dt) This function gets the day that an activity ends.

get_weekday_data(df=None)
This function pulls out data that only corresponds to the weekday data.
Parameters df (pandas.core.frame.DataFrame) -the activity-diary of interest. If df is None, then use the dataframe associated with the diary object Returns the activity-diary of data that occur on weekdays

get_weekday_idx(df=None)
Get the indices of the data that occurs on weekdays. An activity is considered to be on the weekday if the activity ends on Monday -Friday.
Parameters df (pandas.core.frame.DataFrame) -the activity-diary of interest. If df is None, then use the dataframe associated with the diary object The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08

Returns boolean indices of which activities end during the weekend
Return type numpy.ndarray

get_weekend_data(df=None)
This function pulls out data that only corresponds to the weekend data.
Parameters df (pandas.core.frame.DataFrame) -the activity-diary of interest. If df is None, the use the dataframe associated with the current diary object Returns an activity-diary of data that occurs on weekends

get_weekend_idx(df=None)
Get the indices of the data that occurs on weekend. An activity is considered to be on the weekend if the activity ends on Saturday or Sunday.
Parameters df (pandas.core.frame.DataFrame) -the activity-diary of interest. If df is None, then use the dataframe associated with the diary object

Returns boolean indices of which activities end during the weekend
Return type numpy.ndarray

group_activity(t, y)
This function groups activities in chronological order.

Parameters
• t (numpy.ndarray) -the start time for activities • y (numpy.ndarray) -the activity code that corresponds with the respective time Returns a list of each unique group-lists. Each group-list contains a tuple for (time step, activity code)

group_activity_indices(groups)
This function returns the indices for each continuous activity in chronological order.
Note: The output is the time step number not the value of time Parameters groups (list) -a list of tuples of (time step, activity code)

group_activity_key(x)
This is the key function used in groupby in order to group consecutive time-step-activity pairs. This is necessary for creating an activity diary.
Parameters x (tuple) -the data in the form of ( index, (time step, activity code) ) :return the key for sorting ( , activity code) :rtype: tuple

is_weekend(day)
This function returns true if a day is in the weekend and false if it's in a weekday.
Parameters day (numpy.ndarray) -the day of the weekend Returns boolean index of whether or not a day is in the weekend (True) or not (False) Return type numpy.ndarray

same_day(start, dt)
This function returns true if the activity starts and ends on the same day.

Parameters
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08 • start (numpy.ndarray) -the time an activity starts [hours] • dt (numpy.ndarray) -the time an activity ends [hours] Returns a boolean index of whether or not an activity started and ended on the same day Return type numpy.ndarray

toString() This expresses the diary as a string
Returns an expression of the diary as a string Return type string

eat module
This module contains information about the activities associated with eating. This class is an activity.Activity that gives a person.Person the ability to eat and satisfy the need hunger.Hunger.
This module contains the following classes: This class has general capabilities that allow the person to eat in order to satisfy hunger.Hunger. This class acts as a parent class and is expected to inherited.

advertise(p)
This function handles advertising the score to an agent. This function returns 0.
Note: This function should be overloaded when inherited.

Parameters p (person.Person) -the person of interest
Returns the score (0) Return type float

advertise_help(p, dt)
This function does some of the logistics needed for advertise().
This function does the following: 1.sets the suggested recharge rate for hunger 2.calculates the score

Parameters
• p (person.Person) -the person who is being advertised to • dt (float) -the duration of the activity

eat module 21
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08 Returns the score Return type float

advertise_interruption(p)
This function calculates the score of an activity advertisement when a person is going to interrupt an ongoing activity in order to do an eating activity.
This function does the following: 1.temporarily sets the satiation of hunger ℎ ( ) = 2.calculate the score advertised for the potential eating activity that will interrupt a current activity 3.restores the the satiation for hunger to the original value Parameters p (person.Person) -the person whose activity is ending Returns None

end_meal(p)
This function ends the eat activity by doing the following.
1.frees the person's use of the asset 2.sets the state to idle (state.IDLE) 3.sets the satiation of hunger 4.set the current meal for the next day 5.set any skipped meals to be on the next day 6.find the the next meal 7.sets the decay rate of hunger 8.update the scheduler so that hunger will trigger the schedule to stop at the next meal 9.set the next meal to the current meal Parameters p (person.Person) -The person whose meal is ending.
Returns None

set_end_time(p)
This function returns the end time of eating (universal time).
Parameters p (person.Person) -the person of interest.

Return t_end the end time of eating [minutes, universal time]
Return type int

start(p)
This function starts the eating activity.

Chapter 2. Source Directory
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08 Parameters p (person.Person) -The person whose activity is starting.
Returns None

start_meal(p)
This function starts the eat activity by doing the following. This class is used to handle the logistics for eating breakfast.

advertise(p)
This function calculates the score of an activities advertisement to a person.
Advertise to the agent if the following conditions are met 1.the current meal is breakfast 2.the agent's location is at home (location.HOME) 3.calculate the score This class is used to handle the logistics for eating dinner.

advertise(p)
This function calculates the score of an activities advertisement to a Person.
Advertise to the agent if the following conditions are met 1.the current meal is lunch 2.the agent's location is at home (location.HOME) 3.calculate the score If the threshold is not met, score is 0. The advertisements assume that the duration of the activity is the mean duration.

Parameters p (person.Person) -The person of interest
Return score the advertised score of doing the Eat activity Return type float

end_meal(p)
This function goes through the logistics of ending the dinner meal by doing the following: 1.calls end.end_meal() 2.If breakfast will be skipped, update the lunch event to be 2 days from the current day Parameters p (person.Person) -the person who is finishing the eating dinner event Returns None

start_meal(p)
This function goes through the logistics of starting the dinner meal by doing the following: This class is used to handle the logistics for eating lunch. Release 2017.08

advertise(p)
This function calculates the score of an activities advertisement to a person.
Advertise to the agent if the following conditions are met 1.the current meal is lunch 2.the agent's location is at home (location.HOME) or the agent's location is at the workplace (location.OFF_SITE) 3.calculate the score If the threshold is not met, score is 0. The advertisements assume that the duration of the activity is the mean duration.

Parameters p (person.Person) -The person of interest
Return score the advertised score of doing the Eat activity Return type float

end_meal(p)
This function ends the eat activity by doing the following: if dinner is to be skipped, update the dinner event by doing the following: • if the lunch is an interrupting activity set the time until the next lunch activity update the schedule for the interruption to the next lunch activity set the interruption state to False Parameters p (person.Person) -The person whose meal is ending.
Returns None

start_meal(p)
This function handles the logistics for starting the eat activity by doing the following: 1.sets the current meal to lunch 2.call eat.start_meal() Parameters p (person.Person) -the person starting the eat lunch event Returns None

food module
This module contains information about the asset that allows for the eating activity.
This module contains the following class: food.Food.

food module
The

home module
This module governs the control of assets used in the simulation. Mainly, the home contains all of the assets used in the simulation for the current version of the code.
This module contains the following class: home.Home Module author: Dr. Namdi Brandon.
class home.Home(clock) Bases: object Contains all of the physical characteristics of a home/ residence. Currently, the home contains all of the assets within the simulation.
Parameters clock (temporal.Temporal) -the time

Variables
• assets (dict) -contains a list of all of the assets available in the home.
• category (int) -the type of home • do_interruption (bool) -a flag that indicates whether or not we should advertise for interruptions • locale (int) -a local location identifier Returns the advertisements (score, asset, activity, person) containing the various data for each advertisement: ("score", "asset", "activity", "person") coupling Return type dict initialize(people) Initialize the assets in the home.  Returns None

set_recharge_rate(dt)
This function calculates the recharge rate of hunger due to eating the current meal.
Parameters dt (int) -the amount of time it takes to finish a meal [minutes] Returns None

set_suggested_recharge_rate(dt)
This function sets the suggested recharge rate assuming a linear function behavior The suggested recharge rate is based on the duration of the sleeping event and the threshold. The sleep duration is based on the biological data (no rounding).

Parameters dt (int) -The duration of time of the eating event [minutes]
Returns None

toString()
Represents the Hunger object as a string.
Return msg the string representation of the huger object Return type str

income module
This is module contains code for governing the need to work/ be schooled.
This module contains the class income.Income.

interrupt module
This module contains code for interrupting a current activity.
This module contains class interrupt.Interrupt.
Module author: Dr. Namdi Brandon class interrupt.Interrupt Bases: activity.Activity This class allows for the current activity to be interrupted by another activity.

advertise(p, str_need, act)
This function calculates the score of an activities advertisement to a Person. This function does the the following: 1.temporarily sets the value of the Need that must be immediately addressed to a low level.
2.send an advertisement is is made from the potentially interrupting activity 3.calculate the score from the potentially interrupting activity

interrupt module 31
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08

Parameters
• p (person.Person) -the person who is being advertised to • str_need (int) -the id of the Need that needs to be addressed, which could potentially cause an interrupting event • act (activity.Activity) -the activity of interest that could immediately interrupt a current activity Returns the value of the advertisement Return type float

start(p)
This handles the start of an activity.

Parameters p (person.Person) -the person of interest
Returns None

interruption module
This class gives an agent the ability to interrupt a current activity.
This module contains class interruption.Interruption.
Module author: Dr. Namdi Brandon class interruption.Interruption(clock, num_sample_points) Bases: need.Need This class enables a Person to interrupt a current activity.
Interruption is a minor Need (need-association). That is, this need-association is NOT independent of other needs.

is_lunch_time(time_of_day, meals)
This function indicates whether it is lunch time or not. This is used in the interruption to stop the work activity and begin the eat lunch activity.

Parameters
• time_of_day (int) -the time of day [minutes] • meals (list) -a list of the meals (meal.Meal) for the agents. Some of the entries in the list may be None.

perceive(clock)
This gives the result if sleep is done now until a later time corresponding to clock.

Parameters clock (temporal.Temporal) -a clock at a future time
Return out the perceived interruption magnitude reset() This function resets the interruption need completely in order to re run the simulation. In this reset, the history is also reset.

reset_minor() This function resets the interruption need
Returns None

stop_work_to_eat(p)
This function checks to see if an interruption should occur to allow a Person to start the eating activity while doing the work activity An agent may stop the work activity to eat lunch if the following conditions are met: 1.The agent is hungry 2.The current activity is work

Parameters p (person.Person) -the person of interest
Returns None

location module
This module is responsible for containing information about the concept of location.
This module contains class location.Location.
Module author: Dr. Namdi Brandon class location.Location(geography=1, local=0) Bases: object This class holds information relevant to the location of persons and assets.

location module
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08

Parameters
• geography (int) -the geographical location code • local (int) -the local location code

Variables
• geo (int) -the geographical location code within the U.S (e.g. north, south, eats, or west) • local (int) -the local location code (e.g. home, off site, etc)

print_geo() Returns the geographical location in a string format
Returns the string representation of the geographical location Return type str

Returns the local location in a string format
Returns the string representation of the local location Return type str reset() This function resets the location to the default value, (location.HOME).
Returns None toString() This function represents the Location object as a string.

Return msg the string representation of the Location object
Return type str

meal module
This module contains contains information about various meals that an agent would eat in.
This module contains code for class meal.Meal.

Variables
• id (int) -the meal type (breakfast, lunch, or dinner) • dt (int) -the duration of a meal [minutes] • dt_mean (int) -the mean duration of a meal [minutes] • dt_std (int) -the standard deviation of meal duration [minutes] • dt_trunc (int) -the number of standard deviation in the duration distribution update_day() Update the day for the next meal, given the universal start time for the meal (t_start_univ).
Returns None update_dt() Sample the duration distribution to get a duration.
Returns None update_start() Sample the start time distribution to get a start time.
Returns None update_start_univ(day) Given the day for the next meal, update the universal start time for the meal.
Parameters day (int) -the day for the meal Returns None

my_globals module
This module contains constants and functions that are used for general use.
This module contains information about the following constants: This function takes an array of activity start times and activity codes from an activity diary and fills out the activity, minute-by-minute in between two adjacent activities.

Parameters
• t (numpy.ndarray) -the start times in an activity diary • y (numpy.ndarray) -the activity codes in an activity diary my_globals.get_ecdf(data, N=100) Given data, this function calculates the probability data from the empirical cumulative distribution function (ECDF).

Parameters
• data (float) -an array containing the relevant data to get the ECDF of • N (int) -the amount of samples in calculating the ECDF results

Return x the values sampled for the ECDF
Return type float array my_globals.group_time(t) This function takes data from an activity diary and groups that activity diary into , minute by minute arrays from start to end for each activity (start, start + 1, ... end-1, end) Parameters t (numpy.ndarray) -the start times from an activity diary [minutes, universal time] Returns the grouped start/end pairs for ech activitiy Return type list my_globals.hours_to_minutes(t) This function takes a duration of time in hours and converts the time rounded to the nearest minutes.

Parameters t (float) -a duration of time [hours]
Returns the time in minutes my_globals.load(fname) This function loads data from a .pkl file.
Parameters fname (str) -the file name to be loaded from Returns the data unpickled my_globals.sample_normal(std, dx) This function samples a normal distribution centered at zero assuming a max and minimum acceptable value [dx, -dx].

Parameters
• std (float) -the standard deviation • dx (float) -the amount of total deviation from the mean allowd Returns my_globals.save(x, fname) This function saves a python variable by pickling it.

my_globals module 37
The Agent-Based Model of Human Activity Patterns (ABMHAP): Documentation and Users Guide, Release 2017.08 Parameters • x -the data to be saved • fname (str) -the file name of the saved file. It must end with .pkl my_globals.save_zip(out_file, source_dir) This function compresses an entire directory as a zip file.

Parameters
• out_file (str) -the filename of the save zip file with out the .zip extension • source_dir (str) -the directory to be compressed Returns the name of the compressed directory my_globals.set_distribution (lower, upper, mu, std) This function sets the truncated normal probability distribution.

Parameters
• lower ( Returns the function for the truncated normal distribution my_globals.set_distribution_dt (lower, upper, mu, std, x_min) This function set the truncated normal probability distribution subject to the fact that there is an assigned lowest value.
If the lowest value of the normal distribution is lower than the lowest allowed value, change the distribution so that the standard deviation allows the distribution to not be lower than the lowest allowed value.

need module
This module contains information about governing the various needs that agents have in the simulation.
This module contains the class need.Need. Note: This function is meant to be overridden.

print_category()
This function represents the category as a string.
Returns the string representation of the category • commute_to_work_dt_std (int) -the standard deviation to commute to work [minutes] • commute_to_work_dt (int) -the duration to commute to work [minutes] • commute_to_work_dt_trunc (int) -the number of standard deviation in the commute to work duration distribution • commute_to_work_start (int) -the start time for the commute to work activity [minutes] • dt_commute (int) -the duration of the commute [minutes] • dt (int) -the duration of the work activity [minutes] • commute_from_work_dt_mean (int) -the mean duration to commute from work [minutes] • commute_from_work_dt_std (int) -the standard deviation to commute from work [minutes] • commute_from_work_dt (int) -the duration to commute from work [minutes] • commute_from_work_dt_trunc (int) -the number of standard deviations in the commute from work duration distribution •commute to work duration distribution •commute from work duration distribution.
Returns None

set_is_job()
This function checks to see if the current job is actually a job (eg. that it is not NO_JOB).

Sets self.is_job to True if the Occupation is NO_JOB, returns False otherwise
Returns None set_is_same_day() This function sets a flag indicating whether or not a job starts and ends on the same day. The function sets is_same_day to True if the Occupation start time and end time are within the same day. False, otherwise.

Parameters
• id_job (int) -the job identifier Returns None

toString() Represents the Occupation object as a string
Return msg The representation of the Occupation object as a string Return type str update_commute_from_work_dt() Pull a commute from work duration from the respective distribution.
Returns None update_commute_to_work_dt() Pull a commute to work duration from the respective distribution. Also, update the commute to work start time place holder.
Returns None update_commute_to_work_start() Update the commute to work start time.
Returns None

update_work_dt() Update the work duration
Returns None update_work_end() Update the work end time.
Returns None update_work_start() Update the work start time.
Returns None occupation.is_work_time(clock, job, is_commute_to_work=False) Given a clock and a job, this function says whether the clock's time corresponds to a time to be at work or a time to commute to work.
If ∆ > 0, it indicates when it's time to commute to work.

params module
The purpose of this module is to assign parameters necessary to run the Agent-Based Model of Human Activity Patterns (ABMHAP) initialized with data from the Consolidated Human Activity Database (CHAD). This module also have constants used in default runs.
This module contains class params.Params.
Note: Some of the class attributes are not really used and need to be phased out in future versions of the model. Some of these attribtues are: • job_id (list) -the occupation identifier for each person in the household

scheduler module
This module contains code that is is responsible for controlling the scheduler for the simulation. Note that the simulation does not run continuously in from one adjacent time step to the next. Instead the simulation jumps forward in time (i.e. move across multiple time steps in time), stopping only at time steps in which an action could occur. The ability to jump forward in time is controlled by the scheduler.
The scheduler will trigger the simulation to stop skipping time steps for the following reasons: 1. an activity should start 2. an activity should end

a need is under threshold
This module contains class scheduler.Scheduler.

address_needs(do_interruption=False)
This function checks the needs of the agents The function uses a recursion loop to choose activities.
The Recursion: 1.Gather all of the advertisements (object-person pairings) 2.Assigns 1 activity to the Person with the highest score.
3.That Person starts the activity, thereby updating the state of available activities in the home.
4.The recursion starts again, where the Home advertises to all remaining Person(s).
Note If no activity will be done this time step to a Person, a Person is set to the temporary status state.IDLE_TEMP, so that the Home knows not to advertise to that Person.
Parameters do_interruption (bool) -this flag indicates whether or not advertisements should be made for activities that will interrupt the current activity (if True). If False, the advertisements are made for non-interrupting activities.
Returns None

advertise(do_interruption=False)
This function obtains a list of all of the possible activities each person could potentially start in this time step.
Parameters do_interruption (bool) -this flag indicates whether to make advertisements due to an interrupting activity (if True) or not (if False).
Return ads ads is a list of dictionaries for advertisements: Dictionary (score, asset, activity, person) containing the various data for each advertisement: (score, asset, activity, person) coupling Return type list check_expired_activities() This function checks for expired activities. If found, end the activities.
Returns None

decay_needs(dt=None)
This function decays the needs according to the default behavior. That is, assume the needs are not addressed earlier.
Parameters dt (int) -the number of minutes to decay the needs by. The default behavior is to use the scheduler's time. If a number is specified, then it should be the number of minutes until the end of the simulation.

print_activity_info(p)
This function stores activity info used for testing / developing/ debugging as a string.

Parameters p (person.Person) -the person of interest
Returns None

reset(t_univ)
This code resets the simulation by initializing the agents, home, and clock to the beginning status of the simulation.
This code does the following: Returns run() This function is responsible for running the simulation. Instead of running the simulation minute-byminute, in an effort to reduce run-time, the simulation skips time steps and addresses the agent at times that actions should occur. These times are dictated by the scheduler.
The function proceeds as following: While the current time is less than the final time