Independent change principle

Port of infer_nonsta_dir.m from the MATLAB reference, covering both the fixed-bandwidth path and the GP-learned-bandwidth path (via the "gp" mode, which uses scikit-learn's ARD-RBF Gaussian process regression in place of MATLAB's gpml/minimize machinery). See Step 4 — Orientation for the math, the auto-bandwidth heuristic, and the picking-between-modes table.

independent_change_score

independent_change_score(
    parents: NDArray[float64],
    effect: NDArray[float64],
    surrogate: NDArray[float64],
    *,
    width: WidthSpec = AUTO,
    width_t: WidthSpec = AUTO,
    lambda_reg: float = 2.0,
) -> float

Score the hypothesis parents -> effect under non-stationarity.

Returns a scalar dependence statistic between the kernel representation of P(effect | parents) and the kernel representation of P(parents), both as they vary with the surrogate. Lower values support the direction.

Parameters:

Name	Type	Description	Default
parents	NDArray[float64]	Putative cause(s). Shape (T,), (T, 1), or (T, k) for k joint parents.	required
effect	NDArray[float64]	Putative effect. Shape (T,) or (T, 1).	required
surrogate	NDArray[float64]	Distribution-shift surrogate (time index, domain id, etc.). Shape (T,) or (T, 1).	required
width	WidthSpec	Bandwidth for the Gaussian kernels on parents and effect (after standardization). Three accepted forms: a positive float — manual; used verbatim; "auto" (default) — median heuristic on the standardized parents, scaled down by an empirical constant. Fast. "gp" — fit a Gaussian process with an ARD-RBF kernel and use the marginal-likelihood-optimized length scales. Adaptive but slower (~10–50× the cost of "auto" per score call). When "gp" is selected, both width and width_t are learned together by the same GP, regardless of what width_t was set to. The MATLAB reference uses a fixed 0.1 here — pass that explicitly to reproduce the reference exactly.	AUTO
width_t	WidthSpec	Bandwidth for the Gaussian kernel on the surrogate. Accepts the same three forms as width. Ignored when width="gp" (the GP fit handles both).	AUTO
lambda_reg	float	Tikhonov regularization for the kernel matrix inverses.	2.0

Returns:

Type	Description
float	Dependence statistic. Lower is better evidence for the parents -> effect direction.