## 1. Project Overview & Quickstart (Nixtla/neuralforecast)

## File: README.md

# Nixtla 

[](https://twitter.com/intent/tweet?text=Statistical%20Forecasting%20Algorithms%20by%20Nixtla%20&url=https://github.com/Nixtla/neuralforecast&via=nixtlainc&hashtags=StatisticalModels,TimeSeries,Forecasting)
[](https://join.slack.com/t/nixtlacommunity/shared_invite/zt-1pmhan9j5-F54XR20edHk0UtYAPcW4KQ)



## Installation

You can install `NeuralForecast` with:

```python
pip install neuralforecast
```

or

```python
conda install -c conda-forge neuralforecast
```

Vist our [Installation Guide](https://nixtlaverse.nixtla.io/neuralforecast/docs/getting-started/installation.html) for further details.

## Quick Start

**Minimal Example**

```python
from neuralforecast import NeuralForecast
from neuralforecast.models import NBEATS
from neuralforecast.utils import AirPassengersDF

nf = NeuralForecast(
    models = [NBEATS(input_size=24, h=12, max_steps=100)],
    freq = 'ME'
)

nf.fit(df=AirPassengersDF)
nf.predict()
```

**Get Started with this [quick guide](https://nixtlaverse.nixtla.io/neuralforecast/docs/getting-started/quickstart.html).**

## Why?

There is a shared belief in Neural forecasting methods' capacity to improve forecasting pipeline's accuracy and efficiency.

Unfortunately, available implementations and published research are yet to realize neural networks' potential. They are hard to use and continuously fail to improve over statistical methods while being computationally prohibitive. For this reason, we created `NeuralForecast`, a library favoring proven accurate and efficient models focusing on their usability.

## Features

* Fast and accurate implementations of more than 30 state-of-the-art models. See the entire [collection here](https://nixtlaverse.nixtla.io/neuralforecast/docs/capabilities/overview.html).
* Support for exogenous variables and static covariates.
* Interpretability methods for trend, seasonality and exogenous components.
* Probabilistic Forecasting with adapters for quantile losses and parametric distributions.
* Train and Evaluation Losses with scale-dependent, percentage and scale independent errors, and parametric likelihoods.
* Automatic Model Selection with distributed automatic hyperparameter tuning.
* Familiar sklearn syntax: `.fit` and `.predict`.

## Highlights

* Official `NHITS` implementation, published at AAAI 2023. See [paper](https://ojs.aaai.org/index.php/AAAI/article/view/25854) and [experiments](https://github.com/Nixtla/neuralforecast/tree/main/experiments).
* Official `NBEATSx` implementation, published at the International Journal of Forecasting. See [paper](https://www.sciencedirect.com/science/article/pii/S0169207022000413).
* Unified with`StatsForecast`, `MLForecast`, and `HierarchicalForecast` interface `NeuralForecast().fit(Y_df).predict()`, inputs and outputs.
* Built-in integrations with `utilsforecast` and `coreforecast` for visualization and data-wrangling efficient methods.
* Integrations with `Ray` and `Optuna` for automatic hyperparameter optimization.
* Predict with little to no history using Transfer learning. Check the experiments [here](https://github.com/Nixtla/transfer-learning-time-series).

Missing something? Please open an issue or write us in [](https://join.slack.com/t/nixtlaworkspace/shared_invite/zt-135dssye9-fWTzMpv2WBthq8NK0Yvu6A)

## Examples and Guides

The [documentation page](https://nixtlaverse.nixtla.io/neuralforecast/docs/getting-started/introduction.html) contains all the examples and tutorials.

📈 [Automatic Hyperparameter Optimization](https://nixtlaverse.nixtla.io/neuralforecast/docs/capabilities/hyperparameter_tuning.html): Easy and Scalable Automatic Hyperparameter Optimization with `Auto` models on `Ray` or `Optuna`.

🌡️ [Exogenous Regressors](https://nixtlaverse.nixtla.io/neuralforecast/docs/capabilities/exogenous_variables.html): How to incorporate static or temporal exogenous covariates like weather or prices.

🔌 [Transformer Models](https://nixtlaverse.nixtla.io/neuralforecast/docs/tutorials/longhorizon_transformers.html): Learn how to forecast with many state-of-the-art Transformers models.

👑 [Hierarchical Forecasting](https://nixtlaverse.nixtla.io/neuralforecast/docs/tutorials/hierarchical_forecasting.html): forecast series with very few non-zero observations.

👩‍🔬 [Add Your Own Model](https://nixtlaverse.nixtla.io/neuralforecast/docs/tutorials/adding_models.html): Learn how to add a new model to the library.

## Models

See the entire [collection here](https://nixtlaverse.nixtla.io/neuralforecast/docs/capabilities/overview.html).

Missing a model? Please open an issue or write us in [](https://join.slack.com/t/nixtlaworkspace/shared_invite/zt-135dssye9-fWTzMpv2WBthq8NK0Yvu6A)

## How to contribute

If you wish to contribute to the project, please refer to our [contribution guidelines](https://github.com/Nixtla/neuralforecast/blob/main/CONTRIBUTING.md).

## References

This work is highly influenced by the fantastic work of previous contributors and other scholars on the neural forecasting methods presented here. We want to highlight the work of [Boris Oreshkin](https://arxiv.org/abs/1905.10437), [Slawek Smyl](https://www.sciencedirect.com/science/article/pii/S0169207019301153), [Bryan Lim](https://www.sciencedirect.com/science/article/pii/S0169207021000637), and [David Salinas](https://arxiv.org/abs/1704.04110). We refer to [Benidis et al.](https://arxiv.org/abs/2004.10240) for a comprehensive survey of neural forecasting methods.

## 🙏 How to cite

If you enjoy or benefit from using these Python implementations, a citation to the repository will be greatly appreciated.

```bibtex
@misc{olivares2022library_neuralforecast,
    author={Kin G. Olivares and
            Cristian Challú and
            Azul Garza and
            Max Mergenthaler Canseco and
            Artur Dubrawski},
    title = {{NeuralForecast}: User friendly state-of-the-art neural forecasting models.},
    year={2022},
    howpublished={{PyCon} Salt Lake City, Utah, US 2022},
    url={https://github.com/Nixtla/neuralforecast}
}
```

## Contributors ✨

Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):





| [**azul**](https://github.com/AzulGarza)[💻](https://github.com/Nixtla/neuralforecast/commits?author=AzulGarza) [🚧](#maintenance-AzulGarza) | [**Cristian Challu**](https://github.com/cchallu)[💻](https://github.com/Nixtla/neuralforecast/commits?author=cchallu) [🚧](#maintenance-cchallu) | [**José Morales**](https://github.com/jmoralez)[💻](https://github.com/Nixtla/neuralforecast/commits?author=jmoralez) [🚧](#maintenance-jmoralez) | [**mergenthaler**](https://github.com/mergenthaler)[📖](https://github.com/Nixtla/neuralforecast/commits?author=mergenthaler) [💻](https://github.com/Nixtla/neuralforecast/commits?author=mergenthaler) | [**Kin**](https://github.com/kdgutier)[💻](https://github.com/Nixtla/neuralforecast/commits?author=kdgutier) [🐛](https://github.com/Nixtla/neuralforecast/issues?q=author%3Akdgutier) [🔣](#data-kdgutier) | [**Greg DeVos**](https://github.com/gdevos010)[🤔](#ideas-gdevos010) | [**Alejandro**](https://github.com/alejandroxag)[💻](https://github.com/Nixtla/neuralforecast/commits?author=alejandroxag) |
| --- | --- | --- | --- | --- | --- | --- |
| [**stefanialvs**](http://lavattiata.com)[🎨](#design-stefanialvs) | [**Ikko Ashimine**](https://bandism.net/)[🐛](https://github.com/Nixtla/neuralforecast/issues?q=author%3Aeltociear) | [**vglaucus**](https://github.com/vglaucus)[🐛](https://github.com/Nixtla/neuralforecast/issues?q=author%3Avglaucus) | [**Pietro Monticone**](https://github.com/pitmonticone)[🐛](https://github.com/Nixtla/neuralforecast/issues?q=author%3Apitmonticone) |  |  |  |








This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

---

## File: experiments/long_horizon/README.md

# Long Horizon Forecasting Experiments with NHITS

In these experiments we use `NHITS` on the [ETTh1, ETTh2, ETTm1, ETTm2](https://github.com/zhouhaoyi/ETDataset) benchmark datasets.

| Dataset  | Horizon  | NHITS-MSE  | NHITS-MAE  | TIDE-MSE   | TIDE-MAE   |
|----------|----------|------------|------------|------------|------------|
| ETTh1    | 96       | 0.378      | 0.393      | 0.375      | 0.398      |
| ETTh1    | 192      | 0.427      | 0.436      | 0.412      | 0.422      |
| ETTh1    | 336      | 0.458      | 0.484      | 0.435      | 0.433      |
| ETTh1    | 720      | 0.561      | 0.501      | 0.454      | 0.465      |
|----------|----------|------------|------------|------------|------------|
| ETTh2    | 96       | 0.274      | 0.345      | 0.270      | 0.336      |
| ETTh2    | 192      | 0.353      | 0.401      | 0.332      | 0.380      |
| ETTh2    | 336      | 0.382      | 0.425      | 0.360      | 0.407      |
| ETTh2    | 720      | 0.625      | 0.557      | 0.419      | 0.451      |
|----------|----------|------------|------------|------------|------------|
| ETTm1    | 96       | 0.302      | 0.35       | 0.306      | 0.349      |
| ETTm1    | 192      | 0.347      | 0.383      | 0.335      | 0.366      |
| ETTm1    | 336      | 0.369      | 0.402      | 0.364      | 0.384      |
| ETTm1    | 720      | 0.431      | 0.441      | 0.413      | 0.413      |
|----------|----------|------------|------------|------------|------------|
| ETTm2    | 96       | 0.176      | 0.255      | 0.161      | 0.251      |
| ETTm2    | 192      | 0.245      | 0.305      | 0.215      | 0.289      |
| ETTm2    | 336      | 0.295      | 0.346      | 0.267      | 0.326      |
| ETTm2    | 720      | 0.401      | 0.413      | 0.352      | 0.383      |
|----------|----------|------------|------------|------------|------------|


## Reproducibility

1. Create a conda environment `long_horizon` using the `environment.yml` file.
  ```shell
  conda env create -f environment.yml
  ```

3. Activate the conda environment using 
  ```shell
  conda activate long_horizon
  ```

Alternatively simply installing neuralforecast and datasetsforecast with pip may suffice:
```
pip install git+https://github.com/Nixtla/datasetsforecast.git
pip install git+https://github.com/Nixtla/neuralforecast.git
```

4. Run the experiments for each dataset and each model using with 
- `--horizon` parameter in `[96, 192, 336, 720]`
- `--dataset` parameter in `['ETTh1', 'ETTh2', 'ETTm1', 'ETTm2']`


```shell
python run_nhits.py --dataset 'ETTh1' --horizon 96 --num_samples 20
```

You can access the final forecasts from the `./data/{dataset}/{horizon}_forecasts.csv` file. Example: `./data/ETTh1/96_forecasts.csv`.


## References
-[Cristian Challu, Kin G. Olivares, Boris N. Oreshkin, Federico Garza, Max Mergenthaler-Canseco, Artur Dubrawski (2023). "NHITS: Neural Hierarchical Interpolation for Time Series Forecasting". Accepted at the Thirty-Seventh AAAI Conference on Artificial Intelligence.](https://arxiv.org/abs/2201.12886)

---

## File: experiments/kan_benchmark/README.md

# KAN for Forecasting - Benchmark on M3 and M4 datasets

[Kolmogorov-Arnold Networks](https://arxiv.org/abs/2404.19756) (KANs) is an alternative to the multilayer perceptron (MLP). In this experiment, we assess the performance of KANs in forecasting time series.

We use the M3 and M4 datasets, which represents more than 102 000 unique time series covering yearly, quarterly, monthly, weekly, daily and hourly frequencies.

While KANs reduce the number of parameters by 38% to 92% compared to the MLP, it also rarely performs better than the MLP in time series forecasting tasks. In this benchmark, N-BEATS still performs best across the vast majority of datasets.

The detailed results are shown in the table below.

| Dataset       | Model  | MAE         | sMAPE (%)      | time (s)  |
|---------------|--------|-------------|----------------|-----------|
| M3 - Yearly   | KAN    | 1206        | 9.74           | 23        |
|               | MLP    | 1111        | 8.68           | 9         |
|               | NBEATS | **1027**    | **8.35**       | 11        |
|               | NHITS  | 1087 | 8.36    | 14        |
| M3 - Quarterly| KAN    | 565         | 5.19           | 45        |
|               | MLP    | **540**     | 4.99    | 10        |
|               | NBEATS | 542  | **4.97**       | 26        |
|               | NHITS  | 573         | 5.29           | 26        |
| M3 - Monthly  | KAN    | 676         | 7.55           | 38        |
|               | MLP    | 653  | 7.19           | 20        |
|               | NBEATS | **637**     | 7.11    | 24        |
|               | NHITS  | **637**     | **7.08**       | 35        |
| M4 - Yearly   | KAN    | 875         | 7.20           | 132       |
|               | MLP    | 921         | 7.37           | 51        |
|               | NBEATS | 855  | **6.87**       | 62        |
|               | NHITS  | **852**     | 6.88    | 73        |
| M4 - Quarterly| KAN    | 603         | 5.36           | 121       |
|               | MLP    | 602         | 5.35           | 40        |
|               | NBEATS | **588**     | **5.15**       | 49        |
|               | NHITS  | 591  | 5.19    | 61        |
| M4 - Monthly  | KAN    | 607         | 7.00           | 215       |
|               | MLP    | 594  | 6.80    | 150       |
|               | NBEATS | **584**     | **6.70%**      | 131       |
|               | NHITS  | **584**     | **6.70**       | 173       |
| M4 - Weekly   | KAN    | 341         | 4.70           | 34        |
|               | MLP    | 375         | 5.00%          | 22        |
|               | NBEATS | **313**     | **4.00**       | 18        |
|               | NHITS  | 329  | 4.40    | 21        |
| M4 - Daily    | KAN    | 194         | 1.60           | 53        |
|               | MLP    | 189  | 1.60    | 24        |
|               | NBEATS | **176**     | **1.50**       | 43        |
|               | NHITS  | **176**     | **1.50**       | 51        |
| M4 - Hourly   | KAN    | **267**     | **7.10**       | 33        | 
|               | MLP    | 315         | 7.80           | 10        |
|               | NBEATS | 280  | 7.40    | 18        |
|               | NHITS  | 302         | 6.95           | 23        |


## Reproducibility

1. Create a conda environment `kan_benchmark` using the `environment.yml` file.
  ```shell
  conda env create -f environment.yml
  ```

3. Activate the conda environment using 
  ```shell
  conda activate kan_benchmark
  ```

4. Run the experiments using:
- `--dataset` parameter in `['M3-yearly', 'M3-quarterly', 'M3-monthly', 'M4-yearly', 'M4-quarterly', 'M4-monthly', 'M4-weekly', 'M4-daily', 'M4-hourly']`

```shell
python run_experiment.py --dataset 
```


## References
-[Ziming Liu, Yixuan Wang, Sachin Vaidya, Fabian Ruehle, James Halverson, Marin Soljačić, Thomas Y. Hou, Max Tegmark - "KAN: Kolmogorov-Arnold Networks"](https://arxiv.org/abs/2404.19756)

## 2. Official Technical Reference & Guides (Nixtla/docs)

# Mintlify Starter Kit

Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including

- Guide pages
- Navigation
- Customizations
- API Reference pages
- Use of popular components

### 👩‍💻 Development

Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command

```
npm i mintlify
```

Run the following command at the root of your documentation (where mint.json is)

```
mintlify dev
```

### 😎 Publishing Changes

Changes will be deployed to production automatically after pushing to the default branch.

You can also preview changes using PRs, which generates a preview link of the docs.

#### Troubleshooting

- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
- Page loads as a 404 - Make sure you are running in a folder with `mint.json`