update docs

docs/source/index.rst

@@ -12,6 +12,7 @@ Welcome to pyhts's documentation!
    :caption: QuickStart
 
    Quick Start <tutorials/Tutorials.rst>
-   Define Hierarchy <tutorials/hierarchy.rst>
+   Define Hierarchy and TemporalHierarchy <tutorials/hierarchy.rst>
    Define, Fit and Forecast of HFModel <tutorials/hfmodel.rst>
+   Define, Fit and Forecast of TemporalHFModel <tutorials/temporalhfmodel.rst>
    Model Evaluation <tutorials/evaluation.rst>

docs/source/tutorials/evaluation.rst

@@ -2,13 +2,15 @@ Model Evaluation
 ================
 
 After obtaining base forecasts or coherent reconciled forecasts, you can use evaluate the forecasting accuracy
-through :meth:`pyhts.accuracy_base` or :meth:`pyhts.accuracy` respectively.
+through :meth:`pyhts.Hierarchy.accuracy_base`, :meth:`pyhts.Hierarchy.accuracy`, or :meth:`pyhts.TemporalHierarchy.accuracy` (for temporal hierarchies).
 
 
 .. automethod:: pyhts.Hierarchy.accuracy_base
 
 .. automethod:: pyhts.Hierarchy.accuracy
 
+.. automethod:: pyhts.TemporalHierarchy.accuracy
+
 
 Assuming :code:`ht` is a defined hierarchy, :code:`model` is a fitted :class:`~pyhts.HFModel`, :code:`test`
 is real observations in the forecasting horizon. :code:`train` is the history bottom time series.

docs/source/tutorials/hierarchy.rst

@@ -42,7 +42,7 @@ Mixing these two hierarchies gives following levels, totally 4 * 4 = 16 levels:
 
 Another example of this kind of hierarchy is the file system with tags, while usually tags only have one level except the total level.
 
-To construct the product hierarchy using :class:`pyhts.Hierarchy.new()`, use the following statement:
+To construct the product hierarchy using :class:`~pyhts.Hierarchy.new()`, use the following statement:
 
 .. code-block:: Python
 
@@ -56,8 +56,19 @@ You can also specify :code:`excludes` and :code:`includes` to exclude some level
     :members: new
 
 
+Temporal Hierarchy
+------------------
+
+Temporal hierarchy is constructed by multiple levels of temporal aggregation of a time series. :code:`pyhts` provide
+:class:`~pyhts.TemporalHierarchy` to construct temporal hierarchy. The methodology is well-known as THief (Athanasopoulos et al., 2017).
+
+.. autoclass:: pyhts.TemporalHierarchy
+    :members: new, aggregate_ts
 
 Reference
 ---------
 
 [1] Hyndman, R. J., & Athanasopoulos, G. (2021). Forecasting: Principles and Practice (3rd ed.). Otext. https://otexts.com/fpp3/
+
+[2] Athanasopoulos, G., Hyndman, R. J., Kourentzes, N., & Petropoulos, F. (2017). Forecasting with temporal hierarchies. European Journal of Operational Research, 262(1), 60–74. https://doi.org/10.1016/j.ejor.2017.02.046
+

docs/source/tutorials/temporalhfmodel.rst

@@ -0,0 +1,79 @@
+Temporal hierarchical forecasting model
+#######################################
+
+Temporal hierarchical forecasting model is defined by :class:`~pyhts.TemporalHFModel`
+
+
+TemporalHFModel API
+====================
+
+.. autoclass:: pyhts.TemporalHFModel
+   :members: __init__, fit, predict, generate_base_forecast
+
+
+
+Examples 
+========
+
+Randomly generate some dataset and define the hierarchy. Here, we
+consider a monthly time series and aggregation perios are 2, 3, 6, 12.
+
+.. code-block:: python
+
+   >>> import numpy as np
+   >>> from pyhts import TemporalHierarchy
+   >>> ts = np.random.random(120)
+   >>> ht = TemporalHierarchy.new(agg_periods=[1, 2, 3, 6, 12], forecast_frequency=12)
+   >>> ht.level_name
+   ['agg_12', 'agg_6', 'agg_3', 'agg_2', 'agg_1']
+
+
+
+Define and fit temporal hierarchical forecasting model
+------------------------------------------------------
+
+Then we can construct a temporal hierarchical forecasting model using
+the ols reconciliation method and arima models as base forecasters.
+
+.. code-block:: python
+   
+   >>> from pyhts import TemporalHFModel
+   >>> hfmodel = TemporalHFModel(ht, "arima", hf_method='comb', comb_method='ols')
+   >>> hfmodel.fit(ts)
+
+
+Predict and evaluate forecasts
+------------------------------
+
+The horizon here should be the corresponding forecast horizon for the top level.
+For example, if we want to predict the next 12 months, the horizon
+should be 1 (the top level is year).
+
+.. code-block:: python
+
+   >> fcasts = hfmodel.predict(1)
+   {'agg_12': array([5.89485775]),
+   'agg_6': array([2.94742887, 2.94742887]),
+   'agg_3': array([1.47371444, 1.47371444, 1.47371444, 1.47371444]),
+   'agg_2': array([0.98247629, 0.98247629, 0.98247629, 0.98247629, 0.98247629,
+         0.98247629]),
+   'agg_1': array([0.49123815, 0.49123815, 0.49123815, 0.49123815, 0.49123815,
+         0.49123815, 0.49123815, 0.49123815, 0.49123815, 0.49123815,
+         0.49123815, 0.49123815])}
+
+The forecasts can be evaluated using :class:`~pyhts.TemporalHierarchy.accuracy()`
+method. We pass the future observations, forecasts and historical 
+observations (if needed). The measures for each level are returned.
+
+.. code-block:: python
+
+   >> real = np.random.random(12)
+   >> ht.accuracy(real, pred, ts)
+               mase      mape      rmse
+      agg_12  3.023196  0.187241  1.358036
+      agg_6   1.248526  0.186900  0.683057
+      agg_3   0.742426  0.178560  0.455563
+      agg_2   1.144290  0.504512  0.525026
+      agg_1   0.810293  2.290112  0.317474
+
+