bivarhr (version 0.1.5)

placebo_temporal: 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
)

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.

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.

Examples

# \donttest{
# 1. Create a temporary directory for output
tmp_dir <- file.path(tempdir(), "placebo_out")
dir.create(tmp_dir, showWarnings = FALSE)

# 2. Create dummy data (DT)
# Needed because R CMD check runs in a clean environment
N <- 50
DT <- data.frame(
  time = 1:N,
  y = rpois(N, lambda = 4),
  X1 = rnorm(N),
  X2 = rnorm(N)
)
# Ensure it's a data.table if fit_one expects it, or leave as DF
# (The function internally ensures data.table behavior)

# 3. Define auxiliary parameters
k_grid  <- 0:1

# 4. Run the function
# We use a small n_perm for the example to run faster
try({
  out_placebo <- placebo_temporal(DT, spec = "C", k = 1,
                                  controls = c("X1", "X2"),
                                  n_perm = 2, seed = 999,
                                  dir_csv = tmp_dir)
  
  head(out_placebo)
})

# 5. Cleanup
unlink(tmp_dir, recursive = TRUE)
# }