Merge pull request #463 from unit8co/develop

Release 0.11.0

Author: hrzn

.github/scripts/libomp-Linux.sh

@@ -0,0 +1 @@
+exit 0

.github/scripts/libomp-macOS.sh

@@ -0,0 +1,4 @@
+brew install libomp wget
+wget https://raw.githubusercontent.com/Homebrew/homebrew-core/fb8323f2b170bd4ae97e1bac9bf3e2983af3fdb0/Formula/libomp.rb
+brew unlink libomp
+brew install libomp.rb

.github/workflows/develop.yml

@@ -40,14 +40,18 @@ jobs:
         run: |
           ./gradlew installPipLatest
 
-      - name: "5. Attach cache for pip"
+      - name: "5. Install libomp (for LightGBM)"
+        run: |
+          ./.github/scripts/libomp-${{ runner.os }}.sh
+
+      - name: "6. Attach cache for pip"
         uses: actions/cache@v1
         id: cache
         with:
           path: ~/.cache/pip
           key: tests-${{ runner.os }}-${{ matrix.python-version }}-pip-${{ hashFiles('requirements-latest.txt') }}
 
-      - name: "6. Tests"
+      - name: "7. Tests"
         run: |
           ./gradlew "test_${{matrix.flavour}}"
 

.github/workflows/merge.yml

@@ -41,14 +41,18 @@ jobs:
         run: |
           ./gradlew installPipLatest
 
-      - name: "5. Attach cache for pip"
+      - name: "5. Install libomp (for LightGBM)"
+        run: |
+          ./.github/scripts/libomp-${{ runner.os }}.sh
+
+      - name: "6. Attach cache for pip"
         uses: actions/cache@v1
         id: cache
         with:
           path: ~/.cache/pip
           key: tests-${{ runner.os }}-${{ matrix.python-version }}-pip-${{ hashFiles('requirements-latest.txt') }}
 
-      - name: "6. Tests"
+      - name: "7. Tests"
         run: |
           ./gradlew "test_${{matrix.flavour}}"
 

CHANGELOG.md

@@ -4,9 +4,27 @@
 Darts is still in an early development phase and we cannot always guarantee backwards compatibility. Changes that may **break code which uses a previous release of Darts** are marked with a "🔴".
 
 ## [Unreleased](https://github.com/unit8co/darts/tree/develop)
-[Full Changelog](https://github.com/unit8co/darts/compare/0.10.1...develop)
+[Full Changelog](https://github.com/unit8co/darts/compare/0.11.0...develop)
 
-## [0.10.1](https://github.com/unit8co/darts/tree/0.10.0) (2021-08-19)
+## [0.11.0](https://github.com/unit8co/darts/tree/0.11.0) (2021-09-04)
+### For users of the library:
+
+**Added:**
+- New model: `LightGBMModel` is a new regression model. Regression models allow to predict future values
+of the target, given arbitrary lags of the target as well as past and/or future covariates. `RegressionModel`
+already works with any scikit-learn regression model, and now `LightGBMModel` does the same with LightGBM.
+If you want to activate LightGBM support in Darts, please read the detailed install notes on 
+the [README](https://github.com/unit8co/darts/blob/master/README.md) carefully.
+- Added stride support to gridsearch
+
+**Fixed:**
+- A bug which was causing issues when training on a GPU with a validation set
+- Some issues with custom-provided RNN modules in `RNNModel`.
+- Properly handle `kwargs` in the `fit` function of `RegressionModel`s.
+- Fixed an issue which was causing problems with latest versions of Matplotlib.
+- An issue causing errors in the FFT notebook
+
+## [0.10.1](https://github.com/unit8co/darts/tree/0.10.1) (2021-08-19)
 ### For users of the library:
 
 **Fixed:**

README.md

@@ -33,7 +33,7 @@ on multiple time series, and some of the models offer probabilistic forecasts.
 * [Using Past and Future Covariates](https://medium.com/unit8-machine-learning-publication/time-series-forecasting-using-past-and-future-external-data-with-darts-1f0539585993)
 * [Temporal Convolutional Networks and Forecasting](https://medium.com/unit8-machine-learning-publication/temporal-convolutional-networks-and-forecasting-5ce1b6e97ce4)
 
-## Install
+## Quick Install
 
 We recommend to first setup a clean Python environment for your project with at least Python 3.7 using your favorite tool ([conda](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html "conda-env"), [venv](https://docs.python.org/3/library/venv.html), [virtualenv](https://virtualenv.pypa.io/en/latest/) with or without [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)).
 
@@ -123,35 +123,44 @@ inferences of the underlying states/values.
 Here's a breakdown of the forecasting models currently implemented in Darts. We are constantly working
 on bringing more models and features.
 
-Model | Univariate | Multivariate | Probabilistic | Multiple-series training | Past-observed covariates support | Future-known covariates support
---- | --- | --- | --- | --- | --- | ---
-`ARIMA` | x | | x | | |
-`VARIMA` | x | x | | | |
-`AutoARIMA` | x | | | | |
-`ExponentialSmoothing` | x | | x | | |
-`Theta` and `FourTheta` | x | | | | |
-`Prophet` | x | | | | |
-`FFT` (Fast Fourier Transform) | x | | | | |
-`RegressionModel` (incl `RandomForest` and `LinearRegressionModel`) | x | x | | x | x | x
-`RNNModel` (incl. LSTM and GRU); equivalent to DeepAR in its probabilistic version | x | x | x | x | | x
-`BlockRNNModel` (incl. LSTM and GRU) | x | x | | x | x | 
-`NBEATSModel` | x | x | | x | x | 
-`TCNModel` | x | x | x | x | x | 
-`TransformerModel` | x | x | | x | x | 
-Naive Baselines | x | | | | |
-
-## Contribute
+Model | Univariate | Multivariate | Probabilistic | Multiple-series training | Past-observed covariates support | Future-known covariates support | Reference
+--- | --- | --- | --- | --- | --- | --- | ---
+`ARIMA` | x | | x | | | |
+`VARIMA` | x | x | | | | |
+`AutoARIMA` | x | | | | | |
+`ExponentialSmoothing` | x | | x | | | |
+`Theta` and `FourTheta` | x | | | | | | [Theta](https://robjhyndman.com/papers/Theta.pdf) & [4 Theta](https://github.com/Mcompetitions/M4-methods/blob/master/4Theta%20method.R)
+`Prophet` | x | | | | | | [Prophet repo](https://github.com/facebook/prophet)
+`FFT` (Fast Fourier Transform) | x | | | | | |
+`RegressionModel` (incl `RandomForest`, `LinearRegressionModel` and `LightGBMModel`) | x | x | | x | x | x |
+`RNNModel` (incl. LSTM and GRU); equivalent to DeepAR in its probabilistic version | x | x | x | x | | x | [DeepAR paper](https://arxiv.org/abs/1704.04110)
+`BlockRNNModel` (incl. LSTM and GRU) | x | x | | x | x | |
+`NBEATSModel` | x | x | | x | x | | [N-BEATS paper](https://arxiv.org/abs/1905.10437)
+`TCNModel` | x | x | x | x | x | | [TCN paper](https://arxiv.org/abs/1803.01271), [DeepTCN paper](https://arxiv.org/abs/1906.04397), [blog post](https://medium.com/unit8-machine-learning-publication/temporal-convolutional-networks-and-forecasting-5ce1b6e97ce4)
+`TransformerModel` | x | x | | x | x | | 
+Naive Baselines | x | | | | | |
+
+
+## Community & Contact
+
+Anyone is welcome to join our [Discord server](https://discord.gg/Um3jBTYFsA) to
+ask questions, make proposals, discuss use-cases, and more. If you spot a bug or
+or have a feature request, Github issues are also welcome.
+
+If what you want to tell us is not suitable for Discord or Github, 
+feel free to send us an email at <a href="mailto:[email protected]">[email protected]</a> for 
+darts related matters or <a href="mailto:[email protected]">[email protected]</a> for any other 
+inquiries.
+
+### Contribute
 
 The development is ongoing, and there are many new features that we want to add.
-We welcome pull requests and issues on GitHub.
+We welcome pull requests and issues on Github.
 
-Before working on a contribution (a new feature or a fix), [**check our contribution guidelines**](CONTRIBUTE.md).
+Before working on a contribution (a new feature or a fix),
+ [**check our contribution guidelines**](CONTRIBUTE.md).
 
 
-## Contact Us
-
-If what you want to tell us is not a suitable github issue, feel free to send us an email at <a href="mailto:[email protected]">[email protected]</a> for darts related matters or <a href="mailto:[email protected]">[email protected]</a> for any other inquiries.
-
 ## Installation Guide
 
 Some of the models depend on `prophet` and `torch`, which have non-Python dependencies.
@@ -191,6 +200,25 @@ we also maintain the `u8darts` package, which provides the following alternate l
 * Install core + Facebook Prophet: `pip install 'u8darts[prophet]'`
 * Install core + AutoARIMA: `pip install 'u8darts[pmdarima]'`
 
+### Enabling Support for LightGBM
+
+To enable support for LightGBM in Darts, please follow the 
+[installation instructions](https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html) for your OS.
+
+#### MacOS Issues with LightGBM
+At the time of writing, there is an issue with ``libomp`` 12.0.1 that results in 
+[segmentation fault on Mac OS Big Sur](https://github.com/microsoft/LightGBM/issues/4229). 
+Here's the procedure to downgrade the ``libomp`` library (from the 
+[original Github issue](https://github.com/microsoft/LightGBM/issues/4229#issue-867528353)):
+* [Install brew](https://brew.sh/) if you don't already have it.
+* Install `wget` if you don't already have it : `brew install wget`.
+* Run the commands below:
+```
+wget https://raw.githubusercontent.com/Homebrew/homebrew-core/fb8323f2b170bd4ae97e1bac9bf3e2983af3fdb0/Formula/libomp.rb
+brew unlink libomp
+brew install libomp.rb
+```
+
 
 ### Running the examples only, without installing:
 

darts/dataprocessing/dtw/_plot.py

@@ -155,7 +155,7 @@ def plot_alignment(self,
 
     x_coords[0::3] = x_coords1
     x_coords[1::3] = x_coords2
-    x_coords[2::3] = np.nan
+    x_coords[2::3] = np.datetime64("NaT")
 
     y_coords[0::3] = y_coords1
     y_coords[1::3] = y_coords2

darts/models/__init__.py

@@ -40,6 +40,13 @@
 from .random_forest import RandomForest
 from .regression_model import RegressionModel
 
+try:
+    from .gradient_boosted_model import LightGBMModel
+except:
+    logger.warning("Support for LightGBM not available. To enable LightGBM support in Darts, follow the detailed "
+                   "install instructions for LightGBM in the README: "
+                   "https://github.com/unit8co/darts/blob/master/README.md")
+
 # Ensembling
 from .ensemble_model import EnsembleModel
 from .baselines import NaiveEnsembleModel

darts/models/fft.py

@@ -11,6 +11,7 @@
 from .forecasting_model import ForecastingModel
 from ..timeseries import TimeSeries
 from ..logging import get_logger
+from ..utils.missing_values import fill_missing_values
 
 logger = get_logger(__name__)
 
@@ -195,8 +196,7 @@ def __init__(self,
         This model performs forecasting on a TimeSeries instance using FFT, subsequent frequency filtering
         (controlled by the `nr_freqs_to_keep` argument) and  inverse FFT, combined with the option to detrend
         the data (controlled by the `trend` argument) and to crop the training sequence to full seasonal periods
-        (controlled by the `required_matches` argument).
-        Please note that the training sequence must not contain any NaN values for the model to produce useful output.
+        Note that if the training series contains any NaNs (missing values), these will be filled using `darts.utils.missing_values.fill_missing_values()`.
 
         Examples:
 
@@ -234,6 +234,7 @@ def __str__(self):
         return 'FFT(nr_freqs_to_keep=' + str(self.nr_freqs_to_keep) + ', trend=' + str(self.trend) + ')'
 
     def fit(self, series: TimeSeries):
+        series = fill_missing_values(series)
         super().fit(series)
         series = self.training_series
 

darts/models/forecasting_model.py

@@ -438,6 +438,7 @@ def gridsearch(model_class,
                    past_covariates: Optional[TimeSeries] = None,
                    future_covariates: Optional[TimeSeries] = None,
                    forecast_horizon: Optional[int] = None,
+                   stride: int = 1,
                    start: Union[pd.Timestamp, float, int] = 0.5,
                    last_points_only: bool = False,
                    val_series: Optional[TimeSeries] = None,
@@ -498,6 +499,8 @@ def gridsearch(model_class,
             An optional future-known covariate series. This applies only if the model supports future covariates.
         forecast_horizon
             The integer value of the forecasting horizon used in expanding window mode.
+        stride
+            The number of time steps between two consecutive predictions. Only used in expanding window mode.
         start
             The `int`, `float` or `pandas.Timestamp` that represents the starting point in the time index
             of `training_series` from which predictions will be made to evaluate the model.
@@ -568,6 +571,7 @@ def _evaluate_combination(param_combination):
                                        num_samples=1,
                                        start=start,
                                        forecast_horizon=forecast_horizon,
+                                       stride=stride,
                                        metric=metric,
                                        reduction=reduction,
                                        last_points_only=last_points_only)