Configuration file parameters

To see the list of configuration file parameters, along with a description and the value for each, run:

faststi -p

This prints out the parameters in a logical order. Here is an alphabetically arranged reference guide to the parameters:

after_events

These are the events executed after a simulation starts.

Default value: _no_op

Events used in: None

Examples::

after_events = _write_agents_csv;_report

after_events = _no_op # No events are executed after the simulation (default)

age_alpha

If instead of reading in an agent file, the agents are generated with the _generate_agents event, then the initial age of each agent is drawn a random alpha-beta distribution. This is the alpha parameter.

Default value: 0.3

Events used in: _generate_agents, _generate_and_pair

Example:

age_alpha = 0.5

age_beta

If instead of reading in an agent file, the agents are generated with the _generate_agents event, then the initial age of each agent is drawn a random alpha-beta distribution. This is the beta parameter.

Default: 1.0

Events used in: _generate_agents, _generate_and_pair

age_input_time_step

Denomination of agent ages used in input files. This is typically either a year or 5-year age groups.

Default: 1 year (525949 minutes)

Events used in: _read_agents

Examples:

age_input_time_step = 525949

age_input_time_step = YEAR

age_input_time_step = 5 YEARS

age_max

Oldest age that a generated agent at the beginning of a simulation can be initialized to.

Default: 50 years (26297450 minutes)

Events used in: _generate_agents, _generate_and_pair

Examples:

age_max = 26297450

age_max = 50 YEARS

age_min

Youngest age that a generated agent at the beginning of a simulation can be initialized to.

Default: 15 years (7889235 minutes)

Events used in: _generate_agents, _generate_and_pair

Examples:

age_max = 26297450

age_max = 50 YEARS

agents_input_file

Name of the csv file to read agents from. Use empty string for standard input.

Default: agents_in.csv

Events used in: _read_agents

Examples:

agents_input_file = agents_in.csv

agents_input_file = stdin # Reads agents from standard input

agents_output_file

Name of the csv file to write agents to. Use empty string for standard output.

Events used in: _write_agents_csv_header, _write_agents_csv, _write_living_agents_csv, _write_dead_agents_csv

Examples:

agents_output_file = agents_out.csv

agents_output_file = stdout # Writes agents to standard output

before_events

These are the events executed before a simulation starts.

Default: _no_op

Events used in: None

Examples:

before_events = _write_agents_csv_header;_write_results_csv_header;_generate_and_pair

before_events = _no_op # No events are executed after the simulation (default)

birth_event_every_n

Indicates how frequently (i.e. every nth iteration) the birth (_birth) event is executed.

The birth event creates new agents during the simulation. Each new agent is set to the minimum age. Because the number of agents might be too small for their to be births on every iteration, this parameter allows you to execute the births at specified iterations.

Also, births are discrete. There can only be a whole number of births executed by the _birth event. Even if births can take place daily, rounding the expected number of births to a whole number may create a severely inaccurate birth rate. Therefore it may be better to execute the _birth event infrequently but with more births taking place each time it executes, in order to reduce the difference between the births generated by the model and the births in the real-world population being studied.

Default: 73 (i.e. every 73rd iteration - by default this would be every 73rd day of the simulation)

Of course if your simulation doesn’t use the _birth event, this parameter is irrelevant.

Events used in: _birth

Examples:

birth_event_every_n = 73

birth_rate

Birth rate for the period of birth_event_every_n

Events used in: _birth

Default: 0.003968

Example:

birth_rate = 0.002

csv_delimiter

Character that separates CSV fields

Events used in: any event that reads or writes a CSV file.

Default value: ;

Examples:

csv_delimiter = ,

Note

It’s not currently possible to set the csv_delimiter in the configuration file to a semi-colon (;) because this is the delimiter for the configuration file itself. But the default value for csv_delimiter is the semi-colon, so it should be unnecessary to have to set it to anything other than a comma.

dataset_birth_infect

Specifies the location of a dataset used to set the infection stage of agents, if any, when they enter the simulation (when agents are born, so to speak, although since they are born at the minimum age of the simulation, e.g. 15 years old, they may already be sexually active).

See the data/dataset_birth_infect.csv file for an example of this dataset.

In this example file, the the agent characteristics of sex, sex_preferred and age (in 10-year groupings) are used to determine probability of an agent being uninfected (i.e. agent->infected is set to 0), or stage 1, 2, 3 or 4. Note the probabilities are ascending from stage 1 through 4. The _birth event first checks if a uniform random number, r, is < than the stage 1 probability. If it is, agent->infected is set to 1. Then it checks if r is < than the stage 2 probability and >= the stage 1 probability. If it is, agent->infected is set to 2. Etc. If r is >= the stage 4 probability, the agent is uninfected and agent->infected is set to 0. Your simulation can have many stages (up to 254, but this would almost certainly be unmanageable), so long as they are consistently treated across datasets.

Events used in: _birth

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_birth_infect = dataset_birth_infect.csv

dataset_birth_resistant

Specifies the location of a dataset used to set the resistance of infected agents, if any, when they enter the simulation (when agents are born, so to speak, although since they are born at the minimum age of the simulation, e.g. 15 years old, they may already be sexually active). The file can have any number of columns specifying agent characteristics (independent variables). It must have exactly one dependent variable column specifying the risk of resistance for agents with a given set of characteristics.

See the data/dataset_birth_resistant.csv file for an example of this dataset.

Events used in: _birth

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_birth_resistant = dataset_birth_resistant.csv

Note

This mechanism for modelling resistance at birth is a bit too simple and needs to be improved.

dataset_birth_treated

Specifies the location of a dataset used to set the probability of an infected agent being on treatment when they enter the simulation (when agents are born, so to speak, although since they are born at the minimum age of the simulation, e.g. 15 years old, they may already be sexually active). The file can have any number of columns specifying agent characteristics (independent variables). It must have exactly one dependent variable column specifying the probability of treatment for agents with a given set of characteristics

See the data/dataset_birth_treated.csv file for an example of this dataset.

Events used in: _birth

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_birth_treated = dataset_birth_treated.csv

dataset_coinfect

Specifies the location of a dataset used to set the coinfection status of an agent. You can have as many columns specifying agent characteristics (i.e. the independent variables) as you wish but the _coinfect event expects exactly one dependent variable, the probability of the agent being coinfected per time step.

See the data/dataset_coinfect.csv file for an example of this dataset.

Events used in: _coinfect

Examples:

dataset_coinfect = dataset_coinfect.csv

dataset_gen_infect

Specifies the location of a dataset used to set the infection stage of agents, if any, at the beginning of a simulation.

See the data/dataset_gen_infect.csv file for an example of this dataset.

In this example file, the agent characteristics of sex, sex_preferred and age (in 10-year groupings) are used to determine probability of an agent being uninfected (i.e. agent->infected is set to 0), or stage 1, 2, 3 or 4. Note the probabilities are ascending from stage 1 through 4. The _birth event first checks if a uniform random number, r, is < than the stage 1 probability. If it is, agent->infected is set to 1. Then it checks if r is < than the stage 2 probability and >= the stage 1 probability. If it is, agent->infected is set to 2. Etc. If r is >= the stage 4 probability, the agent is uninfected and agent->infected is set to 0. Your simulation can have many stages (up to 254, but this would almost certainly be unmanageable), so long as they are consistently treated across datasets.

Events used in: _generate_agents, _generate_and_pair

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_infect = dataset_gen_infect.csv

dataset_gen_mating

Specifies the location of a dataset used to set the probability of an agent being in the mating pool at the beginning of a simulation. You can have as many columns specifying agent characteristics (i.e. the independent variables) as you wish but the events that use this dataset expect exactly one dependent variable, the probability of the agent being in the initial mating pool.

See the data/dataset_gen_mating.csv file for an example of this dataset.

Events used in: _generate_agents, _generate_and_pair

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_mating = dataset_gen_mating.csv

dataset_gen_resistant

Specifies the location of a dataset used to set the resistance of infected agents, if any, at the beginning of a simulation. The file can have any number of columns specifying agent characteristics (independent variables). It must have exactly one dependent variable column specifying the risk of resistance for agents with a given set of characteristics.

See the data/dataset_gen_resistant.csv file for an example of this dataset.

Events used in: _generate_agents, _generate_and_pair

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_resistant = dataset_gen_resistant.csv

Note

This mechanism for modelling resistance is a bit too simple and needs to be improved.

dataset_gen_sex

Specifies the location of a dataset used to set the sex of an agent at the beginning of a simulation. The file can have zero or more columns specifying agent characteristics (independent variables). It must have exactly one dependent variable column specifying the probability of the agent being male. Typically this is a one-column dataset with a header and one data row set to 0.5. But if you want need more sophisticated initiation of agent sex (e.g. by age), then this is the dataset in which you specify it.

See the data/dataset_gen_sex.csv file for an example of this dataset.

Events used in: _generate_agents, _generate_and_pair

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_sex = dataset_gen_sex.csv

dataset_gen_sex_preferred

Specifies the location of a dataset used to set the sexual preference of an agent at the beginning of a simulation. The file can have zero or more columns specifying agent characteristics (independent variables). It must have exactly one dependent variable column specifying the probability of the agent preferring a male sexual partner.

See the data/dataset_gen_sex_preferred.csv file for an example of this dataset.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_sex_preferred = dataset_gen_sex_preferred.csv

dataset_gen_treated

Specifies the location of a dataset used to set the treatment status of an infected agent at the beginning of a simulation. The file can have zero or more columns specifying agent characteristics (independent variables). The number of dependent variable columns must correspond to the number of possible treatment statuses, incrementing from 1. Events that use this dataset generate a uniform random number, r, and then compare r from the first dependent column onwards. If r is less than the probability in a dependent column, the agent’s treatment status is set to the dependent column number.

Here’s a mixture of C and pseudocode showing how FastSTI does this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 num_stages = simulation->dataset_gen_treated->num_dependents;
 rnd = uniform random number;
 agent->treated = 0;
 row = fsti_dataset_lookup_row(dataset_gen_treated, agent);
 for (col = 1; col <= num_stages; col++) {
     prob = dataset_get(dataset_gen_treated, row, col);
     if (rnd < prob) {
         agent->treated = col;
         break;
     }
 }

See the data/dataset_gen_treated.csv file for an example of this dataset.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_treated = dataset_gen_sex_treated.csv

dataset_infect

Specifies the location of a dataset used to determine whether an agent becomes infected by its sexual partner. This is a two-agent dataset, since the probability of infection is a function of the characteristics of both agents. See Two-agent datasets for details on how this works.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_infect = dataset_gen_infect.csv

dataset_infect_stage

Specifies the location of a dataset used to determine if an infected agent should change the infection stage it is in.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_gen_infect = dataset_gen_infect.csv

This is quite a complicated dataset and is best understood by looking at the commented example in the data directory called dataset_infect_stage.csv. For convenience here it is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
     # Dataset used by _stage event (defined in fsti-events.c as fsti_event_stage)
     #
     # The first three columns are used for matching and correspond to agent fields
     # or properties.
     #
     # The next six columns are instructions on how and when to change the stage.
     #
     # Columns:
     #
     #  1. infected - the infection stage of the agent (0 is uninfected)
     #  2. treated - the treatment regimen of the agent. This particular file
     #               allows for 3 treatment regimens.
     #  3. resistant - 0 if the agent is drug-susceptible to this treatment regimen
     #                 1 if the agent is drug-resistant to this treatment regimen
     #  4. prob_stage_change - probability that the infection stage changes for
     #                         this time step (1 day)
     #  5. stage_incr - if a uniformly generated random number < prob_stage_change
     #                  then change the infect property by this increment
     #  6. prob_treatment_change - probability treatment changes
     #  7. treatment_incr - if a uniformly rand number < prob_treatment_change
     #                      then change the treatment property by this increment
     #  8. prob_resistant - probability resistance status changes
     #  9. resistant_incr - if a uniformly random number < prob_resistant_change
     #                      change the resistant value by this amount
     #
     # Note the |6 after resistant_incr means that there are six columns at the end
     # of each line that are not agent properties.
     #
     # Infection stages:;;;;;;;;
     #  0 = uninfected;;;;;;;;
     #  1 = virally suppressed (usually on treatment);;;;;;;;
     #  2 = primary infection (highly infectious);;;;;;;;
     #  3 = chronic infection;;;;;;;;
     #  4 = Final stage;;;;;;;;
     #
     # HEADER ROW FOLLOWS
     infected;treated;resistant;prob_stage_change;stage_incr;prob_treatment_change;treatment_incr;prob_resistant;resistant_incr|6
     0;0;0;0;0;0;0;0;0
     0;0;1;0;0;0;0;0;0
     0;1;0;0;0;0;0;0;0
     0;1;1;0;0;0;0;0;0
     0;2;0;0;0;0;0;0;0
     0;2;1;0;0;0;0;0;0
     0;3;0;0;0;0;0;0;0
     0;3;1;0;0;0;0;0;0
     1;0;0;0.1;1;0.0001;1;0;0
     1;0;1;0.1;1;0.0001;1;0;0
     1;1;0;0.00001;1;0.00001;1;0.00001;1
     1;1;1;0.1;1;0.0001;1;0;0
     1;2;0;0.00001;1;0.00001;1;0.00001;1
     1;2;1;0.1;1;0.0001;1;0;0
     1;3;0;0.00001;1;0;0;0.0001;1
     1;3;1;0.1;1;0;0;0;0
     2;0;0;0.1;1;0.001;1;0;0
     2;0;1;0.1;1;0.001;1;0;0
     2;1;0;0.1;-1;0;0;0.0001;1
     2;1;1;0.1;1;0.001;1;0;0
     2;2;0;0.1;-1;0;0;0.0001;1
     2;2;1;0.1;1;0.001;1;0;0
     2;3;0;0.1;-1;0;0;0.0001;1
     2;3;1;0.1;1;0;0;0;0
     3;0;0;0.004;1;0.0001;1;0;0
     3;0;1;0.001;1;0.0001;1;0;0
     3;1;0;0.1;-1;0;0;0.0001;1
     3;1;1;0.002;1;0.005;1;0;0
     3;2;0;0.1;-1;0;0;0.0001;1
     3;2;1;0.002;1;0.001;1;0;0
     3;3;0;0.1;-1;0;0;0.0001;1
     3;3;1;0.002;1;0;0;0;0
     4;0;0;0;0;0.005;1;0;0
     4;0;1;0;0;0.005;1;0;0
     4;1;0;0.1;-1;0;0;0.0001;1
     4;1;1;0;0;0.01;1;0;0
     4;2;0;0.1;-1;0;0;0.0001;1
     4;2;1;0;0;0.01;1;0;0
     4;3;0;0.1;-1;0;0;0.0001;1
     4;3;1;0;0;0;0;0;0

dataset_mortality

Specifies the location of a dataset used to determine if an agent should die on the current time step.

See the data/dataset_mortality.csv file for an example of this dataset.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_mortality = dataset_mortality.csv

dataset_rel_period

Specifies the location of a dataset used to determine the length of time an agent relationship should be.

This dataset requires two dependent variable columns: scale and shape, which are used to draw a random number from a Weibull distribution for each agent in the relationship. The values returned are the number of time steps (iterations). The duration of the relationship is the mean of the two random numbers drawn.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_rel_period = dataset_rel_period.csv

dataset_single_period

Specifies the location of a dataset used to determine the length of time an agent should remain single.

This dataset requires two dependent variable columns: scale and shape, which are used to draw a random number from a Weibull distribution for the agent. The value drawn is the number of time steps the agent should remain single.

Default: _no_op # i.e. there is no dataset file specified.

Examples:

dataset_single_period = dataset_single_period.csv

during_events

These are the events executed on every time step of a simulation.

Default: _no_op

Events used in: None

Examples:

during_events=_age;_breakup_and_pair;_infect;_stage;_birth;_death

during_events = _no_op # No events are executed during the simulation (default)

report_frequency

Indicates the frequency that the reporting events specified by the during_events parameter should be specified.

Default: 1, i.e. on every iteration or time step of the simulation. Make sure this is what you really want. If you’re executing _write_agents_csv during the simulation, having a report_frequency of 1 will slow your simulation down and use huge amounts of hard drive space.

Events used in: _write_agents_csv, _write_live_agents_csv, _write_dead_agents_csv, _report

Examples:

report_frequency = 365 # Report every 365 time steps.

initial_infect_stage

When an agent is infected, this parameter determines the initial infection stage.

Default: 2. In the default simulation provided by FastSTI, the agent infected property of 1 implies it is on treatment. No one is on treatment when infected, so 2 represents the primary infection stage, and this is therefore the default value that initial_infect_stage is set to.

Events used in: _infect

Example:

initial_infect_stage = 2

match_k

The value of k when using nearest-neighbour type agent matching algorithms. The agent matching algorithm supplied with GroundUp (implemented by the _rkpm event) chooses the best match for the current agent being considered for matching in the mating pool from the k unmatched agents adjacent to it.

If k is set to 1, this is random matching matching. If k is set larger than the possible number of agents in the mating pool, then this is a kind of brute force matching.

Default: 100 This is usually a good compromise value. The algorithm will execute quickly and the agent selected will on average be a better match than 99% of the remaining agents in the mating pool.

Default: 100

Events used in: _rpkm

Example:

match_k = 300

mutual_csv_partners

Sometimes a CSV file of agents that is used to initialize a simulation only records one of the partners in a relationship. If this is the case then set this parameter to 1. FastSTI will then iterate through all the agents after they’ve been read in, but before the simulation loop begins, and properly initialise all relationships.

Leaving this at 0 if the CSV file does not mutually record agent relationships will give unpredictable results. But setting to 1 is always harmless, albeit resulting in very slightly slower execution.

This parameter has no effect if agents are generated (i.e. not read in via a CSV file).

Default: 1

Events used in: _read_agents

Example:

mutual_csv_partners = 1

num_agents

Determines the number of agents to generate for a simulation.

This parameter has no effect if agents are read in from a CSV file.

Default: 20000

Events used in: _generate_agents, _generate_and_pair

Example:

num_agents = 10000

num_simulations

Indicates the number of times to repeat a simulation in a simulation group.

Default: 1

Events used in: None

Example:

num_simulations = 1

partnerships_file

The csv file name to output partnerships. Set to empty string for stdout. This file will be empty unless one or more of record_breakups, record_infections or record_matches are set.

Default: Empty string (i.e. stdout)

Events used in: _rkpm, _infect, _breakup, _breakup_and_pair, _generate, _generate_and_pair

Example:

partnerships_file = "my_partnerships.csv"

TO DO

prob_birth_infected_msm; Probability a new msm agent is infected; 0.001000

prob_birth_infected_msw; Probability a new msw agent is infected; 0.000100

prob_birth_infected_wsm; Probability a new wsm agent is infected; 0.000500

prob_birth_infected_wsw; Probability a new wsw agent is infected; 0.000100

prob_birth_male; Probability a new agent is male; 0.500000

prob_birth_msw; Probability a new male agent is msw; 0.950000

prob_birth_wsm; Probability a new female agent is wsm; 0.950000

prob_gen_male; Probability a generated agent is male; 0.500000

prob_gen_msw; Probability a generated male agent is msw; 0.950000

prob_gen_wsm; Probability a generated female agent is wsm; 0.950000

record_breakups; Whether to output breakups to the partnership file; 0

record_infections; Whether to output infections to the partnership file; 0

record_matches; Whether to output matches to the partnership file; 0

results_file; File name to output results to (empty string for stdout);

simulation_period; Time period of the simulation (10 years); 5259490

stabilization_events; Events used to stabilize the agent characteristics before the actual simulation; _no_op

stabilization_steps; Number of time steps to run before executing various events; 0

start_date; Start date of simulation (yyyy;mm;dd); 2018; 1; 1

threads; Number of threads (0=system determined); 0

time_step; Time step for each iteration of simulation in minutes(default 1440 minutes == 1 day); 1440

treatment_infect_stage; When treated this is the integer to set infected to; 1