# Time-outcome fan plots

The DUToolkit includes a series of visual outputs that build upon those used in health economics. These visuals are designed to facilitate the intuitive and direct interpretation of model outputs by infectious disease modellers and decision-makers. The visual and numerical presentation of decision risk are designed as complementary outputs to support decision-makers’ deliberations.

Time-outcome fan plots are the first of these visuals. In these plots, the trajectory of the outcome is summarized over time and plotted using the mean value for a given policy alternative. Uncertainty is characterized by shading the 50% and 95% credible intervals (calculated as 25th and 75th percentiles and 2.5th and 97.5th percentiles, respectively). The decision threshold is shown directly on the plot to provide a clear reference point for interpreting the outcome values.

We generate the fan plots for each policy alternative using the `plot_fan()` function.

    # define inputs
    tmin <- min(psa_data$Intervention_1[, 1]) # minimum simulation time
    tmax <- max(psa_data$Intervention_1[, 1]) # maximum simulation time
    Dt <- c(rep(750, length(tmin:tmax))) # decision threshold vector
    Dt_max <- TRUE # indicates the threshold values are maximums

    # generate fan plots
    fan_plots <- plot_fan(psa_data, tmin, tmax, Dt, Dt_max)

    ## example plot
    fan_plots$Baseline

All plotting functions in the DUToolkit return ggplot2 objects. You can adjust/customize the plots after they have been generated (ggplot2 cheat sheet).

    # customize plots
    ## add fixed y-axis limits and change the label of the y-axis
    fan_plots <- lapply(fan_plots, function(x) {
      x + ggplot2::ylim(0, 4000) + ggplot2::labs(y = "Hospital Demand")
    })

    ## remove subtitle and caption
    fan_plots <- lapply(fan_plots, function(x) {
      x + ggplot2::labs(subtitle = NULL, caption = NULL)
    })

    ## example plot
    fan_plots$Baseline

The `calculate_time()` function is used within `plot_fan()` to determine the uncertainty in the timing and duration of threshold exceedances, which are then displayed in the plot subtitle. Additionally, `calculate_time()` can be used independently to generate results in a tabular format without creating fan plots. Its outputs include:

1. Percent of simulations in which the threshold is exceeded (or not met if the threshold is a minimum).

2. Mean simulation time of the first exceedance and 95th percentile range.

3. Mean duration of the first exceedance and 95th percentile range.

4. If the first column of the model output passed to the function is a Date, the mean date of the first and last exceedance.

    # Find mean and 95%CI of time and duration of first violation of the threshold
    time_outcomes_list <- calculate_time(psa_data, tmin, tmax, Dt, Dt_max)
    time_outcomes_list$Baseline
    #>     percent_sims time_first 2.5% 97.5% duration_first 2.5% 97.5% date_first
    #> out    0.9532595   22.88516   16    35       25.03484    9    34 2021-01-23
    #>      date_last
    #> out 2021-02-17

### Sharing outputs

These plots visually illustrate the uncertainty in the outcome (in this case, hospital demand) for each policy and facilitate assessment in relation to the decision threshold (hospital capacity). They can be used to visually assess the probability of exceeding the threshold and to understand the expected magnitude, timing, and duration of any exceedances. These plots should be presented alongside the risk measures to provide decision-makers with a quantitative measure of the risk associated with each policy, alongside a visual representation of uncertainty for additional context.

We also recommend the following standard description for presenting the time-outcome fan plots to decision-makers. We provide the standard description in paragraph and bullet point form for ease of use.

#### Standard description

These graphs visually displays the uncertainty surrounding the scenario’s probability of exceeding 1 the specified policy target. They indicate not only the degree of uncertainty but also provides insight into the magnitude by which the intervention is likely to exceed 2 the target (through percentile shading) and the anticipated duration of the exceedance 3.

The magnitude and the length of time that the shaded areas extends beyond 4 the policy target (dashed red line) signifies the risk that the scenario will not achieve the policy objective. More shaded area above 5 the dashed red line for longer periods indicates a higher risk of not achieving the policy objective.

#### Standard description bullet points

These graphs visually display:

- The uncertainty surrounding the scenario’s probability of exceeding 6 the specified policy target.

- They also provides insight into the magnitude by which the intervention is likely to exceed 7 the target (through percentile shading) and the anticipated duration of the exceedance 8.

- The magnitude and the length of time that the shaded areas extends beyond 9 the policy target (dashed red line) signifies the risk that the scenario will not achieve the policy objective.

- More shaded area above 10 the dashed red line for longer periods indicates a higher risk of not achieving the policy objective.

1. if threshold is a minimum replace with falling below↩︎

2. if threshold is a minimum replace with fall below↩︎

3. if threshold is a minimum replace with short fall↩︎

4. if threshold is a minimum replace with falls below↩︎

5. if threshold is a minimum replace with below↩︎

6. if threshold is a minimum replace with falling below↩︎

7. if threshold is a minimum replace with fall below↩︎

8. if threshold is a minimum replace with short fall↩︎

9. if threshold is a minimum replace with falls below↩︎

10. if threshold is a minimum replace with below↩︎