arfparf 0.1.2

ARF/PARF relevance methods for forecasing time series models based on lags

arfparf

Auto-Relevance (ARF) and Partial Auto-Relevance (PARF) methods for measuring lag importance in time-series forecasting models.

Overview

This package implements the Auto-Relevance (ARF) and Partial Auto-Relevance (PARF) functions, which are designed to measure the contribution of lagged inputs in forecasting models.

The package also introduces alternative strategies for handling missing features in coalition-based relevance methods. In particular, absent features can be replaced using one-step forecasts generated by the same model, allowing more consistent relevance estimation in time-series settings.

The methods are evaluated using both simulated and real datasets. Experiments include models from the seasonal ARMA family as well as recurrent neural networks, showing that the proposed relevance measures successfully recover the expected lag structure in most scenarios.

This package has been built undes Python 3.11.9 version and requires a Python version >=3.11.

Workflow

flowchart LR
    A[Time series data] --> B[Simulation or real dataset]
    B --> C[Create lagged design matrix]
    C --> D[Train forecasting model]

    D --> E[ARF: Ghost-variable approach]
    D --> F[PARF: Shapley-based approach]

    E --> G[Relevance scores by lag]
    F --> G
    G --> H[Visualization and interpretation]

Installation

Install the package from PyPI:

pip install arfparf

Quick Example

The following example illustrates the structure to compute lag relevance using the ARF and PARF methods on a simulated time series.

import numpy as np
from arfparf.simulation import simulate_arma
from arfparf.utils import make_windows
from arfparf.relevance import gh_arf, shapley_parf

# Simulate an ARMA(3,3) process
n = 1000
y = simulate_arma(n=n, ar=[0.6, -0.4, 0.3], ma=[0.5, -0.2, 0.1])

# Define number of lags
p = 9

# Build lagged design matrix
X, yt = make_windows(y, p)

# Fit forecasting model (example: neural network)
model = fit_model(X, yt)

# Compute ARF relevance
arf_mspd, arf_mse = gh_arf(model, X, yt)

# Compute PARF relevance
parf_mspd, parf_mse = shapley_parf(model, X, yt)

print("ARF relevance:", arf_mspd)
print("PARF relevance:", parf_mse)

More detailed examples are available in the experiments/ directory.

Utilities used in experiments/ directory

The following utilities from arfparf are used in the example workflow.

• simulate_sarima
  Generates synthetic time series data from a SARIMA-type process.
  This is useful for controlled experiments where the true lag structure is known.

• make_windows
  Converts a univariate time series into a supervised learning dataset by constructing lagged input vectors.
  For a lag order $p$, each observation is represented by the previous $p$ values of the series.

• arfparf.models
  Builds the forecasting neural network used in each example.
  The model receives lagged inputs and produces one-step-ahead predictions of the time series.

• gh_arf_relevance
  Computes lag relevance using the Auto-Relevance Function (ARF) based on the ghost-variable methodology.
  Each lag is replaced by an imputed value and the resulting change in prediction or prediction error is measured.

• sh_parf_relevance
  Computes lag relevance using the Partial Auto-Relevance Function (PARF) based on Shapley values.
  This method evaluates the contribution of each lag across different subsets of lags, capturing both direct and interaction effects.

• lollipop_compare and lollipop_lags
  Visualization utilities that display lag relevance values in lollipop-style plots, making it easier to compare relevance profiles across methods.

• simulate_lagged_nonlinear Generates synthetic time series data from non linear structures.

Methods

This package implements two complementary approaches for measuring the importance of lagged inputs in univariate time-series forecasting models: Auto-Relevance Function (ARF) and Partial Auto-Relevance Function (PARF).

We consider a univariate time series $ {y_t}_{t=1}^T$, and a one-step-ahead forecasting model trained on the last $p$ lags of the series. The goal is to quantify how relevant each lag is for the predictive performance of the fitted model.

Auto-Relevance Function (ARF)

The ARF measure is based on the ghost variables methodology introduced in Delicado and Peña (2023), adapted here to univariate time-series forecasting.

For each lag $h \in {1, \dots, p}$, the idea is to replace the original lagged value $y_{t-h}$ with a ghost version, that is, an imputed value obtained from the remaining lags. The model prediction using the original lag structure is then compared with the prediction obtained after replacing lag $h$.

More specifically:

• the original prediction is computed using all $p$ lags,
• the modified prediction is obtained by replacing lag $h$ with an imputed value,
• the relevance of lag $h$ is quantified through the discrepancy between both predictions.

In this package, ghost values are generated using an auxiliary linear regression model in which the removed lag is predicted from the remaining $p-1$ lags.

Two contribution criteria are implemented:

ARF with MSPD contributions

This version measures relevance through the mean squared prediction difference (MSPD) between the original and ghost-based predictions. A lag is considered more relevant if replacing it produces a larger change in the model output.

ARF with MSE contributions

This version measures relevance through the change in mean squared error (MSE) produced by replacing a lag with its ghost version. A lag is considered more relevant if removing it leads to a larger deterioration in predictive accuracy.

In this sense:

• MSPD-based ARF focuses on changes in the model prediction,
• MSE-based ARF focuses on changes in prediction performance.

Partial Auto-Relevance Function (PARF)

PARF is a Shapley-based relevance measure designed for time-series forecasting models.

Unlike ARF, which evaluates one lag at a time while keeping all others fixed, PARF evaluates the contribution of each lag across all possible subsets of lags. This allows the method to capture both:

• the direct contribution of a lag,
• and its indirect contribution through interactions with other lags.

For each subset of retained lags, the missing lags are imputed and a prediction is computed. The contribution of a lag is then evaluated by comparing the predictive performance of a coalition of lags before and after adding that lag. These marginal contributions are aggregated using the standard Shapley weighting scheme.

This package includes two PARF variants.

PARF with MSE contributions

This version is based on the improvement in mean squared error produced by adding a lag to a given coalition. The resulting relevance scores satisfy a normalization property: the standardized relevance values sum exactly to 1.

This makes the PARF-MSE scores easy to interpret as a decomposition of the total predictive gain of the full lag set.

PARF with MSPD contributions

This version is based on the mean squared prediction difference induced by adding a lag to a coalition. It is conceptually analogous to the MSPD criterion used in ARF, but extended to the coalition-based Shapley framework.

After normalization, these scores are approximately comparable across lags and can be contrasted with the ARF relevance profile.

ARF vs PARF

The two approaches differ in their interpretation:

• ARF evaluates the effect of replacing one lag while keeping the rest fixed.
• PARF evaluates the contribution of each lag across all possible subsets of lags.

Because of this:

• ARF provides a simpler and more direct notion of relevance,
• PARF provides a richer decomposition that accounts for dependence and interaction among lags.

The term partial in PARF is used by analogy with the partial autocorrelation function (PACF): it aims to isolate the contribution of each lag after accounting for the presence of the others.

Computational considerations

The proposed PARF formulation computes relevance directly at the global level, using averages over the test sample, instead of aggregating local explanations observation by observation as in standard SHAP-based procedures. This considerably reduces the computational burden.

When the number of lags is large, the Shapley sums can also be approximated through random permutations, which provides an efficient alternative in high-dimensional lag settings.

ARF and PARF for ARMA linear models

The directory baselines_arima contains the code and examples used to implement ARF and PARF for models from the ARMA family. Since these experiments were developed only to illustrate the behavior of the proposed methods under controlled settings, the corresponding functions are not included in the arfparf package. However, they are available in this GitHub repository for reproducibility and to support validation of the methodological results.

Reference

If you use these methods, please cite the corresponding paper once it becomes available.

Citation

If you use this package in academic work, please cite:

@software{cardenas_arfparf_2026,
  author = {Julian Cardenas},
  title = {arfparf: Auto-Relevance and Partial Auto-Relevance Methods for Time Series Models},
  year = {2026},
  url = {https://github.com/alojulian15/Autorelevance}
}

Author

Julian Cardenas

License

This project is licensed under the MIT License.