xiacf Development Roadmap

[yetanothersu]

Welcome to the xiacf development roadmap! This document outlines our current status and the exciting features planned for upcoming releases. Our goal is to make xiacf the definitive tool for non-linear, asymmetric time-series causal discovery in R.

📌 Current Status

• v0.2.1 (Hotfix & Stability): Implemented strict NA handling to ensure data integrity during univariate and bivariate MIAAFT surrogate generation.
• Target: "Soak time" (testing with real-world macroeconomics/finance data) followed by CRAN submission.

---

🛠️ Phase 3: The Asymmetry & Network Update (v0.3.x - v0.4.x)

Focus: Shifting from a traditional symmetric CCF mindset to strict directional (asymmetric) evaluation, and scaling up to network-level analysis.

Milestone 1: Optimization and Asymmetric Plotting (v0.3.0)

• Engine Optimization: Deprecate meaningless negative lag computations in C++ to achieve a 2x performance speedup.
• Bidirectional Evaluation (bidirectional = TRUE): Introduce a default option to compute both $X \to Y$ and $Y \to X$ directions simultaneously. This leverages pre-generated MIAAFT surrogates, meaning the reverse direction computation essentially comes at zero additional cost.
• Long-format Data & 2-Panel autoplot: Restructure the output into a tidy long-format dataframe. Upgrade autoplot() to return a clear, 2-panel ggplot (Top: $X$ leads $Y$, Bottom: $Y$ leads $X$) using only positive lags for intuitive causal interpretation.

Milestone 2: $n$-Dimensional MIAAFT Engine (v0.4.0)

• C++ Refactor for Scalability: Expand the MIAAFT (Multivariate Iterative Amplitude Adjusted Fourier Transform) algorithm in RcppArmadillo to accept an $n$-column matrix. This allows generating surrogates for all variables simultaneously in a single pass, avoiding combinatorial explosion.
• Modular Computation (compute_xi): Isolate the pure $\xi$ computation logic from the surrogate generation step to maximize code reuse in pairwise iterations.

Milestone 3: The $\xi$-Correlogram Matrix (v0.4.1)

• xi_matrix() API: Implement a user-friendly wrapper that accepts a dataframe of $n$ time series and returns pairwise directional $\xi$ scores.
• Matrix autoplot: Develop an $n \times n$ grid visualization using ggplot2::facet_grid.
  • Off-diagonal elements: Directional $\xi$-CCF ($Lead \to Lag$).
  • Diagonal elements: $\xi$-ACF (Autocorrelation/Inertia).

---

🔭 Phase 4: Advanced Causal Discovery (Future Research)

Focus: Tackling the "Holy Grail" of time series analysis—controlling for confounding variables and handling non-stationary/irregular data.

Milestone 1: Conditional $\xi$-CCF (Partial $\xi$)

Implementing robust methods to control for confounding variables ($Z$) and eliminate spurious correlations to measure pure functional dependence:

• Approach 1: Residual-based Approach: Regress $X$ and $Y$ on $Z$ (e.g., via Random Forest or GAMs) and apply standard $\xi$-CCF to the residuals $r(X)$ and $r(Y)$.
• Approach 2: Time-Series CODEC (Azadkia-Chatterjee): Extend the Azadkia-Chatterjee conditional dependence coefficient to time series. Apply IAAFT surrogates only to the target variable $X$, preserving the temporal structure of $Y$ and $Z$ to test for strict conditional independence.
• Approach 3: Twin Surrogates / Conditional Permutation: Implement advanced surrogate methods that identify "twins" in the state space of $Z$ to shuffle $X$ locally, destroying the $X-Y$ coupling while preserving the dependencies on $Z$.

Milestone 2: Irregular Time Series Support

• Introduce specialized surrogate generation algorithms (e.g., Lomb-Scargle based) to support unevenly sampled time series data (e.g., paleoclimate records, tick-by-tick financial data).

---

Feedback, feature requests, and pull requests are always welcome!