Plotting

gemsplot(rd::ResultData; type::Symbol = :nothing, plotargs...)
gemsplot(bd::BatchData; type::Symbol = :nothing, combined::Symbol = :all, plotargs...)
gemsplot(rd::Vector{ResultData}; type::Symbol = :nothing, combined::Symbol = :all, plotargs...)

Facilitates the usage of GEMS' inbuilt plots. Just pass the name of the plot-type as a Symbol (must be exactly the same as the respective SimulationPlot-struct). The plotargs... can be any keyworded argument that is available in the standard Plots.jl package.

You can pass a ResultData object to get a plot for one simulation run or even pass a vector of ResultData objects or even a BatchData object. Passing data of multiple simulation runs (ResultData-vector or BatchData) will generate the respective plot with the data of all simulation runs inside. E.g., the :TickCases plot will show one line for each run. Simulations with the same label attribute will be grouped using the same color.

The keyword combined (only applicable for ResultData-vectors or BatchData-objects) determines whether all data is combined in a single plot (:all), each simulation run gets its own subplot (:single), or the plots are separated by label (:bylabel). Note: There might be plots without a multi-plot implementation. They will always be printed as if combined = :single was passed. Check the table below to see which plots are available for single- and multiplots.

Parameters

• rd/bd: Data object to plot. Can be ResultData, Vector{ResultData} or BatchData
• type = :nothing (optional): Plot type (instantiates a plot with the exact same struct name). You can pass a tuple of plots to generate one graph with multiple visualizations
• combined::Symbol = :all (optional): all data in one plot (:all), all individual plots (:singe), plot separated by label (:bylabel).
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Plot using the Plots.jl package's struct.

Examples

Given that rd is a valid ResultData object that came out of a simulation, you can plot a summary like this:

gemsplot(rd)

If you want a specific plot, say the cases-per-tick plot, try this and add a custom title:

gemsplot(rd, type = :TickCases, title = "My Tick Case Plot")

You can also generate multiple plots in one figure like so:

gemsplot(rd, type = (:CompartmentFill, :EffectiveReproduction), layout = (2,1))

The layout keyword makes the plots appear on top of each other in stead of side-by-side.

Generate a multi-plot for a vector of ResultData objects and separate plots by label like so:

# assuming you have a baseline, and a lockdown scenario with two simulation runs each.
# the simulations of these ResultData objects must have the same label ("Baseline" and "Lockdown") to group them
rds = [rd_baseline_1, rd_baseline_2, rd_lockdown_1, rd_lockdown_2]
gemsplot(rds, type = :EffectiveReproduction, combined = :bylabel)

Plot Types

The following plot types can be generated using the gemsplot() function. The mutli-plot column describes which plots can work with ResultData-vector or BatchData-objects. Some of the plots have keyword arguments that are only applicable to that very plot.

Some Useful Keyword Arguments

Here are some examples of the Plots.jl package's keyword arguments that you can also pass to the gemsplot() function and might find helpful:

• xlims = (0, 100): Setting the X-axis range between 0 and 100
• ylims = (0, 200): Setting the Y-axis range between 0 and 200
• size = (300, 400): Resizing the plot
• plot_title = "My New Title": Changing the plot title
• xlabel = "New X-label": Changing the x-axis label
• ylabel = "New Y-label": Changing the y-axis label
• legend = :topright: Changing the legend position (false to disable)
• aspect_ratio = :equal: Having the axis of equal size

Please consult the Plots.jl package documentation for a comprehensive list

emptyplot(message::String)

Returns an empty plot with the argument message as a text overlay. This can be used as a default for plot-generate()-functions, if no data is available in the ResultData object.

plotseries!(p::Plots.Plot, extract_function::Function, rds::Vector{ResultData}; plotargs...)

Extends a plot and adds data grouped by the labels of the ResultData objects. The extract_function argument must be a one-argument function that is the called with a single ResultData object. It must return the data series that should be plotted.

Parameters

• p::Plots.Plot: Input plot object to extend
• extract_function::Function: One-argument lambda function that will be called with each of the ResultData objects in the input vector. This function must return a vector of numberical values that is being added as a line series to input plot p.
• rds::Vector{ResultData}: Vector of ResultData objects to plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Plot using the Plots.jl package's struct.

Example

This code generates a plot of the effective reproduction number with one line per ResultData object and grouped by label.

p = plotseries!(plot(), rd -> effectiveR(rd)[!,"rolling_R"], rds)

saveplot(plot::Plots.Plot, path::AbstractString)

Stores a plot from the juliaplots package to the provided path.

saveplot(plot::GMTWrapper, path::AbstractString)

Copies a GMT plot from the temp folder into the provided path (removes the temporary file).

splitlabel(plt::SimulationPlot, rds::Vector{ResultData}; plotargs...)

Returns a split side-by-side plot for multiple ResultData objects but groups simulation runs by label. If you have 2 scenarios with 10 simulation runs each, this function will generate two plots with 10 data series each.

• plt::SimulationPlot: Simulation plot struct (e.g. TickCases())
• rds::Vector{ResultData}: Vector of ResultData objects to plot (requires the rd objects to have the label attribute)
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Plot using the Plots.jl package's struct.

splitplot(plt::SimulationPlot, rds::Vector{ResultData}; plotargs...)

Returns a split side-by-side plot for multiple ResultData objects.

Parameters

• plt::SimulationPlot: Simulation plot struct (e.g. TickCases())
• rds::Vector{ResultData}: Vector of ResultData objects to plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Plot using the Plots.jl package's struct.

ActiveDarkFigure <: SimulationPlot

A simulation plot type for generating an active-darkfigure-per-tick plot.

generate(plt::ActiveDarkFigure, rd::ResultData; plotargs...)

Generates and returns a active-darkfigure-per-tick plot for a provided ResultData object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::ActiveDarkFigure: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Active Dark Figure plot

AggregatedSettingAgeContacts <: SimulationPlot

A simulation plot type for sampling contacts from the model and build an age group x age group matrix for a given Setting type. The plot displays aggregated age groups and their mean number of contacts.

generate(plt::AggregatedSettingAgeContacts, rd::ResultData;
    settingtype::Union{DataType, Nothing} = nothing, plotargs...)

Generates and returns an age group x age group matrix from sampled contacts for a given Setting type. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::AggregatedSettingAgeContacts: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• settingtype::Union{DataType, Nothing} = nothing (optional): Setting type (e.g. "Household"). If nothing is passed, all setting types in the ResultData object are being ploted.
• show_values = true (optional): If true, values will be printed in the contact matrix
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Aggregated Setting Age Contacts plot

CompartmentFill <: SimulationPlot

A simulation plot type for generating a cumulative infections plot.

generate(plt::CompartmentFill, rd::ResultData; plotargs...)

Generates and returns a plot of the current compartment fill for a provided ResultData object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::CompartmentFill: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Compartment Fill plot

CumulativeCases <: SimulationPlot

A simulation plot type for generating a cumulative infections plot.

generate(plt::CumulativeCases, rd::ResultData; plotargs...)

Generates and returns a cumulative infections plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::CumulativeCases: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Cumulative Cases plot

CumulativeDiseaseProgressions <: SimulationPlot

A simulation plot type for generating a stacked bar chart on the cumulative disease progression.

generate(plt::CumulativeDiseaseProgressions, rd::ResultData; plotargs...)

Generates a stacked bar chart of cumulative disease progressions for all infections. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::CumulativeDiseaseProgressions: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Cumulative Disease Progressions plot

CumulativeIsolations <: SimulationPlot

A simulation plot type for generating a plot displaying the cumulative number of individuals currently in isolation.

generate(plt::CumulativeIsolations, rd::ResultData; plotargs...)

Generates a plot for the cumulative number of isolated individuals per tick. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::CumulativeIsolations: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Cumulative Isolations plot

CustomLoggerPlot <: SimulationPlot

A simulation plot type for generating a time series plot displaying values stored in a ResultDatas CustomLogger dataframe.

generate(plt::CustomLoggerPlot, rd::ResultData; plotargs...)

Generates and returns a plot for the values contained in the custom logger of a ResultData object. It will contain one individual plot per function that was passed to the custom logger. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package. However, be aware that the keyword arguments might be applied to each of the subplots individually.

Parameters

• plt::CustomLoggerPlot: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Custom Logger Plot plot

DetectedCases <: SimulationPlot

A simulation plot type for generating a new-DETECTED-cases-per-tick plot.

generate(plt::DetectedCases, rd::ResultData; plotargs...)

Generates and returns a new-DETECTED-cases-per-tick plot for a provided simulation object. Sorts infections dataframe by test_tickand filters for tested individuals. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::DetectedCases: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Detected Cases plot

EffectiveReproduction <: SimulationPlot

A simulation plot type for generating an effective reproduction number plot.

generate(plt::EffectiveReproduction, rd::ResultData; plotargs...)

Generates a plot for the effective reproduction number per tick. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::EffectiveReproduction: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Effective Reproduction Number plot

GMTWrapper

Wrapper-struct to inform saveplot function about the existance of a GMT-generated plot in the temp-folder (path_to_map).

GenerationTime <: SimulationPlot

A simulation plot type for generating a generation-time-per-tick.

generate(plt::GenerationTime, rd::ResultData; plotargs...)

Generates and returns a generation-time-per-tick plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::GenerationTime: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Generation Time plot

HospitalOccupancy <: SimulationPlot

A simulation plot type for generating a plot with hospitalization numbers etc.

generate(plt::HospitalOccupancy, rd::ResultData; plotargs...)

Generates a plot of the number of hospitalized, ventilated and ICU admitted agents for each tick. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::HospitalOccupancy: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Hospital Occupancy plot

HouseholdAttackRate <: SimulationPlot

A simulation plot type for generating a household-attack-rate plot.

generate(plt::HouseholdAttackRate, rd::ResultData; plotargs...)

Generates and returns a household-attack-rate plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package. However, be aware that the keyword arguments might be applied to each of the subplots individually.

Parameters

• plt::HouseholdAttackRate: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Household Attack Rate plot

Incidence <: SimulationPlot

A simulation plot type for generating an incidence plot.

generate(plt::Incidence, rd::ResultData; plotargs...)

Generates an age-stratified incidence plot. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::Incidence: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Incidence plot

IncubationHistogram <: SimulationPlot

A simulation plot type for generating the distribution of incubation period lengths for symptomatic individuals.

generate(plt::IncubationHistogram, rd::ResultData; plotargs...)

Generates a histrogram of the incubation period distribution (time to symptoms) of collected infections. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Note that this only shows the incubation period for symptomatic individuals!

Parameters

• plt::IncubationHistogram: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Infectious Histogram plot

InfectionDuration <: SimulationPlot

A simulation plot type for visualizing the distribution of infection durations as a histogram.

generate(plt::InfectionDuration, rd::ResultData; plotargs...)

Generates and returns a histogram of the total infection durations in ticks. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::InfectionDuration: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Infection Duration plot

InfectiousHistogram <: SimulationPlot

A simulation plot type for generating the distribution of infectious period lengths.

generate(plt::InfectiousHistogram, rd::ResultData; plotargs...)

Generates a histrogram of the infectious period distribution of collected infections. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::InfectiousHistogram: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Infectious Histogram plot

LatencyHistogram <: SimulationPlot

A simulation plot type for generating the distribution of latency period lengths.

generate(plt::LatencyHistogram, rd::ResultData; plotargs...)

Generates a histrogram of the latency period distribution of collected infections. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::LatencyHistogram: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Latency Histogram plot

ObservedReproduction <: SimulationPlot

A simulation plot type for generating a observed-reproduction-number-plot.

 generate(plt::ObservedReproduction, rd::ResultData; plotargs...)

Generates a plot for the effective reproduction number per tick. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::ObservedReproduction: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Observed Reproduction Number plot

ObservedSerialInterval <: SimulationPlot

A simulation plot type for generating a observed-serial-interval-plot.

generate(plt::ObservedSerialInterval, rd::ResultData; plotargs...)

Generates a plot for the estimation on the observed serial interval per tick. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::ObservedSerialInterval: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Observed Serial Interval plot

PopulationPyramid <: SimulationPlot

A simulation plot type for generating a population pyramid for the associated population model.

generate(plt::PopulationPyramid, rd::ResultData; plotargs...)

Generates population pyramid for a the associated population model.

The current implementation does not offer the option for additional keyworded arguments. The plotargs... argument is just a placeholder.

Parameters

• plt::PopulationPyramid: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): PLACEHOLDER. Currently not implemented.

Returns

• Plots.Plot: Population Pyramid plot

SettingAgeContacts <: SimulationPlot

A simulation plot type for sampling contacts from the model and build an age x age matrix for a given Setting type.

generate(plt::SettingAgeContacts, rd::ResultData; plotargs...)

Generates and returns an age x age matrix from sampled contacts for a given Setting type. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::SettingAgeContacts: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Setting Age Contacts plot

SettingSizeDistribution <: SimulationPlot

A simulation plot type for generating a population pyramid for the associated population model.

generate(plt::SettingSizeDistribution, rd::ResultData; plotargs...)

Generates the setting size distributions for all included settings. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::SettingSizeDistribution: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Setting Size Distribution plot

Supertype for all plots that go into single-run simulation reports

Abstract wrapper function for all simulation report plots. Requires concrete implementation in subtypes

SymptomCategories <: SimulationPlot

A simulation plot type for visualizing the symptom categories of infections by age.

generate(plt::SymptomCategories, rd::ResultData; plotargs...)

Generates and returns a symptom_category x age matrix as heatmap. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::SymptomCategories: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Symptom Categories plot

TestPositiveRate <: SimulationPlot

A simulation plot type for generating a tests-positive-rate-per-tick plot.

generate(plt::TestPositiveRate, rd::ResultData; plotargs...)

Generates and returns a tests-positive-rate-per-tick plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::TestPositiveRate: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Test Positive Rate plot

TickCases <: SimulationPlot

A simulation plot type for generating a new-cases-per-tick plot.

generate(plt::TickCases, rd::ResultData; plotargs...)

Generates and returns a new-cases-per-tick plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::TickCases: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Tick Cases plot

TickCasesBySetting <: SimulationPlot

A simulation plot type for generating tick cases for each included setting type.

generate(plt::TickCasesBySetting, rd::ResultData; plotargs...)

Generates a plot of tick cases for each included setting type. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::TickCasesBySetting: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Tick Cases By Setting plot

TickTests <: SimulationPlot

A simulation plot type for generating a new-tests-per-tick plot.

generate(plt::TickTests, rd::ResultData; plotargs...)

Generates and returns a tests-per-tick plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::TickTests: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Tick Tests plot

TimeToDetection <: SimulationPlot

A simulation plot type for generating a time-to-detection plot.

generate(plt::TimeToDetection, rd::ResultData; plotargs...)

Generates and returns a time-to-detection plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::TimeToDetection: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Time To Detection plot

TotalTests <: SimulationPlot

A simulation plot type for generating a total-tests-per-tick plot.

generate(plt::TotalTests, rd::ResultData; plotargs...)

Generates and returns a total-tests-per-tick plot for a provided simulation object. You can pass any additional keyword arguments using plotargs... that are available in the Plots.jl package.

Parameters

• plt::TotalTests: SimulationPlot struct with meta data (i.e. title, description, and filename)
• rd::ResultData: Input data used to generate plot
• plotargs... (optional): Any argument that the plot() function of the Plots.jl package can take.

Returns

• Plots.Plot: Total Tests plot