Waning effect classes#

The following classes are nested within interventions (both individual-level and node-level) to indicate how their efficacy wanes over time. They can be used with several parameters including Blocking_Config, Killing_Config, and Waning_Config. Note that waning effect parameters do not control the overall duration of an intervention and are not assigned probabilistically.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

See the example below that uses a mix of different waning effect classes and the tables below that describe all parameters that can be used with each waning effect class.

{
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 1.0,
                "Number_Repetitions": -1,
                "Timesteps_Between_Repetitions": 60,
                "Intervention_Config": {
                    "class": "SimpleBednet",
                    "Cost_To_Consumer": 5,
                    "Usage_Config": {
                        "class": "WaningEffectRandomBox",
                        "Initial_Effect": 1.0,
                        "Expected_Discard_Time" : 60
                    },
                    "Blocking_Config": {
                        "class": "WaningEffectExponential",                        
                        "Decay_Time_Constant": 150,
                        "Initial_Effect": 0.5
                    },
                    "Killing_Config": {
                        "class": "WaningEffectConstant",
                        "Initial_Effect": 1.0
                    }
                }
            }
        }
    ],
    "Use_Defaults": 1
}

WaningEffectBox#

The efficacy is held at a constant rate until it drops to zero after the user-defined duration.

{
    "Intervention_Config": {
        "Blocking_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0,
            "class": "WaningEffectBox"
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Box_Duration

float

0

100000

100

The box duration of the effect in days.

 
{
  "Box_Duration": 40
}

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant until the duration is complete, as specified with the Box_Duration parameter for the WaningEffectBox class.

 
{
  "Waning_Config": {
    "Box_Duration": 10,
    "Initial_Effect": 0.75,
    "class": "WaningEffectBox"
  }
}

WaningEffectBoxExponential#

The initial efficacy is held for a specified duration, then the efficacy decays at an exponential rate where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant.

  {
    "Intervention_Config": {
        "Reduction_Config": {
            "class": "WaningEffectBoxExponential",
            "Box_Duration": 100,
            "Decay_Time_Constant": 150,
            "Initial_Effect": 0.1
        }
    }
  }

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Box_Duration

float

0

100000

100

The box duration of the effect in days.

 
{
  "Box_Duration": 3650,
  "Initial_Effect": 0.97,
  "Decay_Time_Constant": 50
}

Decay_Time_Constant

float

0

100000

100

The exponential decay length, in days, where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant (dt equal to delta time).

 
{
  "Box_Duration": 3650,
  "Initial_Effect": 0.97,
  "Decay_Time_Constant": 50
}

Initial_Effect

float

0

1

1

The initial efficacy, held for a duration as specified with the Box_Duration parameter and then decaying at an exponential length (in days), where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant (dt equal to delta time).

 
{
  "Box_Duration": 3650,
  "Initial_Effect": 0.97,
  "Decay_Time_Constant": 50
}

WaningEffectCombo#

The WaningEffectCombo class is used within individual-level interventions and allows for specifiying a list of effects when the intervention only has one WaningEffect defined. These effects can be added or multiplied.

{
    "class" : "WaningEffectCombo",
    "Add_Effects" : 1,
    "Expires_When_All_Expire" :0,
    "Effect_List" : [
        {
            "class": "WaningEffectMapLinear",
            "Initial_Effect" : 1.0,
            "Expire_At_Durability_Map_End" : 1,
            "Durability_Map" :
            {
                "Times"  : [ 0.0, 1.0, 2.0 ],
                "Values" : [ 0.2, 0.4, 0.6 ]
            }
        },
        {
            "class": "WaningEffectBox",
            "Initial_Effect": 0.5,
            "Box_Duration" : 5.0
        }
    ]
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant when using with the WaningEffectConstant class.

 
{
  "Waning_Config": {
    "Initial_Effect": 0.65,
    "class": "WaningEffectConstant"
  }
}

WaningEffectConstant#

The efficacy is held at a constant rate.

{
    "Intervention_Config": {
        "class": "SimpleBednet",
        "Killing_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 1.0
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant when using with the WaningEffectConstant class.

 
{
  "Waning_Config": {
    "Initial_Effect": 0.65,
    "class": "WaningEffectConstant"
  }
}

WaningEffectExponential#

The efficacy decays at an exponential rate where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant.

{
    "Intervention_Config": {
        "class": "SimpleBednet",
        "Blocking_Config": {
            "class": "WaningEffectExponential",            
            "Decay_Time_Constant": 150,
            "Initial_Effect": 0.5
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Decay_Time_Constant

float

0

100000

100

The exponential decay length, in days, where the current effect is equal to 1 - dt/Decay_Time_Constant (dt equal to delta time).

 
{
  "Decay_Time_Constant": 30,
  "Initial_Effect": 0.95
}

Initial_Effect

float

0

1

1

The initial efficacy, held for a specified duration (in days) as specified with the Box_Duration parameter. After this duration the efficacy decays at an exponential decay length (in days), where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant (dt equal to delta time).

 
{
  "Waning_Config": {
    "Decay_Time_Constant": 0.87,
    "Initial_Effect": 0.9,
    "class": "WaningEffectExponential"
  }
}

WaningEffectMapLinear#

The efficacy decays based on the time since the start of the intervention. This change is defined by a map of time to efficacy values in which the time between time/value points is linearly interpolated. When the time since start reaches the end of the times in the map, the last value will be used unless the intervention expires. If the time since start is less than the first value in the map, the efficacy will be zero. This can be used to define the shape of a curve whose magnitude is defined by the Initial_Effect multiplier.

 {
    "Intervention_Config": {
        "class": "ControlledVaccine",
        "Waning_Config": {
            "class": "WaningEffectMapLinear",
            "Reference_Timer": 0,
            "Initial_Effect": 1.0,
            "Expire_At_Durability_Map_End": 1,
            "Durability_Map": {
                "Times": [0, 120, 240, 360],
                "Values": [0.7, 0.8, 1.0, 0.0]
            }
        }
    }
 }

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

json object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
  "Durability_Map": {
    "Times": [
      0.0,
      20.0,
      21.0,
      30.0,
      31.0,
      365.0
    ],
    "Values": [
      1.0,
      1.0,
      0.0,
      0.0,
      1.0,
      1.0
    ]
  }
}

Expire_At_Durability_Map_End

boolean

0

1

0

Set to 1 to let the intervention expire when the end of the map is reached.

 
{
  "Expire_At_Durability_Map_End": 1
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapLinear class.

 
{
  "Waning_Config": {
    "Durability_Map": {
      "Times": [
        0,
        30,
        60,
        90,
        120
      ],
      "Values": [
        0.9,
        0.3,
        0.9,
        0.6,
        1
      ]
    },
    "Expire_At_Durability_Map_End": 0,
    "Initial_Effect": 1,
    "class": "WaningEffectMapLinear"
  }
}

Reference_Timer

integer

0

2147480000.0

0

The timestamp at which linear-map should be anchored.

 
{
  "Reference_Timer": 1
}

Times

array of floats

0

999999

[]

An array of days.

 
{
  "Durability_Map": {
    "Times": [
      0,
      385,
      390,
      10000
    ],
    "Values": [
      0,
      0.0,
      0.5,
      0.5
    ]
  }
}

Values

array of floats

0

3.40282e+38

[]

An array of values to match the defined Times.

 
{
  "Times": [
    1998,
    2000,
    2003,
    2006,
    2009
  ],
  "Values": [
    0,
    0.26,
    0.08,
    0.14,
    0.54
  ]
}

WaningEffectMapLinearAge#

Similar to WaningEffectMapLinear, except that the efficacy decays based on the age of the individual who owns the intervention instead of the time since the start of the intervention.

{
  "class": "WaningEffectMapLinearAge",
  "Initial_Effect": 1,
  "Durability_Map": {
    "Times": [
      1,
      2,
      5,
      7
    ],
    "Values": [
      1,
      0.75,
      0.5,
      0.25
    ]
  }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

json object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
  "Durability_Map": {
    "Times": [
      1,
      2,
      5,
      7
    ],
    "Values": [
      1,
      0.75,
      0.5,
      0.25
    ]
  }
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapLinearAge class.

 
{
  "class": "WaningEffectMapLinearAge",
  "Initial_Effect": 1,
  "Durability_Map": {
    "Times": [
      1,
      2,
      5,
      7
    ],
    "Values": [
      1,
      0.75,
      0.5,
      0.25
    ]
  }
}

Times

array of floats

0

125

[]

An array of years.

 
{
  "Durability_Map": {
    "Times": [
      1,
      2,
      5,
      7
    ],
    "Values": [
      1,
      0.75,
      0.5,
      0.25
    ]
  }
}

Values

array of floats

0

3.40282E+38

[]

An array of values to match the defined Times.

 
{
  "Durability_Map": {
    "Times": [
      1,
      2,
      5,
      7
    ],
    "Values": [
      1,
      0.75,
      0.5,
      0.25
    ]
  }
}

WaningEffectMapLinearSeasonal#

Similar to WaningEffectMapLinear, except that the map will repeat itself every 365 days. That is, the time since start will reset to zero once it reaches 365. This allows you to simulate seasonal effects.

{
    "Intervention_Config": {
        "class": "UsageDependentBednet",
        "Usage_Config_List": [{
            "class": "WaningEffectMapLinearSeasonal",
            "Initial_Effect": 1.0,
            "Durability_Map": {
                "Times": [0.0, 20.0, 21.0, 30.0, 31.0, 365.0],
                "Values": [1.0, 1.0, 0.0, 0.0, 1.0, 1.0]
            }
        }]
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

json object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
  "Durability_Map": {
    "Times": [
      0.0,
      20.0,
      21.0,
      30.0,
      31.0,
      365.0
    ],
    "Values": [
      1.0,
      1.0,
      0.0,
      0.0,
      1.0,
      1.0
    ]
  }
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapLinearSeasonal class.

 
{
  "class": "WaningEffectMapLinearSeasonal",
  "Initial_Effect": 1,
  "Durability_Map": {
    "Times": [
      0,
      20,
      21,
      30,
      31,
      365
    ],
    "Values": [
      1,
      1,
      0,
      0,
      1,
      1
    ]
  }
}

Times

array of floats

0

365

[]

An array of days.

 
{
  "Durability_Map": {
    "Times": [
      0.0,
      20.0,
      21.0,
      30.0,
      31.0,
      365.0
    ],
    "Values": [
      1.0,
      1.0,
      0.0,
      0.0,
      1.0,
      1.0
    ]
  }
}

Values

array of floats

0

3.40282e+38

[]

An array of values to match the defined Times.

 
{
  "Times": [
    1998,
    2000,
    2003,
    2006,
    2009
  ],
  "Values": [
    0,
    0.26,
    0.08,
    0.14,
    0.54
  ]
}

WaningEffectMapPiecewise#

Similar to WaningEffectMapLinear, except that the data is assumed to be constant between time/value points (no interpolation). If the time since start falls between two points, the efficacy of the earlier time point is used.

{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Waning_Config": {
            "class": "WaningEffectMapPiecewise",
            "Initial_Effect": 1.0,
            "Reference_Timer": 0,
            "Expire_At_Durability_Map_End": 0,
            "Durability_Map": {
                "Times": [10, 30, 50],
                "Values": [0.9, 0.1, 0.6]
            }
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

json object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
  "Durability_Map": {
    "Times": [
      0.0,
      20.0,
      21.0,
      30.0,
      31.0,
      365.0
    ],
    "Values": [
      1.0,
      1.0,
      0.0,
      0.0,
      1.0,
      1.0
    ]
  }
}

Expire_At_Durability_Map_End

boolean

0

1

0

Set to 1 to let the intervention expire when the end of the map is reached.

 
{
  "Expire_At_Durability_Map_End": 1
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapPiecewise class.

 
{
  "Waning_Config": {
    "Durability_Map": {
      "Times": [
        10,
        30,
        50
      ],
      "Values": [
        0.9,
        0.1,
        0.6
      ]
    },
    "Expire_At_Durability_Map_End": 0,
    "Initial_Effect": 1,
    "class": "WaningEffectMapPiecewise"
  }
}

Reference_Timer

integer

0

2147480000.0

0

The timestamp at which linear-map should be anchored.

 
{
  "Reference_Timer": 1
}

Times

array of floats

0

999999

[]

An array of days.

 
{
  "Durability_Map": {
    "Times": [
      0,
      385,
      390,
      10000
    ],
    "Values": [
      0,
      0.0,
      0.5,
      0.5
    ]
  }
}

Values

array of floats

0

3.40282e+38

[]

An array of values to match the defined Times.

 
{
  "Times": [
    1998,
    2000,
    2003,
    2006,
    2009
  ],
  "Values": [
    0,
    0.26,
    0.08,
    0.14,
    0.54
  ]
}

WaningEffectRandomBox#

The efficacy is held at a constant rate until it drops to zero after a user-defined duration. This duration is randomly selected from an exponential distribution where Expected_Discard_Time is the mean.

{
    "Intervention_Config": {
        "class": "SimpleBednet",
        "Cost_To_Consumer": 5,
        "Usage_Config": {
            "class": "WaningEffectRandomBox",
            "Initial_Effect": 1.0,
            "Expected_Discard_Time": 60
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Expected_Discard_Time

float

0

100000

100

The mean time, in days, of an exponential distribution of the duration of the effect of an intervention (such as a vaccine or bed net). Specify how this effect decays over time using one of the Waning effect classes.

 
{
  "Expected_Discard_Time": 60
}

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant until the duration is complete when using with the WaningEffectRandomBox class.

 
{
  "Waning_Config": {
    "Expected_Discard_Time": 65,
    "Initial_Effect": 0.85,
    "class": "WaningEffectRandomBox"
  }
}