PyFlux Documentation

PyFlux is an open source time series library for Python that combines a wide range of time series models with flexible frequentist and Bayesian inference options. This allows for a probabilistic approach to time series modelling.

Supported Models

PyFlux includes several categories of models:

• ARIMA/ARIMAX models
• Dynamic Autoregression (DAR) models
• Dynamic Paired Comparison models
• GARCH models (including EGARCH, EGARCH-in-mean, Long Memory EGARCH, and Skew-t-EGARCH variants)
• GAS models (including GASX and GAS State Space models)
• State Space models (Gaussian and Non-Gaussian)
• VAR models

Inference Options

Inference can be performed using various methods:

• Frequentist: Maximum Likelihood and Penalized Maximum Likelihood.
• Bayesian: Black Box Variational Inference, Laplace Approximation, and Metropolis-Hastings.

Vector Autoregression (VAR) models are used to model linear dependencies among multiple variables. A VAR(p) model for a $K \times 1$ vector $y_{t}$ is specified as:

$y_{t} = c + A_{1}y_{t-1} + ... + A_{p}y_{t-p} + e_{t}$

While these models can be estimated quickly using Ordinary Least Squares (OLS), the number of parameters grows rapidly as the number of dependent variables increases. For high-dimensional datasets, consider using Bayesian VARs to manage parameter growth.

PyFlux uses a unified 'Family' API to specify two critical components of a model:

1. Model Measurement Densities: Defining the distribution of the observed data (e.g., specifying if your data follows a Normal, Poisson, or Exponential distribution).
2. Priors on Latent Variables: Defining the prior distributions for the parameters within the model using the adjust_prior method.

Families can be passed directly to model constructors (like pf.ARIMA) or used to update existing priors.

Generalized Autoregressive Score (GAS) models are score-driven versions of traditional state space models. In a standard Kalman filter, the linear update relies on the term $y_{t} - \theta_{t}$. GAS models robustify this process by replacing that linear update with the conditional score of a non-normal distribution.

In a GAS local linear model, the latent variables $\eta$ represent two learning rates or scaling terms that are estimated by the model. The state updates for the level ($\mu_{t}$) and the trend ($\beta_{t}$) are driven by these terms and the precision/score components ($H_{t-1}^{-1}S_{t-1}$):

• $\mu_{t} = \mu_{t-1} + \beta_{t-1} + \eta_{1}{H_{t-1}^{-1}S_{t-1}}$
• $\beta_{t} = \beta_{t-1} + \eta_{2}{H_{t-1}^{-1}S_{t-1}}$

Autoregressive integrated moving average with exogenous variables (ARIMAX) models extend standard ARIMA models by incorporating exogenous data $X$. An $ARIMAX(p, d, q)$ model accounts for:

• $p$: The number of autoregressive lags.
• $d$: The degree of differencing.
• $q$: The number of moving average lags.
• $X$: Exogenous variables that influence the time series $y_t$.

The model equation is expressed as:

$$\Delta^{D}y_{t} = \sum^{p}{i=1}\phi{i}\Delta^{D}y_{t-i} + \sum^{q}{j=1}\theta{j}\epsilon_{t-j} + \sum^{M}{m=1}\beta{m}X_{m,t} + \epsilon_{t}$$

where the error term $\epsilon_{t}$ is assumed to be normally distributed: $\epsilon_{t} \sim N(0, \sigma^{2})$.

The Beta Skew-t in-mean GARCH model is a variation of the Beta t EGARCH model that utilizes a Skew t distribution. This model includes an additional skewness parameter to account for asymmetry in the data distribution.

Note on Performance: This specific model type has not yet been Cythonized, so users may experience slower performance compared to other model types in PyFlux.

GAS ranking models (based on Taylor, R. 2016) are used for modeling pairwise comparisons or competitive activities. They model the point difference between two competitors as a random variable following a specific distribution (e.g., Normal).

Key components of the model include:

• Point Difference: Modeled as a function of a 'home advantage' latent variable ($\delta$) and the difference between team power rankings ($\alpha$).
• Power Rankings: Modeled as random walk processes between matches, where the change in ranking is scaled by a learning rate or scaling parameter ($\eta$).
• Two-Component Extension: The model can be extended to include a second aspect for each competitor (e.g., modeling an NFL team alongside a specific player's power ranking) by adding a second set of power rankings ($\gamma$) that also follow a random walk process.

Dynamic Autoregression (DAR) models are a type of Gaussian state space model (also known as structural time series or unobserved component models). They allow for the decomposition of a time series into distinct components.

In a DAR model, the autoregressive coefficients are not constant; instead, they follow a random walk. This allows the model to adapt to changing dynamics in the time series over time.

The model is defined by:

• $y_{t} = \sum^{p}{i=1}\phi{i,t}y_{t-i} + \epsilon_{t}$
• $\phi_{i,t}= \phi_{i,t-1} + \eta_{i,t}$
• $\epsilon_{t} \sim N(0,\sigma^{2})$
• $\eta_{i,t} \sim N(0,\sigma_{\eta_{i}}^{2})$

Dynamic Linear Regression models are a type of Gaussian state space model (also known as structural time series or unobserved component models). They allow you to decompose a time series into distinct components.

In this framework, the model is defined by:

1. An observation equation: $y_{t} = \boldsymbol{x}{t}^{'}\boldsymbol{eta}{t} + \epsilon_{t}$
2. A state equation: $\boldsymbol{\beta}{t} = \boldsymbol{\beta}{t-1} + \boldsymbol{\eta}_{t}$

Where:

• $\epsilon_{t}$ is the observation error, distributed as $N(0, \sigma_{\epsilon}^{2})$.
• $\boldsymbol{\eta}{t}$ is the state error, distributed as $N(\mathbf{0}, \Sigma{\eta})$.

Components can be extracted in closed form using the Kalman filter if errors are jointly Gaussian, and parameters can be estimated via prediction error decomposition and Maximum Likelihood.

Beta Skew-t EGARCH models (based on Harvey and Chakravarty, 2008) extend standard GARCH models by using a Skew-t conditional score to drive conditional variance. This approach provides increased robustness to outliers. The model utilizes a Skew-t distribution (Fernandez and Steel, 1998) where a latent variable gamma ($\gamma$) represents the degree of skewness:

• $\gamma = 1$: No skewness.
• $\gamma > 1$: Positive skewness.
• $\gamma < 1$: Negative skewness.

Generalized Autoregressive Score (GAS) models are observation-driven time-series models designed for non-normal data. They model a conditional observation density $p(y_t | x_t)$ where the latent time-varying parameter $x_t$ follows a recursion based on past values and the score (the derivative of the log-likelihood) of the previous observations.

In PyFlux, these models serve as approximations to parameter-driven state space models and can be viewed as approximations to non-linear ARIMA processes. They are particularly useful when dealing with non-normal distributions, such as Poisson distributions.