Release 0.18.0 (#867)

* bump u8darts

* update contribution guidelines

* update changelog

* separate install page

* update readme

Author: hrzn

CHANGELOG.md

@@ -4,7 +4,41 @@
 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/master)
-[Full Changelog](https://github.com/unit8co/darts/compare/0.17.1...master)
+[Full Changelog](https://github.com/unit8co/darts/compare/0.18.0...master)
+
+## [0.18.0](https://github.com/unit8co/darts/tree/0.17.1) (2022-03-22)
+### For users of the library:
+
+**Improved**
+- `LinearRegressionModel` and `LightGBMModel` can now be probabilistic, supporting quantile
+  and poisson regression. [#831](https://github.com/unit8co/darts/pull/831), 
+  [#853](https://github.com/unit8co/darts/pull/853) by [Gian Wiher](https://github.com/gnwhr).
+- New models: `BATS` and `TBATS`, based on [tbats](https://github.com/intive-DataScience/tbats).
+  [#816](https://github.com/unit8co/darts/pull/816) by [Julien Herzen](https://github.com/hrzn).
+- Handling of stochastic inputs in PyTorch based models. [#833](https://github.com/unit8co/darts/pull/833)
+  by [Julien Herzen](https://github.com/hrzn).
+- GPU and TPU user guide. [#826](https://github.com/unit8co/darts/pull/826)
+  by [@gsamaras](https://github.com/gsamaras).
+- Added train and validation loss to PyTorch Lightning progress bar.
+  [#825](https://github.com/unit8co/darts/pull/825) by [Dennis Bader](https://github.com/dennisbader).
+- More losses available in `darts.utils.losses` for PyTorch-based models: 
+  `SmapeLoss`, `MapeLoss` and `MAELoss`. [#845](https://github.com/unit8co/darts/pull/845)
+  by [Julien Herzen](https://github.com/hrzn).
+- Improvement to the seasonal decomposition [#862](https://github.com/unit8co/darts/pull/862).
+  by [Gian Wiher](https://github.com/gnwhr).
+- The `gridsearch()` method can now return best metric score.
+  [#822](https://github.com/unit8co/darts/pull/822) by [@nlhkh](https://github.com/nlhkh).
+- Removed needless checkpoint loading when predicting. [#821](https://github.com/unit8co/darts/pull/821)
+  by [Dennis Bader](https://github.com/dennisbader).
+- Changed default number of epochs for validation from 10 to 1.
+  [#825](https://github.com/unit8co/darts/pull/825) by [Dennis Bader](https://github.com/dennisbader).
+
+**Fixed**
+- Fixed some issues with encoders in `fit_from_dataset()`.
+  [#829](https://github.com/unit8co/darts/pull/829) by [Julien Herzen](https://github.com/hrzn).
+- Fixed an issue with covariates slicing for `DualCovariatesForecastingModels`.
+  [#858](https://github.com/unit8co/darts/pull/858) by [Dennis Bader](https://github.com/dennisbader).
+
 
 ## [0.17.1](https://github.com/unit8co/darts/tree/0.17.1) (2022-02-17)
 Patch release
@@ -13,9 +47,13 @@ Patch release
 **Fixed**
 - Fixed issues with (now deprecated) `torch_device_str` parameter, and improved documentation
   related to using devices with PyTorch Lightning. [#806](https://github.com/unit8co/darts/pull/806)
+  by [Dennis Bader](https://github.com/dennisbader).
 - Fixed an issue with `ReduceLROnPlateau`. [#806](https://github.com/unit8co/darts/pull/806)
+  by [Dennis Bader](https://github.com/dennisbader).
 - Fixed an issue with the periodic basis functions of N-BEATS. [#804](https://github.com/unit8co/darts/pull/804)
-- Relaxed requirements for `pandas`; from `pandas>=1.1.0` to `pandas>=1.0.5`. [#800](https://github.com/unit8co/darts/pull/800)
+  by [Vladimir Chernykh](https://github.com/vladimir-chernykh).
+- Relaxed requirements for `pandas`; from `pandas>=1.1.0` to `pandas>=1.0.5`. 
+  [#800](https://github.com/unit8co/darts/pull/800) by [@adelnick](https://github.com/adelnick).
 
 
 ## [0.17.0](https://github.com/unit8co/darts/tree/0.17.0) (2022-02-15)
@@ -25,41 +63,54 @@ Patch release
 - 🚀 Support for [PyTorch Lightning](https://github.com/PyTorchLightning/pytorch-lightning): All deep learning
   models are now implemented using PyTorch Lightning. This means that many more features are now available
   via PyTorch Lightning trainers functionalities; such as tailored callbacks, or multi-GPU training.
-  [#702](https://github.com/unit8co/darts/pull/702)
+  [#702](https://github.com/unit8co/darts/pull/702) by [Dennis Bader](https://github.com/dennisbader).
 - The `RegressionModel`s now accept an `output_chunk_length` parameter; meaning that they can be trained to
   predict more than one time step in advance (and used auto-regressively to predict on longer horizons).
-  [#761](https://github.com/unit8co/darts/pull/761)
+  [#761](https://github.com/unit8co/darts/pull/761) by [Dustin Brunner](https://github.com/brunnedu).
 - 🔴 `TimeSeries` "simple statistics" methods (such as `mean()`, `max()`, `min()` etc, ...) have been refactored
   to work natively on stochastic `TimeSeries`, and over configurable axes. [#773](https://github.com/unit8co/darts/pull/773)
+  by [Gian Wiher](https://github.com/gnwhr).
 - 🔴 `TimeSeries` now support only pandas `RangeIndex` as an integer index, and does not support `Int64Index` anymore,
   as it became deprecated with pandas 1.4.0. This also now brings the guarantee that `TimeSeries` do not have missing
   "dates" even when indexed with integers. [#777](https://github.com/unit8co/darts/pull/777)
+  by [Julien Herzen](https://github.com/hrzn).
 - New model: `KalmanForecaster` is a new probabilistic model, working on multivariate series, accepting future covariates,
   and which works by running the state-space model of a given Kalman filter into the future. The `fit()` function uses the
   N4SID algorithm for system identification. [#743](https://github.com/unit8co/darts/pull/743)
+  by [Julien Herzen](https://github.com/hrzn).
 - The `KalmanFilter` now also works on `TimeSeries` containing missing values. [#743](https://github.com/unit8co/darts/pull/743)
+  by [Julien Herzen](https://github.com/hrzn).
 - The estimators (forecasting and filtering models) now also return their own instance when calling `fit()`,
   which allows chaining calls. [#741](https://github.com/unit8co/darts/pull/741)
+  by [Julien Herzen](https://github.com/hrzn).
 
 
 **Fixed**
-- Fixed an issue with tensorboard and gridsearch when `model_name` is provided. [#759](https://github.com/unit8co/darts/issues/759)
+- Fixed an issue with tensorboard and gridsearch when `model_name` is provided. 
+  [#759](https://github.com/unit8co/darts/issues/759) by [@gdevos010](https://github.com/gdevos010).
 - Fixed issues with pip-tools. [#762](https://github.com/unit8co/darts/pull/762)
+  by [Tomas Van Pottelbergh](https://github.com/tomasvanpottelbergh).
 
 ### For developers of the library:
 - Some linting checks have been added to the CI pipeline. [#749](https://github.com/unit8co/darts/pull/749)
+  by [Tomas Van Pottelbergh](https://github.com/tomasvanpottelbergh).
 
 ## [0.16.1](https://github.com/unit8co/darts/tree/0.16.1) (2022-01-24)
 Patch release
 
 ### For users of the library:
 - Fixed an incompatibility with latest version of Pandas ([#752](https://github.com/unit8co/darts/pull/752))
-- Fixed non contiguous error when using lstm_layers > 1 on gpu ([#740](https://github.com/unit8co/darts/pull/740))
+  by [Julien Herzen](https://github.com/hrzn).
+- Fixed non contiguous error when using lstm_layers > 1 on GPU. ([#740](https://github.com/unit8co/darts/pull/740))
+  by [Dennis Bader](https://github.com/dennisbader).
 - Small improvement in type annotations in API documentation ([#744](https://github.com/unit8co/darts/pull/744))
+  by [Dustin Brunner](https://github.com/brunnedu).
 
 ### For developers of the library:
 - Added flake8 tests to CI pipelines ([#749](https://github.com/unit8co/darts/pull/749),
   [#748](https://github.com/unit8co/darts/pull/748), [#745](https://github.com/unit8co/darts/pull/745))
+  by [Tomas Van Pottelbergh](https://github.com/tomasvanpottelbergh)
+  and [Dennis Bader](https://github.com/dennisbader).
 
 
 ## [0.16.0](https://github.com/unit8co/darts/tree/0.16.0) (2022-01-13)

CONTRIBUTING.md

@@ -52,7 +52,13 @@ and discuss it with some of the core team.
 8. Verify your tests coverage by running `./gradlew coverageTest`
     * Additionally you can generate an xml report and use VSCode Coverage gutter to identify untested
     lines with `./coverage.sh xml`
-9. If your contribution introduces a significant change, add it to `CHANGELOG.md` under the "Unreleased" section.
+9. If your contribution introduces a non-negligible change, add it to `CHANGELOG.md` under the "Unreleased" section.
+   You can already refer to the pull request. In addition, for tracking contributions we are happy if you provide 
+   your full name (if you want to) and link to your Github handle. Example:
+   ```
+   - Added new feature XYZ. [#001](https://https://github.com/unit8co/darts/pull/001)
+     by [<Your Name>](https://github.com/<your-handle>).
+   ```
 10. Create a pull request from your new branch into the **master** branch.
 
 

INSTALL.md

@@ -0,0 +1,100 @@
+# Installation Guide
+
+Some of the models depend on `prophet` and `torch`, which have non-Python dependencies.
+A Conda environment is thus recommended because it will handle all of those in one go.
+
+## From conda-forge
+Currently only the x86_64 architecture with Python 3.7-3.9
+is fully supported with conda; consider using PyPI if you are running into troubles.
+
+To create a conda environment for Python 3.7
+(after installing [conda](https://docs.conda.io/en/latest/miniconda.html)):
+
+    conda create --name <env-name> python=3.7
+
+Don't forget to activate your virtual environment
+
+    conda activate <env-name>
+
+As some models have relatively heavy dependencies, we provide two conda-forge packages:
+
+* Install darts with all available models (recommended): `conda install -c conda-forge -c pytorch u8darts-all`.
+* Install core + neural networks (PyTorch): `conda install -c conda-forge -c pytorch u8darts-torch`
+* Install core only (without neural networks, Prophet or AutoARIMA): `conda install -c conda-forge u8darts`
+
+For GPU support, please follow the instructions to install CUDA in the [PyTorch installation guide](https://pytorch.org/get-started/locally/).
+
+
+## From PyPI
+Install darts with all available models: `pip install darts`.
+
+If this fails on your platform, please follow the official installation guides for
+[prophet](https://facebook.github.io/prophet/docs/installation.html#python)
+and [torch](https://pytorch.org/get-started/locally/), then try installing Darts again.
+
+As some models have relatively heavy (or non-Python) dependencies,
+we also maintain the `u8darts` package, which provides the following alternate lighter install options:
+
+* Install core only (without neural networks, Prophet or AutoARIMA): `pip install u8darts`
+* Install core + neural networks (PyTorch): `pip install "u8darts[torch]"`
+* 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:
+
+If the conda setup is causing too many problems, we also provide a Docker image with everything set up for you and ready-to-use Python notebooks with demo examples.
+To run the example notebooks without installing our libraries natively on your machine, you can use our Docker image:
+```bash
+./gradlew docker && ./gradlew dockerRun
+```
+
+Then copy and paste the URL provided by the docker container into your browser to access Jupyter notebook.
+
+For this setup to work you need to have a Docker service installed. You can get it at [Docker website](https://docs.docker.com/get-docker/).
+
+
+## Tests
+
+The gradle setup works best when used in a python environment, but the only requirement is to have `pip` installed for Python 3+
+
+To run all tests at once just run
+```bash
+./gradlew test_all
+```
+
+alternatively you can run
+```bash
+./gradlew unitTest_all # to run only unittests
+./gradlew coverageTest # to run coverage
+./gradlew lint         # to run linter
+```
+
+To run the tests for specific flavours of the library, replace `_all` with `_core`, `_prophet`, `_pmdarima` or `_torch`.
+
+## Documentation
+
+To build documentation locally just run
+```bash
+./gradlew buildDocs
+```
+After that docs will be available in `./docs/build/html` directory. You can just open `./docs/build/html/index.html` using your favourite browser.