NetLogo User Community Models
by Lisa Sattenspiel, Jessica Dinka, Erin Miller, Carolyn Orbann (Submitted: 08/18/2017)
# Netlogo version of SAmort model
Version date: June 2014
Authors: Lisa Sattenspiel, Jessica Dimka, Erin Miller, and Becca Lander, University of Missouri Columbia, Department of Anthropology
Dana Schmidt also worked on this model in its early stages, and Carolyn Orbann helped develop the original agent-based model on which this model is based.
The SAmort model is an epidemiological model designed to test hypotheses related to the spread of the 1918 influenza pandemic among residents of a small fishing community in Newfoundland and Labrador. The model community is based on the 1921 census population of St. Anthony, NL, located on the tip of the Northern Peninsula of the island of Newfoundland. Model agents are placed on a map-like grid that consists of houses, two churches, a school, an orphanage, a hospital, and several boats. They engage in daily activities that reflect known ethnographic patterns of behavior in St. Anthony and other similar communities. A pathogen is introduced into the community and then it spreads throughout the population as a consequence of individual agent movements and interactions.
## MODEL INITIALIZATION
During the set-up procedure, the agent and map variable files are read in, the community layout and visualization are established, data output files are created, and variables for recording epidemic data are initialized. The first case (or cases, if desired) are selected. Users may decide whether to select a first case at random or according to certain criteria (e.g. an agent of a particular sex, age or occupation type).
## EXTERNAL INPUT FILES
The model requires the use of two external input files, one to read in essential agent characteristics, and one to read in building characteristics. To facilitate explorations of the impact of population size on epidemic outcomes, we have made a number of different agent files and associated building files corresponding to target population sizes. In making different sized agent populations, households are kept together. Each larger population includes all agents from the smaller population files, with newly added households chosen randomly from among remaining households included in the full population until the target population size is reached. Church membership is adjusted to retain about a 50:50 ratio in all population sizes. Building sizes (other than houses and boats) are also adjusted in proportion to the relative population size so that the population density within the buildings remains relatively constant. Because agents can repeatedly attempt to visit empty houses in small population runs, we eliminated from the building files all houses without any assigned agents. To retain average crew sizes for the boats and the possibility of contact between adjacent boats, we also reduced the number of boats proportionately and reassigned agents if necessary. The numbers of agents assigned to specialized occupations such as doctors, nurses, or teachers, are also, in general, kept proportional to the target population size. Specific agents assigned to these professions may vary across agent files. We always assume that there are two churches, however, so all population sizes include only two pastors.
### AGENT CHARACTERISTICS
Agent definition files (SAmortAgents500NL.txt and other similar files for different population sizes) include the following variables:
1. The first column of this file is the user-determined agent ID.
2. Column 2 is residence; this variable refers to the community in which an agent normally resides (e.g., 1 = St. Anthony). This variable is not used in the model at the present time because only a single community is being modeled. It is designed to facilitate the incorporation of additional communities at a future date.
3. Column 3 is an agent's disease status. Currently this variable is initialized at zero for all agents; the program picks an initial infected or exposed agent (or agents) and resets its disease status accordingly (0=susceptible, 1=exposed, 2=infected, 3=recovered, 4=dead).
4. Column 4 is the dwelling of an agent. This is the agent's home base. It is assigned sequentially based on information in the 1921 St. Anthony census data (but could be set arbitrarily if desired) and the assigned numbers correspond to particular buildings on the model space. For example, individuals assigned to dwelling #35 will use building #35 as their home unless no spaces are available, in which case the program reassigns a new permanent dwelling. Orphans indicated as such in the census are assigned to dwelling #85, which corresponds to the orphanage (building #85); children under age 15 who must be reassigned because of a lack of space in their assigned dwelling are assigned to the orphanage (adult agents are assigned randomly to another house).
5. Column 5 is the household of an agent and is an integer variable that corresponds to the family number to which an agent is assigned. This variable is assigned sequentially based on information in the 1921 St. Anthony census. In the census data, households may include individuals other than family members (e.g., servants, boarders, others living there). Multiple households may share a dwelling.
6. Column 6 designates extended family membership. The variable allows connections between related individuals from different households. Since at this time we have little information on family connections beyond a household listed in the census, in the input data files, ext-family is set at 0 for all agents.
7. Column 7 indicates sex of an agent (0 = male, 1 = female). The assigned sex corresponds to information recorded in the census data.
8. Column 8 designates an agent's age in years.
9. Column 9 designates church membership of an agent. In the input data files, agents are arbitrarily and relatively equally divided by household into two church groups, with the exception that all orphans age 15 and older are assigned to the same church. However, the majority of orphans (all those < age 15) attend Sunday services within the orphanage and are assigned to neither of the other churches.
10. Column 10 corresponds to an agent's relative health status. This variable is designed to take into account different possible influences that may impact an agent's outcome when faced with a potential disease-transmitting contact. At present, this variable can range from -1 to 1, with -1 corresponding to a maximum negative impact (i.e., 100% reduction), 0 corresponding to no impact on health, and 1 corresponding to a maximum positive impact. In the current input data files, health-history is set at 0 for all agents because this is something that will be incorporated into the model later.
11. Column 11 designates an agent's occupation. This variable is user-defined and influences the activity patterns of agents. All agents have been assigned a 3-digit occupation code. The assignment rubric is described in the section on occupation categories.
12. Column 12 designates the ID of the boat associated with an agent's household. All agents in households with some fishermen are assigned the specific boat ID of the family fishing boat, regardless of their occupation. In the case that no agents in a household are involved in fishing (e.g., orphanage workers or a house full of doctors), agents are assigned a boat ID of 999.
### BUILDING CHARACTERISTICS
The present model has seven building types that we have designed to reflect important places in St. Anthony, our study community: houses, orphanages, schools, hospitals, churches, and two boat types (to provide two colors for the boats). The number of buildings of each type is calculated by the program as the community map is initialized. Building definition files (SAmortBldgs500NL.txt and other similar files for different population sizes) include the following variables:
1. Columns 1 and 2 give the coordinates of the lower left hand cell of a building (x-coordinate, then y-coordinate).
2. Columns 3 and 4 give the dimensions of the building (width, then length). NOTE: SCHOOL DIMENSIONS SHOULD BE LARGE ENOUGH TO FIT NOT ONLY ALL CHILDREN ASSIGNED TO A SCHOOL, BUT ALSO ALL THE TEACHERS.
3. Column 5 is the building ID, assigned by the user. NOTE: THE BUILDING IDS OF THE BOATS MUST CORRESPOND TO THE BOAT ID GIVEN TO THE AGENTS (column 12 of the agent files).
4. Column 6 designates the building type (house=1, orphanage=2, school=3, hospital=4, church=5, boat type 1 = 6, boat type 2 = 7).
## ESSENTIAL PARAMETERS
The model consists of a number of sliders that can be used to adjust the values of essential parameters. At the present time all parameters are set at constant values. Eventually some parameters other than run length and population size may be modeled using a probability distribution rather than constant values. The slider variables include the following:
1. Length of latent period: This is the number of time ticks that an agent remains in the exposed category. The slider is set up to range from 0 to 60 ticks (0 to 10 days in the present model). A reasonable baseline value of 6 ticks (1 day) was derived from an assessment of various values published in the influenza literature (e.g., Mills et al. 2004, Cori et al. 2012).
2. Length of infectious period: This is the number of time ticks that an agent remains infectious. This slider is also set up to range from 0 to 60 ticks (0 to 10 days in the present model). A baseline value of 18 ticks (3 days) was derived from an assessment of various values published in the influenza literature (e.g., Mills et al. 2004, Cori et al. 2012).
3. Transmission probability: This slider is set up to range between 0 and 1 and corresponds to the probability of transmission when a contact occurs between susceptible and infectious agents. A baseline value of 0.042 was chosen to achieve a target attack rate of 55% prevalence for simulation runs, as suggested for the 1918 influenza epidemic by Ferguson et al. (2004).
4. Probability of death: This slider also ranges from 0 to 1 and corresponds to the probability of death per tick. Death can only occur in the model during the infectious period. The baseline estimate of the death probability was derived by setting the observed case fatality rate (cfr) equal to (1- (1 - d)^i), where d is equal to the probability of death per tick and i is the length of the infectious period in ticks. The quantity (1-d)^i gives the overall probability of NOT dying throughout the period of risk. When this value is subtracted from 1 it gives the cfr (overall probability that an infected individual dies at some time during the infectious period). The equation is then solved for d to give the desired probability of dying PER TICK. For example, the observed death rate in Newfoundland during the 1918 flu was about 7.5 per thousand people. Using the attack rate of 55% estimated by Ferguson, et al. (2004), this converts to a cfr of 13.6 deaths per thousand cases (or 0.0136). So, assuming an infectious period of 18 ticks (3 days), 1 - (1 - d)^18 = 0.0136. The solution to this equation gives a per tick probability of death of 0.00076. NOTE: the model at present assumes that an agent is at risk of dying only when it is infectious and that the risk is equal for each tick it is infectious.
5. Church density: This parameter allows the user to adjust the packing in the church to better model heterogeneity in attendance at different times. A value of 1 means that every cell in the church can be occupied during a service; smaller values indicate the maximum proportion of seats taken up. At present, the model assumes that both churches have the same density of occupants; users who wish to change this would need to add church-specific parameters for the density.
6. Run length: This is the number of time ticks the simulation will be run.
All occupations have been assigned a 3-digit number. The first digit corresponds to the general type of occupation (designated the occ-type); the other two digits identify individual groups within that general occ-type in some way. Agents are assigned to different occupations primarily on the basis of age and sex, but information found in archival records is also used. The overall classification is as follows:
0xx (occ-type 0) -- female with only school-aged children, at least some of whom are under age 10. They are associated with a male fisherman in boat xx and are assigned to the same boat as their associated male. They behave like 2xx females on weekdays, but like 7xx females on weekends.
1xx (occ-type 1) -- male fisherman; xx refers to the particular boat to which the agent is assigned. The full complement of agents is distributed into 23 boats; smaller population sizes incorporate a reduced number of actively used boats. Surname and/or proximity in the census data were used to assign agents to boats. Ethnographic data suggest that 4-8 men would cooperate for fishing purposes, so that was the target range for the number of men assigned to a particular boat.
2xx (occ-type 2) -- female associated with a male fisherman in boat xx. Agents in this category live in a fisherman's household and may include wives who only have children over age 10, unmarried daughters older than school age, or other adult females with no or grown children. Census data indicate that about 40 St. Anthony females were involved in the fishing activities in some way. All females fitting the criteria above who are not otherwise occupied (e.g., nurse, teacher, servant, or mother's helper) are assigned to this category. These females are not assumed to engage in fishing activities every day; thus, they move to the boats with some probability less than 1 (as specified in the code by the user). Other options during fishing time periods are staying at home or visiting other households.
3xx (occ-type 3) -- clergy and teachers. The census lists 3 clergy and 2 teachers, but since we only have modeled 2 churches, we have designated only 2 clergy, both of whom are male. These men have been given an occupational ID of 311, with the middle digit indicating their status as religious leaders. One of the men is assigned to church 1, the other to church 2. During the week, both function as teachers at the school. One pastor is explicitly noted in the census data, the other was chosen on the basis of age (50+) and status as a boarder. We also chose additional teachers from among unmarried women in their 20s (total number of teachers based on population size). These women are assigned an occupational ID of 321. For now, we are assigning all pastors and teachers to school #1 since that is the only school we have. If, or when, we decide to add a second school, e.g., a high school, then we can change some of the occupational codes so that the third digit corresponds to the school at which the agent teaches.
4xx (occ-type 4) -- medical. Two known doctors (Grenfell and Curtis) were listed in the census; in addition, historical evidence indicates that Grenfell would recruit young medical students from the US and other places to assist in his medical mission. These students would board with local families. Males fitting these criteria (i.e., young male boarders) were preferentially assigned to be doctors if they were among the agents chosen for a population sample of a particular size. Doctors and med students were assigned an occupational ID of 411. Some young, unmarried women were designated to be nurses; these individuals were given an occupational ID of 421. The total number of doctors and nurses was adjusted as population size changed so that a fairly constant ratio of medical personnel to general population was retained.
5xx (occ-type 5) -- associated with orphanage, not including school-aged kids. This group consists of four different subgroups: a) probable caretakers who lived outside the orphanage (evidence from historical sources indicates this status) -- code 551, b) orphans older than 15; almost all female - ethnographic evidence suggests they stayed at the orphanage to develop "homemaking" and other kinds of useful skills until they married or moved elsewhere -- code 561, c) children under 5 - too young for the school, assumed to stay at the orphanage under the care of the older girls -- code 561, d) industrial worker - designation given to last person listed in census; we do not know what this refers to exactly, so we assumed it involved activities at the orphanage training the older girls -- code 571.
6xx (occ-type 6) -- servants. All servants were indicated as such in the census; all except one were associated with a fisherman's household. These servants were given an occupational ID of 6xx, where xx is the boat number of the household. The remaining servant was at the end of the census and was placed in a group with Dr. Curtis, a nurse, and the industrial worker. We assigned this servant an occupational ID of 671 to distinguish her from the other servants. NOTE: In Newfoundland and Labrador the word servant could refer to individuals indentured to others for various types of labor, although in the model, because of the small number of servants in the census data, we have assumed that all of them were household servants.
7xx (occ-type 7) -- female caretakers with at least one child under age 5; usually wives of fishermen. Also includes one single mother living in a dwelling that includes another household. The last two digits of the ID correspond to the household's assigned boat. Agents in this category move together every day with individuals in category 9xx who have the same xx assignment and household; school-aged children and fishermen from that household may also move with them under the appropriate conditions (e.g., church or Sunday visiting).
8xx (occ-type 8) -- school-aged children (aged 5-15). All school-aged children are assigned an occupational ID of 8xx. The xx indicates the fishing boat of their household, if it is a fishing household. School-aged orphans are assigned an occupational ID of 861, corresponding to the 561 of the non-school-aged orphanage children; the xx of school-aged children in non-fishing households corresponds to the xx in the occupational code of the head of that household.
9xx (occ-type 9) -- this category includes preschool-aged children, unmarried daughters older than school age, sisters or sisters-in-law, and mothers or mothers-in-law of 7xx women; all of these category 9 agents live in the household of the associated 7xx woman. Adult females are given this code only if the number of small children in the family is large (under the assumption that they would help out with child care). The last two digits of the ID for individuals in this category corresponds to the xx in the occupational code of the head of that household.
## STEP-DEPENDENT PROCEDURES
The general structure of the go procedure follows. The information in quotes at the end of each component gives the section in which more information can be found.
1. a randomly chosen turtle determines the daily time block corresponding to the current tick of the model ("schedule");
The program is set up for six time ticks per day with each time tick 4 hours long. A series of statements using the variable timekeeper sets up a schedule within which agent activities will occur. A day is divided into the following time slots: 6-10am, 10am-2pm, 2-6pm, 6-10pm, 10pm-2am, and 2-6am. Values of timekeeper between 1 and 6 correspond to these 6 slots (in the order listed) on Mondays through Fridays; values of timekeeper between 7 and 12 correspond to these 6 slots on Saturdays; values of timeKeeper between 13 and 18 correspond to these 6 slots on Sundays.
The findDaysActivities method sends an agent to the proper activities for the specific time tick indicated by the timekeeper variable (and designated by the specific do…acts method for that time tick). Although there are 6 time slots per day, we do not include the last two for each day since no activity is occurring during those times in the present model (eventually at least some medical personnel may be active at night).
The model contains a specific do…acts method for each of the time slots other than 10pm-2am and 2am-6am (when agents are assumed to sleep). These methods specify particular behaviors for agents based on their occ-type and sometimes specific occupation. These particular behaviors all involve some type of move method. The model contains 6 different basic move methods: move-home, move-school, move-hospital, move-orphanage, move-boat, move-Sunday, and a number of sub-methods required to complete those basic movements. The movement of occ-type 9 individuals is generally governed by the primary caretaker in the household, typically a female assigned to occ-type 7; other agents sometimes move on their own and sometimes move as part of a family group (see code for individual methods).
###DISEASE RELATED PROCEDURES
The underlying disease transmission model in this simulation is an SEIR epidemic process. All agents begin the simulation in the susceptible state, and then the status of one randomly chosen agent is set to "exposed". The specification of multiple initial infected individuals or specific types of initial cases can be made through simple adjustments of the "infect-first-case" method. Consistent with the SEIR epidemic process, exposed agents convert to the infectious state after a user-specified latent period, which they remain in until recovery (after a user-specified infectious period) or death (which occurs with a user-specified probability during each tick of the infectious period). Immunity is permanent upon recovery. The "update-disease-status" method governs this series of transitions.
Disease transmission can occur between susceptible-infectious pairs of agents that are adjacent to each other on the grid. Agents are considered to be adjacent if they are von Neumann neighbors, i.e., those to the north, south, east, or west. When an agent moves it checks its own disease status as well as that of its neighbors. If a moving agent is susceptible, it calls the method "transmit-from" for all infectious neighbors; if it is infectious, it calls "transmit-to" for all susceptibles. In both cases, transmission is determined by comparing the user-specified transmission probability to a randomly chosen number between 0 and 1. If transmission occurs, the status of the susceptible agent(s) is set to "exposed" and the clock for the disease process begins.
Death of an agent -- agents have a set probability of dying at each tick of the infectious period. Upon death, a ghost (a different turtle breed) with the same agent characteristics as the dying agent is made and data about where and when the agent died are collected. The agents move to a "cemetery" (lower left-hand corner of the grid); the ghosts remain at the location of death. Users can control whether the ghosts are visible or hidden. Each dying agent also takes the shape of a ghost, with the size proportional to the number of agents that have died. Thus, the ghost that appears in the cemetery gets larger as the epidemic progresses.
Reassigning occupation -- any dying caretakers must arrange for another adult member of the household to become the new caretaker for dependent children. If the new caretaker is a male who becomes responsible for preschool-aged children, he becomes a stay-at-home-dad. He retains his fisherman occupation, but does not go to the boats as long as he continues to be responsible for children under age 5. If no suitable caretaker replacement is identified, children are sent to the orphanage. Any dying children with a stay-at-home-dad (SAHD) need to determine whether they have surviving siblings under age 5 and if not, arrange for their SAHD to return to previous activities, e.g. fishing. Female caretakers retain their existing status throughout the rest of the simulation, even if all children die. Dying agents who are engaged in critical occupations (e.g., teachers, pastors, etc.) are also replaced by appropriate agents. The choice of replacement for a dying agent is governed by specific criteria determined by the occupation/status of both the dying agent and the potential replacement. See specific "choose…" and "find-poss…" methods for details. If no suitable replacement for critical occupations is found, no replacement is made and a statement to that effect is printed to the console. After a replacement is specified, occupation, occ-type, dwelling, and other relevant variables are adjusted as needed to reflect the new role of the agent.
###DISPLAY AND OUTPUT PROCEDURES
As the simulation proceeds, a graph showing the numbers of susceptible, exposed, infectious, recovered, and dead agents is created and updated each tick. In addition, three csv (comma-delimited) output files are produced (CasesData.csv, DailyData.csv, and FinalData.csv). In each file, run numbers, global parameters (e.g. transmission probability), and attributes of the first case are always recorded. The “Cases” file also records, for all individuals in the model population, the place and time the individual was infected (the default value of -1 is recorded if the individual escapes the simulated epidemic), and if applicable, the place and time it died as well as characteristics of the agent that infected this individual. The “Daily” file records the number of individuals in each disease status at each tick of the simulation and keeps track of the number of agents that are newly infected and newly dead. The “Final” file records the total number of individuals in each disease status at the end of the simulation, the total number of individuals ever infected [RD], and a count to verify all members of the model community were either susceptible or removed (recovered or dead) [SRD]. This last count provides an easy way to determine that the simulated epidemic finished in the allotted time; in that case the count will equal the total population size.
Cori A, Valleron AJ, Carrat F, Scalia Tomba G, Thomas G, Boëlle PY (2012) Estimating
Ferguson NM, Cummings DAT, Cauchemez S, Fraser C, Riley S, Meeyai A, Iamsirithaworn S,
Mills CE, Robins JM, Lipsitch M (2004) Transmissibility of 1918 pandemic influenza. Nature 432:904–906
##PAPERS USING THE MODEL
Dimka, Jessica, Carolyn Orbann, and Lisa Sattenspiel (2014) Applications of agent-based modeling techniques to studies of historical epidemics: the 1918 flu in Newfoundland and Labrador. Journal of the Canadian Historical Association, New Series 25(2):265-296.
Sattenspiel, Lisa, Erin Miller, Jessica Dimka, Carolyn Orbann, and Amy Warren (2016) Epidemic models with and without mortality: when does it matter? In Mathematical and Statistical Modeling for Emerging and Re-emerging Infectious Diseases, Gerardo Chowell and James M Hyman (eds.) Switzerland: Springer International, pp. 313-327. http://dx.doi.org/10.1007/978-3-319-40413_2.
Orbann, Carolyn, Lisa Sattenspiel, Jessica Dimka, and Erin Miller (2017) Defining epidemics in computer simulation models: how do definitions influence conclusions? Epidemics 19:24-32. http://dx.doi.org/10.1016/j.epidem.2016.12.001
Orbann, Carolyn, Lisa Sattenspiel, Jessica Dimka, and Erin Miller (2014) Agent-based modeling and the second epidemiological transition. In Modern Environments and Human Health: Revisiting the Second Epidemiologic Transition, Molly K Zuckerman (ed). Hoboken, NJ: Wiley-Blackwell, pp. 105-122.
The code for this model was adapted from a Repast model developed by Lisa Sattenspiel, Carolyn Orbann, Jessica Dimka, and Erin Miller at the University of Missouri. The code for reading in the external tab-delimited files that contain building and agent characteristics was modified from code written by Uri Wilensky and submitted to Netlogo's model library. He has waived all copyright and related or neighboring rights to the sample code.
(back to the NetLogo User Community Models)