core.series.Series

core.series.Series()

Ammonyte series object, launching point for most ammonyte analysis.

Child of pyleoclim.Series, so shares all methods with pyleoclim.Series plus those defined here.

Methods

Name	Description
determinism	Calculate determinism of a series
embed	Create a time delay embedding from an ammonyte.Series object
from_csv	Load an ammonyte Series from a CSV file with pyleoclim metadata format.
kstest	Detect tipping points using Kolmogorov-Smirnov test
laminarity	Calculate laminarity of a series
ruptures	Detect transitions using ruptures change point detection

determinism

core.series.Series.determinism(window_size, overlap, m, tau, eps)

Calculate determinism of a series

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

Parameters

window_size : int: Size of window to use when calculating recurrence plots for determinism statistic. Note this is in units of the time axis.
overlap : int: Amount of overlap to allow between windows. Note this is in units of the time axis.
m : int: Embedding dimension to use when performing time delay embedding,
tau : int: Time delay to use when performing time delay embedding
eps : float: Size of radius to use to calculate recurrence matrix

Returns

det_series : ammonyte.Series: Ammonyte.Series object containing time series of the determinism statistic

embed

core.series.Series.embed(m, tau=None)

Create a time delay embedding from an ammonyte.Series object

Parameters

m : int: Embedding dimension (number of delay coordinates).
tau : int = None: Time delay for the embedding. If None, estimated automatically via the first minimum of mutual information using ammonyte.utils.parameters.tau_search.

Returns

TimeEmbeddedSeries : ammonyte.TimeEmbeddedSeries: Time delay embedded representation of the series.

from_csv

core.series.Series.from_csv(file_path)

Load an ammonyte Series from a CSV file with pyleoclim metadata format.

Parameters

file_path : str: Path to the CSV file with pyleoclim metadata header format (### delimited)

Returns

: ammonyte.Series: An ammonyte Series object loaded from the CSV file

Examples

>>> ts = ammonyte.Series.from_csv('data/NGRIP.csv')

kstest

core.series.Series.kstest(
    w_min,
    w_max,
    n_w=15,
    d_c=0.75,
    n_c=3,
    s_c=1.5,
    x_c=None,
)

Detect tipping points using Kolmogorov-Smirnov test

Applies sliding window KS test to detect abrupt transitions in time series data using the method of Bagniewski et al. (2021).

Parameters

w_min : float: Size of smallest sliding window in time units
w_max : float: Size of largest sliding window in time units
n_w : int = 15: Number of window lengths to test. Default is 15
d_c : float = 0.75: Cut-off threshold for KS statistic. Default is 0.75
n_c : int = 3: Minimum sample size per window. Default is 3
s_c : float = 1.5: Standard deviation ratio threshold. Default is 1.5
x_c : float = None: Change threshold. If None, auto-calculated

Returns

: DeterministicTransitions: Object containing detected transitions with their corresponding KS D-statistics and p-values, plus methods for analysis

Examples

Basic tipping point detection:

.. jupyter-execute::

import os, ammonyte as amt
ngrip = amt.Series.from_csv(os.path.join(os.path.dirname(amt.__file__), 'data', 'NGRIP.csv'))
transitions = ngrip.kstest(w_min=0.12, w_max=2.5, n_w=15, d_c=0.77, n_c=3, s_c=2, x_c=0.8)
print(transitions)

Access transition statistics:

.. jupyter-execute::

print(f"D-statistics: {transitions.d_statistics}")
print(f"P-values: {transitions.p_values}")

Plot the results:

.. jupyter-execute::

transitions.plot()

References

.. [1] Bagniewski, W., Ghil, M., & Rousseau, D. D. (2021). Automatic detection of abrupt transitions in paleoclimate records. Chaos: An Interdisciplinary Journal of Nonlinear Science, 31(11), 113129. https://doi.org/10.1063/5.0062543

.. [2] Kolmogorov, A. (1933). Sulla determinazione empirica di una legge di distribuzione. Giornale dell’Istituto Italiano degli Attuari, 4, 83-91.

.. [3] Smirnov, N. (1948). Table for estimating the goodness of fit of empirical distributions. The Annals of Mathematical Statistics, 19(2), 279-281.

laminarity

core.series.Series.laminarity(window_size, overlap, m, tau, eps)

Calculate laminarity of a series

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

Parameters

window_size : int: Size of window to use when calculating recurrence plots for determinism statistic. Note this is in units of the time axis.
overlap : int: Amount of overlap to allow between windows Note this is in units of the time axis.
m : int: Embedding dimension to use when performing time delay embedding,
tau : int: Time delay to use when performing time delay embedding
eps : float: Size of radius to use to calculate recurrence matrix

Returns

lam_series : ammonyte.Series: Ammonyte.Series object containing time series of the laminarity statistic

ruptures

core.series.Series.ruptures(
    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.

Parameters

algo : str = 'Pelt': Search algorithm. Default is ‘Pelt’ Options: ‘Pelt’, ‘Dynp’, ‘Binseg’, ‘BottomUp’, ‘Window’, ‘KernelCPD’
cost : str = 'rbf': Cost function (type of change to detect). Default is ‘rbf’ Options: ‘l1’, ‘l2’, ‘rbf’, ‘normal’, ‘ar’, ‘linear’, ‘rank’, ‘mahalanobis’, ‘cosine’, ‘clinear’
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 - it requires experimentation and domain knowledge. 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. For theoretical details, see ruptures documentation.
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
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

: DeterministicTransitions: Object containing detected transitions with plot() and to_csv() methods

Examples

Basic transition detection:

.. jupyter-execute::

import os, ammonyte as amt
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(transitions)

Plot the results:

.. jupyter-execute::

transitions.plot()

References

.. [1] Truong, C., Oudre, L., & Vayatis, N. (2020). Selective review of offline change point detection methods. Signal Processing, 167, 107299.

core.series.Series

Methods

determinism

Parameters

Returns

embed

Parameters

Returns

See Also

from_csv

Parameters

Returns

Examples

kstest

Parameters

Returns

Examples

See Also

References

laminarity

Parameters

Returns

ruptures

Parameters

Returns

Examples

References