graph_lead_lag: Function provides plots of a time series X(t) versus its lead...
In deandevl/RtsaPkg: Helpful functions in times series analysis

graph_lead_lag

R Documentation

Function provides plots of a time series X(t) versus its lead X(t+k) or lag X(t-k) series for multiple values of k.

Description

The multipanelled plots have the values of a time series along the x axis and its corresponding lead/lag values along the y axis. The purpose of the plots is to pin point the values for k (i.e. the amount of lead or lag) that show a relationship with the current observed time series X(t).

Usage

graph_lead_lag(
  df = NULL,
  time_col = NULL,
  value_col = NULL,
  k_vector = c(1, 2, 3, 4),
  direction = "lag",
  n_columns = 2,
  title = NULL,
  x_limits = NULL,
  x_major_breaks = waiver(),
  y_limits = NULL,
  y_major_breaks = waiver(),
  rot_y_tic_label = FALSE,
  show_major_grids = TRUE,
  show_minor_grids = TRUE,
  show_fit = FALSE,
  fit_color = "blue",
  axis_text_size = 11,
  pts_color = "black",
  pts_fill = "white",
  pts_shape = 21,
  pts_stroke = 1,
  pts_alpha = 1,
  pts_size = 1,
  col_width = 12,
  row_height = 8,
  display_plot = TRUE,
  png_file_path = NULL
)

Arguments

`df`	A time series data frame with columns for a time and their corresponding observed values.
`time_col`	Names the column from `df` for the time values. Values can be numeric or Date/POSIXct.
`value_col`	Names the value column from `df`.
`k_vector`	A vector of integers giving multiple leads or lags k to derive from the `value_col` series.
`direction`	A string that controls either finding the next ("lead") or previous ("lag") values within `values`. The default is "lag".
`n_columns`	An integer that sets the number of columns in the multi-panel.
`title`	A string that defines an overall title to the pair of plots.
`x_limits`	A numeric 2 element vector that sets the minimum and maximum for the x axis time series values. Use NA to refer to the existing minimum and maximum.
`x_major_breaks`	A numeric vector or function that defines the exact major tic locations along the x axis.
`y_limits`	A numeric 2 element vector that sets the minimum and maximum for the y axis lag values. Use NA to refer to the existing minimum and maximum.
`y_major_breaks`	A numeric vector or function that defines the exact major tic locations for the y axis'.
`rot_y_tic_label`	A logical which if TRUE rotates the y tic labels 90 degrees for enhanced readability.
`show_major_grids`	A logical that controls the appearance of major grids.
`show_minor_grids`	A logical that controls the appearance of minor grids.
`show_fit`	A logical that controls the appearance of a fitted line through the points.
`fit_color`	A string that sets the fitted line color if `show_fit` is TRUE.
`axis_text_size`	A numeric that sets the font size along the axis'. Default is 11.
`pts_color`	A string that sets the color of the points.
`pts_fill`	A string that sets the fill color of the points.
`pts_shape`	A numeric integer that sets the shape of the points. Typical values are 21 "circle", 22 "square", 23 "diamond", 24 "up triangle", 25 "down triangle".
`pts_stroke`	A numeric that sets the drawing width for a point shape.
`pts_alpha`	A numeric value that sets the alpha level of `pts_color`.
`pts_size`	A numeric value that sets the size of the points.
`col_width`	An integer that sets the width of each plot column in centimeters.
`row_height`	An integer that sets the height of each plot column in centimeters.
`display_plot`	A logical that if TRUE displays the plot.
`png_file_path`	A character string with the directory and file name to produce a png image of the plot.

Details

The function uses the RplotterPkb package to draw the multi-paneled plot.

If display_plot is TRUE then the plots will be displayed. If display_plot is FALSE then the function returns a named list that includes a plot object which can be displayed from the console by entering:

grid::grid.newpage()
grid::grid.draw(plot object)

Value

Returning a named list with:

"models" – A list of the fitted linear models for each lead or lag values submitted via k_vector.
"predictions" – A list of data frames corresponding to each model with columns for for time "DateTime", predictions "Predictions", and residuals "Residuals".
"plots" – A multi-paneled TableGrob object plotting the lead or lag series with the original series. Use grid::grid.draw(plots) to display the plots.