Package 'mindthegap'

Add Annotation to a ggplot Object

Description

This internal function adds a custom text annotation to a ggplot object, positioning it at a specified proportion of the plot's x and y axis ranges. The default annotation is used to indicate epidemic control.

Usage

adorn_annotation(
  p,
  annotation_label = "<-- Epidemic control",
  annotation_proportion = 0.9
)

Arguments

p	A ggplot2 plot object to which the annotation will be added.
annotation_label	A character string specifying the text to annotate the plot with. The default value is "<– Epidemic control".
annotation_proportion	A numeric value between 0 and 1 indicating the position of the annotation relative to the axis ranges. Default is 0.9, placing the annotation close to the top-right of the plot.

Details

This function calculates the annotation position based on the specified proportion of the plot's axis limits. The annotation is angled at 45 degrees to provide visual emphasis, typically used to indicate a threshold or a notable point in the data.

Value

The original ggplot2 plot object with the annotation added.

---

95's Table Plot

Description

This function creates a summary table showing OU progress toward the 95-95-95's (Deprecated)

Usage

base_plot(
  df,
  cntry,
  denom = c("PLHIV", "Relative"),
  grp = c("All", "Female 15+", "Male 15+", "Peds <15"),
  yr = NULL
)

Arguments

df	dataframe from load_unaids
cntry	PEPFAR country to visualize (list OU name)
denom	which denominator/base to use, "PLHIV" (default) or "Relative"
grp	age/sex group, c("All", "Female 15+", "Male 15+", "Peds <15")
yr	year in question, defaults to max year

Details

Use tab_95s_progress instead.

Value

gt table

See Also

load_unaids()

Examples

## Not run: 
  df_unaids <- load_unaids()
   base_plot(df_unaids, "Kenya", denom = "PLHIV")
   base_plot(df_unaids, "Kenya", denom = "Relative")

## End(Not run)

---

Epidemic Control Plot

Description

This function creates epidemic control curves for "ALL PEPFAR" or selected OU's

Usage

epi_plot(df, sel_cntry = c("All PEPFAR"))

Arguments

df	UNAIDS data frame loaded from load_unaids()
sel_cntry	PEPFAR country to visualize ("ALL PEPFAR" as default or list OU names)

Details

Use plot_epi_trends() instead.

Value

Epidemic control plot showing trends in new infections and total deaths to HIV population

See Also

load_unaids()

Examples

## Not run: 
   df_unaids <- load_unaids(pepfar_only = FALSE)
   epi_plot(df_unaids)
   epi_plot(df_unaids, sel_cntry = "Lesotho")
   epi_plot(df_unaids, sel_cntry = c("South Africa", "Zambia", "Kenya", "Malawi"))

## End(Not run)

---

Full list of expected indicators

Description

A dataframe containing the different indicators and their disaggregate components to ensure all data expected for are being exported from EDMS.

Usage

expected_ind

Format

A data frame with 62 rows and 5 columns:

indicator_edms

Parsed EDMS indicator name

age, sex

EDMS indicator disaggregates

source

Source folder on EDMS

expected

Expected as part of EDMS Epi + 95s pull (TRUE)

---

Mapping of EDMS Indicator Names to those used in OHA

Description

A mapping of the EDMS acronym to common names used by OHA analysts.

Usage

indicator_map

Format

A data frame with 21 rows and 3 columns:

acronym

EDMS Acronym

indicator_edms

Parsed EDMS indicator name

indicator

Common indicator name

---

Load tidy UNAIDS HIV Estimates and Test & Treat Data

Description

This function is used to load the latest UNAIDS data. These data were queried and exported from UNAIDS EMDS database, cleaned using munge_edms and finally loaded up on GitHub as a release. This function downloads the data and loads it into your working session.

Usage

load_unaids(pepfar_only = TRUE)

Arguments

pepfar_only

filters dataset to only PEPFAR countries if TRUE (default = TRUE)

Value

df

Examples

## Not run: 
   df_unaids <- load_unaids(pepfar_only = TRUE)

## End(Not run)

---

Clean UNAIDS Data from EDMS

Description

Clean UNAIDS Data from EDMS

Usage

munge_edms(path, epi_95s_flag = TRUE)

Arguments

path	filepath to the EDMS export (csv)
epi_95s_flag	add variables to dataframe for UNAIDS 95s achievement and epidemic control status, default = TRUE

Value

df

Examples

## Not run: 
  filepath <- "../DataList_10_1_2030-12_00_00-AM.csv"
  df <- munge_edms(filepath)

## End(Not run)

---

Cleaning UNAIDS Data

Description

Deprecated. This function fetches and cleans UNAIDS Estimates/Test and Treat Data

Usage

munge_unaids(return_type, indicator_type)

Arguments

return_type	Returns either 'HIV Estimates' or 'HIV Test & Treat' Data
indicator_type	Returns either 'Integer' or 'Percent' indicator values

Value

df

Examples

## Not run: 
   munge_unaids(return_type = "HIV Test & Treat", indicator_type = "Percent")

## End(Not run)

---

PEPFAR countries + ISO codes

Description

This is a dataframe of countries that receive PEPFAR funding. This df comes from glamr::pepfar_country_list and is originally derived from the PEPFAR Financial Structured Dataset (FSD).

Usage

pepfar

Format

A data frame with 55 rows and 2 columns:

country_pepfar

Country name

iso3

Country ISO3 code

---

Plot Epidemic Control Trajectories

Description

Generates a connected scatterplot of trajectories for deaths and new infections for specified countries.

Usage

plot_connected_scatter(.data, sel_cntry, year_range = 2010:2023)

Arguments

.data	A data frame containing epidemiological data. It should include columns such as country, year, indicator, estimate, and others required for processing.
sel_cntry	A character vector of countries to include in the plot.
year_range	A numeric vector specifying the range of years to include in the analysis. Default is 2010:2023.

Details

This function serves as a wrapper, orchestrating the preparation, calculation, and visualization of the data. It processes the input data, calculates appropriate axis limits, constructs the epidemic control plot, and finally adds an annotation for epidemic control.

Value

A ggplot2 plot object showing the epidemic control trajectories with deaths on the x-axis and new infections on the y-axis.

Examples

## Not run: 
   df_unaids <- load_unaids(pepfar_only = FALSE)
   plot_connected_scatter(df_unaids)
   plot_connected_scatter(df_unaids, sel_cntry = "Lesotho")
   plot_connected_scatter(df_unaids, sel_cntry = c("South Africa", "Zambia", "Kenya", "Malawi"))

## End(Not run)

---

Epidemic Control Plot

Description

This function creates epidemic control curves for "ALL PEPFAR" or selected OU's

Usage

plot_epi_trends(df, sel_cntry = c("All PEPFAR"))

Arguments

df	UNAIDS data frame loaded from load_unaids()
sel_cntry	PEPFAR country to visualize ("ALL PEPFAR" as default or list OU names)

Value

Epidemic control plot showing trends in new infections and total deaths to HIV population

See Also

load_unaids()

Examples

## Not run: 
   df_unaids <- load_unaids(pepfar_only = FALSE)
   plot_epi_trends(df_unaids)
   plot_epi_trends(df_unaids, sel_cntry = "Lesotho")
   plot_epi_trends(df_unaids, sel_cntry = c("South Africa", "Zambia", "Kenya", "Malawi"))

## End(Not run)

---

Prepare UNAIDS Epidemiological Data for Analysis

Description

This function filters and processes UNAIDS epidemiological data by selecting relevant indicators ("Number Total Deaths to HIV Population" and "Number New HIV Infections"), reshaping the data into a wide format, and renaming the resulting columns for readability. It is intended to prepare the dataset for a race to the bottom visualization.

Usage

prep_epi_data(df, sel_cntry, year_range)

Arguments

df	A data frame containing the pre-processed UNAIDS EDMS data.
sel_cntry	A character vector of country names for which data should be filtered. The function will filter the dataset to include only these countries.
year_range	A numeric vector specifying the range of years to filter the dataset by. Only data within this range will be retained.

Details

The function first filters the data to include only the selected countries (sel_cntry), specified year range (year_range), and the indicators "Number Total Deaths to HIV Population" and "Number New HIV Infections". It selects columns relevant for further analysis, reshapes the data into a wide format, and renames the indicator columns to deaths and infections for better readability. If no data matches the provided filters, an error is thrown to inform the user.

Value

A filtered and reshaped data frame containing the selected countries, indicators, and years. The resulting data frame includes columns for region, country, year, iso, pepfar, and estimates of deaths and infections.

Note

This function assumes that the dataset includes all age and sex categories set to "All". Make sure to provide a correctly formatted dataset and verify country names to avoid errors.

Examples

## Not run: 
  # Load a sample UNAIDS dataset
  df_unaids <- load_unaids() # Assume this function loads your dataset

  # Prepare data for Lesotho for the years 2010-2023
  df_prepared <- prep_epi_data(df_unaids, sel_cntry = "Lesotho", year_range = 2010:2023)

## End(Not run)

---

Publish Tidy UNAIDS Data as a GitHub Release

Description

This is a developer's tool to take the output from EDMS that has been tidied via munge_edms and push it to GitHub as a Release. This is performed once annually when the data are updated and then users will access via load_unaids. This function posts versions for all countries as well as PEPFAR only countries in csv and rds formats.

Usage

publish_release(df)

Arguments

df	dataframe created by munge_edms

See Also

munge_edms() and load_unaids()

Examples

## Not run: 
  filepath <- "../DataList_10_1_2030-12_00_00-AM.csv"
  df <- munge_edms(filepath)
  publish_release(df)

## End(Not run)

---

Pull clean UNAIDS HIV Estimates

Description

Deprecated. Pull clean UNAIDS estimates data. Wrapper around pull_unaids.

Usage

pull_estimates(pepfar_only = TRUE)

Arguments

pepfar_only

filters dataset to only PEPFAR countries if TRUE (default = TRUE)

Value

df

Examples

## Not run: 
   pull_estimates()

## End(Not run)

---

Pull clean UNAIDS HIV Test & Treat

Description

Deprecated. Pull clean UNAIDS 2022 (1990-2022) HIV Test & Treat data. Wrapper around pull_unaids.

Usage

pull_testtreat(pepfar_only = TRUE)

Arguments

pepfar_only

filters dataset to only PEPFAR countries if TRUE (default = TRUE)

Value

df

Examples

## Not run: 
   pull_testtreat()

## End(Not run)

---

Pull clean UNAIDS HIV Estimates and Test & Treat Data

Description

Deprecated. Pull clean UNAIDS estimates

Usage

pull_unaids(data_type, pepfar_only = TRUE)

Arguments

data_type	returns one of 2 available data set types eg "HIV Estimates", "HIV Test & Treat" (or both if missing)
pepfar_only	filters dataset to only PEPFAR countries if TRUE (default = TRUE)

Value

df

Examples

## Not run: 
   pull_unaids(data_type = "HIV Estimates", pepfar_only = TRUE)

## End(Not run)

---

EMDS Extract Required Columns

Description

This is a list of the key columns that are needed through the munging process for the clean export. The dataset originates from the UNAIDS EDMS Database.

Usage

req_cols

Format

Character vectors. A vector of length 11

---

UNAIDS Source Info

Description

Returns UNAIDS Source info for consistent sourcing notes

Usage

source_note

Format

An object of class character of length 1.

---

95's Table Plot

Description

This function creates a summary table showing OU progress toward the 95-95-95's

Usage

tab_95s(
  df,
  cntry,
  denom = c("PLHIV", "Relative"),
  grp = c("All", "Female 15+", "Male 15+", "Peds <15"),
  yr = NULL
)

Arguments

df	dataframe from load_unaids
cntry	PEPFAR country to visualize (list OU name)
denom	which denominator/base to use, "PLHIV" (default) or "Relative"
grp	age/sex group, c("All", "Female 15+", "Male 15+", "Peds <15")
yr	year in question, defaults to max year

Value

gt table

See Also

load_unaids()

Examples

## Not run: 
   tab_95s(load_unaids(), "Kenya", denom = "PLHIV")
   tab_95s(load_unaids(), "Kenya", denom = "Relative")

## End(Not run)

---