Package {xiacf}

Type: Package
Title: Nonlinear Dependence and Lead-Lag Analysis via Chatterjee's Xi
Version: 0.5.0
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 Xi-Autocorrelation Function (Xi-ACF) and Xi-Cross-Correlation Function (Xi-CCF). The package allows users to test for non-linear dependence using Iterative Amplitude Adjusted Fourier Transform (IAAFT) 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> and surrogate data testing methods by Schreiber and Schmitz (1996) <doi:10.1103/PhysRevLett.77.635>.
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
RoxygenNote: 7.3.3
Suggests: testthat (≥ 3.3.2)
Config/testthat/edition: 3
NeedsCompilation: yes
Packaged: 2026-05-16 23:52:20 UTC; yasunori
Author: Yasunori Watanabe [aut, cre]
Repository: CRAN
Date/Publication: 2026-05-17 04:10: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 Individual Xi-ACF from a Multivariate Xi-Matrix

Description

Extract Individual Xi-ACF from a Multivariate Xi-Matrix

Usage

extract_xi_acf(object, var, x_raw = NULL)

Arguments

object

An object of class xi_matrix.

var

A character string specifying the variable name.

x_raw

Optional. The original data to calculate linear ACF.

Value

An object of class xi_acf.

Extract Pairwise Xi-CCF from a Multivariate Xi-Matrix

Description

Extract Pairwise Xi-CCF from a Multivariate Xi-Matrix

Usage

extract_xi_ccf(object, var_x, var_y, x_raw = NULL)

Arguments

object

An object of class xi_matrix.

var_x

Variable X name.

var_y

Variable Y name.

x_raw

Optional. The original data to calculate linear CCF.

Value

An object of class xi_ccf.

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.

Directional Xi-CCF Test for Bivariate Time Series

Description

Computes the empirical Cross-Correlation Function (CCF) based on Chatterjee's Xi, and evaluates its statistical significance using MIAAFT surrogates.

Usage

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

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

Arguments

x

A numeric vector. Must not contain missing values (NA) or be a constant.

y

A numeric vector of the same length as x. Must not contain missing values or be a constant.

max_lag

An integer specifying the maximum lag. Default is 10.

n_surr

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

sig_level

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

max_iter

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

...

Additional arguments.

Value

An object of class "xi_ccf" containing the empirical correlations and Max-statistic thresholds.

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.