utils.ruptures_transitions.ruptures_transition

utils.ruptures_transitions.ruptures_transition(
    series,
    algo='Pelt',
    cost='rbf',
    pen=None,
    n_bkps=None,
    min_size=2,
    jump=1,
    width=None,
    params=None,
)

Detect transitions using ruptures change point detection

Applies ruptures algorithms for offline change point detection in time series data.

Note that series must be evenly spaced for this method. See interp, bin, and gkernel methods in parent class pyleoclim.Series for details.

Parameters

series : ammonyte.Series

Series object containing time and value data

algo : str = 'Pelt'

Search algorithm: ‘Pelt’, ‘Dynp’, ‘Binseg’, ‘BottomUp’, ‘Window’, ‘KernelCPD’ Default is ‘Pelt’

cost : str = 'rbf'

Cost function: ‘l1’, ‘l2’, ‘rbf’, ‘normal’, ‘ar’, ‘linear’, ‘rank’, ‘mahalanobis’, ‘cosine’, ‘clinear’ Default is ‘rbf’ (Radial Basis Function - good for nonlinear patterns) For KernelCPD, use ‘linear’, ‘rbf’, or ‘cosine’ (these are kernel functions)

pen : float = None

Penalty parameter controlling sensitivity to changepoints (higher = fewer changepoints) What is penalty? The algorithm minimizes: [fit error] + [number of changepoints × pen] - Low penalty → more changepoints (risk: overfitting, detecting noise as transitions) - High penalty → fewer changepoints (risk: missing real transitions) Choosing penalty is a user decision based on your data characteristics, expected transition frequency, and tolerance for false positives vs. false negatives. There is no single “correct” penalty value. Example approaches for selecting penalty: 1. Fixed empirical values: pen = 5, 10, 20, etc. (experiment to find what works) 2. Information criteria (linear penalties that balance fit vs. complexity): - AIC (Akaike Information Criterion) - more liberal, detects more changepoints - BIC (Bayesian Information Criterion) - more conservative, sample-size dependent - mBIC (modified BIC) - even more conservative Note: The exact formula for each criterion depends on the statistical model and cost function used.

n_bkps : int = None

Exact number of breakpoints to detect (alternative to penalty-based approach) Use when you know how many transitions to expect Note: Cannot be used together with ‘pen’ - choose one or the other

****Stopping** :

• Pelt: requires ‘pen’ (penalty) - Dynp: requires ‘n_bkps’ (number of breakpoints) - Binseg, BottomUp, Window, KernelCPD: requires either ‘pen’ or ‘n_bkps’ (not both)

min_size : int = 2

Minimum samples between change points. Default is 2

jump : int = 1

Subsample (1=all data, 5=every 5th point). Default is 1

width : int = None

Window size (required for Window algorithm)

params : dict = None

Additional algorithm-specific parameters

Returns

result : DeterministicTransitions

Object containing detected transitions: - jump_times: array of transition times - jump_values: array of directions (+1 upward, -1 downward, 0 unclear) - series: original Series object - method: ‘ruptures’ - method_args: dict with algorithm settings - statistics: dict with breakpoint indices

Examples

Basic usage (typically called via Series.ruptures):

.. jupyter-execute::

import os, ammonyte as amt
from ammonyte.utils.ruptures_transitions import ruptures_transition
ngrip = amt.Series.from_csv(os.path.join(os.path.dirname(amt.__file__), 'data', 'NGRIP.csv'))
transitions = ngrip.ruptures(algo='Pelt', cost='rbf', pen=5)
print(f"Detected {len(transitions.jump_times)} transitions")

See Also

Series.ruptures : High-level interface to this function

References

Truong, C., et al. (2020). Selective review of offline change point detection methods. Signal Processing, 167, 107299.