Type: Package
Title: Trend Removal for Vector Autoregressive Workflows
Version: 0.1.2
Description: Detrending multivariate time-series to approximate stationarity when dealing with intensive longitudinal data, prior to Vector Autoregressive (VAR) or multilevel-VAR estimation. Classical VAR assumes weak stationarity (constant first two moments), and deterministic trends inflate spurious autocorrelation, biasing Granger-causality and impulse-response analyses. All functions operate on raw panel data and write detrended columns back to the data set, but differ in the level at which the trend is estimated. See, for instance, Wang & Maxwell (2015) <doi:10.1037/met0000030>; Burger et al. (2022) <doi:10.4324/9781003111238-13>; Epskamp et al. (2018) <doi:10.1177/2167702617744325>.
URL: https://github.com/g-corbelli/statioVAR
BugReports: https://github.com/g-corbelli/statioVAR/issues
License: GPL-3
Encoding: UTF-8
Imports: dplyr, rlang, stats
Suggests: shiny, testthat (≥ 3.0.0), knitr, rmarkdown
Language: en-US
NeedsCompilation: no
Maintainer: Giuseppe Corbelli <giuseppe.corbelli@uniroma1.it>
Config/testthat/edition: 3
RoxygenNote: 7.3.2
Packaged: 2025-07-27 22:40:53 UTC; giuse
Author: Giuseppe Corbelli ORCID iD [aut, cre]
Repository: CRAN
Date/Publication: 2025-07-30 08:00:07 UTC

Trend Removal for Vector Autoregressive Workflows

Description

Detrending multivariate time-series to approximate stationarity when dealing with intensive longitudinal data, prior to Vector Autoregressive (VAR) or multilevel-VAR estimation. Classical VAR assumes weak stationarity (constant first two moments), and deterministic trends inflate spurious autocorrelation, biasing Granger-causality and impulse-response analyses. All functions operate on raw panel data and write detrended columns back to the data set, but differ in the level at which the trend is estimated.

Details

The functions are:

Note

The development of this package was inspired by, and is deeply indebted to, the works of Eiko Fried, Jonas Haslbeck, Sasha Epskamp, Ria Hoekstra and Alessandra Mansueto, among others. This software is provided 'as is', without any express or implied warranties of accuracy or reliability. For suggestions or to report any issue, please contact the author.

Author(s)

Giuseppe Corbelli (<giuseppe.corbelli@uniroma1.it>)

See Also

Useful links:

Within-person linear detrending for multilevel VAR analysis

Description

Remove individual-specific linear trends from panel data to approximate stationarity, preparing inputs for multilevel Vector Autoregressive (VAR) modeling (among others). For each subject and each selected variable, a linear regression of the variable on the time index is tested at significance level alpha; if the slope is significant, the fitted trend is subtracted and the subject's mean is re-added to produce detrended series while preserving between-subject information.

Usage

detrender(
  df,
  id_var,
  time_var,
  vars_to_detrend,
  alpha = 0.05,
  min_obs = 3
)

Arguments

df

Data frame or tibble (long format).

id_var

Character string. Subject identifier column (required).

time_var

Character string. Numeric time index column (required).

vars_to_detrend

Character vector. Column names to detrend within each subject (required).

alpha

Numeric in (0,1). Significance threshold for retaining a non-zero time slope (default: 0.05).

min_obs

Integer >2. Minimum observations per subject-variable to attempt detrending (default: 3).

Value

A named list with:

df

Tibble. The original dataset with additional detrended columns.

n_clusters

Integer. Number of unique subjects (clusters) processed.

total_trends

Integer. Total number of individual trends removed across all variables.

summary

Tibble. Number of removed linear trends per variable, with columns variable and removed_trends.

Examples

df_example <- data.frame(
id = rep(1:2, each = 5),
time = rep(1:5, 2),
x = rep(1:5, 2) + rnorm(10)
)
res <- statioVAR::detrender(
df = df_example,
id_var = "id",
time_var = "time",
vars_to_detrend = "x",
alpha = 0.05,
min_obs = 3
)
res$df[7:9,]
res$n_clusters
res$total_trends
res$summary

Pooled polynomial detrending for multivariate panel data

Description

Remove study‑wide polynomial trend (up to cubic) plus optional cyclic effects from multivariate panel data by fitting a single OLS model on the pooled series. Trend terms up to the chosen degree are estimated; those whose two‑sided t-tests are significant at alpha are retained, non‑significant components are set to 0, and the resulting fitted values are subtracted from every observation of the raw series.

Usage

pooled(
  df,
  id_var,
  time_var = NULL,
  vars_to_detrend,
  poly_order = 1,
  cyc_vars = NULL,
  alpha = 0.05,
  miss_thresh = 0.30
)

Arguments

df

Data frame or tibble (long format).

id_var

Character string. Subject identifier column (required).

time_var

Character string. Numeric time index column (if NULL, then cyc_vars must be specified). If NULL, no polynomial time terms are included.

vars_to_detrend

Character vector. Column names to detrend (required).

poly_order

Integer in {1,2,3}. Maximum degree of the polynomial time trend tested (default: 1):

  • 1 = linear only,

  • 2 = linear + quadratic,

  • 3 = linear + quadratic + cubic.

cyc_vars

Character vector. Column names (e.g. "weekend") for categorical cyclicity variables (if NULL, then time_var must be specified).

alpha

Numeric in (0,1). Significance threshold for retaining polynomial terms (default 0.05).

miss_thresh

Numeric in (0,1). Maximum allowed proportion of missing data per variable (default: 0.30).

Value

A named list with:

df

Tibble with added <var>_detrended columns.

coef_tables

Named list of coefficient tables (one per variable), with columns predictor, estimate, Std. Error, t, p, and a logical flag kept.

formula_str

Character string of the fitted model formula.

n_clusters

Integer: number of unique subjects (clusters).

Examples

dat <- data.frame(
id = rep(1:3, each=5),
time = rep(1:5, 3),
cyc = rep(c("A","B"), length.out=15),
y1 = rnorm(15, sd = 0.5) + seq(1,15)*1.0
)
res <- statioVAR::pooled(
df = dat,
id_var = "id",
time_var = "time",
vars_to_detrend = "y1",
poly_order = 2,
cyc_vars = "cyc",
alpha = 0.05,
miss_thresh = 0.30
)