placebo_temporal: Temporal Placebo Test via Time-Index Permutations

In bivarhr: Bivariate Hurdle Regression with Bayesian Model Averaging

Temporal Placebo Test via Time-Index Permutations

Description

Implements a temporal placebo test for the bivariate hurdle model by randomly permuting the time ordering of DT, re-estimating the model on each permuted dataset, and comparing the PSIS-LOO ELPD of the original fit against the permuted fits.

Usage

placebo_temporal(
  DT,
  spec = "C",
  k = 2,
  controls = character(0),
  n_perm = 10,
  seed = 999,
  dir_csv = NULL
)

Arguments

DT	A data.table (or data.frame) containing the data used by fit_one().
spec	Character scalar; model specification (e.g. "A", "B", "C", "D") passed to fit_one().
k	Integer; lag order passed to fit_one().
controls	Character vector of control variable names passed to fit_one().
n_perm	Integer; number of temporal permutations (placebo datasets) to run.
seed	Integer; base random seed used for reproducibility of the original fit and the permutations.
dir_csv	Character scalar; directory path to save the summary CSV. If NULL (default), the CSV is not saved to disk.

Details

The function:

• Fits the model on the original DT via fit_one(), extracts "log_lik_joint" and computes PSIS-LOO (with moment_match = TRUE).

• For each of n_perm iterations, permutes the row order of DT, refits the model on the permuted data, recomputes PSIS-LOO, and stores the permuted ELPD.

• Reports, for each permutation, the original ELPD, the permuted ELPD, and their difference (elpd_orig - elpd_perm).

This procedure evaluates whether the temporal structure captured by the model is informative: if the model is exploiting genuine time dependence, the original ELPD should typically be higher than that of the permuted (time-scrambled) datasets.

The function assumes that fit_one() is available in the search path.

Value

A data.frame with one row per permutation and columns:

• perm: permutation index (1, ..., n_perm).

• elpd_orig: ELPD of the original (non-permuted) fit.

• elpd_perm: ELPD of the model fit on the permuted data.

• diff: difference elpd_orig - elpd_perm.

Examples

# This example fits Stan models and therefore runs only in an
# interactive session with 'cmdstanr' and a working CmdStan.
if (interactive() && requireNamespace("cmdstanr", quietly = TRUE)) {
  N <- 50
  DT <- data.frame(
    time = seq_len(N),
    y = rpois(N, lambda = 4),
    X1 = rnorm(N),
    X2 = rnorm(N)
  )

  out_placebo <- placebo_temporal(DT, spec = "C", k = 1,
                                  controls = c("X1", "X2"),
                                  n_perm = 2, seed = 999,
                                  dir_csv = tempdir())
  head(out_placebo)
}

bivarhr documentation built on July 7, 2026, 1:06 a.m.