run_transfer_entropy: Transfer Entropy for Counts, Rates, and Binary Series

In bivarhr: Bivariate Hurdle Regression with Bayesian Model Averaging

Transfer Entropy for Counts, Rates, and Binary Series

Description

Computes pairwise transfer entropy between I and C for three transformations of the data: raw counts, rates (count/exposure), and binary presence/absence. Each series is first pre-whitened via a GLM and transfer entropy is then estimated for a grid of lags using RTransferEntropy. Results are written to separate CSV files and to a combined summary.

Usage

run_transfer_entropy(
  DT,
  lags = 1:3,
  shuffles = 1000,
  seed = 123,
  use_progress = TRUE,
  dir_csv = NULL
)

Arguments

DT	A data.table or data.frame containing at least the following columns: I, C: count variables (non-negative integers). exposure50: exposure used to form rates (must be strictly positive). log_exposure50: log of the exposure (offset). t_norm, Regime, EconCycle, PopDensity, Epidemics, Climate, War: covariates used by the pre-whitening GLMs.
lags	Integer vector of lag orders L for which transfer entropy is computed (passed to lx and ly in RTransferEntropy::transfer_entropy()).
shuffles	Integer; number of shuffle replications for the surrogate-distribution-based significance test in transfer_entropy().
seed	Integer; base random seed used for reproducibility of the pre-whitening and transfer entropy computations.
use_progress	Logical; reserved for future use to toggle progress reporting. Currently not used.
dir_csv	Character scalar or NULL; directory where the transfer-entropy CSV files are written. If NULL (default), nothing is written to disk and results are returned in memory only.

Details

This function requires the RTransferEntropy package (listed under Suggests); an informative error is raised at call time if it is not installed.

The function proceeds in four steps:

1. Counts: I and C are pre-whitened via prewhiten_count_glm (Negative Binomial with offset and Poisson fallback). Transfer entropy is computed in both directions (I→C and C→I) for each lag in lags. Results are saved to "transfer_entropy_counts.csv".

2. Rates: I and C are divided by exposure50, pre-whitened via prewhiten_rate_glm, and transfer entropy is recomputed. Results are saved to "transfer_entropy_rates.csv". A check is performed to ensure exposure50 > 0 for all observations.

3. Binary: I and C are recoded as 0/1 presence/absence indicators and pre-whitened via prewhiten_bin_glm. Transfer entropy is computed again and results are saved to "transfer_entropy_binary.csv".

4. Combined: All tables are stacked into a single data frame with a type column ("counts", "rates", "binary") and written to "transfer_entropy.csv".

Internally, the helpers .get_stat and .get_pval are used to extract the transfer entropy statistic and p-value from the objects returned by RTransferEntropy::transfer_entropy(). CSV files are written only when dir_csv is supplied.

Value

A data.frame with one row per lag and type, and columns:

• lag: lag order used in transfer_entropy().

• TE_ItoC, p_ItoC: transfer entropy and p-value from I to C.

• TE_CtoI, p_CtoI: transfer entropy and p-value from C to I.

• type: transformation used ("counts", "rates", or "binary").

Examples

# This example runs only when 'RTransferEntropy' is installed.
if (requireNamespace("RTransferEntropy", quietly = TRUE)) {
  DT <- data.table::data.table(
    I = rpois(30, lambda = 10),
    C = rpois(30, lambda = 8),
    exposure50 = runif(30, 100, 200),
    log_exposure50 = log(runif(30, 100, 200)),
    t_norm = seq(-1, 1, length.out = 30),
    Regime = factor(sample(c("A", "B"), 30, replace = TRUE)),
    EconCycle = rnorm(30),
    PopDensity = rnorm(30),
    Epidemics = rnorm(30),
    Climate = rnorm(30),
    War = rnorm(30)
  )

  # Fewer shuffles for a faster example.
  te_tab <- run_transfer_entropy(DT, lags = 1, shuffles = 10, seed = 123)
  if (!is.null(te_tab)) {
    print(subset(te_tab, type == "counts"))
  }
}

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