Merge branch 'main' into docs/pr_template

ourownstory · Nov 22, 2022 · 5ffcb09 · 5ffcb09
2 parents 917c180 + f0d45f3
commit 5ffcb09
Show file tree

Hide file tree

Showing 100 changed files with 1,413 additions and 2,294 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,6 +23,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip" # caching pip dependencies
+          cache-dependency-path: "**/requirements/*.txt"
       - name: Install dependencies
         run: |
           python3 -m pip install --upgrade pip
@@ -47,11 +48,17 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - name: Install Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+          cache: "pip"
+          cache-dependency-path: "**/requirements/*.txt"
       - name: Setup Pandoc
         uses: r-lib/actions/setup-pandoc@v1
       - name: Setup Requirements
         run: |
-          pip install --upgrade -r requirements.txt # install all requirements, otherwise the code docs don't build
+          pip install --upgrade -r requirements/base.txt # install all requirements, otherwise the code docs don't build
           pip install --upgrade -r requirements/docs.txt
       - name: Build with Sphinx
-        run: sphinx-build -W docs/source _site
+        run: sphinx-build docs/source _site
diff --git a/.github/workflows/metrics.yml b/.github/workflows/metrics.yml
@@ -39,6 +39,7 @@ jobs:
       - name: Compare performance
         run: |
           echo "## Model Benchmark" >> report.md
+          echo "<details>\n<summary>Show benchmark results</summary>\n" >> report.md
           python tests/metrics/compareMetrics.py >> report.md
       - name: Publish report
         env:
@@ -51,6 +52,7 @@ jobs:
           cml asset publish tests/metrics/YosemiteTemps.svg --md >> report.md
           echo "### AirPassengers" >> report.md
           cml asset publish tests/metrics/AirPassengers.svg --md >> report.md
+          echo "\n</details>" >> report.md
           # Post reports as comments in GitHub PRs
           cml comment update --pr report.md # post to PR
           cml check create --title=ModelReport report.md # update status of check in PR

diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml
@@ -33,7 +33,7 @@ jobs:
         uses: r-lib/actions/setup-pandoc@v1
       - name: Setup Requirements
         run: |
-          pip install --upgrade -r requirements.txt # install all requirements, otherwise the code docs don't build
+          pip install --upgrade -r requirements/base.txt # install all requirements, otherwise the code docs don't build
           pip install --upgrade -r requirements/docs.txt
       - name: Build with Sphinx
         run: sphinx-build docs/source _site

diff --git a/.gitignore b/.gitignore
@@ -13,8 +13,12 @@ site/
 **/*.DS_Store
 tests/test-logs/
 **/test_save_model.np
+lightning_logs/
+logs/
+*.ckpt
+*.pt
 tests/metrics/*.json
-tests/metrics/*.png
+tests/metrics/*.svg
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,4 +1,3 @@
 prune scripts
 include LICENSE.md
-include requirements.txt
-
+include requirements/
diff --git a/README.md b/README.md
@@ -84,30 +84,37 @@ cd neural_prophet
 pip install .
 ```
 
-## Model features
-* Autocorrelation modelling through AR-Net
-* Piecewise linear trend with optional automatic changepoint detection
-* Fourier term Seasonality at different periods such as yearly, daily, weekly, hourly.
-* Lagged regressors (measured features, e.g temperature sensor)
-* Future regressors (in advance known features, e.g. temperature forecast)
-* Country holidays & recurring special events
-* Sparsity of coefficients through regularization
-* Plotting for forecast components, model coefficients as well as final predictions
-* Automatic selection of training related hyperparameters
-* Support for panel data by building global forecasting models.
-
-### Coming up soon
-For details, please view the [Development Timeline](notes/development_timeline.md).
-
-The next versions of NeuralProphet are expected to cover a set of new exciting features:
-
+## Features
+### Model components
+* Autoregression: Autocorrelation modelling - linear or NN (AR-Net)
+* Trend: Piecewise linear trend with optional automatic changepoint detection
+* Seasonality: Fourier terms at different periods such as yearly, daily, weekly, hourly.
+* Lagged regressors: Lagged observations (e.g temperature sensor) - linear or NN
+* Future regressors: In advance known features (e.g. temperature forecast) - linear
+* Events: Country holidays & recurring custom events
+
+
+### Framework features
+* Multiple time series: Fit a global/glocal model with (partially) shared model parameters
+* Uncertainty: Estimate values of specific quantiles - Quantile Regression
+* Regularize modelling components
+* Plotting of forecast components, model coefficients and more
+* Time series crossvalidation utility
+* Model checkpointing and validation
+
+
+### Coming soon<sup>:tm:</sup>
+
+* Cross-relation of lagged regressors
+* Cross-relation and non-linear modelling of future regressors
+* Static featues / Time series featurization 
 * Logistic growth for trend component.
-* Uncertainty estimation of predicted values
-* Incorporate time series featurization for improved forecast accuracy.
-* Model bias modelling/correction with secondary model
-* Multimodal dynamics: unsupervised automatic modality-specific forecast.
+* Model bias modelling / correction with secondary model
+* Multimodal seasonality
+
+For a list of past changes, please refer to the [releases page](https://github.com/ourownstory/neural_prophet/releases).
 
-For a complete list of all past and near-future changes, please refer to the [changelogs](notes/changelogs.md).
+The vision for future development can be seen at [Development Timeline](notes/development_timeline.md) (partially outdated).
 
 ## Cite
 Please cite [NeuralProphet](https://arxiv.org/abs/2111.15397) in your publications if it helps your research:

diff --git a/_site/html/index.html b/_site/html/index.html
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/check_nblink_files.py b/docs/check_nblink_files.py
@@ -5,26 +5,25 @@
 
 # define relative paths
 DIR = pathlib.Path(__file__).parent.parent.absolute()
-SRC_DIR = os.path.join(DIR, "docs", "source")
+TARGET_DIR = os.path.join(DIR, "docs", "source", "notebooks")
 FEAT_TUT_DIR = os.path.join(DIR, "tutorials", "feature-use")
 APP_TUT_DIR = os.path.join(DIR, "tutorials", "application-example")
 
 # get list of nblink files and remove all .nblink files
-nblink_list = os.listdir(SRC_DIR)
+nblink_list = os.listdir(TARGET_DIR)
 for nblink_file in nblink_list:
     if nblink_file.endswith(".nblink"):
-        os.remove(os.path.join(SRC_DIR, nblink_file))
-        pass
+        os.remove(os.path.join(TARGET_DIR, nblink_file))
 
 # get list of feature-use tutorial files and generate respective .nblink files
 feature_tutorial_list = os.listdir(FEAT_TUT_DIR)
 for feature_tutorial in feature_tutorial_list:
     if feature_tutorial.endswith(".ipynb"):
         # iterate through feature-use tutorial files and create nb-link file
         filename = feature_tutorial[:-6] + ".nblink"
-        with open(os.path.join(SRC_DIR, filename), "w") as out:
+        with open(os.path.join(TARGET_DIR, filename), "w") as out:
             line1 = "{"
-            line2 = '    "path": "../../tutorials/feature-use/' + feature_tutorial[:-6] + '.ipynb"'
+            line2 = '    "path": "../../../tutorials/feature-use/' + feature_tutorial[:-6] + '.ipynb"'
             line3 = "}"
             out.write(f"{line1}\n{line2}\n{line3}\n")
 
@@ -34,8 +33,8 @@
     if app_tutorial.endswith(".ipynb"):
         # iterate through application-example tutorial files and create nb-link file
         filename = app_tutorial[:-6] + ".nblink"
-        with open(os.path.join(SRC_DIR, filename), "w") as out:
+        with open(os.path.join(TARGET_DIR, filename), "w") as out:
             line1 = "{"
-            line2 = '    "path": "../../tutorials/application-example/' + app_tutorial[:-6] + '.ipynb"'
+            line2 = '    "path": "../../../tutorials/application-example/' + app_tutorial[:-6] + '.ipynb"'
             line3 = "}"
             out.write(f"{line1}\n{line2}\n{line3}\n")
diff --git a/docs/source/Live_plot_during_training.nblink b/docs/source/Live_plot_during_training.nblink
diff --git a/docs/source/Prophet_to_TorchProphet.nblink b/docs/source/Prophet_to_TorchProphet.nblink
diff --git a/docs/source/autoregression_yosemite_temps.nblink b/docs/source/autoregression_yosemite_temps.nblink
diff --git a/docs/source/configure.rst → docs/source/code/configure.rst b/docs/source/configure.rst → docs/source/code/configure.rst
diff --git a/docs/source/df_utils.rst → docs/source/code/df_utils.rst b/docs/source/df_utils.rst → docs/source/code/df_utils.rst
diff --git a/docs/source/code/forecaster.rst b/docs/source/code/forecaster.rst
@@ -0,0 +1,19 @@
+Core Module Documentation
+==========================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   configure.py <configure>
+   df_utils.py <df_utils>
+   hdays.py <hdays>
+   metrics.py <metrics>
+   plot_forecaster.py <plot_forecast>
+   plot_model_parameters.py <plot_model_parameters>
+   time_dataset.py <time_dataset>
+   time_net.py <time_net>
+   utils.py <utils>
+
+.. automodule:: neuralprophet.forecaster
+   :members:
diff --git a/docs/source/hdays.rst → docs/source/code/hdays.rst b/docs/source/hdays.rst → docs/source/code/hdays.rst
diff --git a/docs/source/metrics.rst → docs/source/code/metrics.rst b/docs/source/metrics.rst → docs/source/code/metrics.rst
diff --git a/docs/source/plot_forecast.rst → docs/source/code/plot_forecast.rst b/docs/source/plot_forecast.rst → docs/source/code/plot_forecast.rst
diff --git a/docs/source/plot_model_parameters.rst → docs/source/code/plot_model_parameters.rst b/docs/source/plot_model_parameters.rst → docs/source/code/plot_model_parameters.rst
diff --git a/docs/source/time_dataset.rst → docs/source/code/time_dataset.rst b/docs/source/time_dataset.rst → docs/source/code/time_dataset.rst
diff --git a/docs/source/time_net.rst → docs/source/code/time_net.rst b/docs/source/time_net.rst → docs/source/code/time_net.rst
diff --git a/docs/source/utils.rst → docs/source/code/utils.rst b/docs/source/utils.rst → docs/source/code/utils.rst
diff --git a/docs/source/collect_predictions.nblink b/docs/source/collect_predictions.nblink
diff --git a/docs/source/contribute.md → docs/source/community/contribute.md b/docs/source/contribute.md → docs/source/community/contribute.md
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
@@ -16,7 +16,7 @@ Links
 - `Read the paper <https://arxiv.org/abs/2111.15397?fbclid=IwAR2vCkHYiy5yuPPjWXpJgAJs-uD5NkH4liORt1ch4a6X_kmpMqagGtXyez4>`_
 - `GitHub repository <https://github.com/ourownstory/neural_prophet>`_
 
-Why NeuralProphet? 
+Why NeuralProphet?
 -------------------
 
 NeuralProphet changes the way time series modelling and forecasting is done:
@@ -33,7 +33,7 @@ NeuralProphet changes the way time series modelling and forecasting is done:
 
 .. code-block:: pycon
 
-   >>> from neuralprophet import NeuralProphet 
+   >>> from neuralprophet import NeuralProphet
    >>> m = NeuralProphet()
    >>> metrics = m.fit(your_df, freq='D')
    >>> forecast = m.predict(your_df)
@@ -68,60 +68,47 @@ Alternatively, you can get the most up to date version by cloning directly from
    :hidden:
    :maxdepth: 1
 
+   Home<self>
+   Quick Start Guide<quickstart>
 
-   Quick Start Guide<quickstart.md>
-   Model Overview<model-overview>
-   Changes from prophet<changes-from-prophet>
-   Trend<trend>
-   Seasonality<seasonality>
-   Auto-regression<auto-regression>
-   Lagged-regression<lagged-regressors>
-   Events<events>
-   Future-regression<future-regressors>
-   Hyperparameter-selection<hyperparameter-selection>
-   Contribution<contribute>
 
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Tutorials
+
+   Tutorials<tutorials/tutorials>
 
-Get started with Tutorials
----------------------------
 
 .. toctree::
+   :hidden:
    :maxdepth: 1
-   :caption: Feature Tutorials
-
-   autoregression_yosemite_temps.nblink
-   benchmarking.nblink
-   collect_predictions.nblink
-   test_and_crossvalidate.nblink
-   lagged_covariates_energy_ercot.nblink
-   events_holidays_peyton_manning.nblink
-   season_multiplicative_air_travel.nblink
-   sparse_autoregression_yosemite_temps.nblink
-   sub_daily_data_yosemite_temps.nblink
-   trend_peyton_manning.nblink
-
+   :caption: How To Guides
+
+   Guides<guides/index>
+
 
 .. toctree::
+   :hidden:
    :maxdepth: 1
-   :caption: Application Tutorials   
+   :caption: The Science Behind
+
+   Model Overview<model-overview>
+   Presentation<https://github.com/ourownstory/neural_prophet/raw/61f1c6d4667db19a189e15037eb230ee5e90b80c/notes/NeuralProphet_Introduction.pdf>
+
 
-   energy_hospital_load.nblink
-   energy_solar_pv.nblink
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: API Reference
 
+   forecaster.py <code/forecaster>
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Code Documentations
-
-   configure.py <configure>
-   df_utils.py <df_utils>
-   forecaster.py <forecaster>
-   hdays.py <hdays>
-   metrics.py <metrics>
-   plot_forecaster.py <plot_forecast>
-   plot_model_parameters.py <plot_model_parameters>
-   time_dataset.py <time_dataset>
-   time_net.py <time_net>
-   utils.py <utils>
+   :caption: Community
 
+   Contribution<community/contribute>
+   GitHub <https://github.com/ourownstory/neural_prophet>
+   Slack <https://join.slack.com/t/neuralprophet/shared_invite/zt-1iyfs2pld-vtnegAX4CtYg~6E~V8miXw>
diff --git a/docs/source/energy_hospital_load.nblink b/docs/source/energy_hospital_load.nblink
diff --git a/docs/source/energy_solar_pv.nblink b/docs/source/energy_solar_pv.nblink
diff --git a/docs/source/events_holidays_peyton_manning.nblink b/docs/source/events_holidays_peyton_manning.nblink
diff --git a/docs/source/forecaster.rst b/docs/source/forecaster.rst
diff --git a/docs/source/global_local_modeling.nblink b/docs/source/global_local_modeling.nblink
diff --git a/docs/source/global_modeling.nblink b/docs/source/global_modeling.nblink
diff --git a/docs/source/changes-from-prophet.md → docs/source/guides/changes-from-prophet.md b/docs/source/changes-from-prophet.md → docs/source/guides/changes-from-prophet.md
diff --git a/docs/source/hyperparameter-selection.md → ...source/guides/hyperparameter-selection.md b/docs/source/hyperparameter-selection.md → ...source/guides/hyperparameter-selection.md
diff --git a/docs/source/guides/index.rst b/docs/source/guides/index.rst
@@ -0,0 +1,36 @@
+Feature Guides
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   ./../notebooks/autoregression_yosemite_temps.nblink
+   ./../notebooks/benchmarking.nblink
+   Hyperparameter Selection<hyperparameter-selection>
+   ./../notebooks/collect_predictions.nblink
+   ./../notebooks/test_and_crossvalidate.nblink
+   ./../notebooks/lagged_covariates_energy_ercot.nblink
+   ./../notebooks/events_holidays_peyton_manning.nblink
+   ./../notebooks/season_multiplicative_air_travel.nblink
+   ./../notebooks/sparse_autoregression_yosemite_temps.nblink
+   ./../notebooks/sub_daily_data_yosemite_temps.nblink
+   ./../notebooks/trend_peyton_manning.nblink
+
+
+Application Examples
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   ./../notebooks/energy_hospital_load.nblink
+   ./../notebooks/energy_solar_pv.nblink
+
+
+Migrate From Prophet
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   Changes from prophet<changes-from-prophet>
diff --git a/docs/source/lagged_covariates_energy_ercot.nblink b/docs/source/lagged_covariates_energy_ercot.nblink
diff --git a/docs/source/network_architecture_visualization.nblink b/docs/source/network_architecture_visualization.nblink
diff --git a/docs/source/notebooks/Live_plot_during_training.nblink b/docs/source/notebooks/Live_plot_during_training.nblink
@@ -0,0 +1,3 @@
+{
+    "path": "../../../tutorials/feature-use/Live_plot_during_training.ipynb"
+}