Chapter 16: Transition Guide for FRED Users

FRED 8 represents a major revision of FRED intended to make the FRED language easier to learn and to make the process of developing models in FRED more convenient for a wider range of tasks.

This Chapter highlights some of the changes that will be especially important to current users of FRED 7 as they convert existing models to FRED 8. The details for all these changes appear in the previous Chapters of this Guide as well as in the Reference pages.

FRED_LIBRARY environmental variable

The FRED Library has been moved from the core FRED distribution to a separate GitHub repository. Epistemix will use this public repository to make available a set of free FRED modules.

A new environmental variable FRED_LIBRARY is used to point to the user’s local copy of the Library. If not defined, it defaults to a small Library within the FRED distribution. Users may add their own modules to their local Library without sharing it with other organizations.

Random Number Stream

FRED 8 uses the Boost random library to generate random number streams and random variates. This means that FRED gives consistent numerical results across all computer platforms and operating systems.

Admin Agents

In addition to ordinary agents and the Meta agent, agents who control specific mixing group are now called group_agents (instead of “admin agents”). See Chapter 2.

Declaring Variables

The FRED variable types have been renamed for consistency and clarity.

  • global is now shared numeric

  • global_list is now shared list

  • personal is now agent numeric

  • personal_list is now agent list

  • table is now shared table

  • list_table is now shared list_table

See Chapter 3.

Initialization

The parameters and restart_parameters blocks have been removed.

Any statements in the startup block are executed by the Meta agent prior to the start of the run. Any Meta agent action is permitted in the startup block, including initializing shared variables and opening output files.

Any statements in the group_startup block are executed by the group agents immediately after the startup block, if any.

Any statements in the agent_startup block are executed by the ordinary agents immediately after the group_startup block, if any.

Upon a restart of a snapshot, the startup block is skipped, and the statements in the restart block are executed by the Meta agent.

See Chapter 5.

Start State

The Start state has been eliminated as a default for each condition. The default for ordinary agents is start_state = Excluded, just like group agents and the Meta agent.

User are encouraged to explicitly include the start state property for each type of agent, for example:

condition COND {
    start_state = Start
    group_start_state = Excluded
    meta_start_state = Meta_Start
}

Factors

Factors have been replaced by read-only variables and several new function. See Chapter 6 for the current set of read-only variables.

Order of Agent Transition Events

For each time step during which any state transition occurs, the order in which agents are updated is:

  • the Meta agent updates in all conditions

  • the group agents update in all conditions

  • the ordinary agents update in all conditions

This is a change from FRED 7 in which each condition was executed in order of (a) Meta agent, (b) group agents, (c) ordinary agents. in FRED 8, the Meta agent updates all of its conditions before any group or ordinary agent.

For example, if you want the Meta agent to expose some agents to a transmissible condition at time 0, then the agents’ susceptibility to that condition needs to be set in the agent_startup block, because the Meta agent will execute its actions at time 0 before any ordinary executes its start state.

Synthetic Population

The default synthetic population for FRED 8 is US_2010.v5. Some differences with FRED 7:

  • the only built-in agent variable that is set for each ordinary agent is its age. All other variables in the synthetic population are optional and must be declared as agent variables to be included in the model.

For example, including the following declarations will read the value sex and race from the files in the synthetic population and add then as agent attributes,

variables {
    agent numeric sex
    agent numeric race
}
  • the only built-in place variables are latitude, longitude, and elevation. All other variables in the synthetic population are optional and must be declared as group agent variables to be included in the model.

For example, including the following declarations will read the value income from the files in the synthetic population and add then as group agent attributes,

place Household {
    has_group_agent = 1
}

variables {
    agent numeric income
}

This says that each household has an associated group agent, and that agents may have an income variable. The synthetic population has an income field for each household, so this variable will be set for each household group agent. An ordinary agent can then access its household income via ask(Household,income).

The household variable income is the only additional place attribute in the default synthetic population.

Bypassing the Synthetic Population

FRED program can bypass the default synthetic population entirely by setting the locations = none property in the simulation block. In this case, no agents or places are defined for the model. Agents and places can be added using the methods in the next section.

Adding Agents and Places

FRED programs may read file containing additional agents and additional places, using the function read_agent_file(filename) and read_place_file(filename). These files contain comma-separated rows corresponding to one agent or one place per row. The files contain a header row that defines each field. Certain fields are predefined, as explained in Chapter 10. If these file contain an identifier in the header row that corresponds to a declared agent variable, then this field will be used to set the variables for each agent corresponding to each row.

With the availability of the functions, the alternative population feature is discontinued.

Default Model

Each synthetic population contains a file called default_model.fred that is automatically included in each FRED program by default. The default model model can be used to:

  • define a set of places available in the synthetic population,

  • define schedules for those places,

  • cause agents to join places,

  • or any other actions that are needed for the synthetic population to operate as intended.

Users can substitute their own default models by setting the property:

simulation {
    default_model = <filename>
}

The following causes the default model to be skipped:

simulation {
    default_model = none
}

If default_model = none but locations is not none then the FRED program will read in the agents in the synthetic population for the indicated location and will use only those places explicitly defined in the FRED program. The program will need to define schedules for all defined places as discussed in Chapter 9.

Printing

The FRED printing functions have been revised and expanding, including the option of printing message to the terminal. See Chapter 10.

Renamed Predicates

  • has_been_closed(place) is now is_temporarily_closed(place)

  • date_range(date1, date2) is now is_date_in_range(date1, date2)

  • is_admin(group) is now is_group_agent(group)

  • is_absent(group) is now is_skipping(group)

New Functions

The following functions have been added (Chapter 7)

  • get_contact_rate(group)

  • get_container(container_type, place_type)

  • get_group_agents(group)

  • get_number_of_transmissibles(group)

  • get_population()

  • get_role()

  • get_same_age_bias(group)

  • get_size()

  • get_transmissibility()

  • read_agent_file(filename)

  • read_group_file(filename)

  • read_place_file(filename)

  • unique(list-expression)

Renamed Functions

The following functions have been renamed

  • admin_id(group) is now get_group_id(group)

  • get_admin_agents(group) is now get_group_agents(group)

  • neg_binomial() is now negative_binomial()

  • state(condition) is now current_state(condition)

Removed Functions

The following functions have been removed:

  • adi_state()

  • adi_national()

  • block_group()

  • census_tract()

  • county()

  • filter()

  • get_other()

  • income()

  • sample_cdf()

  • value()

  • zipcode()

The functions related to geographical regions have been replaced with the more general concept of a container. The synthetic population defines container relationships of places with their surrounding areas.

For example to get the block group if an agent’s household, the agent could do:

my_block_group = get_container(Block_Group, Household)