timetk: plot_time_series – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

plot_time_series

Interactive Plotting for One or More Time Series

Description

A workhorse time-series plotting function that generates interactive plotly plots, consolidates 20+ lines of ggplot2 code, and scales well to many time series.

Usage

plot_time_series(
  .data,
  .date_var,
  .value,
  .color_var = NULL,
  .facet_vars = NULL,
  .facet_ncol = 1,
  .facet_scales = "free_y",
  .facet_collapse = TRUE,
  .facet_collapse_sep = " ",
  .line_color = "#2c3e50",
  .line_size = 0.5,
  .line_type = 1,
  .line_alpha = 1,
  .y_intercept = NULL,
  .y_intercept_color = "#2c3e50",
  .smooth = TRUE,
  .smooth_period = "auto",
  .smooth_message = FALSE,
  .smooth_span = NULL,
  .smooth_degree = 2,
  .smooth_color = "#3366FF",
  .smooth_size = 1,
  .smooth_alpha = 1,
  .legend_show = TRUE,
  .title = "Time Series Plot",
  .x_lab = "",
  .y_lab = "",
  .color_lab = "Legend",
  .interactive = TRUE,
  .plotly_slider = FALSE
)

Arguments

`.data`	A `tibble` or `data.frame` with a time-based column
`.date_var`	A column containing either date or date-time values
`.value`	A column containing numeric values
`.color_var`	A categorical column that can be used to change the line color
`.facet_vars`	One or more grouping columns that broken out into `ggplot2` facets. These can be selected using `tidyselect()` helpers (e.g `contains()`).
`.facet_ncol`	Number of facet columns.
`.facet_scales`	Control facet x & y-axis ranges. Options include "fixed", "free", "free_y", "free_x"
`.facet_collapse`	Multiple facets included on one facet strip instead of multiple facet strips.
`.facet_collapse_sep`	The separator used for collapsing facets.
`.line_color`	Line color. Overrided if `.color_var` is specified.
`.line_size`	Line size.
`.line_type`	Line type.
`.line_alpha`	Line alpha (opacity). Range: (0, 1).
`.y_intercept`	Value for a y-intercept on the plot
`.y_intercept_color`	Color for the y-intercept
`.smooth`	Logical - Whether or not to include a trendline smoother. Uses See `smooth_vec()` to apply a LOESS smoother.
`.smooth_period`	Number of observations to include in the Loess Smoother. Set to "auto" by default, which uses `tk_get_trend()` to determine a logical trend cycle.
`.smooth_message`	Logical. Whether or not to return the trend selected as a message. Useful for those that want to see what `.smooth_period` was selected.
`.smooth_span`	Percentage of observations to include in the Loess Smoother. You can use either period or span. See `smooth_vec()`.
`.smooth_degree`	Flexibility of Loess Polynomial. Either 0, 1, 2 (0 = lest flexible, 2 = more flexible).
`.smooth_color`	Smoother line color
`.smooth_size`	Smoother line size
`.smooth_alpha`	Smoother alpha (opacity). Range: (0, 1).
`.legend_show`	Toggles on/off the Legend
`.title`	Title for the plot
`.x_lab`	X-axis label for the plot
`.y_lab`	Y-axis label for the plot
`.color_lab`	Legend label if a `color_var` is used.
`.interactive`	Returns either a static (`ggplot2`) visualization or an interactive (`plotly`) visualization
`.plotly_slider`	If TRUE, returns a plotly date range slider.

Details

plot_time_series() is a scalable function that works with both ungrouped and grouped data.frame objects (and tibbles!).

Interactive by Default

plot_time_series() is built for exploration using:

Interactive Plots: plotly (default) - Great for exploring!
Static Plots: ggplot2 (set .interactive = FALSE) - Great for PDF Reports

By default, an interactive plotly visualization is returned.

Scalable with Facets & Dplyr Groups

plot_time_series() returns multiple time series plots using ggplot2 facets:

group_by() - If groups are detected, multiple facets are returned
plot_time_series(.facet_vars) - You can manually supply facets as well.

Can Transform Values just like ggplot

The .values argument accepts transformations just like ggplot2. For example, if you want to take the log of sales you can use a call like plot_time_series(date, log(sales)) and the log transformation will be applied.

Smoother Period / Span Calculation

The .smooth = TRUE option returns a smoother that is calculated based on either:

A .smooth_period: Number of observations
A .smooth_span: A percentage of observations

By default, the .smooth_period is automatically calculated using 75% of the observertions. This is the same as geom_smooth(method = "loess", span = 0.75).

A user can specify a time-based window (e.g. .smooth_period = "1 year") or a numeric value (e.g. smooth_period = 365).

Time-based windows return the median number of observations in a window using tk_get_trend().

Value

A static ggplot2 plot or an interactive plotly plot

Examples

library(tidyverse)
library(tidyquant)
library(lubridate)
library(timetk)

# Works with individual time series
FANG %>%
    filter(symbol == "FB") %>%
    plot_time_series(date, adjusted, .interactive = FALSE)

# Works with groups
FANG %>%
    group_by(symbol) %>%
    plot_time_series(date, adjusted,
                     .facet_ncol  = 2,     # 2-column layout
                     .interactive = FALSE)

# Can also group inside & use .color_var
FANG %>%
    mutate(year = year(date)) %>%
    plot_time_series(date, adjusted,
                     .facet_vars   = c(symbol, year), # add groups/facets
                     .color_var    = year,            # color by year
                     .facet_ncol   = 4,
                     .facet_scales = "free",
                     .interactive  = FALSE)

# Can apply transformations to .value or .color_var
# - .value = log(adjusted)
# - .color_var = year(date)
FANG %>%
    plot_time_series(date, log(adjusted),
                     .color_var    = year(date),
                     .facet_vars   = contains("symbol"),
                     .facet_ncol   = 2,
                     .facet_scales = "free",
                     .y_lab        = "Log Scale",
                     .interactive  = FALSE)

timetk

A Tool Kit for Working with Time Series in R

v2.6.1

GPL (>= 3)

Authors

Matt Dancho [aut, cre], Davis Vaughan [aut]

Initial release