Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/georgeguimaraes/soothsayer
Elixir library for time series forecasting, inspired by Facebook's Prophet and NeuralProphet
https://github.com/georgeguimaraes/soothsayer
elixir machine-learning neural-networks neuralprophet
Last synced: 3 days ago
JSON representation
Elixir library for time series forecasting, inspired by Facebook's Prophet and NeuralProphet
- Host: GitHub
- URL: https://github.com/georgeguimaraes/soothsayer
- Owner: georgeguimaraes
- License: apache-2.0
- Created: 2024-07-17T12:40:03.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-09-27T00:34:18.000Z (4 months ago)
- Last Synced: 2025-01-15T05:32:29.818Z (10 days ago)
- Topics: elixir, machine-learning, neural-networks, neuralprophet
- Language: Elixir
- Homepage: https://hexdocs.pm/soothsayer
- Size: 90.8 KB
- Stars: 62
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ml-gen-ai-elixir - Soothsayer - Time series forecasting library inspired by Facebook's Prophet and NeuralProphet. (Machine Learning / Traditional Machine Learning)
README
# Soothsayer
Soothsayer is an Elixir library for time series forecasting, inspired by Facebook's Prophet and NeuralProphet. It provides a flexible and easy-to-use interface for creating and training forecasting models.
**Warning:** Soothsayer is currently in alpha stage. The API is unstable and may change at any moment without prior notice. Use with caution in production environments.
## Installation
Add `soothsayer` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:soothsayer, "~> 0.1.0"},
]
end
```
Then run `mix deps.get` to install the dependencies.
## Usage
Here's a basic example of how to use Soothsayer:
```elixir
alias Explorer.DataFrame
alias Explorer.Series
# Create sample data, (or use your own data)
dates = Date.range(~D[2020-01-01], ~D[2022-12-31])
y = Enum.map(dates, fn date ->
day_of_year = Date.day_of_year(date)
trend = 100 + 0.1 * Date.diff(date, ~D[2020-01-01])
seasonality = 10 * :math.sin(2 * :math.pi * day_of_year / 365.25)
trend + seasonality + :rand.normal(0, 5)
end)
df = DataFrame.new(%{
"ds" => dates,
"y" => y
})
# Create and fit the model
model = Soothsayer.new()
fitted_model = Soothsayer.fit(model, df)
# Make predictions
future_dates = Date.range(~D[2023-01-01], ~D[2023-12-31])
predictions = Soothsayer.predict(fitted_model, Series.from_list(Enum.to_list(future_dates)))
# Print the predictions
IO.inspect(predictions)
```
You can also get the components of the forecast:
```elixir
components = Soothsayer.predict_components(fitted_model, Series.from_list(Enum.to_list(future_dates)))
#> %{comboned: ..., trend: ..., yearly_seasonality: ..., weekly_seasonality: ...}
```
### Livebook Example
You can check the `livebook` dir with some examples on how to use Soothsayer.
### Customizing the Model
You can customize various aspects of the model:
```elixir
model = Soothsayer.new(%{
trend: %{enabled: true},
seasonality: %{
yearly: %{enabled: true, fourier_terms: 10},
weekly: %{enabled: false}
},
epochs: 200,
learning_rate: 0.005
})
```
### Using EXLA for Faster Training
Soothsayer can use EXLA (Elixir XLA) for faster training, but it's not the default backend. To use EXLA:
1. Make sure you've added EXLA to your dependencies as shown in the Installation section.
2. Set EXLA as the default backend for Nx. Add the following to your `config/config.exs` file:
```elixir
config :nx, default_backend: EXLA.Backend
```
Alternatively, you can set it at runtime before using Soothsayer:
```elixir
Nx.global_default_backend(EXLA.Backend)
```
## Differences from NeuralProphet
Soothsayer is inspired by NeuralProphet but implemented in Elixir with some key differences:
1. **Elixir Ecosystem**: Soothsayer is built using Elixir and leverages libraries like Explorer for data manipulation and Axon for neural networks.
2. **Simplified Model**: Soothsayer currently offers a more streamlined model with fewer components, focusing on trend and seasonality.
3. **Data Handling**: Soothsayer uses Explorer's DataFrame for data manipulation, which may have different performance characteristics compared to pandas.
4. **Training Process**: The training process in Soothsayer is implemented using Axon and may differ in some aspects from NeuralProphet's PyTorch implementation.
## Features Not Yet Implemented
Soothsayer is a work in progress. The following NeuralProphet features are not yet implemented:
- Auto Regression
- Lagged Regressors
- Future Regressors
- Events and Holidays
- Uncertainty Estimation
- Global and Local Models (models based on geography)
- Multiplicative Seasonality (currently only additive is supported)
- Piecewise Linear Trends (currently only simple linear trend is supported)
- Advanced Regularization Options
- Automatic Changepoint Detection
- Cross-Validation and Hyperparameter Tuning
We plan to implement some of these features in future versions of Soothsayer.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
Soothsayer is released under the Apache License 2.0. See the LICENSE file for details.