graph_acf: Function focuses on calculating and plotting the...
In deandevl/RtsaPkg: Helpful functions in times series analysis

graph_acf

R Documentation

Function focuses on calculating and plotting the autocorrelation of an observed time series.

Description

Function returns a multi-paneled optional plots of the observed time series, the autocorrelation, and partial autocorrelation. The actual autocorrelation values are also returned in a data.frame.

Usage

graph_acf(
  df,
  time_col = NULL,
  value_col = NULL,
  max_lag = 30,
  line_width = 1,
  line_color = "black",
  title = NULL,
  confid_level = NULL,
  CL_color = "blue",
  caption = "Value",
  obs_x_limits = NULL,
  obs_x_major_breaks = waiver(),
  obs_x_major_date_breaks = waiver(),
  obs_x_date_labels = waiver(),
  obs_y_limits = NULL,
  obs_y_major_breaks = waiver(),
  ac_x_limits = NULL,
  ac_x_major_breaks = seq(1, max_lag, 1),
  ac_y_limits = c(-1, 1),
  ac_y_major_breaks = seq(-1, 1, 0.5),
  pac_x_limits = NULL,
  pac_x_major_breaks = seq(1, max_lag, 1),
  pac_y_limits = c(-1, 1),
  pac_y_major_breaks = seq(-1, 1, 0.5),
  layout = "ver",
  show_obs = TRUE,
  show_ac = TRUE,
  show_pc = TRUE,
  show_major_grids = TRUE,
  show_minor_grids = FALSE,
  bold_y = NULL,
  col_width = 18,
  row_height = 4,
  display_plot = TRUE,
  png_file_path = NULL
)

Arguments

`df`	A data.frame containing a time series with both a value and time column.
`time_col`	Names the column from `df` for the time values. Values can be numeric or Date/POSIXct and is required.
`value_col`	Names the numeric column from `df` for time series values and is required.
`max_lag`	An integer that sets the maximum lag for the autocorrelation and partial autocorrelation plots.
`line_width`	A numeric that sets the line widths in all plots.
`line_color`	A string that sets the line color in all plots.
`title`	A string that defines an overall title to the plots.
`confid_level`	A numeric that defines a confidence level which will be drawn over the autocorrelation plots. Typical value is 1.96. If the value is `NULL`, confidence lines will not be drawn.
`CL_color`	A string that sets the confidence line colors.
`caption`	A string that sets the observed plot caption.
`obs_x_limits`	A Date/POSIXct 2 element vector that sets the minimum and maximum for the observed time series along the x axis. Use NA to refer to the existing minimum and maximum.
`obs_x_major_breaks`	A Date/POSIXct vector or function that defines the exact major tic locations for the observed time series along the x axis.
`obs_x_major_date_breaks`	For Date/POSIXct, a string containing the number and date unit for major breaks along the observed time series. Examples: `"1 year"`, `"4 sec"`, `"3 month"`, `"2 week"`.
`obs_x_date_labels`	For Date/POSIXct, a string containing the format codes for the observed time series x axis date format. This can be a strftime format for each x axis tic date label. Examples: `"%Y-%m"`, `"%Y/%b/%d"`, `"%H-%M-%S"`.
`obs_y_limits`	A numeric 2 element vector that sets the minimum and maximum for the observed series y axis.
`obs_y_major_breaks`	A numeric vector or function that defines the exact major tic locations for the observed series y axis.
`ac_x_limits`	A numeric 2 element vector that sets the minimum and maximum lags for the autocorrelation x axis.
`ac_x_major_breaks`	A numeric vector or function that defines the exact major tic locations for the lags on the autocorrelation x axis.
`ac_y_limits`	A numeric 2 element vector that sets the minimum and maximum for the autocorrelation y axis.
`ac_y_major_breaks`	A numeric vector or function that defines the exact major tic locations for the autocorrelation y axis'. Keep in mind that the limits for an autocorrelation are +-1.
`pac_x_limits`	A numeric 2 element vector that sets the minimum and maximum lags for the partial autocorrelation x axis.
`pac_x_major_breaks`	A numeric vector or function that defines the exact major tic locations for the lags on the partial autocorrelation x axis.
`pac_y_limits`	A numeric 2 element vector that sets the minimum and maximum for the partial autocorrelation y axis.
`pac_y_major_breaks`	A numeric vector or function that defines the exact major tic locations for the partial autocorrelation y axis'. Keep in mind that the limits for an autocorrelation are +-1.
`layout`	A string that sets the layout of the 3 plots horizontally "hor" or vertically "ver".
`show_obs`	A logical which if FALSE hides the plot of observations.
`show_ac`	A logical which if FALSE hides the plot of auto correlations.
`show_pc`	A logical which if FALSE hides the plot of the partial auto correlations.
`show_major_grids`	A logical that controls the appearance of major grids.
`show_minor_grids`	A logical that controls the appearance of minor grids.
`bold_y`	A numeric that plots a bold horizontal line at this y value.
`col_width`	A numeric that sets the width of each plot in centimeters.
`row_height`	A numeric that sets the height of each plot 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 RplotterPkg::multi_panel_grid 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:

"acf_df" – A data frame with column variables for lag ("lag"), and optionally auto coorelation ("acf") and partial autocorrelation ("pacf").
"plots" – A TableGrob object optionally showing any or all the original time series, auto correlations, and partial correlations. Use grid::grid.draw(plots) to display the plots.

deandevl/RtsaPkg documentation built on Oct. 5, 2023, 5:23 p.m.