Package {xiacf}

Type: Package
Title: Nonlinear Dependence and Lead-Lag Analysis via Chatterjee's Xi
Version: 0.6.0
Date: 2026-05-29
Maintainer: Yasunori Watanabe <watanabe.yasunori@outlook.com>
Description: Computes Chatterjee's non-parametric correlation coefficient for time series data. It extends the original metric to time series analysis by providing the univariate Xi-Autocorrelation Function (Xi-ACF), directional Xi-Cross-Correlation Function (Xi-CCF), and multivariate network evaluation matrices. The package allows users to test for non-linear dependence using Iterative Amplitude Adjusted Fourier Transform (IAAFT) and Multivariate IAAFT (MIAAFT) surrogate data with strict Family-Wise Error Rate ('FWER') control via Max-statistic approaches. Methodologies are based on Chatterjee (2021) <doi:10.1080/01621459.2020.1758115>, surrogate data testing methods by Schreiber and Schmitz (1996) <doi:10.1103/PhysRevLett.77.635>, and local structural identification by Watanabe (2026) <doi:10.2139/ssrn.6829431>.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: dplyr (≥ 1.1.4), doFuture, foreach, future, ggplot2 (≥ 4.0.1), patchwork, progressr, Rcpp (≥ 1.1.0), stats
LinkingTo: Rcpp, RcppArmadillo
Suggests: testthat (≥ 3.3.2)
Config/testthat/edition: 3
Config/roxygen2/version: 8.0.0
RoxygenNote: 7.3.3
NeedsCompilation: yes
Packaged: 2026-05-29 00:35:07 UTC; yasunori
Author: Yasunori Watanabe [aut, cre]
Repository: CRAN
Date/Publication: 2026-05-29 07:00:02 UTC

Plot method for xi_acf objects

Description

Plot method for xi_acf objects

Usage

## S3 method for class 'xi_acf'
autoplot(object, ...)

Arguments

object

An object of class xi_acf.

...

Additional arguments passed to other methods.

Plot method for xi_ccf objects

Description

Plot method for xi_ccf objects

Usage

## S3 method for class 'xi_ccf'
autoplot(object, ...)

Arguments

object

An object of class xi_ccf.

...

Additional arguments passed to other methods.

Plot method for xi_matrix objects

Description

Plot method for xi_matrix objects

Usage

## S3 method for class 'xi_matrix'
autoplot(object, ...)

Arguments

object

An object of class xi_matrix.

...

Additional arguments passed to other methods.

Extract Univariate Xi-ACF from a Multivariate Xi-Matrix

Description

Extract Univariate Xi-ACF from a Multivariate Xi-Matrix

Usage

extract_xi_acf(obj, var, ...)

Arguments

obj

An object of class xi_matrix.

var

A character string specifying the variable name to extract.

...

Additional arguments passed to xi_acf.

Value

An object of class xi_acf. #' @note This function performs a fresh re-calculation of the surrogate data distribution specifically for the targeted variables. As a result, two differences from the original matrix output should be expected: 1. **FWER Recalibration:** The global threshold will be recalibrated for the bivariate (or univariate) case, typically making it less conservative and restoring statistical power for the specific pathway. 2. **Monte Carlo Variation:** Due to the randomized nature of surrogate data generation, slight numerical variations in the thresholds and confidence intervals may occur unless a random seed is explicitly set (e.g., 'set.seed()') immediately prior to calling this extraction function.

Extract Bivariate Xi-CCF from a Multivariate Xi-Matrix

Description

Extract Bivariate Xi-CCF from a Multivariate Xi-Matrix

Usage

extract_xi_ccf(obj, var_x, var_y, ...)

Arguments

obj

An object of class xi_matrix.

var_x

A character string specifying the lead variable.

var_y

A character string specifying the lag variable.

...

Additional arguments passed to xi_ccf.

Value

An object of class xi_ccf. #' @note This function performs a fresh re-calculation of the surrogate data distribution specifically for the targeted variables. As a result, two differences from the original matrix output should be expected: 1. **FWER Recalibration:** The global threshold will be recalibrated for the bivariate (or univariate) case, typically making it less conservative and restoring statistical power for the specific pathway. 2. **Monte Carlo Variation:** Due to the randomized nature of surrogate data generation, slight numerical variations in the thresholds and confidence intervals may occur unless a random seed is explicitly set (e.g., 'set.seed()') immediately prior to calling this extraction function.

Print method for xi_ccf

Description

Print method for xi_ccf

Usage

## S3 method for class 'xi_ccf'
print(x, ...)

Arguments

x

An object of class xi_ccf.

...

Additional arguments passed to print.

Value

The original object x invisibly.

Print method for xi_matrix

Description

Print method for xi_matrix

Usage

## S3 method for class 'xi_matrix'
print(x, ...)

Arguments

x

An object of class xi_matrix.

...

Additional arguments passed to print.

Value

The original object x invisibly.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggplot2

autoplot()

Rolling Xi-ACF Analysis

Description

Performs a rolling window analysis using Chatterjee's Xi coefficient to assess the time-varying non-linear dependence structure of a time series with FWER control.

Usage

run_rolling_xi_acf(
  x,
  time_index = NULL,
  window_size,
  step_size = 1,
  max_lag,
  n_surr = 399,
  sig_level = 0.05,
  n_cores = NULL,
  save_dir = NULL
)

Arguments

x

A numeric vector representing the time series.

time_index

Optional vector of timestamps.

window_size

An integer specifying the size of the rolling window.

step_size

An integer specifying the step size. Default is 1.

max_lag

An integer specifying the maximum lag.

n_surr

An integer specifying the number of IAAFT surrogate datasets. Default is 399.

sig_level

A numeric value specifying the significance level (FWER). Default is 0.05.

n_cores

An integer specifying the number of cores for parallel execution.

save_dir

A character string specifying the directory path to save intermediate results.

Value

A data.frame containing the rolling window results.

Rolling Directional Xi-CCF Analysis

Description

Performs a rolling window analysis using Chatterjee's Xi cross-correlation to assess the time-varying non-linear lead-lag relationship between two time series with FWER control.

Usage

run_rolling_xi_ccf(
  x,
  y,
  time_index = NULL,
  window_size,
  step_size = 1,
  max_lag,
  n_surr = 399,
  sig_level = 0.05,
  n_cores = NULL,
  save_dir = NULL
)

Arguments

x

A numeric vector representing the first time series (predictor/lead candidate).

y

A numeric vector representing the second time series (response/lag candidate).

time_index

Optional vector of timestamps.

window_size

An integer specifying the size of the rolling window.

step_size

An integer specifying the step size. Default is 1.

max_lag

An integer specifying the maximum positive lag to compute.

n_surr

An integer specifying the number of MIAAFT surrogate datasets. Default is 399.

sig_level

A numeric value specifying the significance level (FWER). Default is 0.05.

n_cores

An integer specifying the number of cores for parallel execution.

save_dir

A character string specifying the directory path to save intermediate results.

Value

A data.frame containing the rolling window results.

Generate Multiple IAAFT Surrogates (Univariate)

Description

Generate Multiple IAAFT Surrogates (Univariate)

Usage

surrogate_iaaft_cpp(x, n_surr, max_iter = 100L)

Arguments

x

A numeric vector.

n_surr

Number of surrogates to generate.

max_iter

Maximum iterations for IAAFT.

Value

A matrix of surrogates (N x n_surr).

Generate Multiple MIAAFT Surrogates (3D Array / Cube)

Description

Generate Multiple MIAAFT Surrogates (3D Array / Cube)

Usage

surrogate_miaaft_cpp(X, n_surr, max_iter = 100L)

Arguments

X

A numeric matrix (N x p).

n_surr

Number of surrogates to generate.

max_iter

Maximum iterations for MIAAFT.

Value

A 3D array (arma::cube) of dimensions N x p x n_surr.

Compute empirical Xi-ACF and its significance via IAAFT surrogates

Description

Compute empirical Xi-ACF and its significance via IAAFT surrogates

Usage

xi_acf(x, max_lag = 10, n_surr = 399, sig_level = 0.05, max_iter = 100, ...)

## S3 method for class 'xi_acf'
print(x, ...)

Arguments

x

A numeric vector representing the time series data. Must not contain missing values (NA) or be a constant.

max_lag

An integer specifying the maximum lag to compute. Default is 10.

n_surr

An integer specifying the number of surrogate datasets to generate. Default is 399.

sig_level

A numeric value between 0 and 1 specifying the significance level. Default is 0.05.

max_iter

An integer specifying the maximum iterations for the IAAFT algorithm. Default is 100.

...

Additional arguments (currently ignored).

Value

An object of class xi_acf containing the empirical ACF, pointwise thresholds, global threshold, and metadata.

Bivariate Xi-Cross-Correlation Function

Description

Computes the directional Chatterjee's Xi coefficient between two time series across multiple lags, with Family-Wise Error Rate (FWER) control.

Usage

xi_ccf(
  x,
  y,
  max_lag = 20,
  n_surr = 399,
  sig_level = 0.05,
  max_iter = 100,
  direction = c("both", "x_leads"),
  ...
)

Arguments

x

A numeric vector representing the first time series.

y

A numeric vector representing the second time series.

max_lag

An integer specifying the maximum lag to compute. Default is 20.

n_surr

An integer specifying the number of MIAAFT surrogate datasets. Default is 399.

sig_level

A numeric value specifying the significance level (FWER). Default is 0.05.

max_iter

An integer specifying the maximum iterations for the MIAAFT algorithm. Default is 100.

direction

A character string specifying the testing direction. "both" computes X->Y and Y->X. "x_leads" computes only X->Y. Default is "both".

...

Additional arguments.

Value

An S3 object of class xi_ccf.

Compute Chatterjee's Xi coefficient (Exported to R)

Description

Compute Chatterjee's Xi coefficient (Exported to R)

Usage

xi_coefficient(x, y)

Arguments

x

A numeric vector.

y

A numeric vector.

Value

The Xi coefficient.

Multivariate Xi-Correlogram Matrix

Description

Computes the pairwise directional Chatterjee's Xi coefficient for a multivariate time series.

Usage

xi_matrix(x, max_lag = 10, n_surr = 399, sig_level = 0.05, max_iter = 100, ...)

Arguments

x

A numeric matrix or data.frame containing the multivariate time series (columns = variables).

max_lag

An integer specifying the maximum positive lag to compute. Default is 10.

n_surr

An integer specifying the number of MIAAFT surrogate datasets. Default is 399.

sig_level

A numeric value between 0 and 1 specifying the significance level. Default is 0.05.

max_iter

An integer specifying the maximum iterations for the MIAAFT algorithm. Default is 100.

...

Additional arguments.

Value

An S3 object of class xi_matrix containing a tidy data frame of pairwise results.

Deprecated functions in xiacf

Description

These functions are provided for backward compatibility with older versions of xiacf and will be removed in future releases.

Usage

xi_test(x, max_lag = 10, n_surr = 399, sig_level = 0.95, max_iter = 100, ...)

generate_iaaft_surrogate(...)

generate_miaaft_surrogates(...)

generate_miaaft_surrogate_cpp(...)

run_rolling_xi_analysis(...)

compute_xi_acf_iaaft(...)

compute_xi_ccf_miaaft(...)

compute_xi_matrix_miaaft(...)

Arguments

x

A numeric vector or matrix depending on the function.

max_lag

An integer specifying the maximum lag.

n_surr

An integer specifying the number of surrogate datasets.

sig_level

A numeric value specifying the significance or confidence level.

max_iter

An integer specifying the maximum iterations.

...

Additional arguments passed to the updated functions.