Feat/improve user guide

README.md

@@ -25,6 +25,7 @@ series, and some of the models offer a rich support for probabilistic forecastin
 
 ## Documentation
 * [Quickstart](https://unit8co.github.io/darts/quickstart/00-quickstart.html)
+* [User Guide](https://unit8co.github.io/darts/userguide.html)
 * [API Reference](https://unit8co.github.io/darts/generated_api/darts.html)
 * [Examples](https://unit8co.github.io/darts/examples.html)
 

docs/source/userguide.rst

@@ -6,25 +6,29 @@ You will find here some more detailed informations about Darts.
 
 **Note:** The user guide is not yet complete and still under construction.
 
-Neural Networks
-===============
-
-Neural Networks (PyTorch-based models)
-
 .. toctree::
    :maxdepth: 2
 
+   userguide/timeseries.md
+
+   userguide/forecasting_overview.md
+
    userguide/torch_forecasting_models.md
-   userguide/performance.md
    userguide/gpu_and_tpu_usage.md
 
+   .. userguide/regression_models.md
 
-Covariates
-==========
+   userguide/covariates.md
+   .. userguide/probabilistic_forecasting.md
 
-Covariates in Darts:
+   .. userguide/ensembling.md
+
+   .. userguide/filtering_models.md
 
-.. toctree::
-   :maxdepth: 1
+   .. userguide/preprocessing_and_pipelines.md
 
-   userguide/covariates.md
+   .. userguide/metrics.md
+
+   .. userguide/hyper_params.md
+
+   userguide/faq.md

docs/userguide/covariates.md

@@ -1,5 +1,6 @@
-# Darts Covariates
-This document was written for darts version 0.15.0.
+# Covariates
+This section was written for darts version 0.15.0 and later.
+
 ## Summary - TL;DR
 In Darts, **covariates** refer to external data that can be used as inputs to models to help improve forecasts.
 In the context of forecasting models, the **target** is the series to be forecasted/predicted, and the
@@ -10,7 +11,7 @@ covariates themselves are not predicted. We distinguish three kinds of covariate
 * **static covariates** are (by definition) covariates constant over time. They are not yet supported in Darts, but we are working on it!
 
 Models in Darts accept `past_covariates` and/or `future_covariates` in their `fit()` and `predict()` methods, depending on their capabilities (some models accept no covariates at all). Both target and covariates must be a `TimeSeries` object. The models will raise an error if covariates were used that are not supported.
-```
+```python
 # create one of Darts' forecasting models
 model = SomeForecastingModel(...)
 
@@ -28,7 +29,7 @@ model.predict(n=12,
 
 If you have several covariate variables that you want to use as past (or future) covariates, you have to `stack()` all of them into a single `past_covariates` (or `future_covariates`) object.
 
-```
+```python
 # stack two TimeSeries with stack()
 past_covariates = past_covariates.stack(other_past_covariates)
 
@@ -39,7 +40,7 @@ past_covariates = concatenate([past_covariates, other_past_covariates], axis=1)
 
 Darts' forecasting models expect one past and/or future covariate series per target series. If you use multiple target series with one of Darts' Global Forecasting Models, you must supply the same number of dedicated covariates to `fit()`.
 
-```
+```python
 # fit using multiple (two) target series
 model.fit(target=[target, target_2],
           past_covariates=[past_covariates, past_covariates_2],
@@ -56,7 +57,7 @@ model.predict(n=12,
 
 If you train a model using `past_covariates`, you'll have to provide these `past_covariates` also at prediction time to `predict()`. This applies to `future_covariates` too, with a nuance that `future_covariates` have to extend far enough into the future at prediction time (all the way to the forecast horizon `n`). This can be seen in the graph below. `past_covariates` needs to include at least the same time steps as `target`, and `future_covariates` must include at least the same time span plus additional `n` forecast horizon time steps.
 
-***You can use the same `*_covariates` for both training and prediction, given that they contain the required time spans.***
+**You can use the same `*_covariates` for both training and prediction, given that they contain the required time spans.**
 
 ![figure0](./images/covariates/top_level.png)
 
@@ -68,25 +69,12 @@ trained with past covariates to make forecasts for some horizon `n > output_chun
 are known far enough into the future. In such cases, the forecasts are obtained by consuming future values
 of the past covariates, and using auto-regression on the target series. If you want to know more details, read on.
 
--------
-
-## Content of this document
-
-[Section 1](#1-introduction---what-are-covariates-in-darts) Gives an introduction to covariates in Darts
-
-[Section 2](#2-using-covariates-with-darts-forecasting-models) Explains everything you need to know about how to use covariates with Darts' Forecasting Models
-- covariate support for each forecasting model
-- quick guide on how to use covariates with Darts' forecasting models
-- time span requirements for covariates
-- examples
 
------
-
-## 1. Introduction - What are covariates (in Darts)?
+## Introduction - What are covariates (in Darts)?
 Covariates provide additional information/context that can be useful to improve the prediction of the `target` series. The `target` series is the variable we wish to predict the future for. We do not predict the covariates themselves, only use them for prediction of the `target`.
 
 Covariates can hold information about the past (upto and including present time) or future. This is always relative to the prediction point (in time) after which we want to forecast the future.
-In Darts, we refer to these two types as `past_covariates` and `future_covariates`. Darts' forecasting models have different support modes for `*_covariates`. Some do not support covariates at all, others support either past or future covariates and some support both (more on that in [section 2.1.](#21-forecasting-model-covariate-support)).
+In Darts, we refer to these two types as `past_covariates` and `future_covariates`. Darts' forecasting models have different support modes for `*_covariates`. Some do not support covariates at all, others support either past or future covariates and some support both (more on that in [this subsection](#forecasting-model-covariate-support)).
 
 Let's have a look at some examples of past and future covariates:
 - `past_covariates`: typically measurements (past data) or temporal attributes
@@ -106,9 +94,8 @@ You might imagine cases where you want to train a model supporting only `past_co
 
 Side note: if you don't have future values (e.g. of measured temperatures), nothing prevents you from applying one of Darts' forecasting models to forecast future temperatures, and then use this as `future_covariates`. Darts is not attempting to forecast the covariates for you, as this would introduce an extra "hidden" modeling step, which we think is best left to the users.
 
-## 2. Using Covariates With Darts' Forecasting Models
 
-## 2.1. Forecasting Model Covariate Support
+## Forecasting Model Covariate Support
 Darts' forecasting models accept optional `past_covariates` and / or `future_covariates` in their `fit()` and `predict()` methods, depending on their capabilities. Table 1 shows the supported covariate types for each model. The models will raise an error if covariates were used that are not supported.
 
 ### Local Forecasting Models (LFMs):
@@ -138,7 +125,7 @@ Model | Past Covariates | Future Covariates
 `TransformerModel` | ✅ |
 `TFTModel` | ✅ | ✅
 
-#### Table 1: Darts' forecasting models and their covariate support
+**Table 1: Darts' forecasting models and their covariate support**
 
 
 `*` `RegressionModel` including `RandomForest`, `LinearRegressionModel` and `LightGBMModel`. `RegressionModel` is a
@@ -151,14 +138,14 @@ and past targets to do predictions.
 
 ----
 
-## 2.2. Quick guide on how to use covariates with Darts' forecasting models
+## Quick guide on how to use covariates with Darts' forecasting models
 It is very simple to use covariates with Darts' forecasting models. There are just some requirements they have to fulfill.
 
-Just like the `target` series, each of your past and / or future covariates series must be a `TimeSeries` object. When you train your model with `fit()` using past and /or future covariates, you have to supply the same types of covariates to `predict()`. Depending on the choice of your model and how long your forecast horizon `n` is, there might be different time span requirements for your covariates. You can find these requirements in the next [section 2.3.](#23-covariate-time-span-requirements-for-local-and-global-forecasting-models).
+Just like the `target` series, each of your past and / or future covariates series must be a `TimeSeries` object. When you train your model with `fit()` using past and /or future covariates, you have to supply the same types of covariates to `predict()`. Depending on the choice of your model and how long your forecast horizon `n` is, there might be different time span requirements for your covariates. You can find these requirements in the [next subsection](#covariate-time-span-requirements-for-local-and-global-forecasting-models).
 
-***You can even use the same `*_covariates` for fitting and prediction if they contain the required time spans. This is because Darts will "intelligently" slice them for you based on the target time axis.***
+**You can even use the same `*_covariates` for fitting and prediction if they contain the required time spans. This is because Darts will "intelligently" slice them for you based on the target time axis.**
 
-```
+```python
 # create one of Darts' forecasting model
 model = SomeForecastingModel(...)
 
@@ -176,17 +163,17 @@ pred = model.predict(n=1,
 
 To use multiple past and / or future covariates with your `target`, you have to stack them all together into a single dedicated `TimeSeries`:
 
-```
+```python
 # stack() time series
 past_covariates = past_covariates.stack(past_covariates2)
 
 # or concatenate()
 from darts import concatenate
 past_covariates = concatenate([past_covariates, past_covariates2, ...], axis=1)
 ```
-GFMs can be trained on multiple `target` series. You have to supply one covariate TimeSeries per `target` TimeSeries you use with `fit()`. At prediction time you have to specify which `target` series you want to predict and supply the corresponding covariates:
 
-```
+GFMs can be trained on multiple `target` series. You have to supply one covariate TimeSeries per `target` TimeSeries you use with `fit()`. At prediction time you have to specify which `target` series you want to predict and supply the corresponding covariates:
+```python
 from darts.models import NBEATSModel
 
 # multiple time series
@@ -204,7 +191,7 @@ pred = model.predict(n=1,
                      past_covariates=all_past_covariates[0])
 ```
 
-## 2.3. Covariate time span requirements for Local and Global Forecasting Models
+## Covariate time span requirements for Local and Global Forecasting Models
 
 There are differences in how Darts' "Local" and "Global" Forecasting Models perform training and prediction. Specifically, how they extract/work with the data supplied during fit() and predict().
 
@@ -222,7 +209,8 @@ GFMs train and predict on fixed-length chunks (sub-samples) of the `target` and
 
 Depending on your forecast horizon `n`, the model can either predict in one go, or auto-regressively, by predicting on multiple chunks in the future. That is the reason why when predicting with `past_covariates` you have to supply additional "future values of your `past_covariates`".
 
-*Time span requirements to use the same past and / or covariates series for both `fit()` and `predict()`:*
+**Time span requirements to use the same past and / or future covariates series for both `fit()` and `predict()`:**
+
 - with `n <= output_chunk_length`:
   - `past_covariates`: **at least** the same time span as `target`
   - `future_covariates`: **at least** the same time span as `target` plus the next `output_chunk_length` time steps after the end of `target`
@@ -232,9 +220,8 @@ Depending on your forecast horizon `n`, the model can either predict in one go,
 
 If you want to know more details about how covariates are used behind the scenes in Global Forecasting Models, read our [guide on Torch Forecasting Models](https://unit8co.github.io/darts/userguide/torch_forecasting_models.html) (PyTorch based GFMs). It gives a step-by-step explanation of the training and prediction process using one of our Torch Forecasting Models.
 
-## 2.4. Examples
-We have lots of great examples showcasing how to use covariates with Darts' forecasting models.
-Here are a few of those:
+## Examples
+Here are a few examples showcasing how to use covariates with Darts forecasting models:
 
 - [Past covariates with GFMs](https://unit8co.github.io/darts/examples/01-multi-time-series-and-covariates.html#Covariates-Series)
 - [Past and future covariates with TFTModel](https://unit8co.github.io/darts/examples/13-TFT-examples.html#Training)

docs/userguide/faq.md

@@ -0,0 +1,33 @@
+# Frequently Asked Questions
+
+- *Is Darts just a wrapper around other libraries?*
+
+  No. When it makes sense, we reuse existing implementations (e.g. from statsforecasts), but we often write our 
+  own implementations (e.g., of neural networks). Furthermore, Darts models often have more features than their original counter-parts. For instance, unlike the original version, our implementation of N-BEATS supports multivariate time series, past covariates, and probabilistic forecasts.
+
+- *Darts looks like an awesome project, can I contribute?*
+
+  Absolutely! We are constantly welcoming contributions from the community. If you contribute, you will be acknowledged in the [wall of fame (a.k.a the changelog)](https://github.com/unit8co/darts/blob/master/CHANGELOG.md)! Contributions don't have to be code only but can also be e.g., documentation. In addition, we're also happy to receive suggestions in the form of issues on Github. The best place to start for contributors is the [contribution guidelines](https://github.com/unit8co/darts/blob/master/CONTRIBUTING.md).
+
+- *I have some ideas for contributing a new model into Darts, is that possible?*
+
+  In general, yes, we do welcome reference implementations of new models. However, we are loosely filtering to keep models that are either classics, or convincingly shown (e.g., in a paper or some other forms of evidence) to be state-of-the-art in some respect.
+
+- *How can I make Darts work on Google Colab?*
+
+  Colab may have issues with recent versions of pyyaml. Installing pyyaml 5.4.1 before installing Darts solves these issues:
+  ```
+  !pip install pyyaml==5.4.1
+  ```
+
+- *I'm getting some NaNs in my forecasts, what should I do?*
+
+  Usually this means one of two things:
+  - You have some NaNs in your training data (targets or covariates). This is the most frequent situation, and it will lead most models
+    to always forecast NaNs.
+  - Training the model causes some numerical divergence. If you're working with neural networks, make sure your data is properly scaled, and if the issue
+    persists, try reducing the learning rate.
+
+- *My forecasting models give bad results, can you help?*
+
+  Getting good forecasts is about more than just calling the `fit()`/`predict()` functions, and always involves some data science work to understand which approaches are appropriate. We cannot give general answers, however if you have important forecasting problems or need help to industrialize your forecasts, Unit8 provides technical consulting. <a href="mailto:info@unit8.co">Feel free to contact us</a>.