| Title: | Nonlinear Dependence and Lead-Lag Analysis via Chatterjee's Xi |
|---|---|
| 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>. |
| Authors: | Yasunori Watanabe [aut, cre] |
| Maintainer: | Yasunori Watanabe <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.6.5 |
| Built: | 2026-06-04 16:58:20 UTC |
| Source: | https://github.com/yetanothersu/xiacf |
Plot method for xi_acf objects
## S3 method for class 'xi_acf' autoplot(object, ...)## S3 method for class 'xi_acf' autoplot(object, ...)
object |
An object of class |
... |
Additional arguments passed to other methods. |
Plot method for xi_ccf objects
## S3 method for class 'xi_ccf' autoplot(object, ...)## S3 method for class 'xi_ccf' autoplot(object, ...)
object |
An object of class |
... |
Additional arguments passed to other methods. |
Plot method for xi_matrix objects
## S3 method for class 'xi_matrix' autoplot(object, ...)## S3 method for class 'xi_matrix' autoplot(object, ...)
object |
An object of class |
... |
Additional arguments passed to other methods. |
Extract Univariate Xi-ACF from a Multivariate Xi-Matrix
extract_xi_acf(obj, var, ...)extract_xi_acf(obj, var, ...)
obj |
An object of class |
var |
A character string specifying the variable name to extract. |
... |
Additional arguments passed to xi_acf. |
An object of class xi_acf.
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
extract_xi_ccf(obj, var_x, var_y, ...)extract_xi_ccf(obj, var_x, var_y, ...)
obj |
An object of class |
var_x |
A character string specifying the lead variable. |
var_y |
A character string specifying the lag variable. |
... |
Additional arguments passed to xi_ccf. |
An object of class xi_ccf.
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
## S3 method for class 'xi_ccf' print(x, ...)## S3 method for class 'xi_ccf' print(x, ...)
x |
An object of class |
... |
Additional arguments passed to print. |
The original object x invisibly.
Print method for xi_matrix
## S3 method for class 'xi_matrix' print(x, ...)## S3 method for class 'xi_matrix' print(x, ...)
x |
An object of class |
... |
Additional arguments passed to print. |
The original object x invisibly.
Rolling Window Analysis for Xi-ACF
run_rolling_xi_acf( x, time_index = NULL, window_size, step_size = 1, max_lag, n_surr = 399, sig_level = 0.05, max_iter = 100, n_cores = NULL, save_dir = NULL )run_rolling_xi_acf( x, time_index = NULL, window_size, step_size = 1, max_lag, n_surr = 399, sig_level = 0.05, max_iter = 100, n_cores = NULL, save_dir = NULL )
x |
A numeric vector representing the time series data. |
time_index |
An optional vector representing 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 to compute. |
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. |
max_iter |
An integer specifying the maximum iterations for the IAAFT algorithm. Default is 100. |
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. |
A data.frame containing the rolling window results.
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.
run_rolling_xi_ccf( x, y, time_index = NULL, window_size, step_size = 1, max_lag, n_surr = 399, sig_level = 0.05, max_iter = 100, n_cores = NULL, save_dir = NULL )run_rolling_xi_ccf( x, y, time_index = NULL, window_size, step_size = 1, max_lag, n_surr = 399, sig_level = 0.05, max_iter = 100, n_cores = NULL, save_dir = NULL )
x |
A numeric vector representing the first time series. |
y |
A numeric vector representing the second time series. |
time_index |
An optional vector representing 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. |
max_iter |
An integer specifying the maximum iterations for the MIAAFT algorithm. Default is 100. |
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. |
A data.frame containing the rolling window results.
Generate Multiple IAAFT Surrogates (Univariate)
surrogate_iaaft_cpp(x, n_surr, max_iter = 100L)surrogate_iaaft_cpp(x, n_surr, max_iter = 100L)
x |
A numeric vector. |
n_surr |
Number of surrogates to generate. |
max_iter |
Maximum iterations for IAAFT. |
A matrix of surrogates (N x n_surr).
Compute empirical Xi-ACF and its significance via IAAFT surrogates
xi_acf(x, max_lag = 10, n_surr = 399, sig_level = 0.05, max_iter = 100, ...) ## S3 method for class 'xi_acf' print(x, ...)xi_acf(x, max_lag = 10, n_surr = 399, sig_level = 0.05, max_iter = 100, ...) ## S3 method for class 'xi_acf' print(x, ...)
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). |
An object of class xi_acf containing the empirical ACF,
pointwise thresholds, global threshold, and metadata.
Computes the directional Chatterjee's Xi coefficient between two time series across multiple lags, with Family-Wise Error Rate (FWER) control.
xi_ccf( x, y, max_lag = 20, n_surr = 399, sig_level = 0.05, max_iter = 100, direction = c("both", "x_leads"), ... )xi_ccf( x, y, max_lag = 20, n_surr = 399, sig_level = 0.05, max_iter = 100, direction = c("both", "x_leads"), ... )
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. |
An S3 object of class xi_ccf.
Compute Chatterjee's Xi coefficient (Exported to R)
xi_coefficient(x, y)xi_coefficient(x, y)
x |
A numeric vector. |
y |
A numeric vector. |
The Xi coefficient.
Computes the pairwise directional Chatterjee's Xi coefficient for a multivariate time series.
xi_matrix(x, max_lag = 10, n_surr = 399, sig_level = 0.05, max_iter = 100, ...)xi_matrix(x, max_lag = 10, n_surr = 399, sig_level = 0.05, max_iter = 100, ...)
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. |
An S3 object of class xi_matrix containing a tidy data frame of pairwise results.
These functions are provided for backward compatibility with older versions of xiacf and will be removed in future releases.
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(...) surrogate_miaaft_cpp(...)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(...) surrogate_miaaft_cpp(...)
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. |