statspai.timeseries

timeseries

Time series methods for causal inference contexts.

Provides VAR (vector autoregression), structural break tests, Granger causality, and cointegration analysis.

VARResult

Results from VAR estimation.

irf

irf(periods: int = 20, impulse: str = None, response: str = None, orthogonal: bool = True) -> Dict[str, Any]

Compute impulse response functions.

granger_test

granger_test(caused: str, causing: str) -> Dict[str, Any]

Test Granger causality.

plot_irf

plot_irf(periods: int = 20, orthogonal: bool = True, **kwargs)

Plot impulse response functions.

StructuralBreakResult

Results from structural break tests.

plot

plot(ax=None, **kwargs)

Plot with break dates marked.

CointegrationResult

Results from cointegration test.

GARCHResult dataclass

forecast

forecast(horizon: int = 1) -> ndarray

Multi-step ahead variance forecast (analytic recursion).

ARIMAResult dataclass

std_errors property

std_errors: Series

Alias for :attr:se (regression-style naming).

tvalues property

tvalues: Series

z-statistics params / se (SARIMAX uses a normal reference).

pvalues property

pvalues: Series

Two-sided p-values from the normal reference distribution.

conf_int

conf_int(alpha: float = 0.05) -> DataFrame

Confidence intervals for each parameter.

Parameters:

Name	Type	Description	Default
alpha	float	1 - alpha is the coverage (0.05 → 95% CI).	0.05

Returns:

Type	Description
DataFrame	Indexed by parameter name with lower / upper columns.

BVARResult dataclass

irf

irf(shock_var: int = 0, horizon: int = 20) -> ndarray

Orthogonalised impulse responses (Cholesky decomposition).

granger_causality

granger_causality(var_result: VARResult = None, data: DataFrame = None, caused: str = None, causing: str = None, lags: int = None) -> Dict[str, Any]

Granger causality test.

Tests whether causing variable Granger-causes caused variable.

Parameters:

Name	Type	Description	Default
var_result	VARResult	Pre-estimated VAR model.	None
data	DataFrame	Data (if var_result not provided).	None
caused	str	Variable being tested for causation.	None
causing	str	Variable hypothesized to cause.	None
lags	int	Number of lags (if fitting new VAR).	None

Returns:

Type	Description
dict	Keys: 'F_stat', 'p_value', 'df1', 'df2', 'caused', 'causing'.

irf

irf(var_result: VARResult, periods: int = 20, impulse: str = None, response: str = None, orthogonal: bool = True) -> Dict[str, Any]

Compute impulse response functions from VAR.

Parameters:

Name	Type	Description	Default
var_result	VARResult	Estimated VAR model.	required
periods	int	Number of periods for IRF.	20
impulse	str	Impulse variable (if None, all).	None
response	str	Response variable (if None, all).	None
orthogonal	bool	Orthogonalized (Cholesky) IRF.	True

Returns:

Type	Description
dict	Keys: 'irf' (dict of arrays), 'periods'.

cusum_test

cusum_test(data: DataFrame, y: str, x: List[str] = None, alpha: float = 0.05) -> Dict[str, Any]

CUSUM test for parameter stability.

Tests H0: parameters are stable vs H1: parameter shift.

Parameters:

Name	Type	Description	Default
data	DataFrame		required
y	str	Dependent variable.	required
x	list of str	Regressors.	None
alpha	float		0.05

Returns:

Type	Description
dict	Keys: 'cusum', 'critical_value', 'reject', 'n_obs'.

engle_granger

engle_granger(data: DataFrame, variables: List[str] = None, lags: int = None, trend: str = 'c', alpha: float = 0.05) -> CointegrationResult

Engle-Granger (1987) two-step cointegration test.

Step 1: OLS regression of y on x Step 2: ADF test on residuals

Parameters:

Name	Type	Description	Default
data	DataFrame		required
variables	list of str	Variables to test (first is dependent).	None
lags	int	Lags for ADF test. If None, uses AIC selection.	None
trend	str		'c'
alpha	float		0.05

Returns:

Type	Description
CointegrationResult

johansen

johansen(data: DataFrame, variables: List[str] = None, lags: int = 1, trend: str = 'c', test: str = 'trace', alpha: float = 0.05) -> CointegrationResult

Johansen (1991) cointegration test.

Tests for the cointegration rank using the trace or maximum eigenvalue test statistic.

Equivalent to Stata's vecrank and R's ca.jo().

Parameters:

Name	Type	Description	Default
data	DataFrame		required
variables	list of str	Variables to test.	None
lags	int	Number of lags in the VECM.	1
trend	str	'n' (none), 'c' (constant), 'ct' (constant + trend).	'c'
test	str	'trace' or 'maxeig' (maximum eigenvalue).	'trace'
alpha	float		0.05

Returns:

Type	Description
CointegrationResult

Examples:

>>> import statspai as sp
>>> result = sp.johansen(df, variables=['gdp', 'consumption', 'investment'], lags=2)
>>> print(result.summary())