Package 'vimcheck'

vimcheck: Diagnostics for Vaccine Impact Modelling Consortium Burden and Impact Estimates

Description

Run diagnostics on burden estimates submitted by modellers in the Vaccine Impact Modelling Consortium (VIMC) and impact estimates calculated by the VIMC Science & Policy team.

Author(s)

Maintainer: Pratik Gupte [email protected] (ORCID)

Authors:

• Katy Gaythorpe (ORCID)

• Xiang Li (ORCID)

• Zoë Gibney (ORCID)

Other contributors:

• Imperial College of Science, Technology and Medicine [copyright holder, funder]

See Also

Useful links:

• https://github.com/vimc/vimcheck

• https://vimc.github.io/vimcheck/

• Report bugs at https://github.com/vimc/vimcheck/issues

---

Sanity checks on burden estimates

Description

Helper function for sanity checks on burden estimate values. Checks whether any burden estimates are non-numeric, missing, or negative.

Usage

basic_burden_sanity(burden)

Arguments

burden

A ⁠<data.frame>⁠ of disease burden estimates. Must have at least a single column named "value" of numeric burden estimates.

Value

A character vector of messages generated by checks on burden estimates, with the length of the vector depending on how many checks fail.

---

Check incoming burden cohort size against interpolated population

Description

Check the modelled disease burden data has similar population sizes as the provided population data.

Usage

check_demography_alignment(
  burden_set,
  wpp,
  gender = c("Both", "Male", "Female")
)

Arguments

burden_set	A ⁠<data.frame>⁠ of modeller-provided burden-set data.
wpp	Population estimates for the country in burden_set, provided by VIMC.
gender	The assigned sex for which demography is to be checked. Options are "Both" (default), "Male", or "Female".

Value

A ⁠<tibble>⁠ giving the alignment, i.e., percentage difference of modelled population size from the WPP-derived population estimates.

---

Package constants

Description

Package constants

Usage

file_dict_colnames

scenario_data_colnames

burden_outcome_names

colnames_plot_demog_compare

Format

An object of class character of length 5.

An object of class character of length 4.

An object of class character of length 10.

An object of class character of length 7.

---

Example of VIMC burden template provided to modellers

Description

An example of the central burden template provided by VIMC to modelling groups.

Usage

eg_burden_template

Format

eg_burden_template

A data frame with 10,201 rows and 11 columns:

disease

Disease name

year

Year

age

Age

country

Country name in short format; this is a placeholder name.

country_name

Country name in long format; this is a placeholder.

cases

Cases of the disease averted

.

dalys

DALYs averted

.

deaths

Deaths averted

.

yll

Years of life-loss averted

.

cohort_size

Population size of the country in a year

.

scenario

Vaccination scenario.

Source

Prepared by the VIMC secretariat.

---

Example of scenario coverage data

Description

Example of scenario coverage data

Usage

eg_coverage

Format

eg_coverage

A data frame with 11 rows and 19 columns.

scenario_type

Scenario type name.

scenario_type_description

Scenario type description string.

scenario

Scenario name string.

scenario_description

Scenario description string.

coverage_set

Coverage set string.

gavi_support_level

String for whether GAVI supported the scenario.

source_from

String identifier for the source.

disease

Infection identifier.

vaccine

Vaccine identifier.

activity_type

Vaccination activity identifier.

year

Year

country

Country name in short format; this is a placeholder name.

age_from

Age limit lower limit.

age_to

Age limit upper limit.

age_range_verbatim

Description of age range.

target

Target for vaccination.

coverage

Proportional coverage.

gender

Sex to which data applies, may be "Male", "Female", or "Both".

proportion_risk

Proportional risk value.

Source

Prepared by the VIMC secretariat.

---

Example of FVP estimate data

Description

Example data of fully-vaccinated persons (FVPs).

Usage

eg_fvps

Format

eg_fvps

A data frame with 11 rows and 24 columns:

scenario_type

Scenario type name.

scenario_type_description

Scenario type description string.

scenario

Scenario name string.

scenario_description

Scenario description string.

coverage_set

Coverage set string.

gavi_support_level

String for whether GAVI supported the scenario.

source_from

String identifier for the source.

disease

Infection identifier.

vaccine

Vaccine identifier.

activity_type

Vaccination activity identifier.

year

Year

country

Country name in short format; this is a placeholder name.

age_from

Age limit lower limit.

age_to

Age limit upper limit.

age_range_verbatim

Description of age range.

target

Target for vaccination.

coverage

Proportional coverage.

gender

Sex to which data applies, may be "Male", "Female", or "Both".

proportion_risk

Proportional risk value.

job

Job code as a numeric.

fvps

Count of FVPs.

fvps_adjusted

Count of adjusted FVPs.

target_adjusted

Adjusted vaccination target.

coverage_adjusted

Ratio of adjusted FVPs to adjusted target.

Source

Prepared by the VIMC secretariat.

---

Example of UN-WPP time-series data

Description

An example of the population estimate data used by VIMC.

Usage

eg_wpp

Format

eg_wpp

A data frame with 65,448 rows and 5 columns:

country

Country name; this is a placeholder name.

year

Year

age

Age

gender

Sex given as three categories, "Male", "Female", or "Both"

.

value

Population size

Source

Derived from data originally prepared by the United Nations as part of the World Population Prospects: https://population.un.org/wpp/.

---

Plot burden and impact diagnostics

Description

Plotting functions for burden and impact diagnostics. All functions operate on data prepared for plotting by a corresponding plotting-preparation function.

Usage

plot_compare_demography(data, fig_number)

plot_age_patterns(burden_age, fig_number)

plot_global_burden_decades(burden_decades, fig_number)

plot_global_burden(burden_data, outcome_name, fig_number)

plot_coverage_set(coverage_set, fig_number)

plot_fvp(fvp_data, fig_number)

Arguments

data	A ⁠<data.frame>⁠ that gives the comparison between VIMC-provided and modeller-used demography values, in long-format. This is expected to be the output of check_demography_alignment() processed by prep_plot_demography().
fig_number	The figure number displayed in the plot title.
burden_age	A ⁠<tibble>⁠ with the minimum column names "age", "value_millions", "burden_outcome", and "scenario"; expected to be the output of prep_plot_age().
burden_decades	A ⁠<tibble>⁠ giving the burden by decade, up to year_max; expected to be the output of prep_plot_burden_decades().
burden_data	This is expected to be a ⁠<tibble>⁠ from a nested-⁠<tibble>⁠ constructed using prep_plot_global_burden().
outcome_name	A string for an outcome name. Allowed outcome names are given in the package constant constants.
coverage_set	A ⁠<tibble>⁠ that is the output of prep_plot_coverage_set().
fvp_data	A ⁠<tibble>⁠ of estimates of fully-vaccinated persons (FVPs) per scenario, with scenarios as factors in order of the number of adjusted-FVPs. Expected to be the output of prep_plot_fvp().

Value

A ⁠<ggplot>⁠ object that can be printed to screen in the plot frame or saved to an output device (i.e., saved as an image file).

---

Prepare data for plotting

Description

Transform burden estimate data from modelling groups to make them suitable for plotting using an appropriate plotting function. Each preparation function corresponds to a plotting function.

Usage

prep_plot_demography(burden)

prep_plot_age(burden)

prep_plot_burden_decades(burden, year_max)

prep_plot_global_burden(burden)

prep_plot_coverage_set(coverage)

prep_plot_fvp(fvp, year_min, year_max)

Arguments

burden	For prep_plot_demography(), a ⁠<tibble>⁠ output from check_demography_alignment(). For other functions, a burden dataset similar to eg_burden_template.
year_max	The maximum year to be represented in a subsequent figure. For prep_plot_burden_decades(), must be a decade, i.e., multiple of 10.
coverage	WIP. Coverage data.
fvp	WIP. Data on counts of fully vaccinated persons.
year_min	Minimum year.

Value

• For prep_plot_demography(): a ⁠<tibble>⁠ in long-format, with the identifier-columns, "scenario", "age", and "year", with the added column "value_millions".

• For prep_plot_age(): a ⁠<tibble>⁠ with the columns "scenario", "burden_outcome", "age", "value_millions".

• For prep_plot_burden_decades(): a ⁠<tibble>⁠ with the columns "scenario", "burden_outcome", "decade_label", and "value_millions".

• For prep_plot_global_burden(): a nested ⁠<tibble>⁠ with the string column "burden_outcome", and a list column of tibbles "burden_data".

• For prep_plot_coverage_set(): WIP

• For prep_plot_fvp(): WIP.

---

Plotting theme for vimcheck

Description

A simple plotting theme building on ggplot2::theme_bw().

Usage

theme_vimc(x_text_angle = 45, y_text_angle = 0, ...)

theme_vimc_noxaxis()

Arguments

x_text_angle	The angle for X-axis labels. Defaults to 45 degrees.
y_text_angle	The angle for Y-axis labels. Defaults to 0 degrees.
...	<dynamic-dots> Other arguments passed to ggplot2::theme(). These will be applied in addition to, or in place of, pre-existing elements defined by this theme. See the examples for this theme's appearance.

Value

A ggplot2 theme that can be added to ggplot2 plots or objects.

Examples

# using an inbuilt dataset
data(mtcars)

# standard theme
ggplot2::ggplot(mtcars, ggplot2::aes(disp, mpg)) +
  ggplot2::geom_point() +
  theme_vimc()

# with X-axis suppression
ggplot2::ggplot(mtcars, ggplot2::aes(disp, mpg)) +
  ggplot2::geom_point() +
  theme_vimc_noxaxis()

---

Validate files in a burden estimate

Description

Check that incoming data files in a burden estimate are complete, and that no extra files have been included. This function expects that incoming burden files are in the directory given by path_burden, which holds a file dictionary which maps each data file to a specific scenario.

Usage

validate_complete_incoming_files(path_burden = "incoming_burden_estimates")

Arguments

path_burden

A directory with burden estimate data.

Value

A ⁠<tibble>⁠ of the scenario file dictionary in path_burden if all checks pass. Otherwise, exits with informative errors on failed checks.

---

Validate file dictionary template

Description

Function to create a file_dictionary template. It maps to touchstone disease scenarios and you will see expected number of scenarios i.e. the number of files that we expect from a model. Users should populate the file column to match the scenario-file. This function will run if a file_dictionary.csv file does not exist

Usage

validate_file_dict_template(disease, path_burden = "incoming_burden_estimates")

Arguments

disease	A disease identifier.
path_burden	A directory with burden estimate data.

Value

Nothing; called primarily for its side-effects. If the file path_burden/file_dictionary.csv does not exist, a file dictionary CSV file is written to the same location. Prints a message to screen informing the user whether any action has been taken.

---

Check incoming burden set against template

Description

Identify extra and missing columns and rows in burden data.

Usage

validate_template_alignment(burden_set, template)

Arguments

burden_set	A ⁠<data.frame>⁠ of modeller-provided burden-set data.
template	A ⁠<data.frame>⁠ of the burden template as provided to modelling groups by VIMC.

Value

A named list of checks carried out on burden_set to compare it against template, with information on missing and extra data.

---