Chapter 9: Mixing Groups
FRED agents interact with each other in mixing groups. Examples of mixing groups include households, schools, workplaces, and friendship networks. Some mixing groups represent specific locations (household, schools) and some do not (friendship networks). This chapter deals with places, which are mixing groups that have a specific geo-location, and networks, which represent relationships among agents but are not associated with a specific location.
Declaring a Mixing Group
To declare a mixing group in FRED, use one of the following statement blocks:
place <place_name> { ... }
network <network_name> { ... }
The code within the brackets defined the properties of mixing groups of the named type. The convention is to use a capitalized, singular name such as School or Workplace. For example, a model may include a new class of places representing pharmacies by including a place block as follows:
place Pharmacy { ... }
Places
Places are mixing groups that have a specific geo-location (latitude, longitude, elevation) as well as other properties. The user can declare any number places in FRED. Each place definition represents a class of individual locations, called sites.
The complete set of properties for a place is shown below. Each property has a default value as shown, so when defining a type of Place in a FRED model, you only need to set properties that do not use the default values. The order of the properties does not matter unless explicitly mentioned below.
place <place_name> {
# Administrative Properties
has_group_agent = 0
# Transmission Properties
contact_prob = 0
contact_rate = 0
same_age_bias = 0
contact_prob_for_condition_name> = -1
contact_rate_for_<condition_name> = -1
same_age_bias_for_<condition_name> = -1
}
The properties fall into two categories:
The Administrative property:
has_group_agent
generates a group agent for each site if set.Transmission properties concern the spread of conditions from one agent to another within the type of mixing group. Transmission Properties are described in Chapter 13.
Places in Synthetic Populations
A synthetic population may define a set of places that are available to any model using that synthetic population. The default synthetic population includes these places:
place Household { ... }
place School { ... }
place Grade { ... }
place Workplace { ... }
place Block_Group { ... }
place Census_Tract { ... }
place County { ... }
place State { ... }
place Prison { ... }
place Nursing_Home { ... }
place College_Dorm { ... }
place Barracks { ... }
Other places can be added by the user.
By default, all of the initial agents are assigned membership in the appropriate default places according to the input files in the synthetic population. These input files gives the latitude, longitude, and elevation of each site associated with each type of place. Not all agents are members of all places, for example, students are members of a school but are not usually members of a workplace. Membership in user-defined places is controlled by the rules of the model.
User-Defined places
A model can define a new place by adding a place block of the form:
place <place_name> { ... }
where <place_name>
is the name of the class of places.
There are two ways to set the location of sites for user-defined places:
Creating new sites by the Meta agent
Reading sites from an external file
Creating sites
The Meta agent can generate new sites by executing the action add_site
:
add_site(<place_name>, <id_expression>, <latitude_expression>, <longitude_expression>, <elevation_expression>)
This action add a new site to the named place with id
,
latitude
, longitude
, and elevation
set to be the values of
the last four expressions in the argument list. If the id
is 0,
a unique site id of the new site is generated by FRED.
Reading sites from a file
The Meta agent can read sites from a file using the fnction
read_place_file
:
read_place_file(<file_name>,<place_name>)
For example, if the model had defined a place type called Pharmacy
as above, then the Meta agent could call
read_place_file(pharmacy.txt, Pharmacy)
to generate pharmacy
sites.
The place input file is a comma-separated text file with a header
line. FRED parses the header line to identify fields of interest,
which must include one fields labeled ID
. Other fields can be used
to define additional variables for the sites. The column labeled
ID
defines the place ID for each site. If the ID
field in a
given row is, say, 12345
, and if no existing group already has
that ID, then a new site will be generated with that ID. If any
existing place of the given type already has that ID, then any
additional properties read from the file will apply to the existing
place. If there is an existing group of another type that has the same
ID, then FRED will abort with an error message. Finally, if the
ID
field has the value 0
, then a unique place ID will be
generated and a new site created.
If there are other fields in the input file and if the header of a field corresponds to the name of an agent variable in the model, then the value of that agent variable will be set to the value of the corresponding field in the file. For example, suppose the model declares an agent variable as follows:
variables {
agent numeric pharmacists
}
Suppose further that the model declares a Pharmacy place type:
place Pharmacy {
has_group_agent = 1
}
And suppose the file pharmacy.txt contains the lines
ID, pharmacists, zipcode
123, 3, 15236
456, 5, 15243
0, 10, 15243
Then the statement
read_place_file(pharmacy.txt, Pharmacy)
would generate three sites for Pharmacy
with IDs 123
, 456
,
and a unique ID something like 70000001
, assuming the that first
two IDs do not clash with any existing group ID. The three pharmacies
would be assign values for their pharmacists
variable of 3
,
5
, and 10
respectively. The zipcode
field would be
ignored, unless zipcode
were also declared as an agent numeric
variable.
Note
FRED searches for the indicated file through the list of directories
defined in the environmental variable FRED_PATH
. Environmental
variables can be set in your .bashrc file or other shell startup
script (.zshrc for Mac users), for example:
export FRED_PATH=".:${HOME}/FRED_PROJECTS/project1:${HOME}/FRED_PROJECTS/project2"
With the settings above, FRED will search for the filename.txt file
first in the current working directory, followed by
${HOME}/FRED_PROJECTS/project1
and then
${HOME}/FRED_PROJECTS/project2
, where $HOME
is the user’s home
directory.
If the FRED_PATH
environmental variable is not set, FRED searches
for the file in the current working directory.
Place Schedules
Agents can only be at one place at a time. In contrast, by default agents may participate in any number of networks at the same time. (Of course, specific models may restrict the participation in network to specific time by including rules that enforce this.)
For an agent to interact with others in a given place at a given time, three requirements must be satisfied:
The agent must be a member of the place.
The place must be open for business.
The agent must be present in the place.
As an example of how to think about this, consider students in schools. In order to attend a school on a given day, the student must be:
enrolled in the school,
the school must be open that day, and
the student must not be skipping that day.
Agents can become a member of a place in a two ways:
The agent can be assigned to a given place by the synthetic population files.
- The agent can become a member of a place as the result of a
join()
action.
Once an agent is a member of a place, the agent is considered to be attending the place during any time that the place is schedule to be open. The times during which a place is open are controoled in three ways:
The FRED program can read the schedule from a file.
The Meta agent can alter the schedule for any place.
The group agent can alter the schedule for its specific site.
The group agent can temporariliy close its place via an action.
changing a place’s schedule
The following actions are used to define place schedules within FRED models:
Actions by the Meta agent:
clear_schedule(expression)
If the expression is a place-typename, this clears the schedule for the named place type. This means that the place type has no scheduled hours of operation. If the expresssion evaluates to an individual place ID, the schedule is cleared just for that place.
add_to_schedule(expression, day-of-week, start-hour, start-minute, end-hour, end-min)
: if the expression is a a place-type name, the place type schedule is changed to be open on the given day of the week, starting at the start-hour and start-minute, and ending just prior to the end-hour and end-minute. If the expression evaluates to an individual place ID, the schedule is changed just for the specific place. The hours must evaluate to 0 .. 23 and the minutes must evaluate to 0..59. Symbolic aliases are recognized, such asMon
for aday_of_week
value of1
and2pm
for anhour
value of14
. In bothadd_to_schedule()
andremove_from_schedule()
, theday-of-week
argument can beWeekdays
meaning Monday through Friday, orWeekends
meaning Sat and Sun, orEveryday
meaning every day of the week.remove_from_schedule(expression, day-of-week, start-hour, start-minute, end-hour, end-min)
: if the expression is a a place-type name, the place type schedule is changed by removing from the the open time the period on the given day of the week, starting at the start-hour and start-minute, and ending just prior to the end-hour and end-minute. If the expression evaluates to an individual place ID, the schedule is changed just for the specific place. The hours must evaluate to 0 .. 23 and the minutes must evaluate to 0..59. Symbolic aliases are recognized, such asMon
for aday_of_week
value of1
and2pm
for anhour
value of14
.reset_schedule(place-ID)
: removes the individualized schedule from the given place, reverting its schedule to that of its place type.
The group agent for a place may call the same actions as above, except that the schedule changes only apply to the group agent’s specific place site:
clear_schedule()
the group agent’s place is changed to have noscheduled hours of operation.
add_to_schedule(day-of-week, start-hour, start-minute, end-hour, end-min)
: the schedule for the group agent’s place is changed to be open on the given day of the week, starting at the start-hour and start-minute, and ending just prior to the end-hour and end-minute.remove_from_schedule(day-of-week, start-hour, start-minute, end-hour, end-min)
: the schedule for the group agent’s place is changed by removing from the the open time the period on the given day of the week, starting at the start-hour and start-minute, and ending just prior to the end-hour and end-minute.reset_schedule()
: removes the individualized schedule from the group agent’s specific place, reverting its schedule to that of its place type.
The default_model
in the synthetic population includes scheduling
actions that define a default daily schedule for agents. For example,
an agent that is a student has the following schedule on weekdays:
6am-8am: interact with members of the household.
9am-11am: interact with members of the same grade.
1pm-3pm: interact with members of the same school.
4pm-5pm: interact with members of the same census block group.
5pm-6pm: interact with members of the same census tract.
6pm-7pm: interact with members of the same county.
The default weekend schedule is the same except that school activities do not occur and the community activities are extended to a three hour period (50% more than on weekdays) by adding a one hour period of interaction with members of the same census block group.
reading schedule changes from a file
The Meta agent can call an action to read schedule changes from a file:
read_schedule_file(filename)
: read in a file which each line has the format:ID,DAYS,OPEN,CLOSE
whereID
is the ID of a specific place site,DAYS
has a format likeMon
for Monday, orMon-Wed
for Monday and Wednesday, orWeekdays
,Weekends` or ``Everyday
for thse groups of days, andOPEN
andCLOSE
have the formatHH:MM
of hour and minute using a 24-hour clock. The specific place schedule is changed to add the indicate times and days to the schedule.
skipping or attending a place
By default, an agent is present in any of its membership places whenever
that place is open. However, agents may decide to temporaily skip
attending a place by taking the action skip(place)
. This action
suspends the agent from participating in the place until the agent
takes an action attend(place)
within the same condition as the
skip()
action.
More details are discussed in chapter 10.
temporary closures
To handle dynamic place closures (e.g. temporary school closures), you may assign a group agent to each group.
has_group_agent = 1 # default = 0
The group agent can close a place by executing a close()
action which
results in the place being temporarily closed, until the group agent
performs a reopen()
action in the same condition as the
close()
action.
More details are discussed in chapter 10).
Containers
Places may be contained within other places. For example, a classroom may be contained within a school.
Containers are defined by the synthetic population
container_metadata.txt
file, which in turns lists all the
place-container files included in the synthetic population.
For example, in the default synthetic population, schools are located
within a specific zip code. The
synthetic population includes a file called school-zipcode.txt
that contains the following lines for one county:
PLACE,CONTAINER
450111632,15851
450110845,15825
450057407,15746
450132458,15767
450066817,15701
450151186,15747
...
Each place ID in the first column represents a specific school, and each value in the second columm represents a zip code. Each place site may have at most one container of any given place type. For example, a school may be contained in only one zip code.
Within a model, agents can access container information by the following function:
get_container(container, place)
: returns the place ID of the container of the type in the first argument that contains the agent’s place of the type in the second argument.
That is, get_container(County, Household)
will return the ID of
the County that contains the agent’s Household. The function follows
the container relationships, so if Households are contained in a
Census_Tracts and a Census_Tracts are contained in a County, then the
function call above will return the specific County that contains the
agent’s Household.
The function returns -1
if there is no such container or if the
agent has no such place.
Places and their containers generally have distinct schedules, that is, times they are “open for business”. However, if a group agent executes a temporary closure on its place, then any places contained within the temporarily closed place are also temporarily closed. For example, closing a school causes all classrooms within the school to be temporarily closed.
Networks
Networks are mixing groups that do not have a specific geo-location. Networks differ fundamentally from places in that all the people who share a given place at a given time are assumed to interact with each other uniformly (except for a possible bias to interact with people of a similar age), whereas people interact in a given network only with other people to whom they are explicitly linked. Networks in FRED can be used to represent network relationships such as friendships, sexual partners, buyers/sellers, health care providers/patients, and other relationships.
The user can declare any number of networks in FRED, and each network has a set of properties that determine how agents interact within that network. Networks are declared by a code block of the form:
network <network_name> {
# STRUCTURAL PROPERTY
is_directed = 1
# ADMINISTRATIVE PROPERTY
has_group_agent = 0
# OUTPUT PROPERTY
output_interval = 0
}
Network output is described in the SIMS Guide.
Note
Unlike a <place_name>
that is generally associated with many
sites, each <network_name>
is associated with exactly one network.
Networks in FRED may contain several connected components; that is,
there may not be a path between every pair of individuals in a network.
In general, individuals are linked to a subset of the other members of
the network. Networks may be undirected or directed. There are no
built-in networks, but transmissible conditions can generate
transmissible conditions by setting the transmission_network
property.
If an edge is added, both agents identified in each edge become members of the network if they are not already members.