to v0.6.0 with BasicForecaster

Author: thierrymoudiki

.DS_Store

@@ -106,3 +106,6 @@ ENV/
 
 # R artifacts
 R-package/.Rproj.*
+
+# Apple stuff
+.DS_Store

.gitignore

@@ -9,12 +9,13 @@ Welcome to __ahead__ (Python version; the R version is [here](https://github.com
 
 `ahead` is a package for univariate and multivariate **time series forecasting**. The Python version is built on top of [the R package](https://techtonique.github.io/ahead/) with the same name. __ahead__'s source code is [available on GitHub](https://github.com/Techtonique/ahead_python).
 
-Currently, 5 forecasting methods are implemented in the Python package:
+Currently, 6 forecasting methods are implemented in the Python package:
 
 - `DynamicRegressor`: **univariate** time series forecasting method adapted from [`forecast::nnetar`](https://otexts.com/fpp2/nnetar.html#neural-network-autoregression). 
 The Python implementation contains only the [automatic version](https://thierrymoudiki.github.io/blog/2021/10/22/r/misc/ahead-ridge).
 - `EAT`: **univariate** time series forecasting method based on combinations of R's `forecast::ets`, `forecast::auto.arima`, and `forecast::thetaf`
 - `ArmaGarch`: **univariate** forecasting simulations of an ARMA(1, 1)-GARCH(1, 1)
+- `BasicForecaster`: **multivariate** time series forecasting methods; mean, median and random walk
 - `Ridge2Regressor`: **multivariate** time series forecasting method, based on __quasi-randomized networks__ and presented in [this paper](https://www.mdpi.com/2227-9091/6/1/22)
 - `VAR`: **multivariate** time series forecasting method using Vector AutoRegressive model (VAR, mostly here for benchmarking purpose)
 

README.md

@@ -0,0 +1,216 @@
+import os
+import numpy as np
+import pandas as pd
+
+from rpy2.robjects.packages import importr
+from rpy2.robjects import FloatVector, numpy2ri
+import rpy2.robjects as robjects
+import rpy2.robjects.packages as rpackages
+from datetime import datetime
+from rpy2.robjects.vectors import StrVector
+
+from ..utils import multivariate as mv
+from ..utils import unimultivariate as umv
+
+required_packages = ["ahead"]  # list of required R packages
+
+if all(rpackages.isinstalled(x) for x in required_packages):
+    check_packages = True  # True if packages are already installed
+else:
+    check_packages = False  # False if packages are not installed
+
+if check_packages == False:  # Not installed? Then install.
+
+    packages_to_install = [
+        x for x in required_packages if not rpackages.isinstalled(x)
+    ]
+
+    if len(packages_to_install) > 0:
+        base = importr("base")
+        utils = importr("utils")
+        base.options(
+            repos=base.c(
+                techtonique="https://techtonique.r-universe.dev",
+                CRAN="https://cloud.r-project.org",
+            )
+        )
+        utils.install_packages(StrVector(packages_to_install))
+        check_packages = True
+
+base = importr("base")
+stats = importr("stats")
+ahead = importr("ahead")
+
+
+class BasicForecaster(object):
+    """Basic forecasting functions for multivariate time series (mean, median, random walk)
+
+    Parameters:
+
+        h: an integer;
+            forecasting horizon
+
+        level: an integer;
+            Confidence level for prediction intervals
+
+        method: a string;
+            Forecasting method, either "mean", "median", or random walk ("rw")    
+
+        type_pi: a string;
+            Type of prediction interval (currently "gaussian",
+            or "bootstrap")
+
+        B: an integer;
+            Number of bootstrap replications for `type_pi == bootstrap`
+
+        date_formatting: a string;
+            Currently:
+            - "original": yyyy-mm-dd
+            - "ms": milliseconds
+
+        seed: an integer;
+            reproducibility seed for type_pi == 'bootstrap'
+
+    Attributes:
+
+        fcast_: an object;
+            raw result from fitting R's `ahead::ridge2f` through `rpy2`
+
+        averages_: a list of lists;
+            mean forecast in a list for each series
+
+        ranges_: a list of lists;
+            lower and upper prediction intervals in a list for each series
+
+        output_dates_: a list;
+            a list of output dates (associated to forecast)
+
+        mean_: a numpy array
+            contains series mean forecast as a numpy array 
+
+        lower_: a numpy array 
+            contains series lower bound forecast as a numpy array   
+
+        upper_: a numpy array 
+            contains series upper bound forecast as a numpy array   
+
+        result_dfs_: a tuple of data frames;
+            each element of the tuple contains 3 columns,
+            mean forecast, lower + upper prediction intervals,
+            and a date index
+
+        sims_: currently a tuple of numpy arrays
+            for `type_pi == bootstrap`, simulations for each series
+
+    Examples:
+
+    ```python
+    import pandas as pd
+    from ahead import BasicForecaster
+
+    # Data frame containing the time series
+    dataset = {
+    'date' : ['2001-01-01', '2002-01-01', '2003-01-01', '2004-01-01', '2005-01-01'],
+    'series1' : [34, 30, 35.6, 33.3, 38.1],
+    'series2' : [4, 5.5, 5.6, 6.3, 5.1],
+    'series3' : [100, 100.5, 100.6, 100.2, 100.1]}
+    df = pd.DataFrame(dataset).set_index('date')
+    print(df)
+
+    # multivariate time series forecasting
+    r1 = BasicForecaster(h = 5)
+    r1.forecast(df)
+    print(r1.result_dfs_)
+    ```
+
+    """
+
+    def __init__(
+        self,
+        h=5,
+        level=95,
+        method="mean",
+        type_pi="gaussian",
+        B=100,        
+        date_formatting="original",
+        seed=123,
+    ):
+
+        self.h = h
+        self.level = level
+        self.method = method
+        self.type_pi = type_pi
+        self.B = B
+        self.date_formatting = date_formatting
+        self.seed = seed
+
+        self.averages_ = None
+        self.ranges_ = None
+        self.output_dates_ = []
+        self.mean_ = None
+        self.lower_ = None
+        self.upper_ = None
+        self.result_df_s_ = None
+        self.sims_ = None
+
+    def forecast(self, df):
+        """Forecasting method from `BasicForecaster` class
+
+        Parameters:
+
+            df: a data frame;
+                a data frame containing the input time series (see example)
+
+        """
+
+        self.input_df = df
+        n_series = len(df.columns)
+
+        # obtain dates 'forecast' -----
+
+        output_dates, frequency = umv.compute_output_dates(
+            self.input_df, self.h
+        )
+
+        # obtain time series forecast -----
+
+        y = mv.compute_y_mts(self.input_df, frequency)
+        self.fcast_ = ahead.basicf(
+            y,
+            h=self.h,
+            level=self.level,
+            method=self.method,
+            type_pi=self.type_pi,
+            B=self.B,
+            seed=self.seed,
+        )
+
+        # result -----
+
+        (
+            self.averages_,
+            self.ranges_,
+            self.output_dates_,
+        ) = mv.format_multivariate_forecast(
+            n_series=n_series,
+            date_formatting=self.date_formatting,
+            output_dates=output_dates,
+            horizon=self.h,
+            fcast=self.fcast_,
+        )
+
+        self.mean_ = np.asarray(self.fcast_.rx2['mean'])
+        self.lower_= np.asarray(self.fcast_.rx2['lower'])
+        self.upper_= np.asarray(self.fcast_.rx2['upper'])
+
+        self.result_dfs_ = tuple(
+            umv.compute_result_df(self.averages_[i], self.ranges_[i])
+            for i in range(n_series)
+        )
+
+        if self.type_pi == "bootstrap":
+            self.sims_ = tuple(
+                np.asarray(self.fcast_.rx2["sims"][i]) for i in range(self.B)
+            )
+
+        return self

ahead/Basic/BasicForecaster.py

@@ -0,0 +1,3 @@
+from .BasicForecaster import BasicForecaster
+
+__all__ = ["BasicForecaster"]

ahead/Basic/__init__.py

@@ -90,23 +90,23 @@ class DynamicRegressor(object):
 
     Examples:
 
-        ```
-            import pandas as pd
-            from ahead import DynamicRegressor
-
-            # Data frame containing the time series
-            dataset = {
-            'date' : ['2020-01-01', '2020-02-01', '2020-03-01', '2020-04-01', '2020-05-01'],
-            'value' : [34, 30, 35.6, 33.3, 38.1]}
-
-            df = pd.DataFrame(dataset).set_index('date')
-            print(df)
-
-            # univariate time series forecasting
-            d1 = DynamicRegressor(h = 5)
-            d1.forecast(df)
-            print(d1.result_df_)
-        ```
+    ```python
+    import pandas as pd
+    from ahead import DynamicRegressor
+
+    # Data frame containing the time series
+    dataset = {
+    'date' : ['2020-01-01', '2020-02-01', '2020-03-01', '2020-04-01', '2020-05-01'],
+    'value' : [34, 30, 35.6, 33.3, 38.1]}
+
+    df = pd.DataFrame(dataset).set_index('date')
+    print(df)
+
+    # univariate time series forecasting
+    d1 = DynamicRegressor(h = 5)
+    d1.forecast(df)
+    print(d1.result_df_)
+    ```
 
     """
 

ahead/DynamicRegressor/DynamicRegressor.py

@@ -95,23 +95,23 @@ class EAT(object):
 
     Examples:
 
-        ```
-            import pandas as pd
-            from ahead import EAT
-
-            # Data frame containing the time series
-            dataset = {
-            'date' : ['2020-01-01', '2020-02-01', '2020-03-01', '2020-04-01', '2020-05-01'],
-            'value' : [34, 30, 35.6, 33.3, 38.1]}
-
-            df = pd.DataFrame(dataset).set_index('date')
-            print(df)
-
-            # univariate time series forecasting
-            e1 = EAT(h = 5) # default, equal weights for each model=[1/3, 1/3, 1/3]
-            e1.forecast(df)
-            print(e1.result_df_)
-        ```
+    ```python
+    import pandas as pd
+    from ahead import EAT
+
+    # Data frame containing the time series
+    dataset = {
+    'date' : ['2020-01-01', '2020-02-01', '2020-03-01', '2020-04-01', '2020-05-01'],
+    'value' : [34, 30, 35.6, 33.3, 38.1]}
+
+    df = pd.DataFrame(dataset).set_index('date')
+    print(df)
+
+    # univariate time series forecasting
+    e1 = EAT(h = 5) # default, equal weights for each model=[1/3, 1/3, 1/3]
+    e1.forecast(df)
+    print(e1.result_df_)
+    ```
 
     """
 

ahead/EAT/EAT.py

@@ -130,24 +130,24 @@ class Ridge2Regressor(object):
 
     Examples:
 
-        ```
-            import pandas as pd
-            from ahead import Ridge2Regressor
-
-            # Data frame containing the time series
-            dataset = {
-            'date' : ['2001-01-01', '2002-01-01', '2003-01-01', '2004-01-01', '2005-01-01'],
-            'series1' : [34, 30, 35.6, 33.3, 38.1],
-            'series2' : [4, 5.5, 5.6, 6.3, 5.1],
-            'series3' : [100, 100.5, 100.6, 100.2, 100.1]}
-            df = pd.DataFrame(dataset).set_index('date')
-            print(df)
-
-            # multivariate time series forecasting
-            r1 = Ridge2Regressor(h = 5)
-            r1.forecast(df)
-            print(r1.result_dfs_)
-        ```
+    ```python
+    import pandas as pd
+    from ahead import Ridge2Regressor
+
+    # Data frame containing the time series
+    dataset = {
+    'date' : ['2001-01-01', '2002-01-01', '2003-01-01', '2004-01-01', '2005-01-01'],
+    'series1' : [34, 30, 35.6, 33.3, 38.1],
+    'series2' : [4, 5.5, 5.6, 6.3, 5.1],
+    'series3' : [100, 100.5, 100.6, 100.2, 100.1]}
+    df = pd.DataFrame(dataset).set_index('date')
+    print(df)
+
+    # multivariate time series forecasting
+    r1 = Ridge2Regressor(h = 5)
+    r1.forecast(df)
+    print(r1.result_dfs_)
+    ```
 
     """