muse
Multiple Unobserved Sources of Error State Space Models
Implements the Power / Trend / Seasonal (PTS) model, a unified
state-space framework based on the Multiple Source of Error (MSOE) model. It brings
the trend, seasonal and irregular component models of Harvey (1989)
muse - Multiple Unobserved Sources of Error
R
Python
muse is an R package implementing the PTS (Power / Trend / Seasonal) state-space family of models for time-series analysis and for forecasting. The estimation engine is written in C++ (Rcpp & RcppArmadillo), wrapping a Kalman filter/smoother around a Multiple Source of Error (MSOE) model whose components are selected analogously to the ETS taxonomy.
The package shares conventions with smooth and greybox: the returned object inherits from c("pts", "smooth") so generics such as forecast(), accuracy(), plot(), AIC(), and BIC() work out of the box.
Installation
The package is not yet on CRAN. Install the development version directly from GitHub:
# install.packages("remotes")
remotes::install_github("openforecast-org/muse")
Once released on CRAN:
install.packages("muse")
What's inside
The user-facing entry point is pts(). In a single call it can:
- Specify a PTS model with a compact three-character string
"PTS"— Power / Trend / Seasonal in that order (e.g."ZZZ","0LT","0.5GD")P— power (Box-Cox λ): a numeric value or"Z"to estimate it jointly with the state-space parameters.T— trend:Nnone,Llocal,Ddamped,Gglobal, orZfor automatic selection.S— seasonal:Nnone,Ddiscrete,Ttrigonometric (harmonic seasonality), orZfor automatic selection.
- Auto-select the best model by AIC / BIC / AICc / BICc on the irregular component (
select = TRUEorZletters in the model string). - Estimate jointly with ARMA / SARMA noise on the irregular component (
arma = c(p, q)or a list). - Handle missing values in the response series — they are filtered through the Kalman recursion natively, no imputation required.
- Detect outliers of type AO (additive), LS (level shift), and SC (slope change) during estimation via
outliers = "use"with a user-supplied confidencelevel(e.g.0.99). Detected outliers are reported in the fitted object and added as dummy regressors. - Take external regressors through the
dataargument (adata.frame/ts/matrixwhose first column is the response). - Produce forecasts with prediction, confidence, or simulated intervals through
forecast(). - Simulate trajectories from the fitted model with
simulate()(in-sample replay from the initial state, forward simulation for forecasts). - Hold out and score automatically via
holdout = TRUEplush = ....
The full method list includes print, summary, plot, coef, vcov, confint, sigma, nobs, nparam, logLik, AIC, BIC, fitted, residuals, rstandard, rstudent, pointLik, accuracy, actuals, modelType, lags, orders, errorType, outlierdummy, and update.
Quick start
library(muse)
# Fit a model with automatic Box-Cox, trend, seasonal,
# holding out the last 12 observations and forecasting them back.
model <- pts(AirPassengers, model = "ZZZ", h = 12,
holdout = TRUE, ic = "AICc")
summary(model)
plot(forecast(model, h = 12))
# With engine-side outlier detection at the 99% confidence level
model_out <- pts(AirPassengers, model = "ZZZ", h = 12,
outliers = "use", level = 0.99)
model_out$outliersDetected
Reporting issues
Bug reports and feature requests are welcome at the issue tracker.
Acknowledgements
Parts of the C++ engine refactoring and the Python translation of the package were developed with the assistance of Anthropic's Claude. Responsibility for the code and its correctness rests with the package authors.
About
muse is developed and maintained by OpenForecast, a demand forecasting and inventory management consultancy. The package implements the methods we use in our consulting and teach in our training courses.