Python API Reference¶

All functions accept np.ndarray and pd.Series and return the same type. The min_periods parameter follows pandas semantics: positions with fewer valid observations than min_periods are set to nan.

High-level functions¶

robustrolling.rolling_max(x, window_size: int, min_periods: int | None = None)[source]¶

Compute the rolling maximum over a sliding window.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).

Returns:

numpy.ndarray or pandas.Series – Rolling maximum values. Positions with fewer than min_periods valid observations are nan.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 3.0, 2.0, 5.0, 4.0])
>>> rr.rolling_max(x, 3)
array([nan, nan,  3.,  5.,  5.])

robustrolling.rolling_min(x, window_size: int, min_periods: int | None = None)[source]¶

Compute the rolling minimum over a sliding window.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).

Returns:

numpy.ndarray or pandas.Series – Rolling minimum values. Positions with fewer than min_periods valid observations are nan.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 3.0, 2.0, 5.0, 4.0])
>>> rr.rolling_min(x, 3)
array([nan, nan,  1.,  2.,  2.])

robustrolling.rolling_variance(x, window_size: int, min_periods: int | None = None, method: str = 'stable')[source]¶

Compute the rolling sample variance (ddof=1) over a sliding window.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).
method ({“stable”, “fast”}, optional) – "stable" uses the Welford online algorithm (numerically stable, default). "fast" uses a prefix-sum approach (faster for large arrays, but susceptible to catastrophic cancellation when values are large and variance is small).

Returns:

numpy.ndarray or pandas.Series – Rolling sample variance. Returns nan when fewer than min_periods valid observations are present, or when fewer than two observations are available (variance undefined).

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
>>> rr.rolling_variance(x, 3)
array([nan, nan,  1.,  1.,  1.])

robustrolling.rolling_median(x, window_size: int, min_periods: int | None = None)[source]¶

Compute the rolling median over a sliding window.

Uses a std::multiset with a tracked median iterator. Time complexity: O(log n) per element.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).

Returns:

numpy.ndarray or pandas.Series – Rolling median values. Positions with fewer than min_periods valid observations are nan.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 3.0, 2.0, 5.0, 4.0])
>>> rr.rolling_median(x, 3)
array([nan, nan,  2.,  3.,  4.])

robustrolling.rolling_mean(x, window_size: int, min_periods: int | None = None, assume_finite: bool = False)[source]¶

Compute the rolling arithmetic mean over a sliding window.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).
assume_finite (bool, optional) – If True, assumes the input contains no NaN values and uses a faster single-pass prefix-sum path with SIMD acceleration. Passing True when the input does contain NaN produces incorrect results. Defaults to False.

Returns:

numpy.ndarray or pandas.Series – Rolling mean values. Positions with fewer than min_periods valid observations are nan.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
>>> rr.rolling_mean(x, 3)
array([nan, nan,  2.,  3.,  4.])

robustrolling.rolling_skewness(x, window_size: int, min_periods: int | None = None, method: str = 'stable')[source]¶

Compute the rolling adjusted Fisher-Pearson skewness over a sliding window.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).
method ({“stable”, “fast”}, optional) – "stable" uses Terriberry’s online algorithm (numerically stable, default). "fast" uses a prefix-sum approach (faster for large arrays, but susceptible to catastrophic cancellation).

Returns:

numpy.ndarray or pandas.Series – Rolling skewness values. Returns nan when fewer than min_periods valid observations are present, or when fewer than three observations are available.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
>>> rr.rolling_skewness(x, 3)
array([nan, nan,  0.,  0.,  0.])

robustrolling.rolling_kurtosis(x, window_size: int, min_periods: int | None = None, method: str = 'stable')[source]¶

Compute the rolling excess kurtosis (Fisher definition) over a sliding window.

Returns excess kurtosis (normal distribution = 0). Requires at least 4 valid observations per window.

Parameters:

x (array-like) – Input sequence. Accepts np.ndarray and pd.Series.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of non-NaN observations required to return a result. Defaults to window_size (pandas-compatible semantics).
method ({“stable”, “fast”}, optional) – "stable" uses Terriberry’s online algorithm (numerically stable, default). "fast" uses a prefix-sum approach (faster for large arrays, but susceptible to catastrophic cancellation).

Returns:

numpy.ndarray or pandas.Series – Rolling excess kurtosis values. Returns nan when fewer than min_periods valid observations are present, or when fewer than four observations are available.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
>>> rr.rolling_kurtosis(x, 4)
array([nan, nan, nan, -1.2, -1.2])

robustrolling.rolling_cov(x, y, window_size: int, min_periods: int | None = None)[source]¶

Compute the rolling sample covariance (ddof=1) over a sliding window.

Uses the 2D Welford online algorithm for O(1) updates.

Parameters:

x (array-like) – First input sequence. Accepts np.ndarray and pd.Series.
y (array-like) – Second input sequence, same length as x.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of valid (non-NaN) pairs required to return a result. Defaults to window_size (pandas-compatible semantics).

Returns:

numpy.ndarray or pandas.Series – Rolling sample covariance values. Positions with fewer than min_periods valid pairs are nan.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
>>> y = np.array([2.0, 4.0, 6.0, 8.0, 10.0])
>>> rr.rolling_cov(x, y, 3)
array([nan, nan,  2.,  2.,  2.])

robustrolling.rolling_cor(x, y, window_size: int, min_periods: int | None = None)[source]¶

Compute the rolling Pearson correlation coefficient over a sliding window.

Uses the 2D Welford online algorithm for O(1) updates.

Parameters:

x (array-like) – First input sequence. Accepts np.ndarray and pd.Series.
y (array-like) – Second input sequence, same length as x.
window_size (int) – Number of observations in the sliding window.
min_periods (int, optional) – Minimum number of valid (non-NaN) pairs required to return a result. Defaults to window_size (pandas-compatible semantics).

Returns:

numpy.ndarray or pandas.Series – Rolling Pearson correlation values in [-1, 1]. Positions with fewer than min_periods valid pairs are nan.

Examples

>>> import numpy as np
>>> import robustrolling as rr
>>> x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
>>> y = np.array([2.0, 4.0, 6.0, 8.0, 10.0])
>>> rr.rolling_cor(x, y, 3)
array([nan, nan,  1.,  1.,  1.])

Low-level classes¶

Six C++ classes are exposed directly for streaming (one observation at a time) or for computing multiple statistics in a single pass without calling several high-level functions.

Class	Algorithm	Key methods
`MonotonicMax`	Monotonic deque	`update`, `get_max`, `process_batch`
`MonotonicMin`	Monotonic deque	`update`, `get_min`, `process_batch`
`MultisetMedian`	`std::multiset` + tracked iterator	`update`, `get_median`, `process_batch`
`SlidingWelford`	Welford + ring buffer	`update`, `get_variance`, `process_batch`
`SlidingMoments`	Terriberry 4th-moment	`update`, `get_mean`, `get_skewness`, `get_kurtosis`
`SlidingCovariance`	2-D Welford	`update`, `get_covariance`, `get_correlation`