Temporal Models¶

Time-dependent data generation with autoregressive processes, Markov chains, and random walks.

Overview¶

Temporal models provide:

Autoregressive (AR) processes for correlated time series
Markov chains for state-based dynamics
Random walks for price-like processes
Exponential smoothing for trend/seasonality

AR(1) Process¶

The AR1 class generates a first-order autoregressive process:

\[X_t = \phi X_{t-1} + \epsilon_t\]

where \(\phi\) is the persistence parameter and \(\epsilon_t\) is white noise.

from superstore import AR1

# Create AR(1) with high persistence
ar = AR1(phi=0.95, sigma=1.0)

# Generate time series
values = ar.generate(n=500)

# Generate with initial value
values = ar.generate(n=500, x0=10.0)

Parameters:

Parameter	Description
`phi`	Persistence parameter (-1 < φ < 1 for stationarity)
`sigma`	Standard deviation of innovations

Properties:

phi close to 1: Highly persistent, slow mean reversion
phi close to 0: Low persistence, rapid mean reversion
phi negative: Oscillating behavior
|phi| >= 1: Non-stationary (explosive or unit root)

AR(p) Process¶

The ARp class generates a higher-order autoregressive process:

\[X_t = \phi_1 X_{t-1} + \phi_2 X_{t-2} + ... + \phi_p X_{t-p} + \epsilon_t\]

from superstore import ARp

# Create AR(3) process
ar = ARp(phi=[0.5, 0.3, 0.1], sigma=1.0)

# Generate time series
values = ar.generate(n=500)

Parameters:

Parameter	Description
`phi`	List of AR coefficients [φ₁, φ₂, …, φₚ]
`sigma`	Standard deviation of innovations

Usage:

# AR(2) with cyclical behavior
ar = ARp(phi=[0.6, -0.3], sigma=1.0)
values = ar.generate(n=1000)

Markov Chain¶

The MarkovChain class generates sequences from a discrete-state Markov chain:

from superstore import MarkovChain

# Define transition matrix (rows must sum to 1)
# State 0: Bull market, State 1: Bear market
transition_matrix = [
    [0.95, 0.05],  # Bull → Bull 95%, Bull → Bear 5%
    [0.10, 0.90],  # Bear → Bull 10%, Bear → Bear 90%
]

mc = MarkovChain(transition_matrix=transition_matrix)

# Generate state sequence
states = mc.generate(n=1000, initial_state=0)

Parameters:

Parameter	Description
`transition_matrix`	Square matrix P where P[i,j] = P(state j \| state i)

Named states:

# Three-state regime model
states = ["low_vol", "normal", "high_vol"]
transition_matrix = [
    [0.90, 0.08, 0.02],  # low → low, normal, high
    [0.05, 0.90, 0.05],  # normal → ...
    [0.03, 0.17, 0.80],  # high → ...
]

mc = MarkovChain(
    transition_matrix=transition_matrix,
    state_names=states,
)

# Returns strings instead of integers
regimes = mc.generate(n=500, initial_state="normal")

Stationary distribution:

# Get long-run state probabilities
stationary = mc.stationary_distribution()

Random Walk¶

The RandomWalk class generates random walk processes (cumulative sum of innovations):

\[X_t = X_{t-1} + \mu + \epsilon_t\]

from superstore import RandomWalk

# Simple random walk
rw = RandomWalk(drift=0.0, sigma=1.0)
values = rw.generate(n=500)

# Random walk with positive drift (trending up)
rw = RandomWalk(drift=0.001, sigma=0.02)
prices = rw.generate(n=252, x0=100.0)

Parameters:

Parameter	Description
`drift`	Drift/trend per step (μ)
`sigma`	Standard deviation of innovations

Geometric random walk (for prices):

import numpy as np

# Generate log-price random walk
rw = RandomWalk(drift=0.0003, sigma=0.015)
log_prices = rw.generate(n=252, x0=0.0)

# Convert to prices
prices = 100 * np.exp(log_prices)

Exponential Smoothing¶

The ExponentialSmoothing class generates smoothed time series with optional trend and seasonality:

from superstore import ExponentialSmoothing

# Simple exponential smoothing
es = ExponentialSmoothing(alpha=0.3)
smoothed = es.smooth(values)

# Holt-Winters with trend and seasonality
es = ExponentialSmoothing(
    alpha=0.3,      # Level smoothing
    beta=0.1,       # Trend smoothing
    gamma=0.1,      # Seasonal smoothing
    period=12,      # Seasonal period
)
smoothed = es.smooth(values)

Parameters:

Parameter	Description
`alpha`	Level smoothing (0 < α < 1)
`beta`	Trend smoothing (0 < β < 1), optional
`gamma`	Seasonal smoothing (0 < γ < 1), optional
`period`	Seasonal period (required if gamma set)

Examples¶

Mean-Reverting Price¶

from superstore import AR1
import numpy as np

# Price that mean-reverts to 100
ar = AR1(phi=0.98, sigma=2.0)
deviations = ar.generate(n=500)
prices = 100 + deviations

Regime-Switching Volatility¶

from superstore import MarkovChain, sampleNormal

# Two volatility regimes
mc = MarkovChain(
    transition_matrix=[[0.95, 0.05], [0.10, 0.90]],
    state_names=["low_vol", "high_vol"],
)
regimes = mc.generate(n=500, initial_state="low_vol")

# Generate returns with regime-dependent volatility
volatilities = {"low_vol": 0.01, "high_vol": 0.03}
returns = [sampleNormal(n=1, std=volatilities[r])[0] for r in regimes]

Stock Price with Drift¶

from superstore import RandomWalk
import numpy as np

# Geometric Brownian Motion approximation
# Annual drift 8%, volatility 20%
daily_drift = 0.08 / 252
daily_vol = 0.20 / np.sqrt(252)

rw = RandomWalk(drift=daily_drift, sigma=daily_vol)
log_returns = rw.generate(n=252, x0=0.0)
prices = 100 * np.exp(log_returns)

Seasonal Time Series¶

from superstore import ExponentialSmoothing, sampleNormal
import numpy as np

# Create noisy seasonal data
t = np.arange(365)
seasonal = 10 * np.sin(2 * np.pi * t / 365)
trend = 0.05 * t
noise = sampleNormal(n=365, std=3.0)
values = 50 + trend + seasonal + noise

# Apply Holt-Winters smoothing
es = ExponentialSmoothing(alpha=0.2, beta=0.05, gamma=0.1, period=365)
smoothed = es.smooth(values)

API Reference¶

See the full API Reference for all temporal model classes.