acf_plot {itsadug}

Generate an ACF plot of an aggregated time series.

Description

Generate an ACF plot of an aggregated time series.

Usage

acf_plot(
  x,
  split_by = NULL,
  max_lag = NULL,
  plot = TRUE,
  fun = mean,
  cond = NULL,
  return_all = FALSE,
  ...
)

Arguments

x

A vector with time series data, typically residuals of a regression model. (See examples for how to avoid errors due to missing values.)

split_by

List of vectors (each with equal length as x) that group the values of x into trials or timeseries events. Generally other columns from the same data frame.

max_lag

Maximum lag at which to calculate the acf. Default is the maximum for the longest time series.

plot

Logical: whether or not to plot the ACF. Default is TRUE.

fun

The function used when aggregating over time series (depending on the value of split_by).

cond

Named list with a selection of the time series events specified in split_by. Default is NULL, indicating that all time series are being processed, rather than a selection.

return_all

Returning acfs for all time series.

...

Other arguments for plotting, see par.

Value

An aggregated ACF plot and / or optionally a list with the aggregated ACF values.

Author(s)

Jacolien van Rij

See Also

Use acf for the original ACF function, and acf_n_plots for inspection of individual time series.

Other functions for model criticism: acf_n_plots(), acf_resid(), derive_timeseries(), resid_gam(), start_event(), start_value_rho()

Examples

data(simdat)

# Default acf function:
acf(simdat$Y)
# Same plot with acf_plot:
acf_plot(simdat$Y)
# Average of ACFs per time series:
acf_plot(simdat$Y, split_by=list(simdat$Subject, simdat$Trial))
# Median of ACFs per time series:
acf_plot(simdat$Y, split_by=list(simdat$Subject, simdat$Trial), fun=median)

# extract value of Lag1:
lag1 <- acf_plot(simdat$Y, 
   split_by=list(Subject=simdat$Subject, Trial=simdat$Trial), 
   plot=FALSE)['1']

#---------------------------------------------
# When using model residuals
#---------------------------------------------

# add missing values to simdat:
simdat[sample(nrow(simdat), 15),]$Y <- NA
# simple linear model:
m1 <- lm(Y ~ Time, data=simdat)

## Not run: 
# This will generate an error:
acf_plot(resid(m1), split_by=list(simdat$Subject, simdat$Trial))

## End(Not run)
# This should work:
el.na <- missing_est(m1)
acf_plot(resid(m1), 
     split_by=list(simdat[-el.na,]$Subject, simdat[-el.na,]$Trial))

# This should also work:
simdat$res <- NA
simdat[!is.na(simdat$Y),]$res <- resid(m1)
acf_plot(simdat$res, split_by=list(simdat$Subject, simdat$Trial))

# see the vignette for examples:
vignette('acf', package='itsadug')