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, derivative_order)	State the smoothing and derivative operators directly, if known.
`bootstrap_uncertainty`(estimate, axis, y, ...)	Bootstrap a nonlinear smoother, preserving short-range dependence.
`evaluate`(axis, y, derivative_order)	Smooth a series and differentiate the smooth.
`evaluate_with_noise`(axis, y, ...)	Evaluate, allowing an adaptive smoother to use a fitted covariance.
`fit`(axis, y[, derivative_order, ...])	Estimate the trend and, optionally, its uncertainty.
`native_posterior`(axis, y, derivative_order, ...)	Uncertainty from the smoother's own probability model.
`operators`(axis, derivative_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`
`uses_noise_for_fit`	Whether a supplied noise model can change the point estimate.
`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.

property uses_noise_for_fit: bool¶: Whether a supplied noise model can change the point estimate.

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

Smooth a series and differentiate the smooth.

Parameters:

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

Returns:

The smoothed values and the derivative.

Return type:

Evaluation

evaluate_with_noise(axis, y, derivative_order, noise)[source]¶

Evaluate, allowing an adaptive smoother to use a fitted covariance.

Parameters:

axis (TimeAxis) – The time axis.
y (npt.NDArray[np.float64]) – Observed values.
derivative_order (int) – Derivative order.
noise (NoiseFit | None) – Fitted covariance, when the caller supplied or requested one.

Returns:

The smoothed values and 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], or None when the configuration has no fixed data-independent scale.
Return type:: float | None

params()[source]¶

Smoother-specific settings, recorded on the result.

Return type:: dict[str, Any]

analytic_operators(axis, derivative_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.
derivative_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, derivative_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.
derivative_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, derivative_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.
derivative_order (int) – Derivative 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, derivative_order=1, with_uncertainty=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.
derivative_order (int) – Derivative derivative_order.
with_uncertainty (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 instance, or 'iid', 'ar1'`, or ``'heteroskedastic'.
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. Fixed linear smoothers only.
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 an argument is outside its domain, the derivative derivative_order is unsupported, bias correction is requested for a nonlinear smoother, or an uncertainty option is incompatible with a native posterior.

Return type:

TrendEstimate

bootstrap_uncertainty(estimate, axis, y, derivative_order, noise_model, noise_fit, confidence_level, n_bootstrap, random_state)[source]¶

Bootstrap a nonlinear smoother, preserving short-range dependence.

Parameters:

estimate (TrendEstimate) – Original fitted result.
axis (TimeAxis) – Time axis.
y (npt.NDArray[np.float64]) – Observed values.
derivative_order (int) – Derivative order.
noise_model (NoiseModel) – Noise model specification.
noise_fit (NoiseFit) – Fitted noise covariance.
confidence_level (float) – Confidence level.
n_bootstrap (int) – Number of replicates.
random_state (int | np.random.Generator | None) – Seed or Generator.

Returns:

Standard errors and percentile interval bounds.

Return type:

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