state_space library

Exact Gaussian process regression for irregular time series, in linear time.

The prior is a Gaussian process with a Markovian kernel, written as a linear SDE and discretised exactly over each gap, so a Kalman filter and RTS smoother compute the same posterior and log marginal likelihood as the O(N^3) textbook expressions in O(N). With the default LocalLinearTrend the posterior mean is a natural cubic smoothing spline.

final data = [
  Observation(0, 81.3),
  Observation(2, 81.0),   // gaps are not a special case
  Observation(3, 80.5),
  Observation(7, 80.0),
  Observation(8, 80.0),
  Observation(8, 79.8),   // neither are duplicate times
  // ... four weeks of readings in all
];

final fitted = fit(
  StructuralModel.localLinearTrend(processVariance: 1e-3),
  data,
);
print(fitted.warnings);               // empty when the fit is determined
final posterior = fitted.model.smooth(data);
print(posterior.mean);                // the trend
print(posterior.credibleInterval(0)); // and how sure it is

Missing data needs no filling, irregular sampling needs no resampling, and two readings at the same instant need no averaging.

Documentation

Classes

ApproximateDiffuse
A proper prior of variance times the model's measurement variance on every diffuse state.
Coefficient
The posterior of one regression coefficient.
ComplexityPenalty
A penalised-complexity penalty (Simpson et al. 2017) on how much of the data's own spread each component may claim.
Component Components How it works
One additive block of a structural time-series model.
ExactDiffuse
Exact diffuse initialisation: the flat directions are handled exactly, as the limit of an infinitely wide prior, rather than approximated by a wide one (Durbin & Koopman 2012, ch. 5).
FitResult Choosing a model
What StructuralModel fitting returned, together with enough diagnostics to tell a well-determined answer from a shrug.
ForecastResult Getting started
The signal projected past the end of the data.
IndicatorRegressor
One while something is happening, zero otherwise.
Initialization How it works
How the prior on the state at the first time step is specified.
InnovationDiagnostics Choosing a model
What the one-step-ahead prediction errors say about the model that produced them.
LocalLevel Components
A level that follows a Wiener process: d(mu) = sigma dB.
LocalLinearTrend Components
A smoothly varying level whose rate of change is a Wiener process.
Matern Components
A stationary Matérn process: the standard Gaussian process kernel, in state-space form.
NoPenalty
Plain maximum likelihood.
Observation Getting started
A single scalar measurement at a point in time.
ParameterSpec Components
What one entry of a component's parameter vector is, as far as fitting is concerned.
Penalty Choosing a model
A term added to the log-likelihood before it is maximised.
RegressionComponent Components
Coefficients on known columns, estimated as part of the state.
Regressor
One column of a regression design: a known function of time whose coefficient is unknown.
ShapeParameter
A parameter describing shape rather than size: a length scale, a period, a damping factor.
SmoothingResult Getting started
The posterior of a model, evaluated at each requested output time.
StepRegressor
A covariate that changes at known instants and holds its value in between: a dose, an altitude, a training load.
StochasticCycle Components
A damped oscillation whose period is estimated from the data.
StructuralModel Getting started Choosing a model
An additive structural time-series model: a list of components plus observation noise.
TimeAxis Getting started
Converts between calendar dates and times in days since an origin, which is the time unit the components' defaults are chosen for.
TrigonometricSeasonal Components
A repeating pattern of fixed period whose shape drifts over time.
VarianceParameter
A log variance, in squared signal units, and the default for a component that does not say otherwise.

Enums

MaternOrder
How many times the process is differentiable, in the usual nu notation.
ParameterStatus
What became of one parameter during a fit.
SearchStart
Where fit begins its search.

Functions

fit(StructuralModel initial, List<Observation> observations, {double lowerLogRatio = -20, double upperLogRatio = 10, int scanPoints = 25, double tolerance = 1e-4, Penalty? penalty, double? fixedMeasurementVariance, double? minimumMeasurementVariance, SearchStart start = SearchStart.bracketScan}) → FitResult Choosing a model
Estimates a model's variances from observations by maximum marginal likelihood.

Typedefs

Band = ({double hi, double lo})
A central interval, in the units of the observations.
Bands = ({Float64List hi, Float64List lo})
A central interval at every output time, as two arrays of the same length.
LjungBoxResult = ({int degreesOfFreedom, int lags, double pValue, double statistic})
Outcome of a Ljung-Box test for autocorrelation in the residuals.
Span = ({double from, double to})
A half-open interval [from, to) on the time axis.

Exceptions / Errors

NumericalBreakdownException
The recursion reached a covariance that is not positive definite.
StateSpaceException Getting started
A model that cannot produce an answer on the data it was given.
UnderdeterminedModelException
The data does not determine the model: too few observations, or two components that produce the same signal on this data.