Create a configuration file

You define the general configuration and processing of a simulation through a JSON-formatted configuration file, typically called config.json. Two forms of the simulation configuration file are used: a flattened version and a hierarchical version. This topic describes how to create a configuration file of other form. The EMOD executable (Eradication.exe) and Eradication binary requires a flattened version of the simulation configuration file. The hierarchical version allows you to organize parameters into logical groups, making them easier to manage. If you use hierarchical configuration files, you must flatten them prior to running a simulation.

The EMOD Regression directory contains many different subdirectories that contain configuration, campaign, and other associated files to run simulations that represent real-world scenarios. Within the each subdirectory, there is usually a hierarchical overlay file (param_overrides.json) and a flattened file (config.json), which has been created by combining param_overrides.json with one of the default files in Regression/defaults. The default files are also organized hierarchically. The naming of these files is an arbitrary convention used at IDM; you may name this files anything you choose. See Use configuration overlay files for more information about flattening hierarchical files.

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 file

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 requires for running simulations.

However, there may be some hierarchical elements in the flattened version. For example, Vector_Species_Params and Malaria_Drug_Params have nested JSON objects.

Below is an example of a flattened configuration file:

{
    "parameters": {
        "Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
        "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
        "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
        "Animal_Reservoir_Type": "NO_ZOONOSIS",
        "Base_Incubation_Period": 0,
        "Base_Individual_Sample_Rate": 1,
        "Base_Infectious_Period": 4,
        "Base_Infectivity": 3.5,
        "Base_Mortality": 0,
        "Base_Population_Scale_Factor": 1,
        "Birth_Rate_Dependence": "POPULATION_DEP_RATE",
        "Birth_Rate_Time_Dependence": "NONE",
        "Burnin_Cache_Mode": "none",
        "Burnin_Cache_Period": 0,
        "Burnin_Name": "",
        "Campaign_Filename": "campaign.json",
        "Climate_Model": "CLIMATE_OFF",
        "Config_Name": "00_DEFAULT",
        "Custom_Reports_Filename": "NoCustomReports",
        "Death_Rate_Dependence": "NONDISEASE_MORTALITY_OFF",
        "Default_Geography_Initial_Node_Population": 1000,
        "Default_Geography_Torus_Size": 10,
        "Demographics_Filenames": [
            "../00_Default/demographics.json"
        ],
        "Enable_Absolute_Time": "NO",
        "Enable_Aging": 1,
        "Enable_Birth": 1,
        "Enable_Default_Reporting": 1,
        "Enable_Default_Shedding_Function": 1,
        "Enable_Demographics_Birth": 0,
        "Enable_Demographics_Builtin": 0,
        "Enable_Demographics_Gender": 1,
        "Enable_Demographics_Other": 0,
        "Enable_Demographics_Reporting": 1,
        "Enable_Disease_Mortality": 0,
        "Enable_Heterogeneous_Intranode_Transmission": 0,
        "Enable_Immune_Decay": 0,
        "Enable_Immunity": 1,
        "Enable_Interventions": 1,
        "Enable_Maternal_Infection_Transmission": 0,
        "Enable_Property_Output": 0,
        "Enable_Spatial_Output": 0,
        "Enable_Superinfection": 0,
        "Enable_Vital_Dynamics": 0,
        "Geography": "",
        "Immunity_Acquisition_Factor": 0,
        "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
        "Immunity_Mortality_Factor": 0,
        "Immunity_Transmission_Factor": 0,
        "Incubation_Period_Distribution": "FIXED_DURATION",
        "Individual_Sampling_Type": "TRACK_ALL",
        "Infection_Updates_Per_Timestep": 1,
        "Infectious_Period_Distribution": "EXPONENTIAL_DURATION",
        "Infectivity_Scale_Type": "CONSTANT_INFECTIVITY",
        "Job_Node_Groups": "Chassis08",
        "Job_Priority": "BELOWNORMAL",
        "Listed_Events": [],
        "Load_Balance_Filename": "",
        "Local_Simulation": 0,
        "Maternal_Transmission_Probability": 0,
        "Max_Individual_Infections": 1,
        "Max_Node_Population_Samples": 40,
        "Migration_Model": "NO_MIGRATION",
        "Minimum_Adult_Age_Years": 15,
        "Mortality_Blocking_Immunity_Decay_Rate": 0.001,
        "Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
        "Mortality_Time_Course": "DAILY_MORTALITY",
        "Node_Grid_Size": 0.042,
        "Num_Cores": 1,
        "Number_Basestrains": 1,
        "Number_Substrains": 1,
        "PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT",
        "Population_Density_C50": 30,
        "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY",
        "Population_Scale_Type": "USE_INPUT_FILE",
        "Report_Event_Recorder": 0,
        "Run_Number": 1,
        "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": 1,
        "Serialization_Test_Cycles": 0,
        "Simulation_Duration": 90,
        "Simulation_Timestep": 1,
        "Simulation_Type": "GENERIC_SIM",
        "Start_Time": 0,
        "Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY",
        "Transmission_Blocking_Immunity_Decay_Rate": 0.1,
        "Transmission_Blocking_Immunity_Duration_Before_Decay": 60,
        "x_Air_Migration": 1,
        "x_Birth": 1,
        "x_Local_Migration": 1,
        "x_Other_Mortality": 1,
        "x_Population_Immunity": 1,
        "x_Regional_Migration": 1,
        "x_Sea_Migration": 1,
        "x_Temporary_Larval_Habitat": 1
    }
}

Hierarchical configuration file

The hierarchical version of a configuration file has a more complex structure. As a way of sorting parameters into logical groups, the parameters can be contained inside nested JSON objects. The names you use to create 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 Use 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",
            "Base_Population_Scale_Factor": 1,
            "Birth_Rate_Dependence": "DEMOGRAPHIC_DEP_RATE",
            "Birth_Rate_Time_Dependence": "NONE",
            "Demographics_Filenames": ["NO_DEFAULT_DEMOGRAPHICS"],
            "Default_Geography_Initial_Node_Population": 1000,
            "Default_Geography_Torus_Size": 10,
            "Enable_Aging": 1,
            "Enable_Birth": 1,
            "Enable_Demographics_Birth": 0,
            "Enable_Demographics_Gender": 1,
            "Enable_Demographics_Builtin": 0,
            "Enable_Demographics_Other": 0,
            "Enable_Demographics_Reporting": 0,
            "Enable_Vital_Dynamics": 1,
            "Minimum_Adult_Age_Years": 15,
            "IMMUNITY": {
                "Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
                "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
                "Enable_Immune_Decay": 1,
                "Enable_Immunity": 1,
                "Immunity_Acquisition_Factor": 0,
                "Immunity_Transmission_Factor": 0,
                "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
                "Susceptibility_Scale_Type": "CONSTANT_SUSCEPTIBILITY",
                "Transmission_Blocking_Immunity_Decay_Rate": 0.1,
                "Transmission_Blocking_Immunity_Duration_Before_Decay": 60
            },
            "MORTALITY": {
                "Base_Mortality": 0,
                "Enable_Disease_Mortality": 0,
                "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER",
                "Immunity_Mortality_Factor": 0,
                "Mortality_Blocking_Immunity_Decay_Rate": 0.001,
                "Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
                "Mortality_Time_Course": "DAILY_MORTALITY"
            },
            "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
            }
        },
        "DISEASE": {
            "Animal_Reservoir_Type": "NO_ZOONOSIS",
            "Enable_Superinfection": 0,
            "INCUBATION": {
                "Base_Incubation_Period": 3,
                "Incubation_Period_Distribution": "FIXED_DURATION"
            },
            "INFECTIOUSNESS": {
                "Base_Infectious_Period": 7,
                "Base_Infectivity": 0.3,
                "Infectious_Period_Distribution": "EXPONENTIAL_DURATION",
                "Infectivity_Scale_Type": "CONSTANT_INFECTIVITY",
                "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_Population_Immunity": 1,
            "x_Regional_Migration": 1,
            "x_Sea_Migration": 1,
            "x_Temporary_Larval_Habitat": 1
        },
        "HPC": {
            "Job_Node_Groups": "Chassis08",
            "Job_Priority": "BELOWNORMAL",
            "Load_Balance_Filename": "",
            "Local_Simulation": 0,
            "Num_Cores": 1
        },
        "INTRANODE_TRANSMISSION": {
            "Enable_Default_Shedding_Function": 1,
            "Enable_Heterogeneous_Intranode_Transmission": 0
        },
        "MIGRATION": {
            "Migration_Model": "NO_MIGRATION"
        },
        "OUTPUT": {
            "Custom_Reports_Filename": "NoCustomReports",
            "Report_Event_Recorder": 0,
            "Enable_Default_Reporting": 1,
            "Enable_Property_Output": 0,
            "Enable_Spatial_Output": 0
        },
        "POLIO": {},
        "PRIMARY": {
            "Config_Name": "DEFAULT_CONFIG_NAME_SHOULD_BE_SET",
            "ENUMS": {
                "Simulation_Type": "GENERIC_SIM"
            },
            "Geography": "DEFAULT_GEOGRAPHY_SHOULD_BE_SET",
            "Node_Grid_Size": 0.042,
            "Run_Number": 0,
            "Simulation_Duration": 365,
            "Simulation_Timestep": 1,
            "Start_Time": 0,
            "Enable_Absolute_Time": "NO"

        },
        "SERIALIZATION": {
            "Burnin_Cache_Mode": "none",
            "Burnin_Cache_Period": 0,
            "Burnin_Name": "",
            "Serialization_Test_Cycles": 0
        },
        "STRAIN_TRACKING": {
            "Number_Basestrains": 1,
            "Number_Substrains": 1
        }
    }
}

Create or modify configuration files

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. Any of the configuration files in the Regression directory may be used; in particular the Regression/defaults directory contains hierarchical configuration files with the common parameter settings used with different simulation types.

The simplest method is to use a text editor to directly edit the parameters or parameter values in the JSON file. However, while direct editing of files may be sufficient for small and infrequent changes, you will likely find that scripting tools are more powerful and reliable for both creating and modifying files.

The following example shows how to read a configuration file to a Python dictionary, modify a parameter, and write it back out to the file:

import json

# load the current config.json
config_file = open( "config.json" )
config_json = json.load( config_file )
config_file.close()

# modify one of the parameter values, e.g. "base_infectivity"
config_json["parameters"]["base_infectivity"] = 0.5

# write the modified config file
modified_file = open( "modified_config.json", "w" )
json.dump( config_json, modified_file, sort_keys=True, indent=4 )
modified_file.close()

The following example shows how to modify a configuration file in MATLAB:

addpath Matlab
addpath Matlab\test

% load the simulation configuration file into MATLAB structure
configjson = loadJson( "config.json" );

% modify one of the values
configjson.parameters.Base_Infectivity = 08.5;

% save the new configuration to file
saveJson( "modified_config.json", configjson );