43 example file converter

.gitlab-ci.yml

@@ -1,4 +1,5 @@
 stages:
+  - examples
   - test
   - doc
   - code_quality
@@ -8,6 +9,7 @@ stages:
 variables:
   COVERAGE_TYPE: "Dymola"
   PAGES_BRANCH: master
+  GIT_REPO: RWTH-EBC/ebcpy
 
 include:
   - project: 'EBC/EBC_all/gitlab_ci/templates'
@@ -22,5 +24,8 @@ include:
     file: 'python/unit-tests/unittest.gitlab-ci.yml'
   - project: 'EBC/EBC_all/gitlab_ci/templates'
     file: 'python/unit-tests/coverage.gitlab-ci.yml'
+  - project: 'EBC/EBC_all/gitlab_ci/templates'
+    file: 'python/examples/examples.gitlab-ci.yml'
+    ref: '18-add-example-file-converter'
   - template: Dependency-Scanning.gitlab-ci.yml
   - template: SAST.gitlab-ci.yml

examples/converter.toml

@@ -0,0 +1,23 @@
+[[ExampleFile]]
+# Add the path of where data is
+filename = "examples/e1_time_series_data_example.py"
+func_name = "main"
+docstrings = true
+
+[[ExampleFile]]
+# Add the path of where data is
+filename = "examples/e2_fmu_example.py"
+func_name = "main"
+docstrings = true
+
+[[ExampleFile]]
+# Add the path of where data is
+filename = "examples/e3_dymola_example.py"
+func_name = "main"
+docstrings = true
+
+[[ExampleFile]]
+# Add the path of where data is
+filename = "examples/e4_optimization_example.py"
+func_name = "main"
+docstrings = true

examples/e1_time_series_data_example.ipynb

@@ -0,0 +1,169 @@
+{
+    "cells": [
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "\"\"\"\nGoals of this part of the examples:\n1. Learn how to use `TimeSeriesData`\n2. Understand why we use `TimeSeriesData`\n3. Get to know the different processing functions\n\"\"\"\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Start by importing all relevant packages\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "import pathlib\nimport numpy as np\nimport matplotlib.pyplot as plt\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Imports from ebcpy\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "from ebcpy import TimeSeriesData\n\n\nwith_plot = True\n\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " First get the path with relevant input files:\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "basepath = pathlib.Path(__file__).parents[1].joinpath(\"tutorial\", \"data\")\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Note: We often use pathlib. If you're not familiar and want to learn more,\n just search for any of the many tutorials available online.\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " ######################### Instantiation of TimeSeriesData ##########################\n First we open a simulation result file (.mat)\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "tsd_mat = TimeSeriesData(basepath.joinpath('simulatedData.mat'))\nprint(tsd_mat)\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Now a .csv. .xlsx works as well.\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "tsd_csv = TimeSeriesData(basepath.joinpath('excelData.csv'))\nprint(tsd_csv)\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Or construct like any pandas DataFrame\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "tsd_df = TimeSeriesData({\"A\": np.random.rand(100), \"B\": np.random.rand(100)})\nprint(tsd_df)\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " ######################### Why do we use TimeSeriesData? ##########################\n As you may have guessed, TimeSeriesData is just a plain old DataFrame.\n It inherits the standard one and adds functionalities used typically on\n energy related time series.\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "print(\"TimeSeriesData inherits from\", TimeSeriesData.__base__)\n\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " ######################### Processing TimeSeriesData ##########################\n Index changing:\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "print(tsd_csv.index)\ntsd_csv.to_datetime_index(unit_of_index=\"s\")\nprint(tsd_csv.index)\ntsd_csv.to_float_index(offset=0)\nprint(tsd_csv.index)\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Some filter options\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "tsd_csv.low_pass_filter(crit_freq=0.1, filter_order=2,\n                        variable=\"outputs.TRoom\", new_tag=\"lowPass2\")\nprint(tsd_csv)\ntsd_csv.moving_average(window=50, variable=\"outputs.TRoom\",\n                       tag=\"raw\", new_tag=\"MovingAverage\")\nprint(tsd_csv)\nfor tag in tsd_csv.get_tags(variable=\"outputs.TRoom\")[::-1]:\n    plt.plot(tsd_csv.loc[:, (\"outputs.TRoom\", tag)], label=tag)\nplt.legend()\n\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " How-to re-sample your data:\n Call the function. Desired frequency is a string (s: seconds), 60: 60 seconds.\n Play around with this value to see what happens.\n First convert to DateTimeIndex (required for this function)\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "tsd_csv.to_datetime_index(unit_of_index=\"s\")\n"
+        },
+        {
+            "cell_type": "markdown",
+            "metadata": {},
+            "source": " Create a copy to later reference the change.\n"
+        },
+        {
+            "cell_type": "code",
+            "execution_count": null,
+            "metadata": {},
+            "outputs": [],
+            "source": "tsd_csv_ref = tsd_csv.copy()\ntsd_csv.clean_and_space_equally(desired_freq=\"60s\")\nplt.figure()\nplt.plot(tsd_csv_ref.loc[:, (\"outputs.TRoom\", \"raw\")], label=\"Reference\", color=\"blue\")\nplt.plot(tsd_csv.loc[:, (\"outputs.TRoom\", \"raw\")], label=\"Resampled\", color=\"red\")\nplt.legend()\nif with_plot:\n    plt.show()\n\n\n\n"
+        }
+    ],
+    "metadata": {
+        "kernelspec": {
+            "display_name": "Python 3",
+            "language": "python",
+            "name": "python3"
+        },
+        "language_info": {
+            "codemirror_mode": {
+                "name": "ipython",
+                "version": 3
+            },
+            "file_extension": ".py",
+            "mimetype": "text/x-python",
+            "name": "python",
+            "nbconvert_exporter": "python",
+            "pygments_lexer": "ipython3",
+            "version": "3.6.4"
+        }
+    },
+    "nbformat": 4,
+    "nbformat_minor": 2
+}

examples/e1_time_series_data_example.md

@@ -0,0 +1,95 @@
+```python
+"""
+Goals of this part of the examples:
+1. Learn how to use `TimeSeriesData`
+2. Understand why we use `TimeSeriesData`
+3. Get to know the different processing functions
+"""
+```
+ Start by importing all relevant packages
+```python
+import pathlib
+import numpy as np
+import matplotlib.pyplot as plt
+```
+ Imports from ebcpy
+```python
+from ebcpy import TimeSeriesData
+
+
+with_plot = True
+
+```
+ First get the path with relevant input files:
+```python
+basepath = pathlib.Path(__file__).parents[1].joinpath("tutorial", "data")
+```
+ Note: We often use pathlib. If you're not familiar and want to learn more,
+ just search for any of the many tutorials available online.
+ ######################### Instantiation of TimeSeriesData ##########################
+ First we open a simulation result file (.mat)
+```python
+tsd_mat = TimeSeriesData(basepath.joinpath('simulatedData.mat'))
+print(tsd_mat)
+```
+ Now a .csv. .xlsx works as well.
+```python
+tsd_csv = TimeSeriesData(basepath.joinpath('excelData.csv'))
+print(tsd_csv)
+```
+ Or construct like any pandas DataFrame
+```python
+tsd_df = TimeSeriesData({"A": np.random.rand(100), "B": np.random.rand(100)})
+print(tsd_df)
+```
+ ######################### Why do we use TimeSeriesData? ##########################
+ As you may have guessed, TimeSeriesData is just a plain old DataFrame.
+ It inherits the standard one and adds functionalities used typically on
+ energy related time series.
+```python
+print("TimeSeriesData inherits from", TimeSeriesData.__base__)
+
+```
+ ######################### Processing TimeSeriesData ##########################
+ Index changing:
+```python
+print(tsd_csv.index)
+tsd_csv.to_datetime_index(unit_of_index="s")
+print(tsd_csv.index)
+tsd_csv.to_float_index(offset=0)
+print(tsd_csv.index)
+```
+ Some filter options
+```python
+tsd_csv.low_pass_filter(crit_freq=0.1, filter_order=2,
+                        variable="outputs.TRoom", new_tag="lowPass2")
+print(tsd_csv)
+tsd_csv.moving_average(window=50, variable="outputs.TRoom",
+                       tag="raw", new_tag="MovingAverage")
+print(tsd_csv)
+for tag in tsd_csv.get_tags(variable="outputs.TRoom")[::-1]:
+    plt.plot(tsd_csv.loc[:, ("outputs.TRoom", tag)], label=tag)
+plt.legend()
+
+```
+ How-to re-sample your data:
+ Call the function. Desired frequency is a string (s: seconds), 60: 60 seconds.
+ Play around with this value to see what happens.
+ First convert to DateTimeIndex (required for this function)
+```python
+tsd_csv.to_datetime_index(unit_of_index="s")
+```
+ Create a copy to later reference the change.
+```python
+tsd_csv_ref = tsd_csv.copy()
+tsd_csv.clean_and_space_equally(desired_freq="60s")
+plt.figure()
+plt.plot(tsd_csv_ref.loc[:, ("outputs.TRoom", "raw")], label="Reference", color="blue")
+plt.plot(tsd_csv.loc[:, ("outputs.TRoom", "raw")], label="Resampled", color="red")
+plt.legend()
+if with_plot:
+    plt.show()
+
+
+
+```