Creates time series plots with support for single or multiple indicators, single or multiple countries, stacked area plots, dual axes, and various visual customizations (e.g., references and legend). The function automatically determines the most appropriate plot type based on the input data structure and specified parameters.

Usage

wp_plot_series(
  data,
  y_axis = NULL,
  right_axis = NULL,
  key_dates = NULL,
  area = FALSE,
  by_indicator = NULL,
  filename = NULL,
  print = TRUE,
  legend = TRUE,
  reference = TRUE,
  title = NULL,
  subtitle = NULL,
  subfig_title = NULL,
  verbose = TRUE,
  debug = FALSE,
  size = NULL,
  base_size = 16,
  bg = "transparent"
)

Arguments

data: data.frame that must contain the following columns: - ISO: ISO 3-letter country codes (required) - Date: dates in Date format (required) - Variable: indicator names (required) - Value: numeric values (required) - Country: country names (optional, auto-generated from ISO if missing) - Reference: source citations (required if reference=TRUE)
y_axis: Single string, vector of strings, TRUE, FALSE, or NULL: - Single string: common y-axis label for all plots - Vector of strings: individual labels for each plot/axis - TRUE: use Variable names as labels - FALSE/NULL: no axis labels For dual axis plots, must be vector of length 2 for left and right axes. For multi-indicator plots, length must match number of indicators.
right_axis: controls the right y-axis behavior: - NULL/FALSE: no right axis (default) - TRUE: automatically assigns variables to right axis based on scale - character vector: names of variables to assign to right axis Only available for plots with 2 or more indicators. Cannot be used with area=TRUE.
key_dates: data.frame for marking significant events: - Must have exactly 2 columns - Column 1: event descriptions - Column 2: corresponding dates in Date format - Events outside plot date range are automatically filtered - NULL for no event markers
area: logical; if TRUE, creates a stacked area plot: - Only for single-country, multi-indicator plots - First variable shown as line on top of stacked areas - Cannot be used with right_axis=TRUE Default is FALSE.
by_indicator: logical; controls faceting in multi-panel plots: - TRUE: creates separate panels for each indicator - FALSE: creates separate panels for each country - Ignored for single country or single indicator plots Default is TRUE.
filename: character string for saving plots: - Specify name without extension - Plots saved as both PNG and PDF in 'img/' directory - NULL/FALSE for no file output
print: logical; controls plot display: - TRUE: displays the plot - FALSE: creates but doesn't display the plot Default is TRUE.
legend: logical; controls legend display: - TRUE: includes a legend - FALSE: omits the legend Default is TRUE.
reference: logical; controls reference panel: - TRUE: includes reference citations panel (requires Reference column) - FALSE: omits reference panel - Automatically set to FALSE if Reference column missing/empty Default is TRUE.
title: character string for main plot title: - NULL/FALSE for no title
subtitle: character string for plot subtitle: - NULL/FALSE for no subtitle
subfig_title: controls subplot titles in multi-panel plots: - TRUE: uses default titles (Variable or Country names) - FALSE: no subplot titles - Character vector: custom titles (length must match number of panels) - Ignored for single panel plots Default is TRUE.
verbose: logical; controls information messages: - TRUE: prints processing information - FALSE: suppresses information messages Default is TRUE.
debug: logical; controls debugging output: - TRUE: prints detailed debugging information - FALSE: suppresses debugging information Default is FALSE.
size: numeric or NULL; controls plot dimensions: - 1: small (10x7 inches) - 2: medium (15x7 inches) - 3: large (15x10 inches) - 4: extra large (20x10 inches) - NULL: auto-sizes based on data
base_size: numeric; base font size in points: - Controls text size throughout the plot - Must be positive number - Default is 16
bg: character; controls plot background color: - "transparent": transparent background (default) - Any valid color string: sets background to that color

Value

A ggplot2 object containing the time series plot

Details

The function automatically selects the appropriate plotting implementation based on the data structure and parameters:

Single country, multiple indicators:
- Basic line plot (default)
- Stacked area plot (if area = TRUE)
- Dual axis plot (if right_axis specified)
Multiple countries, single indicator:
- Multi-line plot with color-coded countries
Multiple countries, multiple indicators:
- Faceted plot by indicator (if by_indicator = TRUE)
- Faceted plot by country (if by_indicator = FALSE)

The function includes multiple features for customization:

Automatic axis scaling and formatting
Event markers with customizable labels
Reference panel for data sources
Flexible legend positioning
Consistent theme across all plot types

Examples

# Basic time series for one country and multiple indicators
data <- data.frame(
  Date = rep(seq(as.Date("2000-01-01"), as.Date("2020-01-01"), by = "year"), 2),
  ISO = "FRA",
  Variable = rep(c("GDP", "Inflation"), each = 21),
  Value = c(rnorm(21, 2, 0.5), rnorm(21, 3, 1)),
  Reference = "World Bank"
)
wp_plot_series(data, y_axis = "Percent")
#>  [COUNTRY] Column Country added to data 
#>  [CONFIG] n_countries = 1 | n_indicators = 2 | plot_type = series 
#>  [SUBPLOT] call 'in_plot_multi_indic_one_ctry' 
#>  [ARGS] Unused arguments for function 'plot_func': subfig_title, bg, right_axis, area, by_indicator, dimensions 
#> Warning: Using `as.character()` on a quosure is deprecated as of rlang 0.3.0. Please use
#> `as_label()` or `as_name()` instead.
#> This warning is displayed once every 8 hours.
#>  [LEGEND] Legend items (display): GDP, Inflation 
#>  [LEGEND] plot_type = 'series' | legend_cols = 2' | legend_height = 1.33333333333333' | n_items = 2 
#>  [ADD_REF] References: World Bank 

# Dual axis plot with manual axis assignment
wp_plot_series(data, 
               y_axis = c("GDP Growth (%)", "Inflation (%)"),
               right_axis = "Inflation")
#>  [COUNTRY] Column Country added to data 
#>  [CONFIG] n_countries = 1 | n_indicators = 2 | plot_type = series 
#>  [SUBPLOT] call 'in_plot_multi_indic_one_ctry_two_axes' 
#>  [ARGS] Unused arguments for function 'plot_func': subfig_title, bg, area, by_indicator, dimensions 
#>  [LEGEND] Legend items (display): GDP, Inflation 
#>  [LEGEND] plot_type = 'series' | legend_cols = 2' | legend_height = 1.33333333333333' | n_items = 2 
#>  [ADD_REF] References: World Bank 

# Stacked area plot
wp_plot_series(data, 
               y_axis = "Percent",
               area = TRUE)
#>  [COUNTRY] Column Country added to data 
#>  [CONFIG] n_countries = 1 | n_indicators = 2 | plot_type = series 
#>  [SUBPLOT] call 'in_plot_one_ctry_area' 
#>  [ARGS] Unused arguments for function 'plot_func': subfig_title, bg, right_axis, area, by_indicator, dimensions 
#> Warning: Duplicated aesthetics after name standardisation: fill
#>  [LEGEND] Legend items (display): GDP, Inflation 
#>  [LEGEND] plot_type = 'series' | legend_cols = 2' | legend_height = 2.33333333333333' | n_items = 2 
#>  [ADD_REF] References: World Bank 

# Multiple countries with event markers
data_multi <- data.frame(
  Date = rep(seq(as.Date("2000-01-01"), as.Date("2020-01-01"), by = "year"), 4),
  ISO = rep(c("FRA", "DEU"), each = 42),
  Variable = rep(rep(c("GDP", "Inflation"), each = 21), 2),
  Value = rnorm(84, 2, 0.5),
  Reference = "World Bank"
)
events <- data.frame(
  Event = c("Financial Crisis", "Euro Crisis"),
  Date = as.Date(c("2008-09-15", "2010-05-01"))
)
wp_plot_series(data_multi,
               y_axis = "Percent",
               key_dates = events,
               by_indicator = TRUE)
#>  [COUNTRY] Column Country added to data 
#>  [CONFIG] n_countries = 2 | n_indicators = 2 | plot_type = series 
#>  [SUBPLOT] call 'in_plot_multi_by_indic' 
#>  [ARGS] Unused arguments for function 'plot_func': bg, right_axis, area, by_indicator, dimensions 
#>  [DATES] add key dates 
#>  [DATES] add key dates 
#>  [LEGEND] Legend items (display): France, Germany 
#>  [LEGEND] plot_type = 'series' | legend_cols = 2' | legend_height = 1.33333333333333' | n_items = 2 
#>  [ADD_REF] References: World Bank

Create Time Series Plots with Multiple Configuration Options

Usage

Arguments

Value

Details

See also

Examples