Configuration overlay files

You can use two configuration files when setting up a simulation. One file contains default parameter settings and an overlay file contains additional parameters or different parameter values that override the values in the default file.

Overlay files allow you to easily separate a subset of parameters that are of particular interest from the rest of the parameters needed to run a simulation. You can easily modify the parameters in the overlay file without needing to maintain a complete configuration file. This can be especially helpful when you want to experiment with the values set in certain parameters of interest without modifying the rest of the settings. You can have one default file and many different overlay files for different configurations. It also allows you to easily update the default values across multiple simulations.

These files must be flattened into a single file and the values in the overlay file will override those in the default file. When using overlay files, the parameters are often organized into logical groups using the hierarchical file format. See Configuration file for more information. When using any kind of hierarchical file, whether or not you are using an overlay file, it must also be flattened using the Python script below.

To flatten two configuration files:

1. Create the default configuration file in JSON. You may, though it is not required, organize the parameters into logical categories of nested JSON objects to make managing the parameters easier. See Configuration parameters for a complete list of all parameters that are available. See the example default configuration file below.

   {
     "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
     }
   }
   

2. Create the overlay configuration file in JSON. This file must include the parameter Default_Config_Path, set to the path to the default configuration file, relative to the location of the flatten_config.py script in the EMOD Regression folder. Again, you may organize the parameters into logical categories if you desire. See the example overlay configuration file below.

   {
        "Default_Config_Path": "defaults/generic-default-config.json",
        "parameters": {
             "DEMOGRAPHICS": {
                 "Enable_Demographics_Builtin": 0,
                 "Birth_Rate_Dependence": "POPULATION_DEP_RATE",
                 "Death_Rate_Dependence" : "NOT_INITIALIZED",
                 "Enable_Vital_Dynamics": 0,
                 "Sample_Rate_Birth": 1,
                 "Enable_Demographics_Reporting": 1
             },
             "DISEASE": {
                 "Base_Incubation_Period": 0,
                 "Base_Infectious_Period": 4,
                 "Base_Infectivity": 3.5,
                 "Enable_Immune_Decay": 0
             },
             "PRIMARY": {
                  "Config_Name": "00_Generic_DEFAULT",
                  "Demographics_Filenames": ["demographics.json"],
                  "Geography": "",
                  "Run_Number": 1,
                  "Simulation_Duration": 90
             }
        }
   }
   

3. In a Command Prompt window, navigate to the Regression folder.

4. Run the flatten_config.py script, providing the relative path to the overlay file:

   python flatten_config.py experiment/parameter_overrides.json
   

5. Open the resulting config.json file in the same folder as parameter_overrides.json and see that it has been flattened into a single layer with all parameters listed alphabetically and any logical categories removed. Eradication.exe will not accept a configuration file with nested JSON objects.

   {
     "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
     }
   }