Other configuration options

Command line inputs

flepiMoP allows some input parameters/options to be specified in the command line at the time of model submission, in addition to or instead of in the configuration file. This can be helpful for users who want to quickly run different versions of the model – typically a different number of simulations or a different intervention scenario from among all those specified in the config – without having to edit or create a new configuration file every time. In addition, some arguments can only be specified via the command line.

In addition to the configuration file and the command line, the inputs described below can also be specified as environmental variables.

In all cases, command line arguments override configuration file entries which override environmental variables. The order of command line arguments does not matter.

Details on how to run the model, including how to add command line arguments or environmental variables, are in the section How to Run.

Command-line only inputs

Argument

Env. Variable

Value type

Description

Required?

Default

-c or --config

CONFIG_PATH

file path

Name of configuration file. Must be located in the current working directory, or else relative or absolute file path must be provided.

Yes

-i or --first_sim_index

FIRST_SIM_INDEX

integar 1

The index of the first simulation

-j or --jobs

FLEPI_NJOBS

integar 1

Number of parallel processors used to run the simulation. If there are more slots that jobs, slots will be divided up between processors and run in series on each.

Number of processors on the computer used to run the simulation

--interactiveor --batch

Choose either option

Run simulation in interactive or batch mode

batch

--write-csv or --no-write-csv

Choose either option

Whether model output will be saved as .csv files

no_write_csv

--write-parquet or --no-write-parquet

Choose either option

Whether model output will be saved as .parquet files (a compressed representation that can be opened and manipulated with minimal memory. May be required for large simulations). Read more about .

write_parquet

Command-line versions of configuration file inputs

Argument

Config item

Env. Variable

Value type

Description

Required?

Default

-s or --npi_scenario

interventions: scenarios

FLEPI_NPI_SCENARIOS

list of strings

Names of the intervention scenarios described in the config file that will be run. Must be a subset of scenarios defined.

All scenarios described in config

-n or --nslots

nslots

FLEPI_NUM_SLOTS

integar 1

Number of independent simulations of the model to be run

Config value

--stochastic or --non-stochastic

seir: integration: method

FLEPI_STOCHASTIC_RUN

choose either option

Whether the model will be run stochastically or non-stochastically (deterministic numerical integration of equations using the RK4 algorithm)

Config value

--in-id

FLEPI_RUN_INDEX

string

Unique ID given to the model runs. If the same config is run multiple times, you can avoid the output being overwritten by using unique model run IDs.

Constructed from current date and time as YYYY.MM.DD.HH/MM/SS

--out-id

FLEPI_RUN_INDEX

string

Unique ID given to the model runs. If the same config is run multiple times, you can avoid the output being overwritten by using unique model run IDs.

Constructed from current date and time as YYYY.MM.DD.HH/MM/SS

Example

As an example, consider running the following configuration file

name: sir
setup_name: minimal
start_date: 2020-01-31
end_date: 2020-05-31
data_path: data
nslots: 1

subpop_setup:
  geodata: geodata_sample_1pop.csv
  mobility: mobility_sample_1pop.csv
  popnodes: population
  nodenames: name

seeding:
  method: FromFile
  seeding_file: data/seeding_1pop.csv

compartments:
  infection_stage: ["S", "I", "R"]

seir:
  integration:
    method: stochastic
    dt: 1 / 10
  parameters:
    gamma:
      value:
        distribution: fixed
        value: 1 / 5
    Ro:
      value:
        distribution: uniform
        low: 2
        high: 3
  transitions:
    - source: ["S"]
      destination: ["I"]
      rate: ["Ro * gamma"]
      proportional_to: [["S"],["I"]]
      proportion_exponent: ["1","1"]
    - source: ["I"]
      destination: ["R"]
      rate: ["gamma"]
      proportional_to: ["I"]
      proportion_exponent: ["1"]

interventions:
  scenarios:
    - None
    - Lockdown
  modifiers:
    None:
      method: SinglePeriodModifier
      parameter: r0
      period_start_date: 2020-04-01
      period_end_date: 2020-05-15
      value:
        distribution: fixed
        value: 0
        settings:
    Lockdown:
      method: SinglePeriodModifier
      parameter: r0
      period_start_date: 2020-04-01
      period_end_date: 2020-05-15
      value:
        distribution: fixed
        value: 0.7

To run this model directly in Python (it can alternatively be run from R, for all details see section How to Run), we could use the command line entry

> gempyor-seir -c sir_control.yml

Alternatively, to run 100 simulations using only 4 of the available processors on our computer, but only running the "" scenario with a deterministic model, and to save the files as .csv (since the model is relatively simple), we could call the model using the command line entry

/> gempyor-seir -c sir_control.yml -n 100 -j 4 -npi_scenario None --non_stochastic --write_csv

Environmental variables

TBA

US-specific configuration file options

Things below here are very out of date. Put here as place holder but not updated recently.

global: smh_round, setup_name, disease

spatial_setup: census_year, modeled_states, state_level

For US-specific population structures

For creating US-based population structures using the helper script build_US_setup.R which is run before the main model simulation script, the following extra parameters can be specified

Config Item

Required?

Type/Format

Description

census_year

optional

integer (year)

Determines the year for which census population size data is pulled.

state_level

optional

boolean

Determines whether county-level population-size data is instead grouped into state-level data (TRUE). Default FALSE

modeled_states

optional

list of location codes

A vector of locations that will be modeled; others will be ignored

Example 2

To simulate an epidemic across all 50 states of the US or a subset of them, users can take advantage of built in machinery to create geodata and mobility files for the US based on the population size and number of daily commuting trips reported in the US Census.

Before running the simulation, the script build_US_setup.R can be run to get the required population data files from online census data and filter out only states/territories of interest for the model. More details are provided in the How to Run section.

This example simulates COVID-19 in the New England states, assuming no transmission from other states, using 2019 census data for the population sizes and a pre-created file for estimated interstate commutes during the 2011-2015 period.

subpop_setup:
  census_year: 2010
  state_level: TRUE
  geodata: geodata_2019_statelevel.csv
  mobility: mobility_2011-2015_statelevel.csv
  modeled_states:
    - CT
    - MA
    - ME
    - NH
    - RI
    - VT

geodata.csv contains

USPS	subpop	population
AL	01000	4876250
AK	02000	737068
AZ	04000	7050299
AR	05000	2999370
CA	06000	39283497
.....

mobility_2011-2015_statelevel.csv contains

ori	dest	amount
01000	02000	198
01000	04000	292
01000	05000	570
01000	06000	1030
01000	08000	328
.....

`importation` section (optional)

This section is optional. It is used by the covidImportation package to import global air importation data for seeding infections into the United States.

If you wish to include it, here are the options.

Config Item

Required?

Type/Format

Description

census_api_key

required

string

travel_dispersion

required

number

ow dispersed daily travel data is; default = 3.

maximum_destinations

required

integer

number of airports to limit importation to

dest_type

required

categorical

location type

dest_country

required

string (Country)

ISO3 code for country of importation. Currently only USA is supported

aggregate_to

required

categorical

location type to aggregate to

cache_work

required

boolean

whether to save case data

update_case_data

required

boolean

deprecated; whether to update the case data or used saved

draw_travel_from_distribution

required

boolean

whether to add additional stochasticity to travel data; default is FALSE

print_progress

required

boolean

whether to print progress of importation model simulations

travelers_threshold

required

integer

include airports with at least the travelers_threshold mean daily number of travelers

airport_cluster_distance

required

numeric

cluster airports within airport_cluster_distance km

param_list

required

See section below

see below

`importation::param_list`

Config Item

Required?

Type/Format

Description

incub_mean_log

required

numeric

incubation period, log mean

incub_sd_log

required

numeric

incubation period, log standard deviation

inf_period_nohosp_mean

required

numeric

infectious period, non-hospitalized, mean

inf_period_nohosp_sd

required

numeric

infectious period, non-hospitalized, sd

inf_period_hosp_mean_log

required

numeric

infectious period, hospitalized, log-normal mean

inf_period_hosp_sd_log

required

numeric

infectious period, hospitalized, log-normal sd

p_report_source

required

numeric

reporting probability, Hubei and elsewhere

shift_incid_days

required

numeric

mean delay from infection to reporting of cases; default = -10

delta

required

numeric

days per estimations period

importation:
  census_api_key: "fakeapikey00000"
  travel_dispersion: 3
  maximum_destinations: Inf
  dest_type: state
  dest_county: USA
  aggregate_to: airport
  cache_work: TRUE
  update_case_data: TRUE
  draw_travel_from_distribution: FALSE
  print_progress: FALSE
  travelers_threshold: 10000
  airport_cluster_distance: 80
  param_list:
    incub_mean_log: log(5.89)
    incub_sd_log: log(1.74)
    inf_period_nohosp_mean: 15
    inf_period_nohosp_sd: 5
    inf_period_hosp_mean_log: 1.23
    inf_period_hosp_sd_log: 0.79
    p_report_source: [0.05, 0.25]
    shift_incid_days: -10
    delta: 1

`report` section

The report section is completely optional and provides settings for making an R Markdown report. For an example of a report, see the Supplementary Material of our preprint

If you wish to include it, here are the options.

Config Item

Required?

Type/Format

Description

data_settings::pop_year

integer

plot_settings::plot_intervention

boolean

formatting::scenario_labels_short

list of strings; one for each scenario in interventions::scenarios

formatting::scenario_labels

list of strings; one for each scenario in interventions::scenarios

formatting::scenario_colors

list of strings; one for each scenario in interventions::scenarios

formatting::pdeath_labels

list of strings

formatting::display_dates

list of dates

formatting::display_dates2

optional

list of dates

a 2nd string of display dates that can optionally be supplied to specific report functions

report:
  data_settings:
    pop_year: 2018
  plot_settings:
    plot_intervention: TRUE
  formatting:
    scenario_labels_short: ["UC", "S1"]
    scenario_labels:
      - Uncontrolled
      - Scenario 1
    scenario_colors: ["#D95F02", "#1B9E77"]
    pdeath_labels: ["0.25% IFR", "0.5% IFR", "1% IFR"]
    display_dates: ["2020-04-15", "2020-05-01", "2020-05-15", "2020-06-01", "2020-06-15"]
    display_dates2: ["2020-04-15", "2020-05-15", "2020-06-15"]

PreviousSpecifying time-varying parameter modifications NextCode structure

Last updated 2 months ago

Command line inputs

Command-line only inputs

Command-line versions of configuration file inputs

Example

Environmental variables

US-specific configuration file options

For US-specific population structures

Example 2

importation section (optional)

importation::param_list

report section

`importation` section (optional)

`importation::param_list`

`report` section