Merge pull request #431 from unit8co/develop

Release v0.10.0

CHANGELOG.md

@@ -4,7 +4,55 @@
 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.9.1...develop)
+[Full Changelog](https://github.com/unit8co/darts/compare/0.10.0...develop)
+
+## [0.10.0](https://github.com/unit8co/darts/tree/0.10.0) (2021-08-13)
+### For users of the library:
+
+**Added:**
+- 🔴 Improvement of the covariates support. Before, some models were accepting a `covariates` (or `exog`) 
+argument, but it wasn't always clear whether this represented "past-observed" or "future-known" covariates. 
+We have made this clearer. Now all covariate-aware models support `past_covariates` and/or `future_covariates` argument 
+in their `fit()` and `predict()` methods, which makes it clear what series is used as a past or future covariate.
+We recommend [this article](https://medium.com/unit8-machine-learning-publication/time-series-forecasting-using-past-and-future-external-data-with-darts-1f0539585993)
+for more informations and examples.
+
+- 🔴 Significant improvement of `RegressionModel` (incl. `LinearRegressionModel` and `RandomForest`).
+These models now support training on multiple (possibly multivariate) time series. They also support both
+`past_covariates` and `future_covariates`. It makes it easier than ever to fit arbitrary regression models (e.g. from
+scikit-learn) on multiple series, to predict the future of a target series based on arbitrary lags of the target and 
+the past/future covariates. The signature of these models changed: It's not using "`exog`" keyword arguments, but
+`past_covariates` and `future_covariates` instead.
+
+- Dynamic Time Warping. There is a brand new `darts.dataprocessing.dtw` submodule that
+implements Dynamic Time Warping between two `TimeSeries`. It's also coming with a new `dtw`
+metric in `darts.metrics`. We recommend going over the 
+[new DTW example notebook](https://github.com/unit8co/darts/blob/master/examples/13-Dynamic-Time-Warping-example.ipynb) 
+for a good overview of the new functionalities
+
+- Conda forge installation support (fully supported with Python 3.7 only for now). You can now
+`conda install u8darts-all`.
+
+- `TimeSeries.from_csv()` allows to obtain a `TimeSeries` from a CSV file directly.
+
+- Optional cyclic encoding of the datetime attributes future covariates; for instance it's now possible to call 
+`my_series.add_datetime_attribute('weekday', cyclic=True)`, which will add two columns containing a sin/cos 
+encoding of the weekday.
+
+- Default seasonality inference in `ExponentialSmoothing`. If left to `None`, the `seasonal_periods` is inferred
+from the `freq` of the provided series.  
+
+- Various documentation improvements.
+
+**Fixed:**
+- Now transformations and forecasting maintain the columns' names of the `TimeSeries`.
+The generation module `darts.utils.timeseries_generation` also comes with better default columns names.
+- Some issues with our Docker build process
+- A bug with GPU usage
+
+**Changed:**
+- For probabilistic PyTorch based models, the generation of multiple samples (and series) at prediction time is now
+vectorized, which improves inference performance.
 
 ## [0.9.1](https://github.com/unit8co/darts/tree/0.9.1) (2021-07-17)
 ### For users of the library:

Dockerfile

@@ -1,26 +1,20 @@
-FROM jupyter/base-notebook:python-3.7.6
+FROM jupyter/base-notebook:python-3.9.5
 
-# By default base-notebook install latest python version and fix it in the pinned constraint
-# remove the file, change the python version and update packages
-
-#RUN rm $CONDA_DIR/conda-meta/pinned
-#RUN conda install python=3.6.8  -y --quiet && conda update --all -y --quiet && \
-#conda clean --all -f -y
-RUN conda install -c conda-forge ipywidgets -y --quiet
+RUN conda update --all -y --quiet \
+ && conda install -c conda-forge ipywidgets -y --quiet \
+ && conda clean --all -f -y
 
 USER root
 
-RUN apt-get update && apt-get -y install curl && apt-get -y install apt-utils
-
-# to build prophet
-RUN apt-get -y install build-essential libc-dev
+# to build pystan
+RUN apt-get update \
+ && apt-get -y install build-essential \
+ && apt-get clean && rm -rf /var/lib/apt/lists/*
 
 USER $NB_USER
 
-# u8ts specific deps
-RUN pip install pystan
 ADD . /home/jovyan/work
 
 WORKDIR /home/jovyan/work
 
-RUN pip install .['all']
+RUN pip install .

README.md

@@ -4,10 +4,11 @@
 
 ---
 [![PyPI version](https://badge.fury.io/py/u8darts.svg)](https://badge.fury.io/py/darts)
-![GitHub Workflow Status](https://img.shields.io/github/workflow/status/unit8co/darts/darts%20release%20workflow/master)
+[![Conda Version](https://img.shields.io/conda/vn/conda-forge/u8darts-all.svg)](https://anaconda.org/conda-forge/u8darts-all)
 ![Supported versions](https://img.shields.io/badge/python-3.7+-blue.svg)
 ![Docker Image Version (latest by date)](https://img.shields.io/docker/v/unit8/darts?label=docker&sort=date)
 ![GitHub Release Date](https://img.shields.io/github/release-date/unit8co/darts)
+![GitHub Workflow Status](https://img.shields.io/github/workflow/status/unit8co/darts/darts%20release%20workflow/master)
 [![Downloads](https://pepy.tech/badge/u8darts)](https://pepy.tech/project/u8darts)
 [![Downloads](https://pepy.tech/badge/darts)](https://pepy.tech/project/darts)
 
@@ -27,6 +28,11 @@ on multiple time series, and some of the models offer probabilistic forecasts.
 * [Introductory Blog Post](https://medium.com/unit8-machine-learning-publication/darts-time-series-made-easy-in-python-5ac2947a8878)
 * [Introductory Video](https://www.youtube.com/watch?v=Sx-uI-PypmU&t=8s&ab_channel=Unit8)
 
+##### Articles on Selected Topics
+* [Training Models on Multiple Time Series](https://medium.com/unit8-machine-learning-publication/training-forecasting-models-on-multiple-time-series-with-darts-dc4be70b1844)
+* [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
 
 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/)).
@@ -35,7 +41,7 @@ Once your environment is set up you can install darts using pip:
 
     pip install darts
 
-For more detailed install instructions you can refer to our installation guide at the end of this page.
+For more detailed install instructions you can refer to our [installation guide](#installation-guide) at the end of this page.
 
 ## Example Usage
 
@@ -95,8 +101,14 @@ from R2-scores to Mean Absolute Scaled Error.
 
 **Backtesting:** Utilities for simulating historical forecasts, using moving time windows.
 
-**Regressive Models:** Possibility to predict a time series from lagged versions of itself
-and of some external covariate series, using arbitrary regression models (e.g. scikit-learn models)
+**Regression Models:** Possibility to predict a time series from lagged versions of itself
+and of some external covariate series, using arbitrary regression models (e.g. scikit-learn models).
+
+**Multiple series training:** All neural networks, as well as `RegressionModel`s (incl. `LinearRegressionModel` and
+`RandomForest`) support being trained on multiple series.
+
+**Past and Future Covariates support:** Some models support past-observed and/or future-known covariate time series
+as inputs for producing forecasts.
 
 **Multivariate Support:** Tools to create, manipulate and forecast multivariate time series.
 
@@ -120,12 +132,12 @@ Model | Univariate | Multivariate | Probabilistic | Multiple-series training | P
 `Theta` and `FourTheta` | x | | | | |
 `Prophet` | x | | | | |
 `FFT` (Fast Fourier Transform) | x | | | | |
-Regression Models (incl `RandomForest` and `LinearRegressionModel`) | x | | | | |
-`RNNModel` (incl. LSTM and GRU); equivalent to DeepAR in its probabilistic version | x | x | x | x | x | x
-`BlockRNNModel` (incl. LSTM and GRU) | x | x | | x | x | ( x )
-`NBEATSModel` | x | x | | x | x | ( x )
-`TCNModel` | x | x | x | x | x | ( x )
-`TransformerModel` | x | x | | x | x | ( 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
@@ -142,16 +154,12 @@ If what you want to tell us is not a suitable github issue, feel free to send us
 
 ## Installation Guide
 
-### Preconditions
-
 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.
 
-The following steps assume running inside a conda environment.
-If that's not possible, first follow the official instructions to install
-[prophet](https://facebook.github.io/prophet/docs/installation.html#python)
-and [torch](https://pytorch.org/get-started/locally/), then skip to
-[Install darts](#install-darts)
+### From conda-forge
+Currently only Python 3.7 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)):
@@ -162,18 +170,18 @@ 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:
 
-#### MAC
-
-    conda install -c conda-forge -c pytorch pip prophet pytorch
-
-#### Linux and Windows
+* Install darts with all available models (recommended): `conda install -c conda-forge u8darts-all`.
+* Install core only (without neural networks, Prophet or AutoARIMA): `conda install -c conda-forge u8darts`
 
-    conda install -c conda-forge -c pytorch pip prophet pytorch cpuonly
 
-### Install darts
+### From PyPI
+Install darts with all available models: `pip install darts`.
 
-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:
@@ -183,6 +191,7 @@ 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]'`
 
+
 ### 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.

build.gradle

@@ -6,8 +6,8 @@ buildscript {
 }
 
 plugins {
-    id "com.palantir.docker" version "0.26.0"
-    id "com.palantir.docker-run" version "0.26.0"
+    id "com.palantir.docker" version "0.27.0"
+    id "com.palantir.docker-run" version "0.27.0"
 }
 
 // needed for palantir plugin
@@ -87,7 +87,7 @@ for(String flavour : flavours) {
 }
 
 task installLocally(type:Exec) {
-    commandLine "pip", "install", ".[all]"
+    commandLine "pip", "install", "."
 }
 
 task pipInstall() {

darts/dataprocessing/dtw/__init__.py

@@ -0,0 +1,3 @@
+from .cost_matrix import CostMatrix
+from .window import Window, NoWindow, Itakura, SakoeChiba, CRWindow
+from .dtw import dtw, DTWAlignment