core.transitions.DeterministicTransitions

core.transitions.DeterministicTransitions(
    series,
    jump_times,
    jump_values,
    method,
    method_args=None,
    label=None,
    statistics=None,
)

Container for deterministic transition detection results

Stores results from tipping point detection algorithms with methods for analysis and visualization.

Parameters

series : ammonyte.Series

Original time series object

jump_times : array - like

Array of detected transition times

jump_values : array - like

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

method : str

Name of detection method used

method_args : dict = None

Dictionary of method parameters

label : str = None

Label for the results

d_statistics : array - like

Array of KS D-statistics corresponding to each transition

p_values : (array - like, optional)

Array of p-values corresponding to each transition

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.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)

Plot the results:

.. jupyter-execute::

transitions.plot()

Access transition data:

.. jupyter-execute::

print(f"Number of transitions: {len(transitions.jump_times)}")
print(f"First transition: {transitions.jump_times[0]:.2f}")

See Also

Series.kstest : Detect transitions

Methods

Name	Description
copy	Create a copy of the DeterministicTransitions object.
plot	Plot the time series with detected transitions.
to_csv	Export detected transitions to CSV file

copy

core.transitions.DeterministicTransitions.copy()

Create a copy of the DeterministicTransitions object.

Returns

: DeterministicTransitions

A deep copy of the current object.

plot

core.transitions.DeterministicTransitions.plot(
    figsize=(12, 8),
    ylabel=None,
    xlabel=None,
    title=None,
    upward_color='red',
    downward_color='blue',
    transition_color=None,
    show_transitions='both',
    ax=None,
    title_fontsize=14,
    label_fontsize=12,
    tick_fontsize=10,
    legend_fontsize=10,
    show_legend=True,
    legend_labels=None,
    legend_loc='best',
    **kwargs,
)

Plot the time series with detected transitions.

Parameters

figsize : tuple = (12, 8)

Figure size (width, height) in inches. Default is (12, 8).

ylabel : str = None

Y-axis label. If None, uses series metadata.

xlabel : str = None

X-axis label. If None, uses series metadata.

title : str = None

Plot title. If None, auto-generated.

upward_color : str = 'red'

Color for upward transition markers. Default is ‘red’. Used when show_transitions is ‘both’ or ‘upward’.

downward_color : str = 'blue'

Color for downward transition markers. Default is ‘blue’. Used when show_transitions is ‘both’ or ‘downward’.

transition_color : str = None

Color for all transitions when show_transitions=‘all’. Default is None. If None, falls back to upward_color. Recommended to use this parameter when show_transitions=‘all’ for clarity.

show_transitions : str = 'both'

Which transitions to show: ‘all’, ‘both’, ‘upward’, or ‘downward’. Default is ‘both’. - ‘all’: Show all transitions in one color without direction distinction (use transition_color) - ‘both’: Show upward and downward transitions in different colors (use upward_color/downward_color) - ‘upward’: Show only upward transitions (use upward_color) - ‘downward’: Show only downward transitions (use downward_color)

ax : matplotlib.axes.Axes = None

Axes object to plot on. If None, creates new figure.

title_fontsize : int = 14

Font size for plot title. Default is 14.

label_fontsize : int = 12

Font size for axis labels. Default is 12.

tick_fontsize : int = 10

Font size for tick labels (numbers on axes). Default is 10.

legend_fontsize : int = 10

Font size for legend. Default is 10.

show_legend : bool = True

Whether to display legend. Default is True.

legend_labels : list of str = None

Custom legend labels. If None, uses auto-generated labels. Provide as list: [‘label1’] for single transition type, or [‘label1’, ‘label2’] for both.

legend_loc : str = 'best'

Legend location. Default is ‘best’. Options: ‘upper right’, ‘upper left’, ‘lower left’, ‘lower right’, ‘right’, ‘center left’, ‘center right’, ‘lower center’, ‘upper center’, ‘center’, ‘best’.

****kwargs** : = {}

Additional arguments passed to matplotlib plot functions.

Returns

fig : matplotlib.figure.Figure

The figure object.

ax : matplotlib.axes.Axes

The axes object.

Examples

>>> # Basic plot
>>> result.plot()
>>>
>>> # Custom colors and size
>>> result.plot(figsize=(15, 10), upward_color='green', downward_color='purple')
>>>
>>> # Show only upward transitions
>>> result.plot(show_transitions='upward', upward_color='red')
>>>
>>> # Show all transitions without direction distinction (single color, single legend)
>>> result.plot(show_transitions='all', transition_color='blue')
>>>
>>> # Custom font sizes
>>> result.plot(title_fontsize=18, label_fontsize=16, tick_fontsize=14, legend_fontsize=14)
>>>
>>> # Hide legend
>>> result.plot(show_legend=False)
>>>
>>> # Custom legend label with 'all' mode
>>> result.plot(show_transitions='all', transition_color='purple',
...             legend_labels=['Detected Transitions'])
>>>
>>> # Custom legend location and color
>>> result.plot(show_transitions='all', transition_color='#1f77b4',
...             legend_loc='upper right')

to_csv

core.transitions.DeterministicTransitions.to_csv(path=None, **kwargs)

Export detected transitions to CSV file

Parameters

path : str = None

Output file path. If None, uses default naming based on method.

****kwargs** : = {}

Additional arguments passed to pandas.to_csv()

Examples

>>> transitions = ngrip.kstest(w_min=0.12, w_max=2.5)
>>> transitions.to_csv('my_transitions.csv')