update the documentation content, style and add hypertuning

FZJ-IEK3-VSA · Aug 21, 2023 · d31d758 · d31d758
1 parent 68bad99
commit d31d758
Show file tree

Hide file tree

Showing 25 changed files with 203 additions and 184 deletions.
diff --git a/.travis.yml b/.travis.yml
diff --git a/README.md b/README.md
@@ -60,11 +60,12 @@ Initialize an aggregation object and define the length of a single period, the n
 	aggregation = tsam.TimeSeriesAggregation(raw, 
 						noTypicalPeriods = 8, 
 						hoursPerPeriod = 24, 
-						rescaleClusterPeriods = False,
 						segmentation = True,
+						noSegments = 8,
 						representationMethod = "distributionAndMinMaxRepresentation",
 						distributionPeriodWise = False
-						clusterMethod = 'hierarchical')
+						clusterMethod = 'hierarchical'
+						)
 ```
 
 Run the aggregation to typical periods

diff --git a/docs/Makefile b/docs/Makefile
@@ -1,20 +1,25 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = tsam
-SOURCEDIR     = source
-BUILDDIR      = build
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = ./source
+BUILDDIR      = ./build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 .PHONY: help Makefile
 
+# Build, watch and serve docs with live reload
+livehtml:
+	sphinx-autobuild -b html --host 0.0.0.0 --port 7000 -c $(SOURCEDIR) $(SOURCEDIR) $(BUILDDIR)/html
+
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/_static/tsam-logo.png b/docs/source/_static/tsam-logo.png
diff --git a/docs/source/aboutUsDoc.rst b/docs/source/aboutUsDoc.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -69,24 +69,24 @@
 
 # General information about the project.
 project = "tsam"
-copyright = "2016-2022, tsam Developer Team"
+copyright = "2016-2023, tsam Developer Team"
 author = "Leander Kotzur, Maximilian Hoffmann"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = "2.0.1"
+version = "2.3.0"
 # The full version, including alpha/beta/rc tags.
-release = "2.0.1"
+release = "2.3.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -105,14 +105,29 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    "repository_url": "https://github.com/FZJ-IEK3-VSA/tsam",
+    "use_repository_button": True,
+    "show_navbar_depth": 1,
+}
+
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "tsam Documentation"
 
+# A shorter title for the navigation bar.  Default is the same as html_title.
+html_short_title = "tsam"
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "_static/tsam-logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -180,7 +195,3 @@
         "Miscellaneous",
     ),
 ]
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
diff --git a/docs/source/durationRepresentationDoc.rst b/docs/source/durationRepresentationDoc.rst
@@ -1,5 +1,5 @@
 #########################################
-The Duration Representation Functionality
+Duration Representation Functionality
 #########################################
 
 .. |br| raw:: html

diff --git a/docs/source/exactKmedoidsDoc.rst b/docs/source/exactKmedoidsDoc.rst
@@ -1,5 +1,5 @@
 #################################
-The Exact k-Medoids Functionality
+Exact k-Medoids Functionality
 #################################
 
 .. |br| raw:: html

diff --git a/docs/source/furtherReadingDoc.rst b/docs/source/furtherReadingDoc.rst
@@ -23,4 +23,6 @@ The publications about time series aggregation for energy system optimization mo
 * | Kannengießer et al. (2019):
   | `Reducing Computational Load for Mixed Integer Linear Programming: An Example for a District and an Island Energy System <https://www.mdpi.com/1996-1073/12/14/2825>`_
 * | Hoffmann et al. (2020):
-  | `A Review on Time Series Aggregation Methods for Energy System Models <https://www.mdpi.com/1996-1073/13/3/641>`_
+  | `A Review on Time Series Aggregation Methods for Energy System Models <https://www.mdpi.com/1996-1073/13/3/641>`_
+* | Hoffmann et al. (2022):
+  | `The Pareto-Optimal Temporal Aggregation of Energy System Models <https://www.sciencedirect.com/science/article/abs/pii/S0306261922004342>`
diff --git a/docs/source/gettingStartedDoc.rst b/docs/source/gettingStartedDoc.rst
@@ -1,39 +1,85 @@
-.. _getting_started:
+.. _start:
 
-###############
+********
 Getting started
-###############
+********
 
-In the following, instructions for installing and using the tsam package on Windows are given. The installation
-instructions for installing and using tsam on Linux/macOS systems are however quite similar and can be, hopefully
-easily, derived from the instructions below.
+**Basic Workflow**
 
-**tsam installation**
+A small example how tsam can be used is decribed as follows
 
-Install via pip by typing
+.. code-block:: python
 
-.. code-block:: bash
+   import pandas as pd
+   import tsam.timeseriesaggregation as tsam
 
-    pip install tsam
+Read in the time series data set with pandas
 
-into the command prompt. Alternatively, download or clone a local copy of the repository to your computer
+.. code-block:: python
 
-.. code-block:: bash
+   raw = pd.read_csv('testdata.csv', index_col = 0)
 
-    git clone https://github.com/FZJ-IEK3-VSA/tsam.git
+Initialize an aggregation object and define the number of typical periods, the length of a single period, the aggregation method
 
-and install tsam in the folder where the setup.py is located with
+.. code-block:: python
 
-.. code-block:: bash
+  aggregation = tsam.TimeSeriesAggregation(raw, 
+    noTypicalPeriods = 8, 
+    hoursPerPeriod = 24, 
+    segmentation = True,
+    noSegments = 8,
+    representationMethod = "distributionAndMinMaxRepresentation",
+    distributionPeriodWise = False
+    clusterMethod = 'hierarchical'
+  )
 
-    pip install -e .
+Run the aggregation to typical periods
 
-or install directly via python as
+.. code-block:: python
 
-.. code-block:: bash
+   typPeriods = aggregation.createTypicalPeriods()
 
-    python setup.py install
+Store the results as .csv file
 
-**Installation of an optimization solver**
+.. code-block:: python
 
-Some clustering algorithms implemented in tsam are based on Mixed-Integer Linear Programming. Accordingy, an appropriate solver for using these functionalities is required that can be accessed by `Pyomo <https://github.com/Pyomo/pyomo/>`_. In theory many solvers can be used (e.g. `GUROBI <http://www.gurobi.com/>`_  or `cbc <https://sourceforge.net/projects/wincbc/files/latest/download>`_). For the installation of GUROBI, follow the instructions on the solver's website. For installation of cbc, move the downloaded folder to a desired location. Then, manually append the Environment Variable *Path* with the absolute path leading to the folder in which the glpsol.exe is located (c.f. w32/w64 folder, depending on operating system type).
+   typPeriods.to_csv('typperiods.csv')
+
+
+**Hypertuned aggregation**
+
+In case you do not know, which number of segments or typical periods to choose, you should make first a run with the HyperTunedAggregations class. It will find the best combination of typical periods and segments for the aggregation by minimizing the error between the original and the aggregated time series. The following example shows how to use it.
+
+
+Either create or provide a TimeSeriesAggregation object and use it as base case to get tuned by the HyperTunedAggregations class.
+
+.. code-block:: python
+
+	tune_aggregation = tune.HyperTunedAggregations(
+    tsam.TimeSeriesAggregation(
+      raw,
+      hoursPerPeriod=24,
+      clusterMethod="hierarchical",
+      representationMethod="distributionRepresentation",
+      rescaleClusterPeriods=False,
+      segmentation=True,
+    )
+  )
+
+Afterwards, define the aggregation level you want to reach. The following examples shows how to reduce the original time series to 5% of the original data set.
+
+.. code-block:: python
+
+  segments, periods, RMSE = tune_aggregation.identifyOptimalSegmentPeriodCombination(
+    dataReduction=0.05
+  )
+
+
+Since, it is quite time consuming, I would recommend to just run it once at the beginning for your time series set, save the resulting segment and period number, and use it as fix values for the original TimeSeriesAggregation object in production.
+
+The scientific documentation of the methodology can be found here: 
+`The Pareto-Optimal Temporal Aggregation of Energy System Models <https://www.sciencedirect.com/science/article/abs/pii/S0306261922004342>`_
+
+**Additional Examples**
+
+More detailed examples can be found on the `GitHub page of tsam <https://github.com/FZJ-IEK3-VSA/tsam>`_.
diff --git a/docs/source/hypertunedaggregationDoc.rst b/docs/source/hypertunedaggregationDoc.rst
@@ -0,0 +1,20 @@
+######################
+Hypertuning segment and period selection
+######################
+
+.. |br| raw:: html
+
+   <br />
+
+Descriptions of the basic functions are given below.
+
+**Function descriptions:**
+
+.. automodule:: hyperparametertuning
+   :member-order: bysource
+
+   .. autoclass:: HyperTunedAggregations
+      :members:
+      :member-order: bysource
+
+      .. automethod:: __init__
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,48 +2,43 @@
    sphinx-quickstart on Sat Nov 10 21:04:19 2018.
 
 
-.. image:: http://www.fz-juelich.de/SharedDocs/Bilder/IBG/IBG-3/DE/Plant-soil-atmosphere%20exchange%20processes/INPLAMINT%20(BONARES)/Bild3.jpg?__blob=poster
-    :target: http://www.fz-juelich.de/iek/iek-3/EN/Forschung/_Process-and-System-Analysis/_node.html
+.. image:: https://www.fz-juelich.de/static/media/Logo.2ceb35fc.svg
+    :target: https://www.fz-juelich.de/en/iek/iek-3
     :width: 230px
     :alt: Forschungszentrum Juelich Logo
     :align: right
 
-Welcome to tsam's documentation!
+Introduction
 ================================
 
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 tsam - time series aggregation module
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 tsam is a python package which uses different machine learning algorithms for the aggregation of typical periods. It is applicable
-for all type of time series, either weather data, load data or both simultaneously. The module is able to significantly reduce input
-time series for energy system models, and therefore the model's complexity and computational time.
+for all type of time series, either weather data, price data, behavioral data, electrical load data or all together. The module is able to significantly reduce input
+time series for mathmatical models, and therefore the model's complexity and computational time.
 
-To use tsam, jump to the :ref:`Section Getting Started<getting_started>`.
+To use tsam, first :ref:`install tsam<installation>` and then :ref:`start aggregating time series <start>`.
 
-The concept of tsam is that scientists, programmers and anyone who is interested all around the world can use tsam to aggregate their
-time series whatever they might be used for. Therefore, tsam is open-source available on `GitHub <https://github.com/FZJ-IEK3-VSA/tsam>`_
-and **open for collaboration**.
-The authors of both, the program and the publications, **kindly request you to cite their work** listed in the
-:ref:`Further Reading Section <further_reading>` if tsam is used in a scientific context.
+tsam is open-source available on `GitHub <https://github.com/FZJ-IEK3-VSA/tsam>`_
+and open for collaboration, help requests etc.
+In case you use tsam in a scientific publication, we kindly request you to cite one of our publications listed in the
+:ref:`Further Reading Section <further_reading>`.
 
 .. toctree::
     :maxdepth: 1
     :caption: Contents:
 
     self
+    installationDoc
     gettingStartedDoc
-    usersGuideDoc
+    structureOfTsamDoc
     mathematicalBackgroundDoc
     newsDoc
     integratedSoftwareDoc
     legalNoticeDoc
-    aboutUsDoc
     furtherReadingDoc
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-