Skip to content

Kantz largest-Lyapunov estimation

Version 0.29 adds a named Kantz estimator alongside the existing Rosenstein estimator.

The package does not treat the two as interchangeable aliases.

Core difference

Rosenstein-style divergence follows one nearest temporally separated neighbor per reference state.

Kantz-style divergence uses a fixed-radius neighborhood:

\[ \mathcal N_i(\varepsilon) = \left\{ j: \lVert\mathbf z_i-\mathbf z_j\rVert_2\le\varepsilon,\ |i-j|>w \right\}. \]

At forward horizon \(k\), the mean distance within each surviving reference neighborhood is computed first, then logged:

\[ S(\varepsilon,k) = \frac{1}{N_k} \sum_i \log\!\left[ \frac{1}{|\mathcal N_i(k)|} \sum_{j\in\mathcal N_i(k)} \lVert\mathbf z_{i+k}-\mathbf z_{j+k}\rVert_2 \right]. \]

A declared linear segment is then fitted as

\[ S(\varepsilon,k) \approx a+\lambda_{\max}k\Delta t. \]

API

kantz = kantz_divergence_curve(
    embedded,
    curve=0,
    radius=0.08,
    min_neighbors=4,
    theiler_window=8,
    max_horizon=10,
)

fit = estimate_largest_lyapunov_kantz(
    kantz,
    fit_start=1,
    fit_end=5,
)

Radius governance

The radius is a scientific analysis parameter.

The function does not:

  • expand it until enough neighbors are found;
  • search a radius grid;
  • optimize fit quality;
  • target a desired neighbor count;
  • select a radius that makes the exponent positive.

Reference states with too few eligible neighbors are excluded from that horizon. If none are usable at horizon zero, the analysis fails.

Use explicit sensitivity analysis if multiple defensible radii must be studied.

Minimum neighbors

min_neighbors is also explicit.

It controls whether a reference state contributes to the neighborhood average. The function retains the initial neighbor count for every reference and the number of contributing references/pairs at each forward horizon.

This prevents an apparently smooth mean-divergence curve from hiding severe loss of support.

Theiler exclusion

Temporal neighbors inside the declared Theiler window are excluded before the radius neighborhood is formed.

A small Euclidean distance is not sufficient if two states are temporally too close under the declared Theiler policy.

Fit interval

The package never detects the "linear region" automatically.

fit = estimate_largest_lyapunov_kantz(
    kantz,
    fit_start=0.03,
    fit_end=0.12,
    fit_units="seconds",
)

At least three finite divergence points are required.

Rosenstein versus Kantz

These are related but distinct local-divergence estimators.

Use Rosenstein when the intended estimator is the nearest-neighbor construction.

Use Kantz when the intended estimator is the fixed-radius local-neighborhood construction.

For robustness work, compare them under a common reconstruction and time contract. Do not report an estimator switch as if it were merely a software implementation detail.

TISEAN explicitly exposes the two methods separately as lyap_r and lyap_k.

Interpretation

A positive fitted slope is evidence of local exponential separation under the declared reconstruction and estimator settings.

It is not by itself proof that eye movements are generated by a deterministic chaotic attractor.

Behavioral gaze can violate assumptions through measurement noise, filtering, nonstationarity, task transitions, finite record length, and weak deterministic structure.

Relation to eye-movement literature

Korda et al. provide direct eye-movement signal-analysis precedent for largest-Lyapunov/log-divergence methods. That precedent supports LLE as a legitimate signal-analysis tool; it does not establish that every behavioral scanpath should be interpreted as a low-dimensional chaotic system.

Kantz (1994) is the primary method source for the neighborhood-based estimator, and Hegger, Kantz, and Schreiber (1999) document its practical TISEAN implementation.

Sensitivity across neighborhood and fit choices

Version 0.30 adds kantz_parameter_sensitivity() for a predeclared robustness grid over:

  • embedding dimension;
  • delay;
  • fixed radius;
  • minimum neighbors;
  • Theiler window;
  • fit interval.

The function retains every Cartesian-product specification and the associated neighborhood-support diagnostics. It does not rank or optimize those choices.

sensitivity = kantz_parameter_sensitivity(
    data,
    curve=0,
    dimensions=("x",),
    embedding_dimensions=(2, 3),
    delays=(1,),
    radii=(0.05, 0.08, 0.12),
    min_neighbors=(1, 2, 4),
    theiler_windows=(6, 10),
    fit_intervals=((1, 4), (2, 5)),
    max_horizon=8,
)

Use plot_kantz_sensitivity() only after filtering the grid to one explicit varying parameter. The helper refuses hidden averaging across the remaining dimensions.

A positive-specification fraction is descriptive of the declared grid. It is not a chaos probability or confidence level.

See nonlinear parameter sensitivity.

Reporting

Report:

  • source state variables;
  • embedding dimension and delay;
  • time units;
  • Kantz radius;
  • minimum-neighbor count;
  • Theiler window;
  • maximum divergence horizon;
  • contributing reference/pair counts over the fitted interval;
  • fit interval;
  • slope, units, (R^2), and slope SE;
  • that the fit interval and radius were not selected automatically;
  • that a positive exponent was not treated as standalone proof of chaos.

See the worked example, limitations, and mathematical reference.