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:

  1. enrolled in the school,

  2. the school must be open that day, and

  3. 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-type

    name, 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 as Mon for a day_of_week value of 1 and 2pm for an hour value of 14. In both add_to_schedule() and remove_from_schedule(), the day-of-week argument can be Weekdays meaning Monday through Friday, or Weekends meaning Sat and Sun, or Everyday 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 as Mon for a day_of_week value of 1 and 2pm for an hour value of 14.

  • 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 no

    scheduled 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 where ID is the ID of a specific place site, DAYS has a format like Mon for Monday, or Mon-Wed for Monday and Wednesday, or Weekdays, Weekends` or ``Everyday for thse groups of days, and OPEN and CLOSE have the format HH: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.