Introduction to this User Manual

This user manual accompanies the United States Disease Outbreak Simulation (USDOS) version 2 as described in Tsao, K. et. al (2019) “Effects of regional differences and demography in modelling foot-and-mouth disease in cattle at the national scale” Interface Focus 10:20190054. USDOS is a simulation model for the spread of a foot-and-mouth disease (FMD)-like disease in the United States cattle population. The model is coded in C++, with R scripts used for pre- and post-processing. The mdoel can be run via the command line or usdosr, a companion R package (see https://github.com/webblabb/usdosr).

This user manual is intended as a guide for running the model. It assumes that the user is familiar with USDOS, has determined that it is a good fit for their question, and has developed the required parameters. To become familiar with USDOS and determine whether it is a good fit for the research question, please see Tsao, K. et. al (2019) “Effects of regional differences and demography in modelling foot-and-mouth disease in cattle at the national scale” Interface Focus 10:20190054 and Buhnerkempe et al (2014) “The Impact of Movements and Animal Density on Continental Scale Cattle Disease Outbreaks in the United States.” Plos One 9(3): 10. Related foundational work building a cattle shipment model for the United States:

This manual also assumes that the user has access to a computer or cluster running a Linux or Mac operating system and the following required software installed:

  • R
  • GNU Compiler Collection (GCC). Version 6.1.0 has been thoroughly tested with the code, though other versions may work.
  • GNU Scientific Library (GSL). Version 2.1 has been thoroughly tested with the code, though other versions may work.

Optional software:

  • usdosr R package

Style conventions used in this guide

Text in this font is code

Items in single quotes (’ ’) are file names

xx signifies a two-digit number (01 to 10)

** signifies text that can vary (such as a filename)

Quick start guide

This section is intended as a brief reminder of the steps required to initialize and run USDOS for experienced users. A more detailed explaination can be found in subsequent sections of this User Manual.

Initial USDOS setup

Note: If USDOS is already initialized on your computing system, please proceed to the run-specific steps below

  1. Download zipped USDOS folder from repository
  2. Unzip USDOS folder into your working directory
  3. Create object directory (mkdir obj)
  4. Add any additional required files
  5. Ensure USDOS compiles (using make) and modify ‘makefile’ if needed
Run-specific steps
  1. Use ‘createConfig_Function.R’ to generate input files
  2. Submit job
  3. Export files
  4. Generate results files with ‘post_processing.R’, and (if desired) results report with ‘USDOS_Results_Report.Rmd’.

Initial USDOS setup

Note: These steps are only required once per model version

  1. Download the zipped USDOS master folder (‘usdos.zip’) from the appropriate repository.

  2. Transfer the zipped directory onto the desired working directory.

  3. Unzip the folder in the working directory: unzip usdos.zip

  4. Enter the upzipped directory: cd ./usdos

  5. Create an object directory: mkdir obj

  6. Add any required files using SFTP

  7. If on a cluster system requiring explicit module loading, load required modules.

module load gcc/6.1.0
module load gsl/2.1
  1. Compile USDOS using make. If it fails to compile, try these troubleshooting steps.

Simulation options

Run types

Several types of run are possible within USDOS. The examples below cover a range of options and are used to throughout this Manual to demonstrate options, but are not intended as an exhaustive set of options. Definitions of terms used can be found here.

  • Base runs do not include any control measures
  • Infected premises (IP) cull runs include culling of the infected premises. Runs of this type are abbreviated “IP cull”.
  • IP cull & Dangerous Contacts (DC) cull runs include culling of both IPs and premises identified as dangerous contacts. Runs of this type are abbreviated “IP & DC cull”.
  • IP cull & DC vaccination runs include culling of IPs and vaccination of DCs. Runs of this type are abbreviated “IP cull & DC Vax”.
  • IP cull & ring vaccination runs include culling of IPs and vaccination within a ring around IPs. Standard ring vaccination radii are 3 and 10 kilometers. Runs of this type are abbreviated “IP cull & XXkm Vax”.

A movement ban can be added to the control types above. As an example, you may have an IP & DC cull run with a 90% effective movement ban.

Configuration file contents

Control type (or lack thereof) and other run parameters are specified in the configuration file. Each line of the config file specifies an option or parameter for the run. These are grouped into sections: Output settings, General settings, Infection-related settings, Grid-related settings, Shipment-related settings, Control-related settings, and Reporting and Tracing (DC) settings.

An example configuration file is shown here. Below the file is a detailed description of each line and instructions for editing the configuration file during pre-processing.

## One variable per row, comments start with #
## Empty rows ignored. Rows with numbers and without descriptions are placeholders for future variables.
## Arguments not provided should be replaced with '*'.
## Values in parentheses are the index in the vector where value is stored.
## '~' after the value indicates that this value is required
## '+' after the value indicates that one of these adjacent options is required
## 'x' after the value indicates that this feature is not yet functional

######################## Output settings ########################
IP_VAX_3km_MvmtBan_90_flaps12_min_0001_01_20190513_ #(1) Batch name, used as prefix for output files. Only letters, numbers and underscore.
1 #(2) Summary output on/off (1/0) - one line per replicate with # infected, duration, seed info, run time
1 #(3) Detailed infection output on/off (1/0) - one line per exposed premises with time, source of infection, route of infection
0 #(4) Print grid cells on/off
0 #(5)xAdditional functionality under development. Do not change default value.
0 #(6)xAdditional functionality under development. Do not change default value.
* #(7)
* #(8)
* #(9)
* #(10)

######################## General settings ########################
FLAPS/flaps12_min_0001.txt #(11)~Name of file containing premises ID, FIPS, x, y, population - ie FLAPS_beefdairy_20151201_formatted.txt. Make sure the premises file doesn't have numbers in 1e+05 format (may happen with IDs)
beef,dairy          #(12)~List of species for which counts are provided in premises file, comma-separated
365 #(13)~Timesteps (days) to run
* #(14) Max infectious premises before stopping an outbreak (* = no limit)
1   #(15)~Verbose level: Output extra information to console as model runs (0=off, 1=basic steps, 2=debug)
0   #(16)x~Disabled
0   #(17)~Reverse x/y option: in case input file is entered as lat/long (y/x)(set to 1) instead of long/lat (x/y)(set to 0)
inputfiles/FIPS_20151805.txt #(18)~Name of file containing fips name, state name, area (m2), x, y. Tab separated.
0   #(19) Day of the year to start simulation/generation on (jan 1 = day 1). Must be 0 - 365. 0 = one random day [1-365].
* #(20)

######################## Infection-related settings ########################
allFips #(21)~Seed source, filename or "allFips". Filename is of file containing identifiers (FIPS codes or premisesIDs) from which to seed infection, one line per simulation. "allFips" specifies to choose from all counties containing premises. To seed from multiple premises at once, provide comma-separated premisesIDs in the file (one line per simulation).
fips #(22)~Seed file type - type of information provided per line of (21). "fips" = choose 1 premises at random within the FIPS code on a given line in (21) or in all FIPS, "singlePremises" = use the premisesID provided on a given line in (21), "multiplePremises" = use all comma separated premisesIDs on a given line in (21)
*   #(23)
1,1 #(24)~Susceptibility exponents(mu), species-specific & comma-separated in order listed in (12) 0.42,0.49
1,1 #(25)~Infectiousness exponents(omega), species-specific & comma-separated in order listed in (12) 0.41,0.2
1,1     #(26)~Susceptibility constants(a), species-specific & comma-separated in order listed in (12) 5.7,1
10.252,10.252 #(27)~Infectiousness constants(b), species-specific & comma-separated in order listed in (12)0.00082,0.00083
0           #(28)~Kernel type for local (diffusion) spread: 0: k1/(1 + (distance/k2)^k3), 1: data file in (30), 2: k1/(1+d/k2)^k3
1.46e-08,1686.155,2.267 #(29)x~Kernel parameters k1, k2, k3
*       #(30) Name of file containing data-based local spread probabilities by distance, ie inputfiles/UKDataKernel.txt
5,0 #(31)~Mean, variance (around normal) days from premises exposure to infectiousness (latency duration)
7,0 #(32)~Mean, variance (around normal) days from premises infectiousness to immunity (infectiousness duration)
0 #(33)+Additional functionality under development. Do not change default value.
* #(34)+Additional functionality under development. Do not change default value.
* #(35)

######################## Grid-related settings ########################
*               #(36)+Filename containing grid cells (will override other options)
*               #(37)+Length of cell side for uniform cells (will override density options)
500,100000  #(38)+Max farms per cell, cell size minimum side length in m
* #(39)
* #(40)

######################## Shipment-related settings ########################
1 #(41)~Method(s) to generate county-county shipments (USAMM), comma-separated (1 = USAMM version 1, -1 = shipments off)
1   #(42)~Timepoints at which to begin using each of the methods above (first timepoint must be 1), comma-separated
0   #(43)xAdditional functionality under development. Do not change default value.
inputfiles/usammv1_beef.res, inputfiles/usammv1_dairy.res #(44) Output files from USAMM with parameters for a, b, N, s and covariates
Q1 #(45) Additional functionality under development. Do not change default value.
1 #(46) Additional functionality under development. Do not change default value.
*,* #(47) Origin covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(48) Destination covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(49) Disabled
1 #(50) Exposed shipments, shipping from a farm with status exposed will cause the receiver to become exposed as well. 1 = on, 0 = off

######################## Control-related settings ########################
shipBan,cull,vax #(51)~Names for unique control types, comma-separated (fixed options: shipBan, cull, vax) '*' will turn off control.
noLimit,stateSum,dailyLimit #(52) Control constraint function types, comma-separated
0;240,0;6804,0 #(53) Control constraint parameters, comma-separated parameters, SEMICOLON-separated by type. stateSum: constraint is mean/var max animals/day/premises. 20 cows/hr*12 hrs/day = 240
state,premises,premises #(54)~Spatial scale at which control is applied, comma-separated (fixed options: premises, county (shipBan only), state (shipBan only))
NA;inputfiles/landfills_flaps12_min_0001.txt;inputfiles/vaccineBankUpdated.txt #(55) List additional files here, comma-separated, SEMICOLON-separated by type
NA;resourceLocs;resourceBoosts #(56) Specify file types for (55) here: (NA, resourceLocs) comma-separated, SEMICOLON-separated by type
0,0,11 #(57)~Implemented to effective: mean number of days, comma-separated for each control type
0,0,0 #(58)~Implemented to effective: variance number of days, comma-separated for each control type
366,366,183 #(59)~Effective to inactive: mean number of days, comma-separated for each control type
0,0,0   #(60)~Effective to inactive: variance number of days, comma-separated for each control type
0.9,0.9;1,1;0.9,0.9 #(61)~Effectiveness (including compliance) of control types as proportion, comma-separated probability of preventing exposure given exposure and probability of transmission given infectiousness. SEMICOLON-separated by type.
* #(62)
newRegionReportsOverX,newPremReportsOverX,newPremReportsOverX #(63)~Control triggers, comma-separated (fixed options). '*' will turn off control.
0,0,0 #(64)~Control trigger thresholds, comma-separated (numeric)
shipBan,cull,vax #(65)~Control trigger responses, comma-separated (must exist in (51))
0,0,3000 #(66)~Control response targets, comma-separated. -1 = DCs, 0 = triggers only, # = radius in units of x/y coordinates of premises
earliest,earliest,earliest #(67)~Control response priority, comma-separated. Currently only accepts earliest for each control type.
* #(68)
* #(69)
* #(70)

######################## Reporting and Tracing (DC) settings ########################
15,0 #(71)x~Mean, variance days from INDEX premises exposure to reporting
8,0 #(72)~Mean, variance days from (non-dangerous-contact) premises exposure to reporting
2,0 #(73)~Mean, variance days from (dangerous-contact) premises exposure to reporting
sus,4;exp,5 #(74) Dangerous Contact scaling parameters relative to risk: status, then scale, SEMICOLON-separated (only used if at least one of (66) is -1)
* #(75)

Configuration file guide

The line number in the config file is denoted by (#), along with a brief descriptive variable name and description including possible values.

Output settings (lines 1-10)

(1) Batch name A string containing only letters, numbers and underscore, used as prefix for output files. This is generated automatically based on selected options. The date and time of run start are appended to the end of the file name.

(2) Summary output Whether to generate the summary result file, which contains one line per replicate with number infected, duration, seed info, and run time.

  • 1 = Summary output on [default]. File will be outputted in working directory with name [Batch name]_[date]_[time]_summary.txt
  • 0 = Summary output off

(3) Detailed output Whether to generate the detail result file, which contains one line per exposed premises with time, source of infection, and route of infection.

  • 1 = Detailed output on [default]. File will be outputted in working directory with name [Batch name]_[date]_[time]_detail.txt
  • 0 = Detailed output off

(4) Print grid cells Whether to generate a file containing the grid cells used.

  • 1 = Grid cells output on. File will be outputted in working directory with name [Batch name]_cells.txt
  • 0 = Grid cells output off [default]

(5) Additional functionality under development. Do not change default value [0].

(6) Additional functionality under development. Do not change default value [0].

(7) Unused

(8) Unused

(9) Unused

(10) Unused

General settings (lines 11-20)

(11) Premises file (FLAPS) Path and name of file containing premises ID, FIPS (county ID), x, y, and population for each species- ie flaps12_min_0001.txt. By default this file is located in the FLAPS folder, and its path would thus be FLAPS/flaps12_min_0001.txt. Make sure there are no numbers in scientific notation (ex. 1e+05). This may happen with IDs in R-formatted files.

(12) Species List of species for which counts are provided in premises file, comma-separated. Default is “beef, dairy”

(13) Timesteps (days) to run Positive integer of maximum number of days to run each simulation. If an outbreak ends before this time, the simulation will end at that point instead. Default is 365.

(14) Max infectious premises Positive integer of threshold number of infectious premises allowed. If the total number of premises that have reached infectious status (not necessarily at the same time) surpasses this number, the simulation will end. The default value of * means there is no limit on the number of infectious premises

(15) Verbose level How much extra information to output to the console as model runs

  • 0 = Output only critical information to console
  • 1 = Output basic progress to console [default]
  • 2 = Output debug-level information to console

(16) Disabled

(17) Reverse x/y This option allows you to specify if input files list locations as latitude(y) before longitude (x) (instead of the default, which is the reverse).

  • 0 = Location input file for premises (line 11) lists longitude (x) before latitude (y) [default]
  • 1 = Location input file for premises (line 11) lists latitude(y) before longitude (x)

(18) FIPS info Name and path of of file containing fips name, state name, area (in square meters), x coordinate, and y coordinate. Tab separated. Default is inputfiles/FIPS_20151805.txt

(19) Day of the year to seed outbreak January 1 = day 1. Must be an integer 0 - 365. The default of 0 selects one random day [1-365].

(20) Unused

Reporting and Tracing (DC) settings (lines 71-75)

(71) Index reporting lag Two comma-separated positive numeric values describing the mean and variance about a normal distribution for the number of days from index premises exposure (the first case) to reporting. Outcomes less than one are set equal to one. Default is 15,0.

(72) Reporting lag Two comma-separated positive numeric values describing the mean and variance about a normal distribution for the number of days from premises exposure to reporting, if the premises has NOT been designated as a dangerous contact. Outcomes less than one are set equal to one. Default is 8,0.

(73) DC reporting lag Two comma-separated positive numeric values describing the mean and variance about a normal distribution for the number of days from premises exposure to reporting, if the premises HAS been designated as a dangerous contact. Outcomes less than one are set equal to one. Default is 2,0.

(74) DC scaling Dangerous contact scaling parameters relative to risk. Only used if at least one value in line 66 is -1, i.e. if dangerous contacts are a specified control target. Comma-separated pairs of a string and a numeric value >=1, semicolon separated. The string is the disease status for which the scaling constant will apply, and the number is the scaling constant. Generally, there will be two pairs, one each for statuses sus and exp. The value for ‘exp’ generally will be higher than the value for ‘sus’, indicating that premises are more likely to be identified as dangerous contacts if they truly are exposed at the time of this identification than if they are not. Default is sus,4; exp,5

(75) Unused


Generating input files

File types required to run the model

Each model run requires one to three types of files:

  • config files, discussed above, set run parameters. Each simulation requires a configuration file. A standard run, during which each of 10 FLAPS iterations is seeded 10 times per county, requires 100 configuration files. Most of the regularly-modified options in the config files can be changed using the pre-processing R script. Details for editing options using the script are below. An example configuration file was shown above, and an example file for each control type can be found in the Appendix.

If running on a cluster enviornment with a queuing system, the following files are also required

  • BATCH files are used in a cluster computing environment to specify computing parameters, such as the run priority, memory allowed, and maximum runtime when running a config file. Each config file has a corresponding BATCH file. The BATCH files are generated automatically using the pre-processing script. Config file names are updated automatically, but if the user wishes to change run options (memory, etc.), that must be done manually by manipulating the template BATCH file (SH_FILE_TEMPLATE.txt in the templates folder). An example BATCH file is below.
#!/bin/bash

##SBATCH -J MI_f01_01

#SBATCH -t 24:00:00
#SBATCH -n 6
#SBATCH -o MI_f01_01.out
#SBATCH -e MI_f01_01.err
#SBATCH --partition smem

#

module load gcc/6.1.0
./USDOSv2_new config_IP_VAX_10km_MvmtBan90_flaps12_0001_min_01_20180925.txt


# End of script, no wait needed
  • A job file is used to run all the BATCH files, which in turn run the config files. This file is also generated automatically using the pre-processing script. The first five lines of an example file are below.
sbatch BATCH_IP_VAX_10km_MvmtBan90_flaps12_0001_min_01_20180925.sh
sbatch BATCH_IP_VAX_10km_MvmtBan90_flaps12_0001_min_02_20180925.sh
sbatch BATCH_IP_VAX_10km_MvmtBan90_flaps12_0001_min_03_20180925.sh
sbatch BATCH_IP_VAX_10km_MvmtBan90_flaps12_0001_min_04_20180925.sh
sbatch BATCH_IP_VAX_10km_MvmtBan90_flaps12_0001_min_05_20180925.sh

Using the pre-processing code to generate required input files

All three types of file (config, batch, and job) are generated using the ‘createConfig_Function.R’ pre-processing script. The options listed below are items in the configuration file that can be set within the createConfigs() function in the ‘createConfig_Function.R’ pre-processing script. For example, the basic command to generate files for an IP & DC cull run with a 90% effective movement ban is createConfigs(sim_type="IPDCcull",ban_eff = 0.9). The options below are grouped according to their location in the config file. Options in the first section, “File locations & run settings”, are not found in the config file but are used to set general options for USDOS.

File locations & run settings

template.config.location The location of the template for the config file. Default is a ‘templates’ folder within the current working directory. The correct template will be selected based on the sim_type (see Control-related settings).

sh_template The location of the SH_FILE_TEMPLATE.txt file. Default is the ‘templates’ folder. Any changes to computing options (priority, memory allocation, etc.) should be made in this template. The relevant config file name will then be inserted by the pre-processing script.

jobfile.name The name of the jobfile to output. Default is ‘USDOS_Sim.job’.

reps The number of times each FLAPS will be repeated. The default value is 10, for a total of 100 runs.

destination.folder The location to put all generated files. Folder must already exist. Default is the current working directory.

replacement.df The dataframe containing all information to use to modify the default config file. This is created with the time, date, and replacement_df as its title.

General settings

flaps The subname of the FLAPS version being used. For example, ‘12_min’ will use the files ‘flaps12_min_0001.txt’ to ‘flaps12_min_0010.txt’.

cutoff_days The number of timesteps (days) to run for each seeded outbreak. Default is 365. Corresponds to line 13 in the config file.

cutoff The max number of infectious premises to allow before stopping each outbreak. The default ’*’ indicates no limit. Corresponds to line 14 in the config file.

fips.info Name of file containing fips name, state name, area (m2), x, y. Tab separated. Default is “inputfiles/FIPS_20151805.txt” Corresponds to line 18 in the config file.

Pre-processing steps

  1. Edit the pre-processing R script using nano createConfig_Function.R

  2. Run ‘createConfig_Function.R’ to generate the required config, batch, and job files

module load R/3.5.0
Rscript createConfig_Function.R

Additional simulation options

  • Generate FLAPS files if not using standard files
    1. To select a subset of states, use ‘CreateSubGeography.R’
    2. ‘Reformat_FLAPS_realizations.R’ is available to merge beef, dairy, and feedlot FLAPS files.
    3. FLAPS files should be contained in a /FLAPS/ folder in the directory containing the USDOS run program.
  • Determine counties to be seeded from one of the following:
    1. Use the default value of ‘allFips’ to seed all counties
    2. Generate random counties with ‘County_Selection_USDOS_Sensitivity.R’
    3. Use previously generated sensitivity counties in ‘SensCounty_shortlist_0219.txt’
    4. Create a .csv list of desired counties to be seeded. This can be a custom list, or can be generated from subset geography using ‘CreateSubGeography.R’
  • To conduct sensitivity analysis, randomize parameters with ‘LH_Parameters.R’ or use the previously generated random parameter values with ‘LHS_Parameters.csv.’ The generated ‘LHS_Parameter_Summary.csv’ file gives information on the parameter values that were randomized.

Running the model

Ensure that you have followed the initial setup steps and that the job, batch, and config files are saved in the folder containing the USDOS program. Note: This folder should also contain the /inputfiles, /include, and /FLAPS folders.

There are two options for running USDOS. One is via usdosr, the companion R package, and the other is via the command line.

Option 1: usdosr.

This package is a wrapper for the USDOS C++ code. It compiles the model and allows the user to set up a cluster for running USDOS. To use the package, visit https://github.com/webblabb/usdosr. Download the package and follow the instructions on the page to build the package, the use it to set up and cluster and run USDOS.

Option 2: Command line.

  1. If needed, load required modules
module load gcc/6.1.0
module load gsl/2.1
  1. Compile the run program with make Note: if you have made changes since the previous run, use make clean to remove the previous program, then make to re-generate it

  2. Run the program

  • In this step, you can run the jobfile on a cluster environment
chmod a+x jobname.job
./jobname.job

Running the ./jobname.job command above should result in a list of 100 (per run) lines reading “Submitted batch job [a number]”

  • It is also possible to run individual BATCH files
chmod a+x BATCH.sh
./BATCH.sh
  1. Check that the run is working
    1. Check your working directory for .err and .out files (’MI_**_fxx_xx.err/.out’)
      1. If nothing is present, check your queue-your job may not have been allocated computing time yet.
      2. If present, check these files using nano [file name]
        1. .err files should be blank
        2. .out files should list steps the process has completed. Note: These steps take some time to complete, so what you see in the .out file will vary depending on how far along the process is.
    2. If the .err and .out files look good, wait for the runs to complete.

Output files

Four types of files are generated by the model. Each of these output file types contains different information about the simulations.

The .err and .out files display information on the run itself: the .err file records any errors during model runs, while the .out file records step taken during the run. This includes the time to initialize various model components and information on the outbreaks resulting from the seeded infection. The information in these files is not intended for analysis, but is useful for diagnosing issues while running the models.

The detail and summary files contain the results. The detail file contains one line per exposure event, whereas the summary file contains one line per replicate.

The summary file contains information about the number of infected premises and counties, the outbreak duration, seed premises and FIPS, and whether control measures were implemented and effective. Summary file columns and descriptions are below. The first seven columns will be in the summary files for all run types, but the control-specific columns are ommitted if that control type is not used.

Summary file variable name Description
Rep The replicate number. One per seed unit (usually a county)
Num_Inf The number of premises/animals infected
nAffCounties The number of counties affected
Duration The length (in days) of the simulation, from the first time a premises is infected until there are no more infectious premises.
Seed_Farms The premises where infection was seeded (usually one per replicate, chosen randomly from within the seed county)
Seed_FIPS The FIPS code of the county seeded with infection
RunTimeSec The computation time (in seconds) taken to run the outbreak
shipBanImplemented The number of geographical units (state or county, as specified by your parameters) in which a movement ban was implemented. This column is only present for runs with a Shipment Ban.
shipBanEffective The number of geographical units (state or county, as specified by your parameters) in which a movement ban was effective. This column is only present for runs with a Shipment Ban.
cullImplemented The number of premises on which culling was implemented. This column is only present for runs with Culling.
cullEffective The number of premises on which culling was effective. This column is only present for runs with Culling.
vaxImplemented The number of premises on which vaccination was implemented. This column is only present for runs with Vaccination.
vaxEffective The number of premises on which vaccination was effective. This column is only present for runs with Vaccination.
cullImplementedDCSubset The number of DC culls. This column is only present for runs with DC Culling.
meanDCsPerRP The mean number of DCs identified per reported premises. This column is only present for runs with DC Culling.

The detail file contains information on the source and exposed premises and county, time and route of exposure, and whether/how the exposure was prevented. Detail file columns and descriptions are below.

Detail file variable name Description
Rep The replicate during which the exposure occurred
ExposedID The exposed premises
atTime The simulation day on which exposure occurred
SourceID The infectious premises that exposed the ExposedID premises
InfRoute The route of infection (0 = local spread, 1 = shipment spread)
ControlPrevented Was this exposure prevented by a control measure. “none” signifies a successful exposure event, while the name of a control measure (ex “shipBan”) indicates that the exposure was prevented by that control measure. “src” indicates the control measure was applied to the source premises, whereas “exp” indicates control applied to the exposed premises. “src:vax” therefore indicates a potential exposure that was prevented by vaccination of the source premises.
ExposedCounty The FIPS code of the exposed county
SourceCounty The FIPS code of the source county

Post-processing

When the run is completed, extract all run-associated files and save them in a directory with the ‘post-processing.R’ code:

  • Input files
    • config
    • BATCH
    • .job
    • Runlog.txt
  • Output files
    • .err
    • .out
    • _detail.txt
    • _summary.txt

You can process the detail and summary files using the post-processing code ‘post-processing.R’. For each of the metrics described below, this code will generate a .csv file that contains metric-specific data from all summary and/or detail files and .jpeg files that include histograms, violin plots, and maps of the results for that metric. These files can be inserted into a Report that collates and describes the results using the ‘USDOS_Results_Report.Rmd’ file.

Metrics generated during post-processing:

  • Number of infected premises: The national total number of infected and reported premises.
  • Number of cattle infected: The national total number of infected and reported cattle.
  • Number of infected counties: The total number of counties infected when infection is seeded in that county, also known as epidemic extent.
  • County risk: The proportion of simulations in which a county is infected, not including simulations in which infection was seeded in that county.
  • Duration: The bumer of days between the initial seed infection and when there are no more infected premises, or 365 days, whichever happens sooner.
  • Proportion local transmission: The proportion of transmission events at the county level that result from local transmission (as opposed to shipment spread)

Additional Information

Abbreviations & Acronyms

Base: A run with no control implemented

DC: Dangerous Contact

FIPS: Federal Information Processing Standard

FLAPS: Farm Location and Animal Population Simulator

IP: Infected Premises

IP cull: A type of control run that implements culling of IPs

IP & DC cull: A type of control run that implements culling of IPs and DCs

IP cull & DC vax: A type of control run that implements culling of IPs and vaccination of DCs

IP cull & XXkm vax: A type of control run that implements culling of IPs and vaccination of premises with a radius of XX kilometers.

SFTP: Secure File Transfer Protocol

USAMM: United States Animal Movement Model

USDOS: United States Disease Outbreak Simulation

VAX: Vaccine/vaccinated/vaccination

Definitions

Cull: To depopulate the animals on a permises.

Dangerous Contact (DC): Premises that have an epidemiological link to the infected premises or are at a higher risk of infection from infected premises.

FIPS code: A five-digit code assigned to each US county. The first two digits indicate the state, and the final three are county-specific.

Infected Premises (IP): Premises that are infected and have been detected and reported.

Movement ban: A prohibition on animal movements, here implemented at the state or county level.

(Ring) Vaccination: Vaccination in a solid circle centered on the IP. Rings of radius 3 or 10 kilometers are commonly used in modeling studies and encompass a good range of possible ring sizes. The optimum ring size for controlling the UK 2001 outbreak was predicted to be around 10Km (Tildesley, et al. 2006). Currently, vaccinations are prioritized by the time when a premises was identified as requiring vaccination. This does not follow either the ‘outside-in’ or ‘inside-out’ vaccination method. Vaccination is currently vaccination to die.

Model file descriptions

File Group File Type File Naming Pattern File Contents
Input files
Config(uration) config_**.txt The parameters used for a set of model runs.
Batch BATCH_**.sh The computing options for the runs. There is one batch file per config file.
Job **.job The master queuing file that runs all the batch files.
Output files
Error MI_**_fxx_xx.err The errors generated while running a given config file. Will be empty for a successful run.
Out MI_**_fxx_xx.out Information on the steps for each config file and the time they took. Will be large for a successful run. May also contain helpful error messages showing where a run stopped.
Detail **_detail.txt One line per exposure containing information the replicate generating the exposure, the source and exposed premises and county, time and route of exposure, and whether/how the exposure was prevented. Additional details on this file’s contents can be found here.
Summary **_summary.txt One line per replicate containing information replicate runtime, the number of infected premises and counties, the outbreak duration, seed premises and FIPS, and whether control measures were implemented and effective. Additional details on this file’s contents can be found here.

Troubleshooting

Pre-processing

“>50 warnings of”In readLines(template.config.location) : incomplete final line found on templates/USDOS_CONFIG_TEMPLATE_NoControls_workaround.txt’"

  • Incomplete final line in template: open the file, hit return after last line, save and close.

Running the model

Can’t access BATCH files

  • Check in R code that allFips is correctly capitalized (is not “allfips”)
  • Make sure FLAPS names are right in R code (“12_min”)

Compile fail

  • Check that your makefile shows the following, and edit if not using nano makefile. The top lines (CC through INCLUDE) may vary by system, as they are pointers to local directories for required libraries.
CC        =g++
CFLAGS    =-c -std=gnu++11 -Wall -O3 -I/curc/sw/gsl/2.1/gcc/6.1.0/include
LDFLAGS   =-lstdc++ -L/curc/sw/gsl/2.1/gcc/6.1.0/lib -lgsl -lgslcblas -lm
INCLUDE   =-I./include/
OBJDIR    =obj/

# Backslash for linebreak, and comment is #, but beware, it affects the *whole* line.
OBJLIST   = Point.o Farm.o Shipment_kernel.o \
                        Region.o County.o State.o Grid_cell.o Grid_checker.o \
                        Grid_manager.o Status_manager.o shared_functions.o \
                        File_manager.o main.o Control_manager.o Shipment_manager.o \
                        Local_spread.o Control_resource.o USAMM_parameters.o Population_manager.o

OBJECTS   = $(addprefix $(OBJDIR), $(OBJLIST) )

all:USDOSv2_new

USDOSv2_new: $(OBJECTS)
        $(CC) $(LDFLAGS) $(OBJECTS) -o $@

$(OBJECTS): ./$(OBJDIR)%.o: src/%.cpp
        $(CC) $(CFLAGS) $? -o $@ $(INCLUDE)

clean:
        rm obj/*.o
  • If your makefile is correct and it is still failing to compile, you will need to change the #include <gsl_xxxx.h> and #include “gsl_xxxx.h” lines to #include <gsl/gsl_xxxx.h> and #include “gsl/gsl_xxxx.h” in the following files:

    • include/County.h
    • include/State.h
    • include/Shipment_manager.h
    • src/County.cpp
    • src/State.cpp
    • src/Shipment_manager.cpp
    • Note: If the error looks anything like items that you are supposed to change when updating, follow these instructions
  • Always double check the makefile if you get further errors. Any time it errors and a restart of ‘make’ is needed, use:

make clean
make

The model runs, but only produces .err and .out files

  • Look into these files
  • If the last line refers to a file, re-download it and try again (might have an end of line error)

Appendix: Example configuration files

This section includes an example configuration file for each of the standard run types: Base (no control), IP culling, IP & DC culling, IP Culling & DC vaccination, and IP culling & ring vaccination

Base (no control)

## One variable per row, comments start with #
## Empty rows ignored. Rows with numbers and without descriptions are placeholders for future variables.
## Arguments not provided should be replaced with '*'.
## Values in parentheses are the index in the vector where value is stored.
## '~' after the value indicates that this value is required
## '+' after the value indicates that one of these adjacent options is required
## 'x' after the value indicates that this feature is not yet functional

######################## Output settings ########################
base_flaps12_min_0001_01_20190513_ #(1) Batch name, used as prefix for output files. Only letters, numbers and underscore.
1 #(2) Summary output on/off (1/0) - one line per replicate with # infected, duration, seed info, run time
1 #(3) Detailed infection output on/off (1/0) - one line per exposed premises with time, source of infection, route of infection
0 #(4) Print grid cells on/off
0 #(5)xAdditional functionality under development. Do not change default value.
0 #(6)xAdditional functionality under development. Do not change default value.
* #(7)
* #(8)
* #(9)
* #(10)

######################## General settings ########################
FLAPS/flaps12_min_0001.txt #(11)~Name of file containing premises ID, FIPS, x, y, population - ie FLAPS_beefdairy_20151201_formatted.txt. Make sure the premises file doesn't have numbers in 1e+05 format (may happen with IDs)
beef,dairy          #(12)~List of species for which counts are provided in premises file, comma-separated
365 #(13)~Timesteps (days) to run
* #(14) Max infectious premises before stopping an outbreak (* = no limit)
1   #(15)~Verbose level: Output extra information to console as model runs (0=off, 1=basic steps, 2=debug)
0   #(16)x~Disabled
0   #(17)~Reverse x/y option: in case input file is entered as lat/long (y/x)(set to 1) instead of long/lat (x/y)(set to 0)
inputfiles/FIPS_20151805.txt #(18)~Name of file containing fips name, state name, area (m2), x, y. Tab separated.
0   #(19) Day of the year to start simulation/generation on (jan 1 = day 1). Must be 0 - 365. 0 = one random day [1-365].
* #(20)

######################## Infection-related settings ########################
allFips #(21)~Seed source, filename or "allFips". Filename is of file containing identifiers (FIPS codes or premisesIDs) from which to seed infection, one line per simulation. "allFips" specifies to choose from all counties containing premises. To seed from multiple premises at once, provide comma-separated premisesIDs in the file (one line per simulation).
fips #(22)~Seed file type - type of information provided per line of (21). "fips" = choose 1 premises at random within the FIPS code on a given line in (21) or in all FIPS, "singlePremises" = use the premisesID provided on a given line in (21), "multiplePremises" = use all comma separated premisesIDs on a given line in (21)
*   #(23)
1,1 #(24)~Susceptibility exponents(mu), species-specific & comma-separated in order listed in (12) 0.42,0.49
1,1 #(25)~Infectiousness exponents(omega), species-specific & comma-separated in order listed in (12) 0.41,0.2
1,1     #(26)~Susceptibility constants(a), species-specific & comma-separated in order listed in (12) 5.7, 1
10.252,10.252 #(27)~Infectiousness constants(b), species-specific & comma-separated in order listed in (12)0.00082,0.00083
0           #(28)~Kernel type for local (diffusion) spread: 0: k1/(1 + (distance/k2)^k3), 1: data file in (30), 2: k1/(1+d/k2)^k3
1.46e-08,1686.155,2.267 #(29)x~Kernel parameters k1, k2, k3
*               #(30) Name of file containing data-based local spread probabilities by distance, ie inputfiles/UKDataKernel.txt
5,0 #(31)~Mean, variance (around normal) days from premises exposure to infectiousness (latency duration)
7,0 #(32)~Mean, variance (around normal) days from premises infectiousness to immunity (infectiousness duration)
0 #(33)+Additional functionality under development. Do not change default value.
* #(34)+Additional functionality under development. Do not change default value.
* #(35)

######################## Grid-related settings ########################
*       #(36)+Filename containing grid cells (will override other options)
*       #(37)+Length of cell side for uniform cells (will override density options)
500,100000  #(38)+Max farms per cell, cell size minimum side length in m
* #(39)
* #(40)

######################## Shipment-related settings ########################
1 #(41)~Method(s) to generate county-county shipments (USAMM), comma-separated (1 = USAMM version 1, -1 = shipments off)
1   #(42)~Timepoints at which to begin using each of the methods above (first timepoint must be 1), comma-separated
0   #(43)xAdditional functionality under development. Do not change default value.
inputfiles/usammv1_beef.res, inputfiles/usammv1_dairy.res #(44) Output files from USAMM with parameters for a, b, N, s and covariates
Q1 #(45) Additional functionality under development. Do not change default value.
1 #(46) Additional functionality under development. Do not change default value.
*,* #(47) Origin covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(48) Destination covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(49) Disabled
1 #(50) Exposed shipments, shipping from a farm with status exposed will cause the receiver to become exposed as well. 1 = on, 0 = off

######################## Control-related settings ########################
* #(51)~Names for unique control types, comma-separated (fixed options: shipBan, cull, vax) '*' will turn off control.
noLimit,stateSum    #(52) Control constraint function types, comma-separated
0;240,0 #(53) Control constraint parameters, comma-separated parameters, SEMICOLON-separated by type. stateSum: constraint is mean/var max animals/day/premises. 20 cows/hr*12 hrs/day = 240
state,premises #(54)~Spatial scale at which control is applied, comma-separated (fixed options: premises, county (shipBan only), state (shipBan only))
NA;inputfiles/landfills_flaps12_min_0001.txt #(55) List additional files here, comma-separated, SEMICOLON-separated by type
NA;resourceLocs #(56) Specify file types for (55) here: (NA, resourceLocs) comma-separated, SEMICOLON-separated by type
0,0 #(57)~Implemented to effective: mean number of days, comma-separated for each control type
0,0 #(58)~Implemented to effective: variance number of days, comma-separated for each control type
366,366 #(59)~Effective to inactive: mean number of days, comma-separated for each control type
0,0 #(60)~Effective to inactive: variance number of days, comma-separated for each control type
0,0;1,1 #(61)~Effectiveness (including compliance) of control types as proportion, comma-separated probability of preventing exposure given exposure and probability of transmission given infectiousness. SEMICOLON-separated by type.
* #(62)
* #(63)~Control triggers, comma-separated (fixed options). '*' will turn off control.
0,0 #(64)~Control trigger thresholds, comma-separated (numeric)
shipBan,cull #(65)~Control trigger responses, comma-separated (must exist in (51))
0,0 #(66)~Control response targets, comma-separated. -1 = DCs, 0 = triggers only, # = radius in units of x/y coordinates of premises
earliest,earliest #(67)~Control response priority, comma-separated. Currently only accepts earliest for each control type.
* #(68)
* #(69)
* #(70)

######################## Reporting and Tracing (DC) settings ########################
15,0 #(71)x~Mean, variance days from INDEX premises exposure to reporting
8,0 #(72)~Mean, variance days from (non-dangerous-contact) premises exposure to reporting
2,0 #(73)~Mean, variance days from (dangerous-contact) premises exposure to reporting
sus,4;exp,5 #(74) Dangerous Contact scaling parameters relative to risk: status, then scale, SEMICOLON-separated (only used if at least one of (66) is -1)
* #(75)

IP cull

## One variable per row, comments start with #
## Empty rows ignored. Rows with numbers and without descriptions are placeholders for future variables.
## Arguments not provided should be replaced with '*'.
## Values in parentheses are the index in the vector where value is stored.
## '~' after the value indicates that this value is required
## '+' after the value indicates that one of these adjacent options is required
## 'x' after the value indicates that this feature is not yet functional

######################## Output settings ########################
IP_MvmtBan_90_flaps12_min_0001_01_20190513_ #(1) Batch name, used as prefix for output files. Only letters, numbers and underscore.
1 #(2) Summary output on/off (1/0) - one line per replicate with # infected, duration, seed info, run time
1 #(3) Detailed infection output on/off (1/0) - one line per exposed premises with time, source of infection, route of infection
0 #(4) Print grid cells on/off
0 #(5)xAdditional functionality under development. Do not change default value.
0 #(6)xAdditional functionality under development. Do not change default value.
* #(7)
* #(8)
* #(9)
* #(10)

######################## General settings ########################
FLAPS/flaps12_min_0001.txt #(11)~Name of file containing premises ID, FIPS, x, y, population - ie FLAPS_beefdairy_20151201_formatted.txt. Make sure the premises file doesn't have numbers in 1e+05 format (may happen with IDs)
beef,dairy          #(12)~List of species for which counts are provided in premises file, comma-separated
365 #(13)~Timesteps (days) to run
* #(14) Max infectious premises before stopping an outbreak (* = no limit)
1   #(15)~Verbose level: Output extra information to console as model runs (0=off, 1=basic steps, 2=debug)
0   #(16)x~ Disabled
0   #(17)~Reverse x/y option: in case input file is entered as lat/long (y/x)(set to 1) instead of long/lat (x/y)(set to 0)
inputfiles/FIPS_20151805.txt #(18)~Name of file containing fips name, state name, area (m2), x, y. Tab separated.
0   #(19) Day of the year to start simulation/generation on (jan 1 = day 1). Must be 0 - 365. 0 = one random day [1-365].
* #(20)

######################## Infection-related settings ########################
allFips #(21)~Seed source, filename or "allFips". Filename is of file containing identifiers (FIPS codes or premisesIDs) from which to seed infection, one line per simulation. "allFips" specifies to choose from all counties containing premises. To seed from multiple premises at once, provide comma-separated premisesIDs in the file (one line per simulation).
fips #(22)~Seed file type - type of information provided per line of (21). "fips" = choose 1 premises at random within the FIPS code on a given line in (21) or in all FIPS, "singlePremises" = use the premisesID provided on a given line in (21), "multiplePremises" = use all comma separated premisesIDs on a given line in (21)
*   #(23)
1,1 #(24)~Susceptibility exponents(mu), species-specific & comma-separated in order listed in (12) 0.42,0.49
1,1 #(25)~Infectiousness exponents(omega), species-specific & comma-separated in order listed in (12) 0.41,0.2
1,1     #(26)~Susceptibility constants(a), species-specific & comma-separated in order listed in (12) 5.7,1
10.252,10.252 #(27)~Infectiousness constants(b), species-specific & comma-separated in order listed in (12)0.00082,0.00083
0           #(28)~Kernel type for local (diffusion) spread: 0: k1/(1 + (distance/k2)^k3), 1: data file in (30), 2: k1/(1+d/k2)^k3
1.46e-08,1686.155,2.267 #(29)x~Kernel parameters k1, k2, k3
*               #(30) Name of file containing data-based local spread probabilities by distance, ie inputfiles/UKDataKernel.txt
5,0 #(31)~Mean, variance (around normal) days from premises exposure to infectiousness (latency duration)
7,0 #(32)~Mean, variance (around normal) days from premises infectiousness to immunity (infectiousness duration)
0 #(33)+Additional functionality under development. Do not change default value.
* #(34)+Additional functionality under development. Do not change default value.
* #(35)

######################## Grid-related settings ########################
*               #(36)+Filename containing grid cells (will override other options)
*               #(37)+Length of cell side for uniform cells (will override density options)
500,100000  #(38)+Max farms per cell, cell size minimum side length in m
* #(39)
* #(40)

######################## Shipment-related settings ########################
1 #(41)~Method(s) to generate county-county shipments (USAMM), comma-separated (1 = USAMM version 1, -1 = shipments off)
1   #(42)~Timepoints at which to begin using each of the methods above (first timepoint must be 1), comma-separated
0   #(43)xAdditional functionality under development. Do not change default value.
inputfiles/usammv1_beef.res, inputfiles/usammv1_dairy.res #(44) Output files from USAMM with parameters for a, b, N, s and covariates
Q1 #(45) Additional functionality under development. Do not change default value.
1 #(46) Additional functionality under development. Do not change default value.
*,* #(47) Origin covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(48) Destination covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(49) Disabled
1 #(50) Exposed shipments, shipping from a farm with status exposed will cause the receiver to become exposed as well. 1 = on, 0 = off

######################## Control-related settings ########################
shipBan,cull #(51)~Names for unique control types, comma-separated (fixed options: shipBan, cull, vax) '*' will turn off control.
noLimit,stateSum    #(52) Control constraint function types, comma-separated
0;240,0 #(53) Control constraint parameters, comma-separated parameters, SEMICOLON-separated by type. stateSum: constraint is mean/var max animals/day/premises. 20 cows/hr*12 hrs/day = 240
state,premises #(54)~Spatial scale at which control is applied, comma-separated (fixed options: premises, county (shipBan only), state (shipBan only))
NA;inputfiles/landfills_flaps12_min_0001.txt #(55) List additional files here, comma-separated, SEMICOLON-separated by type
NA;resourceLocs #(56) Specify file types for (55) here: (NA, resourceLocs) comma-separated, SEMICOLON-separated by type
0,0 #(57)~Implemented to effective: mean number of days, comma-separated for each control type
0,0 #(58)~Implemented to effective: variance number of days, comma-separated for each control type
366,366 #(59)~Effective to inactive: mean number of days, comma-separated for each control type
0,0 #(60)~Effective to inactive: variance number of days, comma-separated for each control type
0.9,0.9;1,1 #(61)~Effectiveness (including compliance) of control types as proportion, comma-separated probability of preventing exposure given exposure and probability of transmission given infectiousness. SEMICOLON-separated by type.
* #(62)
newRegionReportsOverX,newPremReportsOverX #(63)~Control triggers, comma-separated (fixed options). '*' will turn off control.
0,0 #(64)~Control trigger thresholds, comma-separated (numeric)
shipBan,cull #(65)~Control trigger responses, comma-separated (must exist in (51))
0,0 #(66)~Control response targets, comma-separated. -1 = DCs, 0 = triggers only, # = radius in units of x/y coordinates of premises
earliest,earliest #(67)~Control response priority, comma-separated. Currently only accepts earliest for each control type.
* #(68)
* #(69)
* #(70)

######################## Reporting and Tracing (DC) settings ########################
15,0 #(71)x~Mean, variance days from INDEX premises exposure to reporting
8,0 #(72)~Mean, variance days from (non-dangerous-contact) premises exposure to reporting
2,0 #(73)~Mean, variance days from (dangerous-contact) premises exposure to reporting
sus,4;exp,5 #(74) Dangerous Contact scaling parameters relative to risk: status, then scale, SEMICOLON-separated (only used if at least one of (66) is -1)
* #(75)

IP & DC cull

## One variable per row, comments start with #
## Empty rows ignored. Rows with numbers and without descriptions are placeholders for future variables.
## Arguments not provided should be replaced with '*'.
## Values in parentheses are the index in the vector where value is stored.
## '~' after the value indicates that this value is required
## '+' after the value indicates that one of these adjacent options is required
## 'x' after the value indicates that this feature is not yet functional

######################## Output settings ########################
IP_DC_MvmtBan_90_flaps12_min_0001_01_20190513_ #(1) Batch name, used as prefix for output files. Only letters, numbers and underscore.
1 #(2) Summary output on/off (1/0) - one line per replicate with # infected, duration, seed info, run time
1 #(3) Detailed infection output on/off (1/0) - one line per exposed premises with time, source of infection, route of infection
0 #(4) Print grid cells on/off
0 #(5)xAdditional functionality under development. Do not change default value.
0 #(6)xAdditional functionality under development. Do not change default value.
* #(7)
* #(8)
* #(9)
* #(10)

######################## General settings ########################
FLAPS/flaps12_min_0001.txt #(11)~Name of file containing premises ID, FIPS, x, y, population - ie FLAPS_beefdairy_20151201_formatted.txt. Make sure the premises file doesn't have numbers in 1e+05 format (may happen with IDs)
beef,dairy          #(12)~List of species for which counts are provided in premises file, comma-separated
365 #(13)~Timesteps (days) to run
* #(14) Max infectious premises before stopping an outbreak (* = no limit)
1   #(15)~Verbose level: Output extra information to console as model runs (0=off, 1=basic steps, 2=debug)
0   #(16)x~Disabled
0   #(17)~Reverse x/y option: in case input file is entered as lat/long (y/x)(set to 1) instead of long/lat (x/y)(set to 0)
inputfiles/FIPS_20151805.txt #(18)~Name of file containing fips name, state name, area (m2), x, y. Tab separated.
0   #(19) Day of the year to start simulation/generation on (jan 1 = day 1). Must be 0 - 365. 0 = one random day [1-365].
* #(20)

######################## Infection-related settings ########################
allFips #(21)~Seed source, filename or "allFips". Filename is of file containing identifiers (FIPS codes or premisesIDs) from which to seed infection, one line per simulation. "allFips" specifies to choose from all counties containing premises. To seed from multiple premises at once, provide comma-separated premisesIDs in the file (one line per simulation).
fips #(22)~Seed file type - type of information provided per line of (21). "fips" = choose 1 premises at random within the FIPS code on a given line in (21) or in all FIPS, "singlePremises" = use the premisesID provided on a given line in (21), "multiplePremises" = use all comma separated premisesIDs on a given line in (21)
*   #(23)
1,1 #(24)~Susceptibility exponents(mu), species-specific & comma-separated in order listed in (12) 0.42,0.49
1,1 #(25)~Infectiousness exponents(omega), species-specific & comma-separated in order listed in (12) 0.41,0.2
1,1     #(26)~Susceptibility constants(a), species-specific & comma-separated in order listed in (12) 5.7,1
10.252,10.252 #(27)~Infectiousness constants(b), species-specific & comma-separated in order listed in (12) 0.00082,0.00083
0           #(28)~Kernel type for local (diffusion) spread: 0: k1/(1 + (distance/k2)^k3), 1: data file in (30), 2: k1/(1+d/k2)^k3
1.46e-08,1686.155,2.267 #(29)x~Kernel parameters k1, k2, k3
*               #(30) Name of file containing data-based local spread probabilities by distance, ie inputfiles/UKDataKernel.txt
5,0 #(31)~Mean, variance (around normal) days from premises exposure to infectiousness (latency duration)
7,0 #(32)~Mean, variance (around normal) days from premises infectiousness to immunity (infectiousness duration)
0 #(33)+Additional functionality under development. Do not change default value.
* #(34)+Additional functionality under development. Do not change default value.
* #(35)

######################## Grid-related settings ########################
*               #(36)+Filename containing grid cells (will override other options)
*               #(37)+Length of cell side for uniform cells (will override density options)
500,100000  #(38)+Max farms per cell, cell size minimum side length in m
* #(39)
* #(40)

######################## Shipment-related settings ########################
1 #(41)~Method(s) to generate county-county shipments (USAMM), comma-separated (1 = USAMM version 1, -1 = shipments off)
1   #(42)~Timepoints at which to begin using each of the methods above (first timepoint must be 1), comma-separated
0   #(43)xAdditional functionality under development. Do not change default value.
inputfiles/usammv1_beef.res, inputfiles/usammv1_dairy.res #(44) Output files from USAMM with parameters for a, b, N, s and covariates
Q1 #(45) Additional functionality under development. Do not change default value.
1 #(46) Additional functionality under development. Do not change default value.
*,* #(47) Origin covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(48) Destination covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(49) Disabled
1 #(50) Exposed shipments, shipping from a farm with status exposed will cause the receiver to become exposed as well. 1 = on, 0 = off

######################## Control-related settings ########################
shipBan,cull #(51)~Names for unique control types, comma-separated (fixed options: shipBan, cull, vax) '*' will turn off control.
noLimit,stateSum    #(52) Control constraint function types, comma-separated
0;240,0 #(53) Control constraint parameters, comma-separated parameters, SEMICOLON-separated by type. stateSum: constraint is mean/var max animals/day/premises. 20 cows/hr*12 hrs/day = 240
state,premises #(54)~Spatial scale at which control is applied, comma-separated (fixed options: premises, county (shipBan only), state (shipBan only))
NA;inputfiles/landfills_flaps12_min_0001.txt #(55) List additional files here, comma-separated, SEMICOLON-separated by type
NA;resourceLocs #(56) Specify file types for (55) here: (NA, resourceLocs) comma-separated, SEMICOLON-separated by type
0,0 #(57)~Implemented to effective: mean number of days, comma-separated for each control type
0,0 #(58)~Implemented to effective: variance number of days, comma-separated for each control type
366,366 #(59)~Effective to inactive: mean number of days, comma-separated for each control type
0,0 #(60)~Effective to inactive: variance number of days, comma-separated for each control type
0.9,0.9;1,1 #(61)~Effectiveness (including compliance) of control types as proportion, comma-separated probability of preventing exposure given exposure and probability of transmission given infectiousness. SEMICOLON-separated by type.
* #(62)
newRegionReportsOverX,newPremReportsOverX,newPremReportsOverX #(63)~Control triggers, comma-separated (fixed options). '*' will turn off control.
0,0,0 #(64)~Control trigger thresholds, comma-separated (numeric)
shipBan,cull,cull #(65)~Control trigger responses, comma-separated (must exist in (51))
0,0,-1 #(66)~Control response targets, comma-separated. -1 = DCs, 0 = triggers only, # = radius in units of x/y coordinates of premises
earliest,earliest,earliest #(67)~Control response priority, comma-separated. Currently only accepts earliest for each control type.
* #(68)
* #(69)
* #(70)

######################## Reporting and Tracing (DC) settings ########################
15,0 #(71)x~Mean, variance days from INDEX premises exposure to reporting
8,0 #(72)~Mean, variance days from (non-dangerous-contact) premises exposure to reporting
2,0 #(73)~Mean, variance days from (dangerous-contact) premises exposure to reporting
sus,4;exp,5 #(74) Dangerous Contact scaling parameters relative to risk: status, then scale, SEMICOLON-separated (only used if at least one of (66) is -1)
* #(75)

IP cull & DC vaccination

## One variable per row, comments start with #
## Empty rows ignored. Rows with numbers and without descriptions are placeholders for future variables.
## Arguments not provided should be replaced with '*'.
## Values in parentheses are the index in the vector where value is stored.
## '~' after the value indicates that this value is required
## '+' after the value indicates that one of these adjacent options is required
## 'x' after the value indicates that this feature is not yet functional

######################## Output settings ########################
IP_VAX_MvmtBan_90_flaps12_min_0001_01_20190513_ #(1) Batch name, used as prefix for output files. Only letters, numbers and underscore.
1 #(2) Summary output on/off (1/0) - one line per replicate with # infected, duration, seed info, run time
1 #(3) Detailed infection output on/off (1/0) - one line per exposed premises with time, source of infection, route of infection
0 #(4) Print grid cells on/off
0 #(5)xAdditional functionality under development. Do not change default value.
0 #(6)xAdditional functionality under development. Do not change default value.
* #(7)
* #(8)
* #(9)
* #(10)

######################## General settings ########################
FLAPS/flaps12_min_0001.txt #(11)~Name of file containing premises ID, FIPS, x, y, population - ie FLAPS_beefdairy_20151201_formatted.txt. Make sure the premises file doesn't have numbers in 1e+05 format (may happen with IDs)
beef,dairy          #(12)~List of species for which counts are provided in premises file, comma-separated
365 #(13)~Timesteps (days) to run
* #(14) Max infectious premises before stopping an outbreak (* = no limit)
1   #(15)~Verbose level: Output extra information to console as model runs (0=off, 1=basic steps, 2=debug)
0   #(16)x~Disabled
0   #(17)~Reverse x/y option: in case input file is entered as lat/long (y/x)(set to 1) instead of long/lat (x/y)(set to 0)
inputfiles/FIPS_20151805.txt #(18)~Name of file containing fips name, state name, area (m2), x, y. Tab separated.
0   #(19) Day of the year to start simulation/generation on (jan 1 = day 1). Must be 0 - 365. 0 = one random day [1-365].
* #(20)

######################## Infection-related settings ########################
allFips #(21)~Seed source, filename or "allFips". Filename is of file containing identifiers (FIPS codes or premisesIDs) from which to seed infection, one line per simulation. "allFips" specifies to choose from all counties containing premises. To seed from multiple premises at once, provide comma-separated premisesIDs in the file (one line per simulation).
fips #(22)~Seed file type - type of information provided per line of (21). "fips" = choose 1 premises at random within the FIPS code on a given line in (21) or in all FIPS, "singlePremises" = use the premisesID provided on a given line in (21), "multiplePremises" = use all comma separated premisesIDs on a given line in (21)
*   #(23)
1,1 #(24)~Susceptibility exponents(mu), species-specific & comma-separated in order listed in (12) 0.42,0.49
1,1 #(25)~Infectiousness exponents(omega), species-specific & comma-separated in order listed in (12) 0.41,0.2
1,1     #(26)~Susceptibility constants(a), species-specific & comma-separated in order listed in (12) 5.7,1
10.252,10.252 #(27)~Infectiousness constants(b), species-specific & comma-separated in order listed in (12)0.00082,0.00083
0           #(28)~Kernel type for local (diffusion) spread: 0: k1/(1 + (distance/k2)^k3), 1: data file in (30), 2: k1/(1+d/k2)^k3
1.46e-08,1686.155,2.267 #(29)x~Kernel parameters k1, k2, k3
*       #(30) Name of file containing data-based local spread probabilities by distance, ie inputfiles/UKDataKernel.txt
5,0 #(31)~Mean, variance (around normal) days from premises exposure to infectiousness (latency duration)
7,0 #(32)~Mean, variance (around normal) days from premises infectiousness to immunity (infectiousness duration)
0 #(33)+Additional functionality under development. Do not change default value.
* #(34)+Additional functionality under development. Do not change default value.
* #(35)

######################## Grid-related settings ########################
*               #(36)+Filename containing grid cells (will override other options)
*               #(37)+Length of cell side for uniform cells (will override density options)
500,100000  #(38)+Max farms per cell, cell size minimum side length in m
* #(39)
* #(40)

######################## Shipment-related settings ########################
1 #(41)~Method(s) to generate county-county shipments (USAMM), comma-separated (1 = USAMM version 1, -1 = shipments off)
1   #(42)~Timepoints at which to begin using each of the methods above (first timepoint must be 1), comma-separated
0   #(43)xAdditional functionality under development. Do not change default value.
inputfiles/usammv1_beef.res, inputfiles/usammv1_dairy.res #(44) Output files from USAMM with parameters for a, b, N, s and covariates
Q1 #(45) Additional functionality under development. Do not change default value.
1 #(46) Additional functionality under development. Do not change default value.
*,* #(47) Origin covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(48) Destination covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(49) Disabled
1 #(50) Exposed shipments, shipping from a farm with status exposed will cause the receiver to become exposed as well. 1 = on, 0 = off

######################## Control-related settings ########################
shipBan,cull,vax #(51)~Names for unique control types, comma-separated (fixed options: shipBan, cull, vax) '*' will turn off control.
noLimit,stateSum,dailyLimit #(52) Control constraint function types, comma-separated
0;240,0;6804,0 #(53) Control constraint parameters, comma-separated parameters, SEMICOLON-separated by type. stateSum: constraint is mean/var max animals/day/premises. 20 cows/hr*12 hrs/day = 240
state,premises,premises #(54)~Spatial scale at which control is applied, comma-separated (fixed options: premises, county (shipBan only), state (shipBan only))
NA;inputfiles/landfills_flaps12_min_0001.txt;inputfiles/vaccineBankUpdated.txt #(55) List additional files here, comma-separated, SEMICOLON-separated by type
NA;resourceLocs;resourceBoosts #(56) Specify file types for (55) here: (NA, resourceLocs) comma-separated, SEMICOLON-separated by type
0,0,11 #(57)~Implemented to effective: mean number of days, comma-separated for each control type
0,0,0 #(58)~Implemented to effective: variance number of days, comma-separated for each control type
366,366,183 #(59)~Effective to inactive: mean number of days, comma-separated for each control type
0,0,0   #(60)~Effective to inactive: variance number of days, comma-separated for each control type
0.9,0.9;1,1;0.9,0.9 #(61)~Effectiveness (including compliance) of control types as proportion, comma-separated probability of preventing exposure given exposure and probability of transmission given infectiousness. SEMICOLON-separated by type.
* #(62)
newRegionReportsOverX,newPremReportsOverX,newPremReportsOverX #(63)~Control triggers, comma-separated (fixed options). '*' will turn off control.
0,0,0 #(64)~Control trigger thresholds, comma-separated (numeric)
shipBan,cull,vax #(65)~Control trigger responses, comma-separated (must exist in (51))
0,0,-1 #(66)~Control response targets, comma-separated. -1 = DCs, 0 = triggers only, # = radius in units of x/y coordinates of premises
earliest,earliest,earliest #(67)~Control response priority, comma-separated. Currently only accepts earliest for each control type.
* #(68)
* #(69)
* #(70)

######################## Reporting and Tracing (DC) settings ########################
15,0 #(71)x~Mean, variance days from INDEX premises exposure to reporting
8,0 #(72)~Mean, variance days from (non-dangerous-contact) premises exposure to reporting
2,0 #(73)~Mean, variance days from (dangerous-contact) premises exposure to reporting
sus,4;exp,5 #(74) Dangerous Contact scaling parameters relative to risk: status, then scale, SEMICOLON-separated (only used if at least one of (66) is -1)
* #(75)

IP cull & ring vaccination

## One variable per row, comments start with #
## Empty rows ignored. Rows with numbers and without descriptions are placeholders for future variables.
## Arguments not provided should be replaced with '*'.
## Values in parentheses are the index in the vector where value is stored.
## '~' after the value indicates that this value is required
## '+' after the value indicates that one of these adjacent options is required
## 'x' after the value indicates that this feature is not yet functional

######################## Output settings ########################
IP_VAX_3km_MvmtBan_90_flaps12_min_0001_01_20190513_ #(1) Batch name, used as prefix for output files. Only letters, numbers and underscore.
1 #(2) Summary output on/off (1/0) - one line per replicate with # infected, duration, seed info, run time
1 #(3) Detailed infection output on/off (1/0) - one line per exposed premises with time, source of infection, route of infection
0 #(4) Print grid cells on/off
0 #(5)xAdditional functionality under development. Do not change default value.
0 #(6)xAdditional functionality under development. Do not change default value.
* #(7)
* #(8)
* #(9)
* #(10)

######################## General settings ########################
FLAPS/flaps12_min_0001.txt #(11)~Name of file containing premises ID, FIPS, x, y, population - ie FLAPS_beefdairy_20151201_formatted.txt. Make sure the premises file doesn't have numbers in 1e+05 format (may happen with IDs)
beef,dairy          #(12)~List of species for which counts are provided in premises file, comma-separated
365 #(13)~Timesteps (days) to run
* #(14) Max infectious premises before stopping an outbreak (* = no limit)
1   #(15)~Verbose level: Output extra information to console as model runs (0=off, 1=basic steps, 2=debug)
0   #(16)x~Disabled
0   #(17)~Reverse x/y option: in case input file is entered as lat/long (y/x)(set to 1) instead of long/lat (x/y)(set to 0)
inputfiles/FIPS_20151805.txt #(18)~Name of file containing fips name, state name, area (m2), x, y. Tab separated.
0   #(19) Day of the year to start simulation/generation on (jan 1 = day 1). Must be 0 - 365. 0 = one random day [1-365].
* #(20)

######################## Infection-related settings ########################
allFips #(21)~Seed source, filename or "allFips". Filename is of file containing identifiers (FIPS codes or premisesIDs) from which to seed infection, one line per simulation. "allFips" specifies to choose from all counties containing premises. To seed from multiple premises at once, provide comma-separated premisesIDs in the file (one line per simulation).
fips #(22)~Seed file type - type of information provided per line of (21). "fips" = choose 1 premises at random within the FIPS code on a given line in (21) or in all FIPS, "singlePremises" = use the premisesID provided on a given line in (21), "multiplePremises" = use all comma separated premisesIDs on a given line in (21)
*   #(23)
1,1 #(24)~Susceptibility exponents(mu), species-specific & comma-separated in order listed in (12) 0.42,0.49
1,1 #(25)~Infectiousness exponents(omega), species-specific & comma-separated in order listed in (12) 0.41,0.2
1,1     #(26)~Susceptibility constants(a), species-specific & comma-separated in order listed in (12) 5.7,1
10.252,10.252 #(27)~Infectiousness constants(b), species-specific & comma-separated in order listed in (12)0.00082,0.00083
0           #(28)~Kernel type for local (diffusion) spread: 0: k1/(1 + (distance/k2)^k3), 1: data file in (30), 2: k1/(1+d/k2)^k3
1.46e-08,1686.155,2.267 #(29)x~Kernel parameters k1, k2, k3
*       #(30) Name of file containing data-based local spread probabilities by distance, ie inputfiles/UKDataKernel.txt
5,0 #(31)~Mean, variance (around normal) days from premises exposure to infectiousness (latency duration)
7,0 #(32)~Mean, variance (around normal) days from premises infectiousness to immunity (infectiousness duration)
0 #(33)+Additional functionality under development. Do not change default value.
* #(34)+Additional functionality under development. Do not change default value.
* #(35)

######################## Grid-related settings ########################
*               #(36)+Filename containing grid cells (will override other options)
*               #(37)+Length of cell side for uniform cells (will override density options)
500,100000  #(38)+Max farms per cell, cell size minimum side length in m
* #(39)
* #(40)

######################## Shipment-related settings ########################
1 #(41)~Method(s) to generate county-county shipments (USAMM), comma-separated (1 = USAMM version 1, -1 = shipments off)
1   #(42)~Timepoints at which to begin using each of the methods above (first timepoint must be 1), comma-separated
0   #(43)xAdditional functionality under development. Do not change default value.
inputfiles/usammv1_beef.res, inputfiles/usammv1_dairy.res #(44) Output files from USAMM with parameters for a, b, N, s and covariates
Q1 #(45) Additional functionality under development. Do not change default value.
1 #(46) Additional functionality under development. Do not change default value.
*,* #(47) Origin covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(48) Destination covariates for all counties. One file for each species, comma separated. Must have header: FIPS, name1, name2... Names must match name component of covariate parameters in USAMM parameter file.
*,* #(49) Disabled
1 #(50) Exposed shipments, shipping from a farm with status exposed will cause the receiver to become exposed as well. 1 = on, 0 = off

######################## Control-related settings ########################
shipBan,cull,vax #(51)~Names for unique control types, comma-separated (fixed options: shipBan, cull, vax) '*' will turn off control.
noLimit,stateSum,dailyLimit #(52) Control constraint function types, comma-separated
0;240,0;6804,0 #(53) Control constraint parameters, comma-separated parameters, SEMICOLON-separated by type. stateSum: constraint is mean/var max animals/day/premises. 20 cows/hr*12 hrs/day = 240
state,premises,premises #(54)~Spatial scale at which control is applied, comma-separated (fixed options: premises, county (shipBan only), state (shipBan only))
NA;inputfiles/landfills_flaps12_min_0001.txt;inputfiles/vaccineBankUpdated.txt #(55) List additional files here, comma-separated, SEMICOLON-separated by type
NA;resourceLocs;resourceBoosts #(56) Specify file types for (55) here: (NA, resourceLocs) comma-separated, SEMICOLON-separated by type
0,0,11 #(57)~Implemented to effective: mean number of days, comma-separated for each control type
0,0,0 #(58)~Implemented to effective: variance number of days, comma-separated for each control type
366,366,183 #(59)~Effective to inactive: mean number of days, comma-separated for each control type
0,0,0   #(60)~Effective to inactive: variance number of days, comma-separated for each control type
0.9,0.9;1,1;0.9,0.9 #(61)~Effectiveness (including compliance) of control types as proportion, comma-separated probability of preventing exposure given exposure and probability of transmission given infectiousness. SEMICOLON-separated by type.
* #(62)
newRegionReportsOverX,newPremReportsOverX,newPremReportsOverX #(63)~Control triggers, comma-separated (fixed options). '*' will turn off control.
0,0,0 #(64)~Control trigger thresholds, comma-separated (numeric)
shipBan,cull,vax #(65)~Control trigger responses, comma-separated (must exist in (51))
0,0,3000 #(66)~Control response targets, comma-separated. -1 = DCs, 0 = triggers only, # = radius in units of x/y coordinates of premises
earliest,earliest,earliest #(67)~Control response priority, comma-separated. Currently only accepts earliest for each control type.
* #(68)
* #(69)
* #(70)

######################## Reporting and Tracing (DC) settings ########################
15,0 #(71)x~Mean, variance days from INDEX premises exposure to reporting
8,0 #(72)~Mean, variance days from (non-dangerous-contact) premises exposure to reporting
2,0 #(73)~Mean, variance days from (dangerous-contact) premises exposure to reporting
sus,4;exp,5 #(74) Dangerous Contact scaling parameters relative to risk: status, then scale, SEMICOLON-separated (only used if at least one of (66) is -1)
* #(75)

Acknowledgements & Contact Information

This work is supported by funding provided by the U.S. Department of Homeland Security Science and Technology Directorate under contract numbers HSHQDC-13-B0028, and D15PC00278.

The findings and conclusions in this preliminary publication have not been formally disseminated by the U.S. Department of Agriculture and should not be construed to represent any agency determination or policy. The analyses, views and conclusions contained in this document are those of the authors and should not be interpreted as representing the regulatory opinions, official policies, either expressed or implied, of the U.S. Department of Homeland Security.

If you have questions or comments regarding USDOS or this User Manual, please contact Dr. Colleen Webb at .