utils.lerm_transitions.lerm_transition

utils.lerm_transitions.lerm_transition(
    series,
    transition_interval=None,
    upper=95,
    lower=5,
    w=50,
    n_samples=10000,
)

Detect transitions using LERM Fisher Information threshold crossings

Identifies complete transitions where the Fisher Information series crosses from one confidence bound to the other, indicating abrupt changes in the dynamical system.

Parameters

series : (ammonyte.Series, ammonyte.RQARes)

Fisher Information series from LERM analysis (typically smoothed)

transition_interval : tuple = None

(upper_bound, lower_bound) for detecting transitions. If None, automatically computes via bootstrapping using the parameters below.

upper : int = 95

Upper percentile for confidence interval. Default is 95 Only used if transition_interval is None.

lower : int = 5

Lower percentile for confidence interval. Default is 5 Only used if transition_interval is None.

w : int = 50

Bootstrap sample size. Default is 50 Only used if transition_interval is None.

n_samples : int = 10000

Number of bootstrap samples. Default is 10000 Only used if transition_interval is None.

Returns

jump_times : numpy.ndarray

Array of transition times

jump_directions : numpy.ndarray

Array of transition directions (+1 for upward, -1 for downward)

upper_bound : float

Upper confidence bound used for detection

lower_bound : float

Lower confidence bound used for detection

Examples

Basic usage (typically called via Series.lerm_transitions):

.. jupyter-execute::

import os, ammonyte as amt
from ammonyte.utils.lerm_transitions import lerm_transition

# Load data and perform LERM analysis
ngrip = amt.Series.from_csv(os.path.join(os.path.dirname(amt.__file__), 'data', 'NGRIP.csv'))
NGRIP_td = amt.TimeEmbeddedSeries(ngrip, m=11)
NGRIP_epsilon = NGRIP_td.find_epsilon(eps=1, target_density=0.05)
NGRIP_rm = NGRIP_epsilon['Output']
NGRIP_lp = NGRIP_rm.laplacian_eigenmaps(w_size=20, w_incre=4)
NGRIP_lp_smooth = amt.utils.fisher.smooth_series(NGRIP_lp, block_size=3)

# Detect transitions
jump_times, jump_directions, upper_bound, lower_bound = lerm_transition(NGRIP_lp_smooth)
print(f"Detected {len(jump_times)} transitions")
print(f"Bounds used: upper={upper_bound:.4f}, lower={lower_bound:.4f}")

See Also

Series.lerm_transitions : High-level interface to this function confidence_interval : Bootstrap confidence interval calculation

Notes

This function detects complete transitions where the series crosses from one confidence threshold to the other. The algorithm:

  1. Interpolates the series to step=1 for fine-grained detection
  2. Computes or uses provided confidence bounds (upper, lower)
  3. Tracks crossings above the upper threshold
  4. Tracks crossings below the lower threshold
  5. Identifies complete transitions:
    • Upward (+1): from below lower bound to above upper bound
    • Downward (-1): from above upper bound to below lower bound
  6. Assigns transition time at the midpoint between threshold crossings