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

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. JSON does not permit comments, but you can add “dummy” parameters to add contextual information to your files.

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": {
                        "Box_Duration": 100,
                        "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.

Parameter Data type Minimum Maximum Default Description Example
Box_Duration float 0 100000 100 The box duration of the effect in days. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Killing_Config": {
        "Box_Duration": 40,
        "Decay_Time_Constant": 0,
        "Initial_Effect": 0,
        "class": "WaningEffectBoxExponential"
    }
}
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}

WaningEffectBoxExponential

The initial efficacy is held for a specified duration, then the efficacy decays at an exponential rate.

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

Parameter Data type Minimum Maximum Default Description Example
Box_Duration float 0 100000 100 The box duration of the effect in days. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Waning_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 1,
        "class": "WaningEffectBox"
    }
}
Decay_Time_Constant float 0 100000 100 The exponential decay length, in days.
{
    "Killing_Config": {
        "Box_Duration": 40,
        "Decay_Time_Constant": 0,
        "Initial_Effect": 0,
        "class": "WaningEffectBoxExponential"
    }
}

WaningEffectConstant

The efficacy is held at a constant rate.

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

Parameter Data type Minimum Maximum Default Description Example
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}

WaningEffectExponential

The efficacy decays at an exponential rate.

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

Parameter Data type Minimum Maximum Default Description Example
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}
Decay_Time_Constant float 0 100000 100 The exponential decay length, in days.
{
    "Killing_Config": {
        "Box_Duration": 40,
        "Decay_Time_Constant": 0,
        "Initial_Effect": 0,
        "class": "WaningEffectBoxExponential"
    }
}

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.

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

Parameter Data type Minimum Maximum Default Description Example
Durability_Map JSON object NA NA NA The time, in days, since the intervention was distributed to a multiplier times the Initial_Effect.
{
    "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]
    }
}
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.
{
    "Changing_Effect": {
        "class": "WaningEffectConstant",
        "Initial_Effect": 1.0,
        "Expire_At_Durability_Map_End": 1
    }
}
Reference_Timer integer 0 2.15E+0 0 The timestamp at which linear-map should be anchored.
{
    "Changing_Effect": {
        "Initial_Effect": 1.0,
        "class": "WaningEffectMapLinear",
        "Expire_At_Durability_Map_End": 1,
        "Reference_Timer": 1,
        "Durability_Map": {
            "Times": [0, 385, 390, 10000],
            "Values": [0, 0.0, 0.5, 0.5]
        }
    }
}
Times array of floats 0 999999 NA An array of days.
{
    "Changing_Effect": {
        "Initial_Effect": 1.0,
        "class": "WaningEffectMapLinear",
        "Expire_At_Durability_Map_End": 1,
        "Reference_Timer": 1,
        "Durability_Map": {
            "Times": [0, 385, 390, 10000],
            "Values": [0, 0.0, 0.5, 0.5]
        }
    }
}
Values array of floats 0 3.40E+3 NA An array of values to match the defined Times.
{
    "Time_Value_Map": {
        "Times": [1998, 2000, 2003, 2006, 2009],
        "Values": [
            0,
            0.260000,
            0.080000,
            0.140000,
            0.540000
        ]
    }
}
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}

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.

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

Parameter Data type Minimum Maximum Default Description Example
Times array of floats 0 125 NA An array of years.
{
    "class": "WaningEffectMapLinearAge",
    "Initial_Effect": 1.0,
    "Durability_Map": {
        "Times": [0.0, 12.99999, 13.0, 125.0],
        "Values": [0.0, 0.0, 1.0, 1.0]
    }
}
Durability_Map JSON object NA NA NA The time, in days, since the intervention was distributed to a multiplier times the Initial_Effect.
{
    "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]
    }
}
Values array of floats 0 3.40E+3 NA An array of values to match the defined Times.
{
    "Time_Value_Map": {
        "Times": [1998, 2000, 2003, 2006, 2009],
        "Values": [
            0,
            0.260000,
            0.080000,
            0.140000,
            0.540000
        ]
    }
}
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}

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.

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

Parameter Data type Minimum Maximum Default Description Example
Times array of floats 0 365 NA An array of days.
{
    "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]
    }
}
Durability_Map JSON object NA NA NA The time, in days, since the intervention was distributed to a multiplier times the Initial_Effect.
{
    "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]
    }
}
Values array of floats 0 3.40E+3 NA An array of values to match the defined Times.
{
    "Time_Value_Map": {
        "Times": [1998, 2000, 2003, 2006, 2009],
        "Values": [
            0,
            0.260000,
            0.080000,
            0.140000,
            0.540000
        ]
    }
}
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}

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.

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

Parameter Data type Minimum Maximum Default Description Example
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.
{
    "Changing_Effect": {
        "class": "WaningEffectConstant",
        "Initial_Effect": 1.0,
        "Expire_At_Durability_Map_End": 1
    }
}
Reference_Timer integer 0 2.15E+0 0 The timestamp at which linear-map should be anchored.
{
    "Changing_Effect": {
        "Initial_Effect": 1.0,
        "class": "WaningEffectMapLinear",
        "Expire_At_Durability_Map_End": 1,
        "Reference_Timer": 1,
        "Durability_Map": {
            "Times": [0, 385, 390, 10000],
            "Values": [0, 0.0, 0.5, 0.5]
        }
    }
}
Times array of floats 0 999999 NA An array of days.
{
    "Changing_Effect": {
        "Initial_Effect": 1.0,
        "class": "WaningEffectMapLinear",
        "Expire_At_Durability_Map_End": 1,
        "Reference_Timer": 1,
        "Durability_Map": {
            "Times": [0, 385, 390, 10000],
            "Values": [0, 0.0, 0.5, 0.5]
        }
    }
}
Durability_Map JSON object NA NA NA The time, in days, since the intervention was distributed to a multiplier times the Initial_Effect.
{
    "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]
    }
}
Values array of floats 0 3.40E+3 NA An array of values to match the defined Times.
{
    "Time_Value_Map": {
        "Times": [1998, 2000, 2003, 2006, 2009],
        "Values": [
            0,
            0.260000,
            0.080000,
            0.140000,
            0.540000
        ]
    }
}
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}

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.

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

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.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}
Initial_Effect float 0 1 -1 Initial strength of the effect. Specify how this effect decays over time using one of the Waning effect classes.
{
    "Usage_Config": {
        "class": "WaningEffectRandomBox",
        "Initial_Effect": 1.0,
        "Expected_Discard_Time": 60
    }
}