The Agent-Based Model of Human Activity Patterns (ABMHAP, pronounced "ab-map") is one of the modules for the Life Cycle Human Exposure Model (LC-HEM) project as described in the United States Environmental Protection Agency (U.S. EPA) research plan, which may be found here. ABMHAP is a model capable of creating agents that simulate longitudinal human behavior. The current version of ABMHAP is able to simulate daily routines for the following behaviors:
- Sleeping
- Eating Breakfast
- Eating Lunch
- Eating Dinner
- Working
- Commuting to Work
- Commuting from Work
- Being Idle (i.e., time spent not doing the above activities)
ABMHAP requires the user to input parameters that describe the longitudinal variation in behavior of a single individual. Information on the design of the model, modeling assumptions, and limitations of the model are described in the publications:
- Brandon et al. Simulating Exposure-Related Behaviors using Agent-Based Models Embedded with Needs-Based Artificial Intelligence, Journal of Exposure Science and Environmental Epidemiology, submitted 2018.
- Brandon, N and Price, P. Simulating Long-Term Patterns in Exposure-Related Behaviors using the Agent-Based Model of Human Activity Patterns, Journal of Exposure Science and Environmental Epidemiology, submitted 2018.
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.
- matplotlib
- multiprocessing
- numpy
- pandas
- scipy
- sphinx
- statsmodels
Some of the features within ABMHAP also use Jupyter Notebook. More information on Project Jupyter may be found here.
ABMHAP is written by Dr. Namdi Brandon (ORCID: 0000-0001-7050-1538).
- 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.
The current version of ABMHAP may be run in two different ways.
- ABMHAP may run with user-defined parameters in order to simulate one household
- ABMHAP may run with parameters derived from empirical data as a Monte-Carlo simulation in order to simulate multiple households
The following describes how to run an ABMHAP simulation of one household (ABMHAP currenlty simulates one agent per household). In order to do so, the user must do the following:
- set the input parameters of the simulation in the file
\run\main_params.py - run the executable using
\run\main.py
In order to run ABMHAP, the user must set the following types of input parameters in
\run\main_params.py:
- input parameters that govern the general logistics of the simulation
- input parameters that govern the the length of simulation duration
- 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
\output_directory\outputfile.csv
The user must set the input parameters that govern the general logistics of the simulation:
# whether (if True) or not (if False) the output of the simulation should # print a message to screen do_print = False # whether (if True) or not (if False) the output of the simulation should # be plotted a message to screen do_plot = False # whether (if True) or not (if False) the output of the simulation should # be saved in a file do_save = False # the name of the output file should the output be saved. The filename # should have a ".csv" extension fname = 'output_directory\\outputfile.csv'
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 number of days for the simulation num_days = 7 # the number of additional hours num_hours = 8 # the number of additional minutes num_min = 0
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:
# an agent-based model module with capabilities concerning time import temporal # the value of Sunday SUNDAY = temporal.SUNDAY # convert one day into minutes DAY_2_MIN = temporal.DAY_2_MIN # convert one hour into minutes HOUR_2_MIN = temporal.HOUR_2_MIN # the number of minutes in one season (13 weeks) SEASON_2_MIN = temporal.SEASON_2_MIN # the number of minutes in one week WEEK_2_MIN = temporal.WEEK_2_MIN # the winter season (has the value 0) WINTER = temporal.WINTER
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.
- sleeping
- eating breakfast
- eating lunch
- eating dinner
- working
- commuting to work
- commuting from work
In order to set the sleeping behavior, the user must set the the mean and standard deviation for the start time and end time for the sleep activity. The agent's behavior for sleeping is set as follows:
# set the mean start time to be 22:00 sleep_start_mean = np.array( [22 * HOUR_2_MIN] ) # set the standard deviation of the start time to be 30 minutes sleep_start_std = np.array( [30] ) # set the mean end time to be 8:00 sleep_end_mean = np.array( [8 * HOUR_2_MIN] ) # set the standard deviation of the end time to be 15 minutes sleep_end_std = np.array( [15] )
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:
# set the mean start time to be 8:00 bf_start_mean = np.array( [8 * HOUR_2_MIN] ) # set the standard deviation of the start time to be 10 minutes bf_start_std = np.array( [10] ) # set the mean duration to be 15 minutes bf_dt_mean = np.array( [15] ) # set the standard deviation of the duration to be 10 minutes bf_dt_std = np.array( [10] )
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:
# set the mean start time to be 19:00 dinner_start_mean = np.array( [19 * HOUR_2_MIN] ) # set the standard deviation of start time to be 10 minutes dinner_start_std = np.array( [10] ) # set the mean of duration to be 45 minutes dinner_dt_mean = np.array( [45] ) # 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] ) # set the mean end time to be 17:00 work_end_mean = np.array( [17 * HOUR_2_MIN] ) # set the standard deviation of end time to be 5 minutes work_end_std = np.array( [5] )
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:
# set the mean duration to be 30 minutes commute_from_work_dt_mean = np.array( [30] ) # set the standard deviation to be 10 minutes commute_from_work_dt_std = np.array( [10] )
After defining all of the parameters in the file \run\main_params.py, the code is run by doing
the following:
- go to the
\rundirectory. - enter
python main.pyinto the terminal (or command line) - press enter (or return)
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. Recall that ABMHAP saves the activity diary in terms of a .csv file
| day | start | end | dt | act | loc |
|---|---|---|---|---|---|
| 0 | 16 | 19 | 3 | -1 | 0 |
| 0 | 19 | 19.75 | 0.75 | 4 | 0 |
| 0 | 19.75 | 22 | 2.25 | -1 | 0 |
| 0 | 22 | 8 | 10 | 6 | 0 |
| 1 | 8 | 8.25 | 0.25 | 3 | 0 |
| 1 | 8.25 | 8.5 | 0.25 | -1 | 0 |
| 1 | 8.5 | 9 | 0.5 | 2 | 1 |
| 1 | 9 | 12 | 3 | 7 | 3 |
| 1 | 12 | 12.5 | 0.5 | 5 | 3 |
| 1 | 12.5 | 17 | 4.5 | 7 | 3 |
| 1 | 17 | 17.5 | 0.5 | 1 | 1 |
| 1 | 17.5 | 19 | 1.5 | -1 | 0 |
| 1 | 19 | 19.75 | 0.75 | 4 | 0 |
| 1 | 19.75 | 22 | 2.25 | -1 | 0 |
| 1 | 22 | 8 | 10 | 6 | 0 |
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.
| Day | Start | End | Duration | Activity Code | Location Code |
|---|---|---|---|---|---|
| 0 | 16:00 | 19:00 | 180 | Idle | Home |
| 0 | 19:00 | 19:45 | 45 | Eat dinner | Home |
| 0 | 19:45 | 22:00 | 135 | Idle | Home |
| 0 | 22:00 | 8:00 | 600 | Sleep | Home |
| 1 | 8:00 | 8:15 | 15 | Eat breakfast | Home |
| 1 | 8:15 | 8:30 | 15 | Idle | Home |
| 1 | 8:30 | 9:00 | 30 | Commute to work | Out of doors |
| 1 | 9:00 | 12:00 | 180 | Work | Workplace |
| 1 | 12:00 | 12:30 | 30 | Eat lunch | Workplace |
| 1 | 12:30 | 17:00 | 270 | Work | Workplace |
| 1 | 17:00 | 17:30 | 30 | Commute from work | Out of doors |
| 1 | 17:30 | 19:00 | 90 | Idle | Home |
| 1 | 19:00 | 19:45 | 45 | Eat dinner | Home |
| 1 | 19.45 | 22:00 | 135 | Idle | Home |
| 1 | 22:00 | 8:00 | 600 | Sleep | Home |
ABMHAP may be also used to simulate agents whose parametrization is derived from an empirical dataset, as opposed to using user-defined parameters. Specifically, the current version of ABMHAP uses the Consolidated Human Activity Database (CHAD) to parametrize the behavior of agents. More information about CHAD may be found here. Currently, ABMAHP uses data from CHAD to parametrize agents that simulate the behaviors of people that represent the following demographic groups within the general United States population:
- working adults (ages 18 and above)
- non-working adults (ages 18 and above)
- school-age children (ages 5 through 17)
- preschool children (ages 1 through 4)
To simulate a demographic, we run ABMHAP via a Monte-Carlo simulation that creates multiple households (ABMHAP currently simulates one agent per household) and randomly parametrizes their behavior based on empirical distributions from CHAD data. In order to decrease the runtime of simulating multiple households, ABMHAP has the capability to run the Monte-Carlo simulations in parallel.
In order to run the Monte-Carlo simulations, the user must do the following:
- set the input parameters of the simulation in the file
\run_chad\driver_params.py - run the executable using
\run_chad\driver.py
In order to run ABMHAP, the user must set the following types of input parameters in
\run_chad\driver_params.py:
- input parameters that govern the general logistics of the simulation
- input parameters that govern the the length of simulation duration
- input parameters that define the demographic of the agents
For illustrative purposes, what follows is a demonstration of how to parametrize a run for ABMHAP. See, the earlier section "Setting the input parameters" in "How to Run the Code Using User-Defined Parameters" to understand how to set up the input parameters:
# the number of days for the simulation num_days = 364 # the number of additional hours num_hours = 8 # the number of additional minutes num_min = 0 # should the simulation plot results at the end of the run do_plot = False # should the simulation print messages to the screen do_print = True # should the simulation save the results (both input and output) # of the simulation do_save = False
In addition, the user must define the demographic of the agents being simulated. This causes ABMHAP to use the empirical data from the respective demographic in CHAD to parametrize the agent:
# this causes ABMHAP to use empirical data from CHAD corresponding # to the working adult demographic in order to parametrize the agents demographic = dmg.ADULT_WORK # the path to the output directory where should the output results # should be saved fpath = '\\output_directory' # load input data from a previous simulation do_load_trials = False # the file name for "trials" data without the .pkl extension, # which will be used for saving the trial information fname_load_trials_base = None
After defining all of the parameters in the file \run_chad\driver_params.py, the code is run by doing
the following:
go to the
\run_chaddirectory.enter the following into the terminal (or command line):
python driver.py num_process num_hhld num_batchwhere
num_processis the total number of cores (i.e, processing units) used in the simulationnum_hhldis the number of housholds to run per batchnum_batchis the number of batches used per core
press enter (or return)
To run the code, do the following.
Note
This code may be run in batches in order to run many households while conserving memory. That is, instead of running 32 households at once (and keeping 32 households in memory), the program can run 2 batches of 16 households (for a total of 32 households). This halves the amount of memory used in the simulation compared to running the simulation of 1 batch of 32 households. We will shown how to run the code using "batches" below.
The following are examples on how to run the code in serial.
To run in serial with with 64 households per batch, 1 batch (implied)
>
python driver.py 1 64 1>
python driver.py 1 64
To run in serial using 2 batches with 1 thread with 32 households per batch, 2 batches
> python driver.py 1 32 2
The following are examples on how to run the code in parallel.
To run in parallel using 4 cores with 64 households total (16 household per core per batch), 1 batch (implied)
>
python driver.py 4 64 1>
python driver.py 4 64
To run in parallel using 4 cores with 32 households per batch, 2 batches(8 households per core per batch)
> python driver.py 4 32 2
ABMHAP outputs the record of the activities that each agent did during the simulation. Each agent's 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. The output is a combined record of every agent simulated where each agent is given a unique integer as an identifier.
Below is an example of the output of ABMHAP. Recall that ABMHAP saves the activity diary in terms of a .csv file
| id | day | start | end | dt | act | loc |
|---|---|---|---|---|---|---|
| 0 | 0 | 16 | 19 | 3 | -1 | 0 |
| 0 | 0 | 19 | 19.75 | 0.75 | 4 | 0 |
| \vdots | ||||||
| 0 | 364 | 22 | 0 | 2 | 6 | 0 |
| 1 | 0 | 16 | 20 | 4 | -1 | 0 |
| 1 | 0 | 20 | 20.5 | 0.5 | 4 | 0 |
| \vdots | ||||||
| 1 | 364 | 23 | 0 | 1 | 6 | 0 |
where id, day, start, end, dt, act, and loc represent the agent identifier, 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. Each agent in the Mont-Carlo simulation is given a unique identifier via "id".
The following table is an interpretation of the example output shown above. In the table, the duration is expressed in minutes.
| Identifier | Day | Start | End | Duration | Activity Code | Location Code |
|---|---|---|---|---|---|---|
| 0 | 0 | 16:00 | 19:00 | 180 | Idle | Home |
| 0 | 0 | 19:00 | 19:45 | 45 | Eat dinner | Home |
| \vdots | ||||||
| 0 | 364 | 22:00 | 00:00 | 120 | Sleep | Home |
| 1 | 0 | 16:00 | 20:00 | 240 | Idle | Home |
| 1 | 0 | 20:00 | 20:30 | 30 | Eat dinner | Home |
| \vdots | ||||||
| 1 | 364 | 23:00 | 00:00 | 60 | Sleep | Home |
Given that ABMHAP is set to simulate working adults, the results from a ABMHAP simulation are saved in the following files:
\output_directory\data_adult_work.csv\output_directory\trials_adult_work.pkl\output_directory\data_adult_work.pkl
The .csv file contains the activity diary of all of the simulations. The other files are
created for the following reason. Because these runs are capable of simulating large numbers
of agents, in order to save memory space, the results from ABMHAP are saved in a compressed
file format unique to python called "pickle" file format, which is denoted with a
.pkl extension. The saved python objects correspond to
\output_directory\trials_adult_work.pklcontains the input data for each household being simulated. The file contains a list of :class:`trial.Trial` objects.\output_directory\data_adult_work.pklcontains the output data (i.e., the activity diaries) for each household being simulated. The file contains a :class:`driver_result.Driver_Result` object
The following is the documentation of all of the files that are within the ABMHAP code. The code is divided into the following directories:
\source, which handles the key components for ABMHAP\run, which handles code for running ABMHAP with user-defined parameters\run_chad, which handles running ABMHAP as a Monte-Carlo simulation with agents parameterized with empirical data from CHAD\plotting, which handles some plotting capability\processing, which handles parses the data from CHAD
These files are the key modules that are used to create the ABMHAP algorithm.
Contents:
.. toctree:: :maxdepth: 4 activity asset bed bio chad chad_code commute .. config diary eat food home hunger income interrupt interruption location meal my_globals need occupation params person rest scheduler sleep social state temporal transport travel universe work workplace
These are the files needed to run an instance of ABMHAP with one agent parametrized by user-defined parameters.
The driver for these type of runs is main.py.
Contents:
.. toctree:: :maxdepth: 4 main main_params .. output scenario singleton
These are the files needed to run an instance of ABMHAP as a monte-carlo simulation consisting of multiple households of agents parametrized with the data from the Consolidated Human Activity Database (CHAD).
These simulations may be run in parallel.The driver for these type of runs is driver.py.
Contents:
.. toctree:: :maxdepth: 4 analysis .. analysis_sleep analyzer chad_demography chad_demography_adult_non_work chad_demography_adult_work chad_demography_child_school chad_demography_child_young chad_parameter_figures chad_params commute_from_work_trial commute_to_work_trial data_counter driver driver_params driver_result eat_breakfast_trial eat_dinner_trial eat_lunch_trial evaluation fig_driver figure_loader figure_loader_with_without_variation figure_residuals longitude_plot plot_graphs my_debug omni_trial sleep_trial trial variation work_trial
These functions handle plotting capabilities.
Contents:
.. toctree:: :maxdepth: 4 plot_diary plotter
These functions handle the logistics in dealing with CHAD.
Contents:
.. toctree:: :maxdepth: 4 commute_school commute_work count_records datum demographics demography eat_new .. full_save this is for development school_new sleep_new