incline.Smoother¶

class incline.Smoother[source]¶

Base class for every trend estimator.

Subclasses implement evaluate() and with_scale() and declare whether they are linear. Everything else – uncertainty, bias correction, simultaneous bands, result assembly – is inherited.

__init__()¶

Methods

`__init__`()
`analytic_operators`(axis, order)	State the smoothing and derivative operators directly, if known.
`evaluate`(axis, y, order)	Smooth a series and differentiate the smooth.
`fit`(axis, y[, order, se, noise, ...])	Estimate the trend and, optionally, its uncertainty.
`native_posterior`(axis, y, order, ...)	Uncertainty from the smoother's own probability model.
`operators`(axis, order)	The smoothing and derivative operators for this configuration.
`params`()	Smoother-specific settings, recorded on the result.
`scale_of`(axis)	Report this smoother's current scale as a fraction of the span.
`with_scale`(scale, axis)	Return a copy smoothing across `scale` of the series span.

Attributes

`has_native_posterior`
`is_linear`	Whether the derivative is a fixed linear map of the data.
`linear`
`requires_regular_grid`
`supported_orders`
`name`

name: ClassVar[str]¶

linear: ClassVar[bool] = False¶

has_native_posterior: ClassVar[bool] = False¶

supported_orders: ClassVar[frozenset[int]] = frozenset({1, 2})¶

requires_regular_grid: ClassVar[bool] = False¶

property is_linear: bool¶

Whether the derivative is a fixed linear map of the data.

A property rather than the class attribute alone because some smoothers are linear only in certain configurations.

abstractmethod evaluate(axis, y, order)[source]¶

Smooth a series and differentiate the smooth.

Parameters:

axis (TimeAxis) – The time axis.
y (npt.NDArray[np.float64]) – Observed values.
order (int) – Derivative order.

Returns:

The smoothed values and the derivative.

Return type:

Evaluation

abstractmethod with_scale(scale, axis)[source]¶

Return a copy smoothing across scale of the series span.

Parameters:

scale (float) – Fraction of the span in (0, 1].
axis (TimeAxis) – The time axis, for converting to native units.

Returns:

A new smoother.

Return type:

Self

abstractmethod scale_of(axis)[source]¶

Report this smoother’s current scale as a fraction of the span.

Parameters:: axis (TimeAxis) – The time axis.
Returns:: The scale in (0, 1].
Return type:: float

params()[source]¶

Smoother-specific settings, recorded on the result.

Return type:: dict[str, Any]

analytic_operators(axis, order)[source]¶

State the smoothing and derivative operators directly, if known.

A linear smoother’s operators are already implicit in the arithmetic it performs, so a smoother that fits a local system per point can emit its operator rows from the same solve. Doing so turns an O(n) probe into a constant factor. Returning None falls back to probing.

Parameters:

axis (TimeAxis) – The time axis.
order (int) – Derivative order.

Returns:

Tuple of (smoothing operator, derivative operator), or None.

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]] | None

operators(axis, order)[source]¶

The smoothing and derivative operators for this configuration.

Cached: an operator depends on the smoother’s settings, the axis and the derivative order, but never on the observed values. Repeated fits over the same grid – a multi-scale sweep, a Monte Carlo study – reuse the work.

Parameters:

axis (TimeAxis) – The time axis.
order (int) – Derivative order.

Returns:

Tuple of (smoothing operator, derivative operator).

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]

native_posterior(axis, y, order, confidence_level)[source]¶

Uncertainty from the smoother’s own probability model.

Overridden by smoothers that are probability models and therefore already know their posterior variance.

Parameters:

axis (TimeAxis) – The time axis.
y (npt.NDArray[np.float64]) – Observed values.
order (int) – Derivative order.
confidence_level (float) – Confidence level.

Returns:

Tuple of (se, ci_lower, ci_upper), or None if unsupported.

Return type:

tuple[npt.NDArray[np.float64], npt.NDArray[np.float64] | None, npt.NDArray[np.float64] | None] | None

fit(axis, y, order=1, se=False, noise=None, bias_correct=False, simultaneous=False, confidence_level=0.95, pilot_scale=None, n_bootstrap=200, random_state=None)[source]¶

Estimate the trend and, optionally, its uncertainty.

Parameters:

axis (TimeAxis) – The time axis.
y (npt.NDArray[np.float64]) – Observed values.
order (int) – Derivative order.
se (bool) – Whether to compute standard errors. Off by default because the exact route costs one smoother evaluation per observation.
noise (NoiseModel | str | None) – Noise model, or 'iid' / 'ar1'.
bias_correct (bool) – Subtract an estimate of smoothing bias using a less-smoothed pilot fit. Linear smoothers only.
simultaneous (bool) – Return a band covering the whole curve at once rather than pointwise intervals.
confidence_level (float) – Confidence level for intervals.
pilot_scale (float | None) – Scale of the pilot fit used for bias correction. Defaults to a third of this smoother’s scale.
n_bootstrap (int) – Replicates, for nonlinear smoothers.
random_state (int | np.random.Generator | None) – Seed or Generator.

Returns:

The estimate.

Raises:

ValueError – If the derivative order is unsupported, or bias correction is requested for a nonlinear smoother.

Return type:

TrendEstimate