Configuration file

The primary means of configuring the disease simulation is the configuration file. This required file is a JSON (JavaScript Object Notation) formatted file that is typically named config.json. The configuration file controls many different aspects of the simulation. For example,

  • The names of the campaign file and other input files to use

  • How to use additional demographics, climate, and migration data (such as enabling features or scaling values)

  • General disease attributes such as infectivity, immunity, mortality, and so on

  • Attributes specific to the disease type being modeled, such as infectivity and mortality

  • The reports to output from the simulation

Although you can create configuration files entirely from scratch, it is often easier to start from an existing configuration file and modify it to meet your needs. You can download sets of configuration and campaign files that illustrate how to model different disease scenarios at EMOD scenarios. For more information, see Tutorials and simulation examples.

The simplest method of working with the configuration files is to use a text editor to directly edit the parameters or parameter values in the JSON file. However, you may want to use Python or another scripting language to make large modifications. See Example scripts to modify a configuration file for more information.

For a complete list of configuration parameters that are available to use with this simulation type, see Configuration parameters. For more information about JSON, see EMOD parameter reference.

Flattened configuration files

A flattened configuration file is generally a single-depth JSON file with configuration parameters listed alphabetically. This is the configuration file format that Eradication.exe and Eradication binary for Linux both require for running simulations.

Below is an example of a flattened configuration file:

{
  "parameters": {
    "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
    "Base_Infectivity": 0.3,
    "Climate_Model": "CLIMATE_OFF",
    "Config_Name": "1_Generic_MinimalConfig",
    "Custom_Reports_Filename": "",
    "Default_Geography_Initial_Node_Population": 100,
    "Default_Geography_Torus_Size": 3,
    "Enable_Default_Reporting": 1,
    "Enable_Demographics_Builtin": 1,
    "Enable_Demographics_Reporting": 0,
    "Enable_Demographics_Risk": 0,
    "Enable_Disease_Mortality": 0,
    "Enable_Heterogeneous_Intranode_Transmission": 0,
    "Enable_Immunity": 0,
    "Enable_Initial_Prevalence": 0,
    "Enable_Initial_Susceptibility_Distribution": 0,
    "Enable_Interventions": 0,
    "Enable_Maternal_Infection_Transmission": 0,
    "Enable_Maternal_Protection": 0,
    "Enable_Property_Output": 0,
    "Enable_Skipping": 0,
    "Enable_Spatial_Output": 0,
    "Enable_Superinfection": 0,
    "Enable_Susceptibility_Scaling": 0,
    "Enable_Vital_Dynamics": 0,
    "Geography": "NONE",
    "Incubation_Period_Constant": 3,
    "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Individual_Sampling_Type": "TRACK_ALL",
    "Infection_Updates_Per_Timestep": 1,
    "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Exponential": 7,    
    "Listed_Events": [],
    "Load_Balance_Filename": "",
    "Maternal_Infection_Transmission_Probability": 0,
    "Migration_Model": "NO_MIGRATION",
    "Node_Grid_Size": 0.042,
    "Number_Basestrains": 1,
    "Number_Substrains": 1,
    "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY",
    "Population_Scale_Type": "USE_INPUT_FILE",
    "Report_Event_Recorder": 0,
    "Run_Number": 1,
    "Simulation_Duration": 180,
    "Simulation_Timestep": 1,
    "Simulation_Type": "GENERIC_SIM",
    "Start_Time": 0,
    "Symptomatic_Infectious_Offset": 0
  }
}

Hierarchical configuration files

A hierarchical file allows you to organize parameters into logical groups by nesting them within JSON objects, making them easier to manage. If you use hierarchical configuration files, you must flatten them prior to running a simulation. The names you use to label these logical categories are unimportant; the scripts used to flatten the files will search through the hierarchies and retain only the “leaf” values in the resulting flattened file. See Configuration overlay files for more information on flattening files.

Below is an example of a hierarchical configuration file:

{
  "parameters": {
    "CAMPAIGNS": {
      "Campaign_Filename": "campaign.json",
      "Enable_Interventions": 1,
      "Listed_Events": [],
      "PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT"
    },
    "CLIMATE": {
      "Climate_Model": "CLIMATE_OFF"
    },
    "DEMOGRAPHICS": {
      "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
      "Birth_Rate_Dependence": "DEMOGRAPHIC_DEP_RATE",
      "Birth_Rate_Time_Dependence": "NONE",
      "Default_Geography_Initial_Node_Population": 1000,
      "Default_Geography_Torus_Size": 10,
      "Demographics_Filenames": [
        "NO_DEFAULT_DEMOGRAPHICS"
      ],
      "Enable_Aging": 1,
      "Enable_Birth": 1,
      "Enable_Demographics_Birth": 0,
      "Enable_Demographics_Builtin": 0,
      "Enable_Demographics_Reporting": 0,
      "Enable_Demographics_Risk": 0,
      "Enable_Natural_Mortality": 1,
      "Enable_Vital_Dynamics": 1,
      "IMMUNITY": {
        "Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
        "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
        "Enable_Immune_Decay": 1,
        "Enable_Immunity": 1,
        "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
        "Post_Infection_Acquisition_Multiplier": 0,
        "Post_Infection_Transmission_Multiplier": 0,
        "Susceptibility_Scaling_Type": "CONSTANT_SUSCEPTIBILITY",
        "Transmission_Blocking_Immunity_Decay_Rate": 0.1,
        "Transmission_Blocking_Immunity_Duration_Before_Decay": 60
      },
      "MORTALITY": {
        "Base_Mortality": 0,
        "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER",
        "Enable_Disease_Mortality": 0,
        "Mortality_Blocking_Immunity_Decay_Rate": 0.001,
        "Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
        "Mortality_Time_Course": "DAILY_MORTALITY",
        "Post_Infection_Mortality_Multiplier": 0
      },
      "Minimum_Adult_Age_Years": 15,
      "Population_Density_C50": 30,
      "Population_Scale_Type": "USE_INPUT_FILE",
      "SAMPLING": {
        "Base_Individual_Sample_Rate": 1,
        "Individual_Sampling_Type": "TRACK_ALL",
        "Max_Node_Population_Samples": 40,
        "Sample_Rate_0_18mo": 1,
        "Sample_Rate_10_14": 1,
        "Sample_Rate_15_19": 1,
        "Sample_Rate_18mo_4yr": 1,
        "Sample_Rate_20_Plus": 1,
        "Sample_Rate_5_9": 1,
        "Sample_Rate_Birth": 2
      },
      "x_Base_Population": 1
    },
    "DISEASE": {
      "Enable_Superinfection": 0,
      "INCUBATION": {
        "Incubation_Period_Constant": 3,
        "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION"
      },
      "INFECTIOUSNESS": {
        "Base_Infectivity": 0.3,
        "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
        "Infectious_Period_Exponential": 7,        
        "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY"
      },
      "Infection_Updates_Per_Timestep": 1,
      "Max_Individual_Infections": 1,
      "TRANSMISSION": {
        "Enable_Maternal_Infection_Transmission": 0,
        "Maternal_Transmission_Probability": 0
      }
    },
    "FUDGE_FACTORS": {
      "x_Air_Migration": 1,
      "x_Birth": 1,
      "x_Local_Migration": 1,
      "x_Other_Mortality": 1,
      "x_Regional_Migration": 1,
      "x_Sea_Migration": 1,
      "x_Temporary_Larval_Habitat": 1
    },
    "HPC": {
      "Load_Balance_Filename": ""
    },
    "INTRANODE_TRANSMISSION": {
      "Enable_Heterogeneous_Intranode_Transmission": 0
    },
    "MIGRATION": {
      "Migration_Model": "NO_MIGRATION"
    },
    "OUTPUT": {
      "Custom_Reports_Filename": "NoCustomReports",
      "Enable_Default_Reporting": 1,
      "Enable_Property_Output": 0,
      "Enable_Spatial_Output": 0,
      "Report_Event_Recorder": 0
    },
    "POLIO": {},
    "PRIMARY": {
      "Config_Name": "DEFAULT_CONFIG_NAME_SHOULD_BE_SET",
      "ENUMS": {
        "Simulation_Type": "GENERIC_SIM"
      },
      "Node_Grid_Size": 0.042,
      "Run_Number": 0,
      "Simulation_Duration": 365,
      "Simulation_Timestep": 1,
      "Start_Time": 0
    },
    "STRAIN_TRACKING": {
      "Number_Basestrains": 1,
      "Number_Substrains": 1
    },
    "Symptomatic_Infectious_Offset": 0
  }
}