Merge pull request #313 from unit8co/develop

Develop

.github/workflows/develop.yml

@@ -7,10 +7,11 @@ on:
 
 jobs:
   tests:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8]
+        os: [macos-latest, ubuntu-latest]
+        python-version: [3.7, 3.8, 3.9]
         flavour: ['core', 'all']
 
     steps:
@@ -43,10 +44,10 @@ jobs:
       - name: "1. Clone repository"
         uses: actions/checkout@v2
 
-      - name: "2. Set up Python 3.6"
+      - name: "2. Set up Python 3.8"
         uses: actions/setup-python@v1
         with:
-          python-version: 3.6
+          python-version: 3.8
 
       - name: "3. Install pandoc"
         run: |
@@ -61,7 +62,7 @@ jobs:
         id: cache
         with:
           path: ~/.cache/pip
-          key: tests-${{ runner.os }}-3.6-pip-${{ hashFiles('requirements/core.txt', 'requirements/release.txt') }}
+          key: tests-${{ runner.os }}-3.8-pip-${{ hashFiles('requirements/core.txt', 'requirements/release.txt') }}
 
       - name: "6. Build docs"
         run: |
@@ -76,10 +77,10 @@ jobs:
       - name: "1. Clone repository"
         uses: actions/checkout@v2
 
-      - name: "2. Set up Python 3.7"
+      - name: "2. Set up Python 3.8"
         uses: actions/setup-python@v1
         with:
-          python-version: 3.7
+          python-version: 3.8
 
       - name: "3. Run examples ${{matrix.example-name}}"
         run: |

.github/workflows/merge.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         os: [macos-latest, ubuntu-latest]
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
         flavour: ['core', 'all', 'pmdarima', 'torch', 'fbprophet']
 
     steps:
@@ -48,10 +48,10 @@ jobs:
       - name: "1. Clone repository"
         uses: actions/checkout@v2
 
-      - name: "2. Set up Python 3.7"
+      - name: "2. Set up Python 3.8"
         uses: actions/setup-python@v1
         with:
-          python-version: 3.7
+          python-version: 3.8
 
       - name: "3. Run examples ${{matrix.example-name}}"
         run: |
@@ -64,10 +64,10 @@ jobs:
       - name: "1. Clone repository"
         uses: actions/checkout@v2
 
-      - name: "2. Set up Python 3.6"
+      - name: "2. Set up Python 3.8"
         uses: actions/setup-python@v1
         with:
-          python-version: 3.6
+          python-version: 3.8
 
       - name: "3. Install pandoc"
         run: |
@@ -82,7 +82,7 @@ jobs:
         id: cache
         with:
           path: ~/.cache/pip
-          key: release-${{ runner.os }}-3.6-pip-${{ hashFiles('requirements/core.txt', 'requirements/release.txt') }}
+          key: release-${{ runner.os }}-3.8-pip-${{ hashFiles('requirements/core.txt', 'requirements/release.txt') }}
 
       - name: "6. Build docs"
         run: |

.github/workflows/release.yml

@@ -16,10 +16,10 @@ jobs:
         with:
           fetch-depth: '1'
 
-      - name: "2. Set up Python 3.6"
+      - name: "2. Set up Python 3.8"
         uses: actions/setup-python@v1
         with:
-          python-version: 3.6
+          python-version: 3.8
 
       - name: "3. Update pip"
         run: |
@@ -113,10 +113,10 @@ jobs:
       - name: "1. Clone repository"
         uses: actions/checkout@v2
 
-      - name: "2. Set up Python 3.6"
+      - name: "2. Set up Python 3.8"
         uses: actions/setup-python@v1
         with:
-          python-version: 3.6
+          python-version: 3.8
 
       - name: "3. Install pandoc"
         run: |

CHANGELOG.md

@@ -4,7 +4,40 @@ Darts is still in an early development phase and we cannot always guarantee back
 
 ## [Unreleased](https://github.com/unit8co/darts/tree/develop)
 
-[Full Changelog](https://github.com/unit8co/darts/compare/0.6.0...develop)
+[Full Changelog](https://github.com/unit8co/darts/compare/0.7.0...develop)
+
+
+## [0.7.0](https://github.com/unit8co/darts/tree/0.7.0) (2021-04-14)
+
+[Full Changelog](https://github.com/unit8co/darts/compare/0.6.0...0.7.0)
+### For users of the library:
+
+**Added:**
+- `darts` Pypi package. It is now possible to `pip install darts`. The older name `u8darts` is still maintained
+and provides the different flavours for lighter installs.
+- New forecasting model available: VARIMA (Vector Autoregressive moving average).
+- Support for exogeneous variables in ARIMA, AutoARIMA and VARIMA (optional `exog` parameter in `fit()` and `predict()` 
+methods).
+- New argument `dummy_index` for `TimeSeries` creation. If a series is just composed of a sequence of numbers
+without timestamps, setting this flag will allow to create a `TimeSeries` which uses a "dummy time index" behind the 
+scenes. This simplifies the creation of `TimeSeries` in such cases, and makes it possible to use all forecasting models,
+except those that explicitly rely on dates.
+- New method `TimeSeries.diff()` returning differenced `TimeSeries`.
+- Added an example of `RegressionEnsembleModel` in intro notebook.
+
+**Changed:**
+- Improved N-BEATS example notebook.
+- Methods `TimeSeries.split_before()` and `split_after()` now also accept integer or float arguments (in addition to
+timestamp) for the breaking point (e.g. specify 0.8 in order to obtain a 80%/20% split).
+- Argument `value_cols` no longer has to be provided if not necessary when creating a `TimeSeries` from a `DataFrame`.
+- Update of dependency requirements to more recent versions.
+
+**Fixed:**
+- Fix issue with MAX_TORCH_SEED_VALUE on 32-bit architectures (https://github.com/unit8co/darts/issues/235).
+- Corrected a bug in TCN inference, which should improve accuracy.
+- Fix historical forecasts not returning last point.
+- Fixed bug when calling the `TimeSeries.gaps()` function for non-regular time frequencies.
+- Many small bug fixes.
 
 
 ## [0.6.0](https://github.com/unit8co/darts/tree/0.6.0) (2021-02-02)
@@ -30,9 +63,9 @@ several time series.
 https://github.com/unit8co/darts/blob/master/examples/02-multi-time-series-and-covariates.ipynb
 
 **Changed:**
-🔴 removed the arguments `training_series` and `target_series` in `ForecastingModel`s. Please consult
+- 🔴 removed the arguments `training_series` and `target_series` in `ForecastingModel`s. Please consult
 the API documentation of forecasting models to see the new signatures.
-🔴 removed `UnivariateForecastingModel` and `MultivariateForecastingModel` base classes. This distinction does
+- 🔴 removed `UnivariateForecastingModel` and `MultivariateForecastingModel` base classes. This distinction does
 not exist anymore. Instead, now some models are "global" (can be trained on multiple series) or "local" (they cannot).
 All implementations of `GlobalForecastingModel`s support multivariate time series out of the box, except N-BEATS.
 - Improved the documentation and README.

README.md

@@ -5,18 +5,18 @@
 ---
 [![PyPI version](https://badge.fury.io/py/u8darts.svg)](https://badge.fury.io/py/u8darts)
 ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/unit8co/darts/darts%20release%20workflow/master)
-![Supported versions](https://img.shields.io/badge/python-3.6+-blue.svg)
+![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)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/u8darts)
 ![GitHub Release Date](https://img.shields.io/github/release-date/unit8co/darts)
 
-**darts** is a python library for easy manipulation and forecasting of time series.
-It contains a variety of models, from classics such as ARIMA to neural networks.
+**darts** is a Python library for easy manipulation and forecasting of time series.
+It contains a variety of models, from classics such as ARIMA to deep neural networks.
 The models can all be used in the same way, using `fit()` and `predict()` functions,
 similar to scikit-learn. The library also makes it easy to backtest models,
 and combine the predictions of several models and external regressors. Darts supports both
 univariate and multivariate time series and models, and the neural networks can be trained
-multiple time series.
+on multiple time series.
 
 ## Documentation
 * [Examples & Tutorials](https://unit8co.github.io/darts/examples.html)
@@ -28,11 +28,11 @@ multiple time series.
 
 ## Install
 
-We recommend to first setup a clean python environment for your project with at least python 3.6 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/)).
+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/)).
 
-Once your environment is setup you can install darts using pip:
+Once your environment is set up you can install darts using pip:
 
-    pip install 'u8darts[all]'
+    pip install darts
 
 For more detailed install instructions you can refer to our installation guide at the end of this page.
 
@@ -117,7 +117,7 @@ Before working on a contribution (a new feature or a fix) make sure you can't fi
 1. Create an issue, describe how you would attempt to solve it, and if possible wait for a discussion.
 2. Fork the repository.
 3. Clone the forked repository locally.
-4. Create a clean python env and install requirements with pip: `pip install -r requirements/dev-all.txt`
+4. Create a clean Python env and install requirements with pip: `pip install -r requirements/dev-all.txt`
 5. Create a new branch:
     * Branch off from the **develop** branch.
     * Prefix the branch with the type of update you are making:
@@ -169,10 +169,10 @@ Don't forget to activate your virtual environment
 
 ### Install darts
 
-Install Darts with all available models: `pip install 'u8darts[all]'`.
+Install Darts with all available models: `pip install darts`.
 
 As some models have relatively heavy (or non-Python) dependencies,
-we also provide the following alternate lighter install options: 
+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]'`
@@ -181,7 +181,7 @@ we also provide the following alternate lighter install options:
 
 ### 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.
+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

conda_recipe/environment.yml

@@ -1,6 +1,6 @@
 # conda-specific dependencies for the dev environment
 name: darts-dev
 dependencies:
-  - python>=3.6
+  - python>=3.7
   - conda-build
   - conda-verify

darts/models/__init__.py

@@ -12,6 +12,7 @@
 from .theta import Theta, FourTheta
 from .arima import ARIMA
 from .fft import FFT
+from .varima import VARIMA
 
 try:
     from .auto_arima import AutoARIMA

darts/models/arima.py

@@ -10,48 +10,68 @@
 .. [1] https://wikipedia.org/wiki/Autoregressive_integrated_moving_average
 """
 
-from statsmodels.tsa.arima_model import ARMA as staARMA
-from statsmodels.tsa.arima_model import ARIMA as staARIMA
+from statsmodels.tsa.arima.model import ARIMA as staARIMA
+from typing import Optional, Tuple
 
-from .forecasting_model import ForecastingModel
+from .forecasting_model import ExtendedForecastingModel
 from ..timeseries import TimeSeries
 from ..logging import get_logger
 
 logger = get_logger(__name__)
 
 
-class ARIMA(ForecastingModel):
-    def __init__(self, p: int = 12, d: int = 1, q: int = 0):
+class ARIMA(ExtendedForecastingModel):
+    def __init__(self,
+                 p: int = 12, d: int = 1, q: int = 0,
+                 seasonal_order: Tuple[int, int, int, int] = (0, 0, 0, 0),
+                 trend: Optional[str] = None):
         """ ARIMA
+        ARIMA-type models extensible with exogenous variables and seasonal components.
 
         Parameters
         ----------
         p : int
             Order (number of time lags) of the autoregressive model (AR)
         d : int
-            The order of differentiation; i.e., the number of times the data have had past values subtracted. (I)
+            The order of differentiation; i.e., the number of times the data
+            have had past values subtracted. (I)
         q : int
             The size of the moving average window (MA).
+        seasonal_order: Tuple[int, int, int, int]
+            The (P,D,Q,s) order of the seasonal component for the AR parameters,
+            differences, MA parameters and periodicity
+        trend: str
+            Parameter controlling the deterministic trend. ‘n‘ indicates no trend,
+            ‘c’ a constant term, ‘t’ linear trend in time, and ‘ct’ includes both.
+             Default is ‘c’ for models without integration, and no trend for models with integration.
         """
         super().__init__()
-        self.p = p
-        self.d = d
-        self.q = q
+        self.order = p, d, q
+        self.seasonal_order = seasonal_order
+        self.trend = trend
         self.model = None
 
+
     def __str__(self):
-        return 'ARIMA({},{},{})'.format(self.p, self.d, self.q)
-
-    def fit(self, series: TimeSeries):
-        super().fit(series)
-        series = self.training_series
-        m = staARIMA(series.values(),
-                     order=(self.p, self.d, self.q)) if self.d > 0 else staARMA(series.values(), order=(self.p, self.q))
-        self.model = m.fit(disp=0)
-
-    def predict(self, n):
-        super().predict(n)
-        forecast = self.model.forecast(steps=n)[0]
+        if self.seasonal_order == (0, 0, 0, 0):
+            return f'ARIMA{self.order}'
+        return f'SARIMA{self.order}x{self.seasonal_order}'
+
+    def fit(self, series: TimeSeries, exog: Optional[TimeSeries] = None):
+        super().fit(series, exog)
+        m = staARIMA(
+            self.training_series.values(),
+            exog=exog.values() if exog else None,
+            order=self.order,
+            seasonal_order=self.seasonal_order,
+            trend=self.trend
+        )
+        self.model = m.fit()
+
+    def predict(self, n: int, exog: Optional[TimeSeries] = None):
+        super().predict(n, exog)
+        forecast = self.model.forecast(steps=n,
+                                       exog=exog.values() if exog else None)
         return self._build_forecast_series(forecast)
 
     @property