preprocess: Preprocess and audit idiographic time-series data

In idiographic: Person-Specific (Idiographic) and Heterogeneous Complex Networks

Preprocess and audit idiographic time-series data

Description

Builds the same lag-1 design used by fit_graphical_var() and fit_var(), optionally detrends or differences each series, and returns tidy diagnostics for missingness, day-boundary drops, simple linear trends, AR(1) persistence, split-half mean/variance drift, an ADF-style unit-root screen, and zero-variance variables. It makes the modelling input explicit before estimating VAR, graphical VAR, uSEM, GIMME, or mlVAR models; with detrend it also cleans a non-stationary series in place so the flags can be rechecked on the transformed data.

Usage

preprocess(
  data,
  vars,
  id = NULL,
  day = NULL,
  beep = NULL,
  scale = TRUE,
  center_within = TRUE,
  detrend = "none",
  checks = c("trend", "high_ar", "unit_root", "mean_shift", "sd_shift", "zero_variance"),
  delete_missings = TRUE,
  min_obs = NULL,
  subject = NULL,
  trend_alpha = 0.05,
  ar_threshold = 0.95,
  mean_shift_threshold = 0.8,
  sd_ratio_threshold = 2,
  unit_root_t_cutoff = -2.86
)

Arguments

data	A data.frame or matrix with columns for variables and optional id/day/beep columns.
vars	Character vector of variable names.
id	Character. Name of the person-ID column, or NULL for a single series.
day	Character. Name of the day/session column, or NULL.
beep	Character. Name of the measurement-occasion column, or NULL.
scale	Logical. Whether to standardize variables before lagging. Default TRUE.
center_within	Logical. Whether to centre within person when more than one id is present. Default TRUE.
detrend	How to remove non-stationarity from each series before lagging. Either a single string applied to every variable, or a named character vector giving a per-variable method (unlisted variables are left untouched, e.g. c(planning = "difference", value = "linear")). The available methods are: "none" Default; diagnose only, transform nothing. "auto" Detrend only the subject-series that are flagged, leaving the stationary ones untouched: differencing a stochastic trend (unit root or near-unit-root persistence) and linearly detrending a deterministic trend. The "clean whoever needs it" option – no subsetting, one call over everyone. Can be set per variable too. "linear" Replace the series with the residuals of a within-person regression on a linear time index. "difference" First-difference the series within id/day blocks. The diagnostics and the returned design reflect the detrended series, so the trend and unit-root flags can be rechecked after cleaning.
checks	Character vector selecting which stationarity checkups to run: any of "trend", "high_ar", "unit_root", "mean_shift", "sd_shift", "zero_variance". Defaults to all of them. Deselecting a check turns its flag off in the report, in the flag_stationarity_risk roll-up, and in the "auto" detrend decision, so you can screen for only what you care about.
delete_missings	Logical. If TRUE, ⁠$pairs⁠ contains only complete current/lagged rows; if FALSE, first rows of blocks and incomplete rows are retained with NA lags, matching .gvar_tsdata(). Default TRUE.
min_obs	Integer or NULL. Keep only subjects with at least this many observations.
subject	Optional vector naming the subject(s) to preprocess.
trend_alpha	Numeric p-value cutoff for the trend flag. Default 0.05.
ar_threshold	Numeric absolute AR(1) cutoff for the high-persistence flag. Default 0.95.
mean_shift_threshold	Numeric absolute standardized split-half mean shift cutoff. Default 0.8.
sd_ratio_threshold	Numeric split-half SD ratio cutoff. Default 2.
unit_root_t_cutoff	Numeric cutoff for the ADF-style lag-level t-statistic. Values greater than this cutoff are flagged as unit-root risk. Default -2.86, a common large-sample intercept-only screening cutoff.

Value

A preprocess_result object with:

pairs

The ordered current/lagged design table, including intercept and ⁠L1_*⁠ columns.

counts

Per-subject/per-day row and lag-pair counts.

diagnostics

Per-subject/per-variable missingness, trend, AR(1), split-half drift, unit-root screen, and stationarity risk indicators.

matrices

The exact data_c and data_l matrices returned by the VAR/GVAR preprocessing path.

Examples

set.seed(1)
d <- data.frame(id = 1, day = 1, beep = 1:40,
                A = cumsum(rnorm(40)), B = rnorm(40))
pp <- preprocess(d, vars = c("A", "B"), id = "id", day = "day", beep = "beep")
pp$counts
pp$diagnostics
# Difference the trending series and recheck the flags:
preprocess(d, vars = c("A", "B"), id = "id", day = "day", beep = "beep",
           detrend = "difference")$diagnostics

idiographic documentation built on Aug. 4, 2026, 1:07 a.m.