Skip to content

next_with_prob

Syntax

next_with_prob(<state_name>, <probability>)

Parameters

<state_name>
A valid name of a state within the current condition as the target of the transition.
<probability>
The probability of the given state transition. 0 represents a 0% chance and 1 represents a 100% chance.

Description

Important

This is a special action which cannot appear within an if statement or loop!

Each agent typically transitions from one state to another after waiting for a period of time. The next_with_prob statement defines a probabilistic transition to another state.

Multiple next_with_prob statements can be used to define different possible transitions. Transition rule probabilities are normalized if they sum to more than 1.0. If probabilities sum to less than 1.0, the default transition rule is assigned the remaining probability.

The difference between transition rules

There are three types of transition rules:

  1. next_with_prob - Defines a transition with an explicit probability
  2. next_if - Defines a transition that applies with 100% probability when its condition is true
  3. default - Defines the transition that applies when other rules don't apply or for the remaining probability

A state can only have one default transition rule, and it cannot be conditionally defined. However, multiple next_with_prob and next_if rules can be defined within a state.

All transition rule probabilities are considered together. For next_with_prob, the probability is explicitly specified. For next_if, the probability is 100% when the condition is true, and 0% when false.

If the combined probabilities from all applicable transition rules (including next_with_prob and next_if) sum to more than 1.0, they are normalized so that the sum is exactly 1.0. If the probabilities sum to less than 1.0, the default rule is assigned the remaining probability.

Example: Combined age-based transitions

Suppose we have three states A, B, and C, and we are writing transition rules for state A. If we want agents less than 10 years old to transition from A to B with probability 0.25 and to state C with probability 0.75 (and all other agents to always transition to state C), we would write:

state A {
    age_based_prob = 0
    if (age() < 10) {
        age_based_prob = 0.25
    }
    wait(0)
    next_with_prob(B, age_based_prob)
    default(C)
}

For agents less than 10 years old, the probability of going to state B is 0.25. Because the total probability is less than 1.0, the default transition rule applies with probability 0.75 = 1.0 - 0.25.

For agents 10 or older, age_based_prob remains 0, so the total probability equals 0.0. In this case, the default transition rule applies with probability 1.0.

Missing Default Rule

If no default rule is included in a state, the default transition state is the state itself, so these two snippets are equivalent:

state A {
    wait(24)
    next_if(B, age() <= 10)
}

state A {
    wait(24)
    next_if(B, age() <= 10)
    default(A)
}

This might lead to unexpected results if a missing default rule is applied. For example:

state A {
    wait(0)
    next_if(B, age() <= 10) # WRONG!
}

For all agents over age 10, the above code would lead to an infinite loop back to state A, which is problematic because we do not wait in this state.

Examples

This example shows a portion of a possible INFLUENZA condition.

condition INFLUENZA {
    ...
    state Exposed {
        set_sus(INFLUENZA, 0)
        wait(24 * lognormal(1.9, 1.23))
        next_with_prob(InfectiousAsymptomatic, 0.33)
        default(InfectiousSymptomatic)
    }

    state InfectiousAsymptomatic {
        ...
    }

    state InfectiousSymptomatic {
        ...
    }
    ...
}

In this example, a transition between state A and state B is defined with a probability of 50%.

state A {
    wait(24)
    next_with_prob(B, 0.5)
    default(Excluded)
}

For combining conditional logic with probabilities, you must use variables. For example:

# Assume age_based_prob is a shared numeric variable
state A {
    wait(24)
    age_based_prob = 0
    if (age() < 10) {
        age_based_prob = 0.25
    }
    next_with_prob(B, age_based_prob)
    default(C)
}

See Also