Package 'its.analysis'

Run Interrupted Time Series Analyses

Description

Sets up an Interrupted Time Series Analysis (ITSA) for analysing short time series data.

Usage

itsa.model(
  data = NULL,
  time = NULL,
  depvar = NULL,
  interrupt_var = NULL,
  covariates = NULL,
  alpha = 0.05,
  no.plots = FALSE,
  bootstrap = TRUE,
  Reps = 1000,
  parr = "no",
  print = TRUE
)

Arguments

data	define data. Must be a data frame or object coercible into a data frame.
time	define time variable, must either be numeric (such as a year) or of class date.
depvar	define dependent variable, must be continuous.
interrupt_var	define interruption treatment/condition variable, must be a factor.
covariates	specify a covariate, or vector of covariates, default is NULL.
alpha	desired alpha (p-value boundary of null hypothesis rejection), default is 0.05.
no.plots	logical, specify that function should not return the ITSA plot, default is FALSE.
bootstrap	logical, specify where function should run bootstrap estimations of F-values and return table of results, default is TRUE.
Reps	numeric, define number of replications for bootstrapping, default is 1000.
parr	character, define if parallelisation should be used for bootstrapper, options are inherited from boot package (the default of "no", or "multicore" and "snow").
print	logical, specify whether the main model result should be printed to the console.

Details

This function provides an Interrupted Time Series Analysis (ITSA) model using a variance-centric approach to estimating change in a dependent variable over time.

Using the defined variables, a Type-2 Sum Squares ANCOVA Lagged Dependent Variable model is fitted which estimates the difference in means between interrupted and non-interrupted time periods, while accounting for the lag of the dependent variable and any further specified covariates.

The function includes a bootstrap model, which runs by default. This repeats 1000 replications of the main model with randomly drawn samples. A trimmed median (10 percent removed) F-value is reported and a bootstrapped p-value derived from it. Users may turn off the bootstrapping model, or the number of replications for the bootstrap model to pass through can be altered using the Reps argument.

Variable names must be defined using quotation marks, or their column index number within the data. Any number of covariates can be passed into the covariates argument as a list of vectors (both must be within the same data as the dependent and independent variables).

Also returned as warning messages are the results of ANOVA and residual autocorrelation assumptions check ran in the background, if any are potentially violated. These tests and further post-estimation can be done through the itsa.postest function.

Returns to console the results from analysis of variance test, results of the F-value bootstrap model, and a summary of the result (relative to user defined alpha) and any assumption violation warnings. Users may force this return off by declaring print=FALSE in the model arguments.

Further returns a plot to the plot window graphing the dependent variable time series and interruption points. As this is a ggplot2 generated object, users can call the plot and make further customisations to it as an output.

Assigning to an object will return a list of all of the above, plus further tests including a Tukey Honest Significant Differences test, the data and arguments set by the user, a table of time-series group means, the full bootstrap model results and results of assumptions tests, and the full list of residual and fitted values.

If any of data, depvar, interrupt_var, or time are undefined, the process will stop and an error message will appear.

Value

Returns a large list which can be assigned to the global environment, containing results and necessary information for running post-estimation itsa.postest function. It also contains the Time Series Interruption plot (itsa.plot) and bootstrap results, if applied.

Examples

# Build variables

year <- c(2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018)
depv <- c(8.22, 8.19, 8.23, 8.28, 8.32, 8.39, 8.02,
7.92, 7.62, 7.23, 7.1, 7.11, 6.95, 7.36, 7.51, 7.78, 7.92, 7.81)
interruption <- c(0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0)
cov1 <- c(3.1, 3.3, 5.1, 5.2, 5.4, 4.5, 4.7, 4.9, 5.3,
5.6, 5.8, 6.0, 4.8, 5.2, 4.5, 4.6, 5.1, 4.7)

x <- as.data.frame(cbind(year, depv, interruption, cov1))

# First example model
itsa.model(data=x, time="year", depvar="depv", interrupt_var = "interruption",
alpha=0.05, bootstrap=TRUE, Reps = 250)

# Add a covariate, change alpha to 0.1
itsa.model(data=x, time="year", depvar="depv", interrupt_var = "interruption",
covariates = "cov1", alpha=0.1, bootstrap=TRUE, Reps = 250)

# Force no plots and turn off bootstrap
itsa.model(data=x, time="year", depvar="depv", interrupt_var = "interruption",
covariates = "cov1", alpha=0.1, no.plots=TRUE, bootstrap=FALSE)

# Example of no significant result
itsa.model(data=x, time="year", depvar="cov1", interrupt_var = "interruption",
 alpha=0.05, bootstrap=FALSE)

---

Post-estimating ITSA models

Description

Function to produce post-estimation plots from the itsa.model function.

Usage

itsa.postest(
  model = NULL,
  no.plots = FALSE,
  alpha = 0.05,
  bootstrap = TRUE,
  print = TRUE
)

Arguments

model	define ITSA model results object.
no.plots	logical, specify whether function should present post-estimation plots (default is FALSE).
alpha	define alpha level for test statistics, default is 0.05.
bootstrap	logical, declare if itsa.model was bootstrapped for plot of these results.
print	logical, specify whether the main model result should be printed to the console.

Details

This function runs and reports post-estimation tests on fits from the itsa.model function, and generates four plots.

Main tests are whether two key ANCOVA assumptions are met, and an additional autocorrelation test for the time series framework.

The Shapiro-Wilks test examines the residuals from the fitted model for abnormality. A p-value less than alpha indicates abnormal residuals. In this instance, the user should consider replicating the its.analysis model design using a non-parametric ANCOVA equivalent.

The Levene's Test makes sure that there are equal variances between the treated groups. A p-value less than alpha indicates heterogeneous variances.

A QQ-Norm and Boxplot are generated with the test results overlaid (respectively), with a Residual v Fitted and Autocorrelation Function Plot also generated.

The results of bootstrap estimations in itsa.model will be plotted, unless argument is switched to FALSE. See plot.boot help file for assistance on interpreting these plots.

Default is to generate plots and summary table, but plots may be overridden using no.plots argument.

Default alpha value for post-estimation statistics is 0.05, test results will suggest potential presence of problems at higher values (and also at higher levels relative to a user-defined alpha), but user discretion is needed (examined in tandem with the Residuals v Fitted plot).

See 'itsa.model' documentation for further information.

Value

Returns a list containing post-estimation test results and four plots (plus one additional if bootstrapping applied) which are also sent directly to the plot tab.

---