Soothsayer is an Elixir library for time series forecasting, inspired by Facebook's Prophet and NeuralProphet.
What is Soothsayer?
Soothsayer decomposes your time series into interpretable components and uses neural networks to learn the patterns. The model equation is:
y(t) = trend(t) + seasonality(t) + ar(t) + events(t)Where:
- trend(t) captures long-term growth or decline
- seasonality(t) captures repeating patterns (yearly, weekly)
- ar(t) captures dependencies on recent values (auto-regression)
- events(t) captures the impact of special occasions (holidays, promotions)
Each component can be enabled or disabled depending on your data.
Why Soothsayer?
- Interpretable: See what each component contributes to the forecast
- Neural network powered: Uses Axon for flexible learning
- Elixir native: Built for the BEAM ecosystem with Nx and Explorer
- Familiar API: If you've used Prophet or NeuralProphet, you'll feel at home
Comparison with NeuralProphet
Soothsayer implements a subset of NeuralProphet's features:
| Feature | Soothsayer | NeuralProphet |
|---|---|---|
| Trend | Yes | Yes |
| Changepoints | Yes | Yes |
| Yearly seasonality | Yes | Yes |
| Weekly seasonality | Yes | Yes |
| Auto-regression (AR) | Yes | Yes |
| Deep AR-Net | Yes | Yes |
| Events | Yes | Yes |
| Lagged regressors | Planned | Yes |
| Future regressors | Planned | Yes |
| Country holidays | Planned | Yes |
| Multiplicative events | Planned | Yes |
| Event regularization | Planned | Yes |
| Recurring events | Planned | Yes |
| Uncertainty estimation | Planned | Yes |
| Multiplicative seasonality | Planned | Yes |
Quick Example
alias Explorer.DataFrame
alias Explorer.Series
# Prepare your data with "ds" (dates) and "y" (values) columns
df = DataFrame.new(%{
"ds" => Date.range(~D[2020-01-01], ~D[2022-12-31]),
"y" => your_values
})
# Create and fit a model
model = Soothsayer.new()
fitted_model = Soothsayer.fit(model, df)
# Make predictions
future_dates = Series.from_list(Date.range(~D[2023-01-01], ~D[2023-12-31]) |> Enum.to_list())
predictions = Soothsayer.predict(fitted_model, future_dates)
# Get individual components
components = Soothsayer.predict_components(fitted_model, future_dates)
# => %{combined: ..., trend: ..., yearly_seasonality: ..., weekly_seasonality: ..., ar: ..., events: ...}Next Steps
- The Basics - Learn the fundamentals with trend and seasonality
- Trends - Piecewise linear trends with changepoint detection
- Seasonality - Yearly and weekly patterns with Fourier terms
- Auto-Regression - Capture dependencies on recent values
- Events - Model holidays, promotions, and special occasions
Resources
- NeuralProphet Documentation - The Python library that inspired Soothsayer
- Prophet Documentation - Facebook's original forecasting library
- Interactive Livebook Tutorial - Run the examples yourself