| Type: | Package |
| Title: | Quantifying Nonlinear Dependence and Lead-Lag Dynamics via Chatterjee's Xi |
| Version: | 0.4.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. Main functions include xi_acf() and xi_ccf() for computation, along with matrix extraction tools. 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), latex2exp, 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-04-10 18:54:56 UTC; yasunori |
| Author: | Yasunori Watanabe [aut, cre] |
| Repository: | CRAN |
| Date/Publication: | 2026-04-16 10:40:02 UTC |
Plot Xi-ACF Comparison
Description
Visualizes the comparison between the standard linear Autocorrelation Function (ACF) and the non-linear Chatterjee's Xi coefficient, including their respective significance thresholds.
Usage
## S3 method for class 'xi_acf'
autoplot(object, ...)
Arguments
object |
An object of class |
... |
Additional arguments passed to other methods. |
Value
A ggplot object representing the correlogram.
Plot Directional Xi-CCF Comparison
Description
Visualizes the comparison between the standard linear Cross-Correlation Function (CCF) and the non-linear Chatterjee's Xi cross-correlation across two directions (X leads Y, Y leads X).
Usage
## S3 method for class 'xi_ccf'
autoplot(object, ...)
Arguments
object |
An object of class |
... |
Additional arguments passed to other methods. |
Value
A ggplot object representing the directional cross-correlogram.
Plot Multivariate Xi-Correlogram Matrix
Description
Visualizes the result of a multivariate Xi-matrix analysis using a facet grid. Rows represent the leading (predictor) variable, and columns represent the lagging (response) variable.
Usage
## S3 method for class 'xi_matrix'
autoplot(object, ...)
Arguments
object |
An object of class |
... |
Additional arguments (currently ignored). |
Value
A ggplot object.
Compute Xi-ACF for Multiple Lags (Core Engine)
Description
Calculates Chatterjee's Xi coefficient for multiple lags and generates IAAFT (Iterative Amplitude Adjusted Fourier Transform) surrogates to establish confidence intervals for non-linear dependence.
Usage
compute_xi_acf_iaaft(x, max_lag, n_surr)
Arguments
x |
A numeric vector (time series). |
max_lag |
An integer specifying the maximum number of lags to compute. |
n_surr |
An integer specifying the number of surrogate datasets to generate. |
Value
A list containing xi_original (the Xi coefficients for the original series)
and xi_surrogates (a matrix of Xi coefficients for the surrogate datasets).
Compute MIAAFT-based Directional Xi-CCF
Description
Compute MIAAFT-based Directional Xi-CCF
Usage
compute_xi_ccf_miaaft(x, y, max_lag, n_surr)
Arguments
x |
First time series (numeric vector, potential cause) |
y |
Second time series (numeric vector, potential effect) |
max_lag |
Maximum positive lag to evaluate |
n_surr |
Number of surrogate datasets to generate |
Value
A list containing forward (X leads Y) and backward (Y leads X) Xi coefficients and surrogates.
Compute Pairwise Directional Xi-CCF for a Multivariate Matrix
Description
Compute Pairwise Directional Xi-CCF for a Multivariate Matrix
Usage
compute_xi_matrix_miaaft(x, max_lag, n_surr)
Arguments
x |
A numeric matrix (rows = time, cols = variables). |
max_lag |
An integer specifying the maximum positive lag. |
n_surr |
An integer specifying the number of surrogate datasets. |
Value
A list containing flat vectors for lead/lag variable indices, lags, original Xi values, and a matrix of surrogate Xi values.
Generate a Single MIAAFT Surrogate Matrix
Description
Generate a Single MIAAFT Surrogate Matrix
Usage
generate_miaaft_surrogate_cpp(x, max_iter = 100L)
Arguments
x |
A numeric matrix (rows = time, cols = variables). |
max_iter |
An integer specifying the maximum number of iterations. |
Value
A numeric matrix representing the generated MIAAFT surrogate.
Print method for xi_acf objects
Description
Print method for xi_acf objects
Usage
## S3 method for class 'xi_acf'
print(x, ...)
Arguments
x |
An object of class |
... |
Additional arguments. |
Value
Invisibly returns the original object.
Print method for xi_ccf objects
Description
Print method for xi_ccf objects
Usage
## S3 method for class 'xi_ccf'
print(x, ...)
Arguments
x |
An object of class |
... |
Additional arguments. |
Value
Invisibly returns the original object.
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 |
... |
Additional arguments passed to print. |
Value
The original object x invisibly. Called primarily for its side effect of printing the matrix to the console.
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.
Usage
run_rolling_xi_analysis(
x,
time_index = NULL,
window_size,
step_size = 1,
max_lag = 20,
n_surr = 100,
sig_level = 0.95,
n_cores = NULL,
save_dir = NULL
)
Arguments
x |
A numeric vector representing the time series (e.g., log-returns). |
time_index |
Optional vector of timestamps (e.g., Date, POSIXct) corresponding to x. |
window_size |
An integer specifying the size of the rolling window. |
step_size |
An integer specifying the step size by which the window is shifted. Default is 1. |
max_lag |
An integer specifying the maximum lag to compute Chatterjee's Xi for. |
n_surr |
An integer specifying the number of surrogate datasets for the null hypothesis test. |
sig_level |
A numeric value specifying the significance level for the confidence intervals. Default is 0.95. |
n_cores |
An integer specifying the number of cores for parallel execution. If |
save_dir |
A character string specifying the directory path to save intermediate window results as RDS files. If |
Value
A data.frame containing the rolling window results, including timestamps if provided.
Rolling Multivariate 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.
Usage
run_rolling_xi_ccf(
x,
y,
time_index = NULL,
window_size,
step_size = 1,
max_lag = 20,
n_surr = 100,
bidirectional = TRUE,
sig_level = 0.95,
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 (e.g., Date, POSIXct) corresponding to x and y. |
window_size |
An integer specifying the size of the rolling window. |
step_size |
An integer specifying the step size by which the window is shifted. 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 for the null hypothesis test. |
bidirectional |
Logical. If TRUE (default), computes both "X leads Y" and "Y leads X". |
sig_level |
A numeric value specifying the significance level for the confidence intervals. Default is 0.95. |
n_cores |
An integer specifying the number of cores for parallel execution. If |
save_dir |
A character string specifying the directory path to save intermediate window results as RDS files. If |
Value
A data.frame containing the rolling window results in a tidy long-format.
Xi-ACF Test for Time Series
Description
Calculates Chatterjee's Xi and the standard Autocorrelation Function (ACF) along with their respective significance thresholds.
Usage
xi_acf(x, max_lag = 20, n_surr = 100, sig_level = 0.95)
xi_test(x, max_lag = 20, n_surr = 100)
Arguments
x |
A numeric vector representing the time series data. |
max_lag |
An integer specifying the maximum number of lags to compute. |
n_surr |
An integer specifying the number of surrogate datasets to generate for the IAAFT test. |
sig_level |
A numeric value between 0 and 1 specifying the significance level. Default is 0.95. |
Value
An object of class "xi_acf" containing the computed statistics and metadata.
Directional Xi-CCF Test for Multivariate Time Series
Description
Calculates Chatterjee's Xi cross-correlation and the standard Cross-Correlation Function (CCF) across positive lags to evaluate directional lead-lag relationships.
Usage
xi_ccf(
x,
y,
max_lag = 20,
n_surr = 100,
bidirectional = TRUE,
sig_level = 0.95
)
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 positive lag. |
n_surr |
An integer specifying the number of MIAAFT surrogate datasets. |
bidirectional |
Logical. If TRUE (default), computes both directions. |
sig_level |
A numeric value between 0 and 1 specifying the significance level. Default is 0.95. |
Value
An object of class "xi_ccf".
Calculate Chatterjee's Rank Correlation Coefficient (Xi)
Description
Computes Chatterjee's rank correlation coefficient (Xi) between two numeric vectors. Ties are broken uniformly at random to ensure strict inequalities.
Usage
xi_coefficient(x, y)
Arguments
x |
A numeric vector. |
y |
A numeric vector of the same length as |
Value
A numeric scalar representing the Chatterjee's Xi coefficient.
Multivariate Xi-Correlogram Matrix
Description
Computes the pairwise directional Chatterjee's Xi coefficient for a multivariate time series dataset. It evaluates both "Lead -> Lag" and "Lag -> Lead" relationships across all variable pairs, as well as the Xi-ACF (autocorrelation) for individual variables.
Usage
xi_matrix(x, max_lag = 20, n_surr = 100, sig_level = 0.95)
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. |
n_surr |
An integer specifying the number of MIAAFT surrogate datasets for hypothesis testing. |
sig_level |
A numeric value between 0 and 1 specifying the significance level for the surrogate threshold. Default is 0.95. |
Value
An S3 object of class xi_matrix containing a tidy data frame of pairwise results.