-
Notifications
You must be signed in to change notification settings - Fork 34
Parameters
parameter: days
default value: 240
type: INT
definition:
The number of days in a single simulation run. FRED runs for the given
number of days regardless of the epidemic state (that is, FRED does not
stop early if no one is currently infected.)
parameter: start_date
default value: 2012-01-02
type: STRING
definition:
The value used as the start date for each simulation run. The format is
YYYY-MM-DD.
parameter: seed
default value: 123456
type: INT
definition:
The seed for the random number generator. The seed values for all runs
of the simulation are based on the initial seed and the run number, and
are independent of the number of random numbers generated in other runs.
The user should not normally have to change the seed value.
parameter: verbose
default value: 1
type: INT
definition:
If set, print information for monitoring system progress to the LOG
file. Higher values produce more (probably too much) output.
parameter: debug
default value: 0
type: INT
definition:
If set, print verbose debugging output to stdout. Higher values produce
more output.
parameter: outdir
default value: OUT
type: STRING
definition:
The directory containing the output files. If the string beings with "/"
it is interpreted as an absolute path. If it begins with "$FRED_HOME/",
it is relative the ${FRED_HOME} directory. Otherwise, it is relative to
the current working directory.
parameter: quality_control
default value: 1
type: INT
definition:
If set, information about the size and age distribution for the various
types of places is printed out in the Log file.
parameter: report_age_of_infection
default value: 0
type: INT
definition:
If set, the output file includes info on daily incidence by age groups. You get
different info depending on the value of the parameter.
report_age_of_infection = 1
The output includes variables giving the daily incidence counts for the
following age groups (not including the upper bounds):
Infants: 0.0 - 0.5 yrs
Toddlers: 0.5 - 2.0
Pre_School: 2 - 6
Elementary 6 - 12
High_School: 12 - 18
Young_Adults: 18 - 21
Adults: 21 - 65
Elderly: 65 - 120
report_age_of_infection = 2
A slightly different set of age groups:
Infants: 0.0 - 1.5 yrs
Toddlers: 1.5 - 2.0
Pre_School: 2 - 5
Elementary 5 - 12
High_School: 12 - 18
Young_Adults: 18 - 21
Adults: 21 - 65
Elderly: 65 - 120
report_age_of_infection = 3
The output will include variables
A0, A1, ..., A120
which give the daily counts for new infections in people in each yearly
age group, and also variables
Age0, Age1, ... Age120
which give the daily counts per 100,000 people in each yearly age group.
parameter: report_place_of_infection
default value: 0
type: INT
definition:
If set to 1, the output file contains the daily incidence count by place
of infection, including the following:
X: number of people externally infected (seeds).
H: number of people infected in households.
Nbr: number of people infected in neighborhoods.
Sch: number of people infected in schools.
Cls: number of people infected in classrooms.
Wrk: number of people infected in workplaces.
Off: number of people infected in offices.
Hosp: number of people infected in hospitals.
parameter: report_generation time
default value: 0
type: INT
definition:
If set to 1, the output file contains the mean generation time for all
infections occurring on the given day. The generation time (or serial
interval) is defined as the number of days between the infection of the
infector and the current infectee.
The output variable for gneration time is "Tg".
parameter: report_serial_interval
default value: 0
type: INT
definition:
If set to 1, the output file contains the mean generation time for all
infections occurring on the given day. The generation time (or serial
interval) is defined as the number of days between the infection of the
infector and the current infectee.
The output variable for gneration time is "Tg".
parameter: report_incidence_by_county
default value: 0
type: INT
definition:
If set, the output file contains a daily report of incidence based on
the household of each infected person. The output variable is
"County_NNNNN", where NNNNN is the five digit FIPS code for the county.
For example, County_42003 for the incidence of Allegheny County, PA.
parameter: track_infection_events
default value: 0
type: INT
definition:
If set, then a file called infections<n>.txt is created for run <n>.
This file contains one line per transmission event, showing the
id of the infector, the infectee, and various other information. The
format for the infections file is:
DAY DISEASE_ID HOST_ID HOST_AGE INFECTOR_ID INFECTOR_AGE PLACE_ID
If track_infection_events > 1, additional data is written on each line.
For further details, see: Infection.cc.
parameter: enable_visualization_layer
default value: 0
type: INT
definition:
If set, create files that contain data for maps and movies. This adds
additional overhead in runtime, so it is off by default.
parameter: household_visualization_mode
default value: 0
type: INT
definition:
If set to 1, create files containing household level data showing the
location of each household with residents in each epidemic state, for
each simulation day. This data can be used for making maps and movies.
parameter: census_tract_visualization_mode
default value: 0
type: INT
definition:
If set to 1, create files containing census-tract level data showing the
counts of residents in each epidemic state, for each simulation day.
This data can be used for making maps and movies.
parameter: visualization_grid_size
default value: 250
type: INT
definition:
Maximum rows or columns in visualization grid.
The following parameters select the location that FRED simulates.
parameter: synthetic_population_id
default value: 2010_ver1_42003
type: STRING
definition:
The synthetic_population_id parameter is the default determinant of the
population files used in FRED. The default value corresponds to
Allegheny County Population (RTI 2010 Synthetic Population, Ver 1).
For convenience, the parameters "fips", "city", "county", and "state",
if set, will override the default, in that order of precedence. That
is, a specified FIPS code overrides a city name, which overrides county
and so on. In all cases, the name is ultimately transformed into a FIPS
code.
parameter: fips
default value: none
type: STRING
definition:
If set, has highest precedence and overrides city, state and county. See
explanation below. The synthetic_population_id parameter is the default
determinant of the population files used in FRED. The parameters
"fips", "city", "county", and "state", if set, will override the
default, in that order of precedence. That is, a FIPS code overrides a
city name, which overrides county and so on. In all cases, the name is
ultimately transformed into a FIPS code.
Example:
fips = 42003
**For a complete list of recognized fips codes, see the file
FRED/input_files/countries/usa/fips_county_state.txt
parameter: city
default value: none
type: STRING
definition:
If set, overrides state and county. Format is "name state_abbreviation".
The synthetic_population_id parameter is the default determinant of the
population files used in FRED. The parameters "fips", "city", "county",
and "state", if set, will override the default, in that order of
precedence. That is, a FIPS code overrides a city name, which overrides
county and so on. In all cases, the name is ultimately transformed into
a FIPS code.
Example:
city = Pittsburgh PA
parameter: county
default value: none
type: STRING
definition:
If set, overrides state. Format is "name state_abbreviation". The
synthetic_population_id parameter is the default determinant of the
population files used in FRED. The parameters "fips", "city", "county",
and "state", if set, will override the default, in that order of
precedence. That is, a FIPS code overrides a city name, which overrides
county and so on. In all cases, the name is ultimately transformed into
a FIPS code.
Example:
county = Allegheny County, PA
parameter: state
default value: none
type: STRING
**
definition:**
The state format can be the state name or abbreviation, such as:
state = New York
or
state = NY
parameter: use_mean_latitude
default value: 1
type: INT
definition:
If use_mean_latitude = 1, then the mean latitude in the households file
is used for the planar projection from (longitude,latitude) to (x,y)
coordinates. This is recommended.
If set to 0, then the mean US latitude is used.
parameter: regional_patch_size
default value: 20.0
type: REAL
definition:
Size of regional grid patches in km.
FRED represents geography as a hierarchy of fixed square grids. There
are three layers in the hierarchy, the Global grid, the Regional grid
and the Neighborhood grid.
The Regional Grid consists of 20km x 20km cells by default. The Regional
Grid is aligned to the global geo-coordinate system. Cells in the
Regional Grid store the population count for the cell, along with a
vector of all persons residing in that cell. The Regional Grid can also
be used to store climate or other environmental profiles.
parameter: neigborhood_patch_size
default value: 1.0
type: REAL
definition:
Size of local neighborhood patches in km.
FRED represents geography as a hierarchy of fixed square grids. There
are three layers in the hierarchy, the Global grid, the Regional grid
and the Neighborhood grid.
The Neighborhood grid consists of 1km x 1km cells by default. These
cells contain neighborhood units, and store information about the
preferred schools and workplaces attended by people living with the
cells. This information is used when agents need to change schools, or
leave school and start to work.
The following parameters control overnight travel in FRED.
parameter: enable_travel
default value: 0
type: INT
definition:
If non-zero, enable long-distance overnight travel.
parameter: travel_duration
default value: 9 0 0.2 0.4 0.6 0.67 0.74 0.81 0.9 1.0
type: VECTOR CDF
definition:
Distribution of trip duration in days.
The default values corresponds to the following probabilities:
Duration Prob
1 0.2
2 0.2
3 0.2
4 0.07
5 0.07
6 0.07
7 0.09
8 0.1
parameter: travel_age_prob_age_groups
default value: 9 16 25 35 45 55 65 75 85 120
type: VECTOR CDF
definition:
Age groups that may have distinct travel probabilities.
parameter: travel_age_prob_values
default value: 9 0.05 0.12 0.10 0.30 0.17 0.14 0.07 0.05 0.00
type: VECTOR OF REALS
definition:
Travel probability for each age group.
parameter: min_travel_distance
default value: 100.0
type: REAL
definition:
Minimum distance traveled for overnight trips (in km).
parameter: travel_hub_file
default value: $FRED_HOME/input_files/countries/usa/msa_hubs.txt
type: STRING
definition:
List of travel hubs based on US air travel.
parameter: trips_per_day_file
default value: $FRED_HOME/input_files/countries/usa/trips_per_day.txt
type: STRING
definition:
Matrix of trips per day between hubs.
Each condition requires a set of parameters to describe the
- name of the condition
- the natural history of the condition
- how the condition is transmitted.
The condition parameters generally include the name of the condition as prefix.
parameter: condition_names
default value: 1 influenza
type: VECTOR OF STRINGS
definition:
The list of conditions to be included in the current FRED simulation. The
first value indicates the number of conditions. This is followed by the
list of condition names.
Any number of conditions is allowed. Runtime and memory required is
proportional to the number of conditions.
Natural History parameters describe the distributions for the infectious and symptomatic periods, as well as the case fatality rates and other condition descriptors.
parameter: <condition_name>_natural_history_model
default value: basic
type: STRING
definition:
The basic natural history model includes the specifications for the
distributions for the incubation period, the symptomatic period, the
latent period, and the infectious period for the named condition.
The incubation period and symptomatic period can be specified as a
lognormal distribution (with an optional upper bound), or using an
explicit cumulative distribution function (CDF).
The latent period and periods period can also be specified as a
lognormal distribution (with an optional upper bound), as a CDF, or with
offsets from the symptomatic period. Examples are given below.
If additional aspects of the natural history are needed, the user can
define a customized natural history model. See the HIV_Natural_History
class for an example.
parameter: <condition_name>_symptoms_distributions
default value: lognormal
type: STRING
definition:
This parameter specifies the type of distributions to be used for the
incubation period and the symptomatic period. Possible values are
"lognormal" and "cdf".
Lognormal Symptoms Parameters
If the symptoms distribution is lognormal, then the following parameters are required:
parameter: <condition_name>_incubation_period_median
parameter: <condition_name>_incubation_period_dispersion
parameter: <condition_name>_symptoms_duration_median
parameter: <condition_name>_symptoms_duration_dispersion
default value: NONE
type: REAL
definition:
The median and dispersion of the lognormal distribution are typically
how incubation periods and symptoms are reported in the literature,
e.g. (Lessler, 2009). They are translated into to the parameters of the
lognormal distribution using the formulas:
location = log(median)
scale = 0.5 * log(dispersion)
We can expect that about 95% of the draws from this lognormal
distribution will fall between (median / dispersion) and (median *
dispersion).
Examples: (from Lessler, 2009)
influenza_incubation_period_median = 1.9
influenza_incubation_period_dispersion = 1.81
influenza_symptoms_duration_median = 5.0
influenza_symptoms_duration_dispersion = 1.5
These values given an expected incubation period of about 1 to 3.5 days,
and symptoms lasting about 3 to 7.5 days.
parameter: <condition_name>_infectious_distributions
default value: NONE
type: STRING
definition:
This parameter specifies the type of distributions to be used for the
latent period and the infectious period. Possible values are
"offset_from_symptoms", "offset_from_start_of_symptoms", "lognormal" and "cdf".
Offset Infectious Period Parameters
In many cases, it makes sense to link the infectious period to the symptoms period, since both symptoms and infectiousness are related to the same underlying mechanisms, for example, the person's viral load. FRED provides two ways to link infectiousnes to symptoms:
<condition_name>_infectious_distributions = offset_from_symptoms
<condition_name>_infectious_distributions = offset_from_start_of_symptoms
These settings mean that infectiousness begins and ends based on the
period of a person's symptoms, possible with one or more days offset.
Offsets are specified with the following required parameters:
<condition_name>_infectious_start_offset = <offset_start>
<condition_name>_infectious_end_offset = <offset_end>
If offset_from_symptoms, then the infectious period is defined as follows:
infectious_start_date = symptoms_start_date + infectious_start_offset
infectious_end_date = symptoms_end_date + infectious_end_offset
If offset_from_start_of symptoms, then the infectious period is defined
as follows:
infectious_start_date = symptoms_start_date + infectious_start_offset
infectious_end_date = symptoms_start_date + infectious_end_offset
Examples:
The following settings would results in each person's infectiousness to
coincide with the symptomatic period:
influenza_infectious_distributions = offset_from_symptoms
influenza_infectious_start_offset = 0
influenza_infectious_end_offset = 0
The following settings would result in each person's infectiousness to
begin 1 day before symptoms and end 3 days after symptoms start:
influenza_infectious_distributions = offset_from_start_of_symptoms
influenza_infectious_start_offset = -1
influenza_infectious_end_offset = 3
The following settings would result in each person's infectiousness to
begin 1 day before symptoms and end 1 day after symptoms end:
influenza_infectious_distributions = offset_from_symptoms
influenza_infectious_start_offset = -1
influenza_infectious_end_offset = 1
Lognormal Infectious Period Parameters
Another option is to make the infectious period independent of the symptoms.
<condition_name>_infectious_distributions = lognormal
If the infectous distribution is lognormal, then the following parameters are required:
parameter: <condition_name>_latent_period_median
parameter: <condition_name>_latent_period_dispersion
parameter: <condition_name>_infectious_duration_median
parameter: <condition_name>_infectious_duration_dispersion
default value: NONE
type: REAL
definition:
Like the symptoms distribution parameters, the lognormal infectious
period parameters are translated into to the parameters of the lognormal
distribution using the formulas:
location = log(median)
scale = 0.5 * log(dispersion)
We can expect that about 95% of the draws from this lognormal
distribution will fall between (median / dispersion) and (median *
dispersion).
Optional Upper Bounds for Lognormal Distributions
The following lognormal parameters are optional:
parameter: <condition_name>_incubation_period_upper_bound
parameter: <condition_name>_symptoms_duration_upper_bound
parameter: <condition_name>_latent_period_upper_bound
parameter: <condition_name>_infectious_duration_median
default value: 0
type: REAL
definition:
If an upper bound is greater than 0, then any draw from the
corresponding lognormal distribution that exceeds the given upper bound
will be replaced by a random draw between 0.0 and the upper bound. This
feature can help to eliminate unrealistically long natural history
periods.
Examples:
influenza_incubation_period_upper_bound = 7
influenza_symptoms_period_upper_bound = 15
CDF Symptoms Parameters
If the symptoms distribution is cdf, then the following parameters are required:
parameter: <condition_name>_days_incubating
default value: NONE
type: VECTOR CDF
definition:
The distribution of incubation period, expressed as a cumulative
distribution function (CDF). The first value is the size of the CDF and
the remaining values are the cumulative probability for each day,
starting with day 0.
Example:
<condition_name>_days_incubating = 3 0.0 0.8 1.0
This specifies that 80% of infected individuals will have an incubation
period of 1 day, and 20% will have an incubation of 2 days.
parameter: <condition_name>_days_symptomatic
default value: NONE
type: VECTOR CDF
definition:
The distribution of the duration of symptoms, expressed as a
cumulative distribution function (CDF). The first value is the size of
the CDF and the remaining values are the cumulative probability for each
day, starting with day 0.
Example:
<condition_name>_days_symptomatic = 7 0.0 0.0 0.0 0.3 0.7 0.9 1.0
This specifies that 30% of infected individuals will have symptoms for 3
days, 40% will have symptoms for 4 days, 20% will have symptoms for 5
days, and 10% will have symptoms for 6 days.
If the infectious distribution is cdf, then the following parameters are required:
parameter: <condition_name>_days_latent
default value: NONE
type: VECTOR CDF
definition:
The distribution of latency duration, expressed as a cumulative
distribution function (CDF). The first value is the size of the CDF and
the remaining values are the cumulative probability for each day,
starting with day 0.
Example:
<condition_name>_days_latent = 3 0.0 0.8 1.0
This specifies that 80% of infected individuals will have a latency
period of 1 day, and 20% will have an latency of 2 days.
parameter: <condition_name>_days_infectious
default value: NONE
type: VECTOR CDF
definition:
The distribution of the duration of infectiousness, expressed as a
cumulative distribution function (CDF). The first value is the size of
the CDF and the remaining values are the cumulative probability for each
day, starting with day 0.
Example:
<condition_name>_days_infectious = 7 0.0 0.0 0.0 0.3 0.7 0.9 1.0
This specifies that 30% of infected individuals will be infectious for 3
days, 40% will be infectious for 4 days, 20% will be infectious for 5
days, and 10% will be infectious for 6 days.
Probability of Showing Symptoms
Regardless of the type of symptoms distribution specified above, each infected person will be assigned a non-zero level of symptoms with a probability given by the following parameter. That is, a person may have a symptomatic period of 1 or more days, but still show no symptoms during that period of time.
parameter: <condition_name>_probability_of_symptoms
default value: 0.67
type: REAL
definition:
The probability that an infected person will develop symptoms.
Example:
<condition_name>_probability_of_symptoms = 0.67
This means that 67% of individual who are infected will develop
symptoms.
Probability of symptoms can optionally be assigned by age group:
parameter: <condition_name>_prob_symptoms_age_groups
default value: 0
type: VECTOR OF REALS
definition:
The probability that an infected person of a given age group will
develop symptoms. If this is set, it overrides the single values
probability_of_symptoms parameter above.
parameter: <condition_name>_prob_symptoms_values
default value: 0
type: VECTOR OF REALS
definition:
The probabilities associated with the <condition_name>_prob_symptoms_age_groups.
Example:
<condition_name>_prob_symptoms_age_group = 2 10 120
<condition_name>_prob_symptoms_values = 2 0.9 0.5
This means that people between 0 and 10 years of age have a 90% chance
of developing symptoms, and people between 10 and 120 years of age have
a 50% chance of developing symptoms. (These values are for illustration
purposes only.)
Levels of Symptoms and Infectiousness
FRED represents the level of symptoms and the level of infectiousness as real numbers between 0 and 1 inclusive. If a person has symptoms, the level of symptoms is 1.0 by default throughout the symptomatic period. Likewise, the level of infectiousness is by default through the infectious period. These defaults can be modified through the following optional parameters:
parameter: <condition_name>_full_symptoms_start
default value: 0
type: REAL
parameter: <condition_name>_full_symptoms_end
default value: 1
type: REAL
definition:
These parameters specify fractions that divide the symptoms period into
three segments: increasing symptoms, full symptoms and declining
symptoms. The level of symptoms increases according to a sigmoid curve
from 0.0 on the day before symptoms start to 1.0 at the
full_symptoms_start mark. The level of symptoms then decreases
according to a sigmoid curve from 1.0 at the full_symptoms_end mark to
0.0 on the day after symptoms ends.
parameter: <condition_name>_full_infectious_start
default value: 0
type: REAL
parameter: <condition_name>_full_infectious_end
default value: 1
type: REAL
definition:
These parameters specify fractions that divide the infectious period
into three segments: increasing infectivity, full infectivity and
declining infectivity. The level of infectivity increases according to
a sigmoid curve from 0.0 on the day before infectivity start to 1.0 at
the full_infectious_start mark. The level of infectivity then decreases
according to a sigmoid curve from 1.0 at the full_infectious_end mark to
0.0 on the day after infectivity ends.
parameter: <condition_name>_transmission_mode
default value: respiratory
type: STRING
definition:
FRED defaults to respiratory person-to-person transmission. Vector
transmission and sexual transmission modes are under active development,
but are considered experimental.
parameter: <condition_name>_transmissibility
default value: 1
type: REAL
definition:
This is a coefficient that modulates the transmissibility of a
condition. Higher values correspond to higher values for R0.
parameter: <condition_name>_asymp_infectivity
default value: 0.5
type: REAL
definition:
The relative infectivity of an asymptomatic person, compared to a
symptomatic person.
parameter: <condition_name>_residual_immunity_age_groups
default value: 0
type: VECTOR OF REALS
definition:
A list of age groups that may have different prior immunity.
parameter: <condition_name>_residual_immunity_values
default value: 0
type: VECTOR OF REALS
definition:
The probability that a person of a given age group will have residual
(prior) immunity.
Example:
<condition_name>_residual_immunity_age_groups = 2 20 120
<condition_name>_residual_immunity_value = 2 0.5 0.1
This means that people between o and 20 years old have a 50% chance of
prior immunity, and those between 20 and 120 years have a 10% chance of
prior immunity.
parameter: <condition_name>_infection_immunity_age_groups
default value: 1 120
type: VECTOR OF REALS
definition:
A list of age groups that may have different probability of immunity as
the result of infection.
parameter: <condition_name>_infection_immunity_values
default value: 1 1.0
type: VECTOR OF REALS
definition:
The probability that a person of given age group will develop immunity
after an infection.
parameter: <condition_name>_immunity_loss_rate
default value: 0
type: REAL
definition:
The rate at which a person loses immunity after recovering from
infection. If greater than 0.0, the number of days of immunity is drawn
from an exponential distribution with rate parameter immunity_loss_rate,
giving a mean time of (1/immunity_loss_rate) until loss of immunity. A
value of 0 means permanent immunity after infection.
<condition_name>_infectivity_threshold = 0.0
<condition_name>_symptomaticity_threshold = 0.0
<condition_name>_evolution = 0
<condition_name>_enable_case_fatality = 0
parameter: primary_cases_file
default value: $FRED_HOME/input_files/primary_cases_10_on_day_0.txt
type: STRING
definition:
The location of the file that specifies the schedule of initial seed
cases for the epidemic.
The primary cases file is a required file giving the number of primary infections to introduce for each simulation day. By default, the file specifies how many imported cases are introduced on specifed days. Optionally, the file can specify other details of imported cases, such as where they should be located. The format of the file is:
#line_format
start end attempts [ strain [ prob [ min [ lat lon radius ] ] ] ]
There can be any number of schedule line after the header line. Only the first three fields are mandatory. The first two fields give the starting and ending day, and the third field specifies the number of attempted infections per day. For each specified day we attempt to generate new cases by randomly selecting agents (with replacement) and infecting them if they are susceptible. Note that the actual number of infections may be less than the number of attempts because some selected agents may already be infected or may be immune. The process continues until the end day indicated on the same line in the file, or until the end of the simulation.
The other fields are optional, but if present, must be given in the order above. If a location is specified, then all three location fields must be present (lat, lon & radius). The radius is specified in kilometers. To disable geographic seeding either omit lat, lon and radius or give a value for radius that is greater than 40075 or less than zero.
The example below will make 100 seeding attempts of strain 0 on day 0, each with attempt probability of 1, requiring a minimum of 100 transmissions, all selected randomly from people whose households are within 100km of the specified point.
#line_format
0 0 100 0 1 100 40.44181 -80.01278 100
The following parameters provide additional control of how imported cases are selected from the population:
parameter: seed_by_age
default value: 0
type: INT
definition:
If set, imported cases are selected by age.
parameter: seed_age_lower_bound
default value: 0
type: INT
definition:
Minimum age for imported cases.
parameter: seed_age_upper_bound
default value: 120
type: INT
definition:
Maximum age for imported cases.
parameter: advanced_seeding
default value: exposed
type: STRING
definition:
The parameter controls how far into their infection trajectory
the imported cases are on day 0:
"exposed" => all seeded infections start on day 0 [ DEFAULT ]
"infectious" => all seeded infections start on first infectious day
"random" => randomly select the day in the infection trajectory
with uniform probability
"exposed:<float>;infectious:<float>" => user-specified fraction
of initially exposed/infectious seeds
(e.g. "exposed:0.25;infectious:0.75"); must sum to ~1.0
© 2012-2015 [Public Health Dynamics Laboratory] (http://www.phdl.pitt.edu "PHDL website"), University of Pittsburgh