tsam 2.3.9__tar.gz → 3.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {tsam-2.3.9 → tsam-3.1.0}/LICENSE.txt +21 -21
- {tsam-2.3.9 → tsam-3.1.0}/MANIFEST.in +3 -3
- {tsam-2.3.9/src/tsam.egg-info → tsam-3.1.0}/PKG-INFO +123 -81
- {tsam-2.3.9 → tsam-3.1.0}/README.md +191 -167
- tsam-3.1.0/environment.yml +30 -0
- tsam-3.1.0/pyproject.toml +137 -0
- tsam-3.1.0/src/tsam/__init__.py +79 -0
- tsam-3.1.0/src/tsam/api.py +603 -0
- tsam-3.1.0/src/tsam/config.py +891 -0
- tsam-3.1.0/src/tsam/exceptions.py +17 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/hyperparametertuning.py +289 -245
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/periodAggregation.py +140 -141
- tsam-3.1.0/src/tsam/plot.py +513 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/representations.py +177 -167
- tsam-3.1.0/src/tsam/result.py +397 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/timeseriesaggregation.py +1526 -1361
- tsam-3.1.0/src/tsam/tuning.py +1038 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/durationRepresentation.py +229 -223
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/k_maxoids.py +138 -145
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/k_medoids_contiguity.py +139 -140
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/k_medoids_exact.py +232 -239
- tsam-3.1.0/src/tsam/utils/segmentation.py +232 -0
- {tsam-2.3.9 → tsam-3.1.0/src/tsam.egg-info}/PKG-INFO +123 -81
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam.egg-info/SOURCES.txt +12 -12
- tsam-3.1.0/src/tsam.egg-info/requires.txt +32 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_accuracyIndicators.py +57 -63
- {tsam-2.3.9 → tsam-3.1.0}/test/test_adjacent_periods.py +38 -42
- {tsam-2.3.9 → tsam-3.1.0}/test/test_aggregate_hiearchical.py +393 -402
- tsam-3.1.0/test/test_api_equivalence.py +565 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_assert_raises.py +231 -234
- {tsam-2.3.9 → tsam-3.1.0}/test/test_averaging.py +53 -57
- {tsam-2.3.9 → tsam-3.1.0}/test/test_cluster_order.py +130 -132
- tsam-3.1.0/test/test_clustering_e2e.py +498 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_durationCurve.py +59 -63
- {tsam-2.3.9 → tsam-3.1.0}/test/test_durationRepresentation.py +140 -148
- tsam-3.1.0/test/test_extremePeriods.py +237 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_hierarchical.py +79 -78
- {tsam-2.3.9 → tsam-3.1.0}/test/test_hypertuneAggregation.py +175 -170
- {tsam-2.3.9 → tsam-3.1.0}/test/test_k_maxoids.py +60 -59
- {tsam-2.3.9 → tsam-3.1.0}/test/test_k_medoids.py +56 -53
- {tsam-2.3.9 → tsam-3.1.0}/test/test_k_medoids_contiguity.py +79 -83
- {tsam-2.3.9 → tsam-3.1.0}/test/test_minmaxRepresentation.py +66 -70
- tsam-3.1.0/test/test_new_api.py +665 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_preprocess.py +31 -43
- {tsam-2.3.9 → tsam-3.1.0}/test/test_properties.py +204 -208
- tsam-3.1.0/test/test_reconstruct_samemean_segmentation.py +111 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_samemean.py +46 -49
- tsam-3.1.0/test/test_segmentation.py +114 -0
- {tsam-2.3.9 → tsam-3.1.0}/test/test_subhourlyResolution.py +50 -54
- {tsam-2.3.9 → tsam-3.1.0}/test/test_subhourly_periods.py +39 -41
- {tsam-2.3.9 → tsam-3.1.0}/test/test_weightingFactors.py +64 -70
- tsam-2.3.9/examples/results/paretoOptimalAggregation.csv +0 -389
- tsam-2.3.9/examples/results/preprocessed_wind.csv +0 -368
- tsam-2.3.9/examples/results/testperiods_hierarchical.csv +0 -241
- tsam-2.3.9/examples/results/testperiods_kmeans.csv +0 -193
- tsam-2.3.9/examples/results/testperiods_kmedoids.csv +0 -1345
- tsam-2.3.9/examples/results/testperiods_predefClusterOrder.csv +0 -193
- tsam-2.3.9/examples/results/testperiods_predefClusterOrderAndClusterCenters.csv +0 -193
- tsam-2.3.9/examples/results/testperiods_segmentation.csv +0 -241
- tsam-2.3.9/examples/testdata.csv +0 -8761
- tsam-2.3.9/pyproject.toml +0 -53
- tsam-2.3.9/requirements.txt +0 -7
- tsam-2.3.9/requirements.yml +0 -6
- tsam-2.3.9/requirements_dev.txt +0 -12
- tsam-2.3.9/src/tsam/utils/segmentation.py +0 -118
- tsam-2.3.9/src/tsam.egg-info/requires.txt +0 -16
- tsam-2.3.9/test/test_extremePeriods.py +0 -93
- tsam-2.3.9/test/test_segmentation.py +0 -109
- {tsam-2.3.9 → tsam-3.1.0}/setup.cfg +0 -0
- /tsam-2.3.9/src/tsam/__init__.py → /tsam-3.1.0/src/tsam/py.typed +0 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/__init__.py +0 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam.egg-info/dependency_links.txt +0 -0
- {tsam-2.3.9 → tsam-3.1.0}/src/tsam.egg-info/top_level.txt +0 -0
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2017 Leander Kotzur (FZJ IEK-3), Maximilian Hoffmann (FZJ IEK-3), Peter Markewitz (FZJ IEK-3), Martin Robinius (FZJ IEK-3), Detlef Stolten (FZJ IEK-3)
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2017-2025 Leander Kotzur (FZJ IEK-3), Maximilian Hoffmann (FZJ IEK-3), Peter Markewitz (FZJ IEK-3), Martin Robinius (FZJ IEK-3), Detlef Stolten (FZJ IEK-3)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
include examples/testdata.csv
|
|
2
|
-
include examples/results/*.csv
|
|
3
|
-
include
|
|
1
|
+
include examples/testdata.csv
|
|
2
|
+
include examples/results/*.csv
|
|
3
|
+
include environment.yml
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tsam
|
|
3
|
-
Version:
|
|
3
|
+
Version: 3.1.0
|
|
4
4
|
Summary: Time series aggregation module (tsam) to create typical periods
|
|
5
5
|
Author-email: Leander Kotzur <leander.kotzur@googlemail.com>, Maximilian Hoffmann <maximilian.hoffmann@julumni.fz-juelich.de>
|
|
6
6
|
Maintainer-email: Julian Belina <j.belina@fz-juelich.de>
|
|
7
7
|
License: MIT License
|
|
8
8
|
|
|
9
|
-
Copyright (c) 2017 Leander Kotzur (FZJ IEK-3), Maximilian Hoffmann (FZJ IEK-3), Peter Markewitz (FZJ IEK-3), Martin Robinius (FZJ IEK-3), Detlef Stolten (FZJ IEK-3)
|
|
9
|
+
Copyright (c) 2017-2025 Leander Kotzur (FZJ IEK-3), Maximilian Hoffmann (FZJ IEK-3), Peter Markewitz (FZJ IEK-3), Martin Robinius (FZJ IEK-3), Detlef Stolten (FZJ IEK-3)
|
|
10
10
|
|
|
11
11
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
12
|
of this software and associated documentation files (the "Software"), to deal
|
|
@@ -25,6 +25,7 @@ License: MIT License
|
|
|
25
25
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
26
26
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
27
27
|
SOFTWARE.
|
|
28
|
+
|
|
28
29
|
Keywords: clustering,optimization
|
|
29
30
|
Classifier: Development Status :: 4 - Beta
|
|
30
31
|
Classifier: Intended Audience :: End Users/Desktop
|
|
@@ -33,34 +34,51 @@ Classifier: License :: OSI Approved :: MIT License
|
|
|
33
34
|
Classifier: Natural Language :: English
|
|
34
35
|
Classifier: Operating System :: OS Independent
|
|
35
36
|
Classifier: Programming Language :: Python
|
|
36
|
-
Classifier: Programming Language :: Python :: 2
|
|
37
37
|
Classifier: Programming Language :: Python :: 3
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
38
42
|
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
39
43
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
40
|
-
Requires-Python: <3.
|
|
44
|
+
Requires-Python: <3.15,>=3.10
|
|
41
45
|
Description-Content-Type: text/markdown
|
|
42
46
|
License-File: LICENSE.txt
|
|
43
|
-
Requires-Dist: scikit-learn
|
|
44
|
-
Requires-Dist: pandas
|
|
45
|
-
Requires-Dist: numpy
|
|
46
|
-
Requires-Dist: pyomo
|
|
47
|
-
Requires-Dist: networkx
|
|
48
|
-
Requires-Dist: tqdm
|
|
49
|
-
Requires-Dist: highspy
|
|
50
|
-
Provides-Extra:
|
|
51
|
-
Requires-Dist: pytest; extra == "
|
|
52
|
-
Requires-Dist: pytest-cov; extra == "
|
|
53
|
-
Requires-Dist:
|
|
54
|
-
Requires-Dist:
|
|
55
|
-
Requires-Dist: sphinx
|
|
56
|
-
Requires-Dist:
|
|
57
|
-
Requires-Dist:
|
|
47
|
+
Requires-Dist: scikit-learn<=1.8.0,>=1.3.0
|
|
48
|
+
Requires-Dist: pandas<=3.0.0,>=2.2.0
|
|
49
|
+
Requires-Dist: numpy<=2.4.1,>=1.22.4
|
|
50
|
+
Requires-Dist: pyomo<=6.95,>=6.4.8
|
|
51
|
+
Requires-Dist: networkx<=3.6.1,>=2.5
|
|
52
|
+
Requires-Dist: tqdm<=4.67.2,>=4.21.0
|
|
53
|
+
Requires-Dist: highspy<=1.12.0,>=1.7.2
|
|
54
|
+
Provides-Extra: develop
|
|
55
|
+
Requires-Dist: pytest; extra == "develop"
|
|
56
|
+
Requires-Dist: pytest-cov; extra == "develop"
|
|
57
|
+
Requires-Dist: pytest-xdist; extra == "develop"
|
|
58
|
+
Requires-Dist: codecov; extra == "develop"
|
|
59
|
+
Requires-Dist: sphinx; extra == "develop"
|
|
60
|
+
Requires-Dist: sphinx-autobuild; extra == "develop"
|
|
61
|
+
Requires-Dist: sphinx_book_theme; extra == "develop"
|
|
62
|
+
Requires-Dist: nbsphinx; extra == "develop"
|
|
63
|
+
Requires-Dist: twine; extra == "develop"
|
|
64
|
+
Requires-Dist: nbval; extra == "develop"
|
|
65
|
+
Requires-Dist: ruff; extra == "develop"
|
|
66
|
+
Requires-Dist: mypy; extra == "develop"
|
|
67
|
+
Requires-Dist: pandas-stubs; extra == "develop"
|
|
68
|
+
Requires-Dist: pre-commit; extra == "develop"
|
|
69
|
+
Requires-Dist: plotly>=5.0.0; extra == "develop"
|
|
70
|
+
Requires-Dist: notebook>=7.5.0; extra == "develop"
|
|
71
|
+
Provides-Extra: plot
|
|
72
|
+
Requires-Dist: plotly>=5.0.0; extra == "plot"
|
|
73
|
+
Provides-Extra: notebooks
|
|
74
|
+
Requires-Dist: notebook>=7.5.0; extra == "notebooks"
|
|
75
|
+
Requires-Dist: plotly>=5.0.0; extra == "notebooks"
|
|
58
76
|
Dynamic: license-file
|
|
59
77
|
|
|
60
|
-
[](https://pypi.python.org/pypi/tsam) [](https://anaconda.org/conda-forge/tsam) [](https://tsam.readthedocs.io/en/latest/) []((https://github.com/FZJ-IEK3-VSA/tsam/blob/master/LICENSE.txt)) [](https://codecov.io/gh/FZJ-IEK3-VSA/tsam)
|
|
61
79
|
[](https://mybinder.org/v2/gh/FZJ-IEK3-VSA/voila-tsam/HEAD?urlpath=voila/render/Time-Series-Aggregation-Module.ipynb)
|
|
62
80
|
|
|
63
|
-
<a href="https://www.fz-juelich.de/en/iek/iek-3"><img src="https://www.fz-juelich.de/static/media/Logo.2ceb35fc.svg" alt="Forschungszentrum Juelich Logo" width="230px"></a>
|
|
81
|
+
<a href="https://www.fz-juelich.de/en/iek/iek-3"><img src="https://www.fz-juelich.de/static/media/Logo.2ceb35fc.svg" alt="Forschungszentrum Juelich Logo" width="230px"></a>
|
|
64
82
|
|
|
65
83
|
# tsam - Time Series Aggregation Module
|
|
66
84
|
tsam is a python package which uses different machine learning algorithms for the aggregation of time series. The data aggregation can be performed in two freely combinable dimensions: By representing the time series by a user-defined number of typical periods or by decreasing the temporal resolution.
|
|
@@ -72,109 +90,135 @@ The documentation of the tsam code can be found [**here**](https://tsam.readthed
|
|
|
72
90
|
* flexible handling of multidimensional time-series via the pandas module
|
|
73
91
|
* different aggregation methods implemented (averaging, k-means, exact k-medoids, hierarchical, k-maxoids, k-medoids with contiguity), which are based on scikit-learn, or self-programmed with pyomo
|
|
74
92
|
* hypertuning of aggregation parameters to find the optimal combination of the number of segments inside a period and the number of typical periods
|
|
75
|
-
* novel representation methods, keeping statistical attributes, such as the distribution
|
|
93
|
+
* novel representation methods, keeping statistical attributes, such as the distribution
|
|
76
94
|
* flexible integration of extreme periods as own cluster centers
|
|
77
95
|
* weighting for the case of multidimensional time-series to represent their relevance
|
|
78
96
|
|
|
79
97
|
|
|
80
98
|
## Installation
|
|
81
|
-
It is recommended to install tsam within its own environment. If you are no familiar with python environments, plaese consider to read some [external documentation](https://realpython.com/python-virtual-environments-a-primer/). In the following we assume you have a [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html) or [conda](https://www.anaconda.com/) installation. All conda and mamba command are interchangeable.
|
|
82
|
-
|
|
83
|
-
### Direct Installations from Package Manager Repositories
|
|
84
|
-
|
|
85
|
-
If you want to prevent any possible dependency conflicts create a new environment using the following command:
|
|
86
|
-
|
|
87
|
-
mamba create -n tsam_env python pip
|
|
88
|
-
|
|
89
|
-
Activate an existing or the newly create environment afterward
|
|
90
99
|
|
|
91
|
-
|
|
100
|
+
To avoid dependency conflicts, it is recommended that you install Tsam in its own environment. You can use either [uv](https://docs.astral.sh/uv/) or [conda/mamba](https://conda-forge.org/download/) ) to manage environments and installations. Before proceeding, you must install either UV or Conda/Mamba, or both.
|
|
92
101
|
|
|
93
|
-
|
|
102
|
+
**Quick Install with uv**
|
|
94
103
|
|
|
95
|
-
|
|
104
|
+
```bash
|
|
105
|
+
uv venv tsam_env
|
|
106
|
+
uv pip install tsam
|
|
107
|
+
```
|
|
96
108
|
|
|
97
|
-
|
|
109
|
+
Or from conda-forge:
|
|
98
110
|
|
|
99
|
-
|
|
111
|
+
```bash
|
|
112
|
+
conda create -n tsam_env -c conda-forge tsam
|
|
113
|
+
```
|
|
100
114
|
|
|
101
|
-
|
|
102
|
-
Alternatively, clone a local copy of the repository to your computer
|
|
115
|
+
conda and mamba can be used interchangeably
|
|
103
116
|
|
|
104
|
-
|
|
117
|
+
### Development Installation
|
|
105
118
|
|
|
106
|
-
|
|
119
|
+
```bash
|
|
120
|
+
git clone https://github.com/FZJ-IEK3-VSA/tsam.git
|
|
121
|
+
cd tsam
|
|
122
|
+
```
|
|
107
123
|
|
|
108
|
-
|
|
124
|
+
# Using uv (recommended)
|
|
125
|
+
```bash
|
|
126
|
+
uv venv
|
|
127
|
+
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
128
|
+
uv pip install -e ".[develop]"
|
|
129
|
+
```
|
|
109
130
|
|
|
110
|
-
|
|
131
|
+
# Using conda-forge
|
|
111
132
|
|
|
112
|
-
|
|
133
|
+
```bash
|
|
134
|
+
conda env create -n tsam_env --file=environment.yml
|
|
135
|
+
conda activate tsam_env
|
|
136
|
+
pip install -e . --no-deps
|
|
137
|
+
```
|
|
113
138
|
|
|
114
|
-
|
|
139
|
+
# Set up pre-commit hooks
|
|
140
|
+
```bash
|
|
141
|
+
pre-commit install
|
|
142
|
+
```
|
|
115
143
|
|
|
116
|
-
|
|
144
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
|
|
117
145
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
pip install -e .[dev]
|
|
122
|
-
|
|
123
|
-
### Installation of MILP Solver for k-medoids
|
|
124
|
-
In order to use the k-medoids clustering, make sure that you have installed a MILP solver. As default [HiGHS](https://github.com/ERGO-Code/HiGHS) is installed and used. Nevertheless, in case you have access to a license we recommend commercial solvers (e.g. Gurobi or CPLEX) since they have a better performance.
|
|
146
|
+
### MILP Solver for k-medoids
|
|
125
147
|
|
|
126
|
-
|
|
148
|
+
[HiGHS](https://github.com/ERGO-Code/HiGHS) is installed by default. For better performance on large problems, commercial solvers (Gurobi, CPLEX) are recommended if you have a license
|
|
127
149
|
|
|
128
|
-
In order to setup a virtual environment in Linux, correct the python name in the Makefile and call
|
|
129
150
|
|
|
130
|
-
make setup_venv
|
|
131
|
-
|
|
132
|
-
|
|
133
151
|
## Examples
|
|
134
152
|
|
|
135
153
|
### Basic workflow
|
|
136
154
|
|
|
137
|
-
A small example how tsam can be used is
|
|
155
|
+
A small example how tsam can be used is described as follows:
|
|
138
156
|
```python
|
|
139
|
-
|
|
140
|
-
|
|
157
|
+
import pandas as pd
|
|
158
|
+
import tsam
|
|
141
159
|
```
|
|
142
160
|
|
|
143
161
|
|
|
144
162
|
Read in the time series data set with pandas
|
|
145
163
|
```python
|
|
146
|
-
|
|
164
|
+
raw = pd.read_csv('testdata.csv', index_col=0, parse_dates=True)
|
|
147
165
|
```
|
|
148
166
|
|
|
149
|
-
|
|
167
|
+
Run the aggregation - specify the number of typical periods and configure clustering/segmentation options:
|
|
150
168
|
```python
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
169
|
+
from tsam import aggregate, ClusterConfig, SegmentConfig
|
|
170
|
+
|
|
171
|
+
result = tsam.aggregate(
|
|
172
|
+
raw,
|
|
173
|
+
n_clusters=8,
|
|
174
|
+
period_duration='24h', # or 24, '1d'
|
|
175
|
+
cluster=ClusterConfig(
|
|
176
|
+
method='hierarchical',
|
|
177
|
+
representation='distribution_minmax',
|
|
178
|
+
),
|
|
179
|
+
segments=SegmentConfig(n_segments=8),
|
|
180
|
+
)
|
|
160
181
|
```
|
|
161
182
|
|
|
162
|
-
|
|
183
|
+
Access the results:
|
|
163
184
|
```python
|
|
164
|
-
|
|
185
|
+
# Get the typical periods DataFrame
|
|
186
|
+
cluster_representatives = result.cluster_representatives
|
|
187
|
+
|
|
188
|
+
# Check accuracy metrics
|
|
189
|
+
print(f"RMSE: {result.accuracy.rmse.mean():.4f}")
|
|
190
|
+
|
|
191
|
+
# Reconstruct the original time series from typical periods
|
|
192
|
+
reconstructed = result.reconstructed
|
|
193
|
+
|
|
194
|
+
# Save results
|
|
195
|
+
cluster_representatives.to_csv('cluster_representatives.csv')
|
|
165
196
|
```
|
|
166
197
|
|
|
167
|
-
|
|
168
|
-
|
|
198
|
+
### Legacy API
|
|
199
|
+
|
|
200
|
+
For backward compatibility, the class-based API of TSAM Version 2 is still available.
|
|
169
201
|
```python
|
|
170
|
-
|
|
202
|
+
import tsam.timeseriesaggregation as tsam_legacy
|
|
203
|
+
|
|
204
|
+
aggregation = tsam_legacy.TimeSeriesAggregation(
|
|
205
|
+
raw,
|
|
206
|
+
noTypicalPeriods=8,
|
|
207
|
+
hoursPerPeriod=24,
|
|
208
|
+
segmentation=True,
|
|
209
|
+
noSegments=8,
|
|
210
|
+
representationMethod="distributionAndMinMaxRepresentation",
|
|
211
|
+
clusterMethod='hierarchical'
|
|
212
|
+
)
|
|
213
|
+
cluster_representatives = aggregation.createTypicalPeriods()
|
|
171
214
|
```
|
|
172
215
|
|
|
173
216
|
### Detailed examples
|
|
217
|
+
Detailed examples can be found at:/docs/source/examples_notebooks/
|
|
174
218
|
|
|
175
|
-
A [**
|
|
219
|
+
A [**quickstart example**](/docs/source/examples_notebooks/quickstart.ipynb) shows the capabilities of tsam as a Jupyter notebook.
|
|
176
220
|
|
|
177
|
-
A [**second example**](/
|
|
221
|
+
A [**second example**](/docs/source/examples_notebooks/optimization_input.ipynb) shows in more detail how to access the relevant aggregation results required for parameterizing e.g. an optimization.
|
|
178
222
|
|
|
179
223
|
The example time series are based on a department [publication](https://www.mdpi.com/1996-1073/10/3/361) and the [test reference years of the DWD](https://www.dwd.de/DE/leistungen/testreferenzjahre/testreferenzjahre.html).
|
|
180
224
|
|
|
@@ -182,7 +226,7 @@ The example time series are based on a department [publication](https://www.mdpi
|
|
|
182
226
|
|
|
183
227
|
MIT License
|
|
184
228
|
|
|
185
|
-
Copyright (C)
|
|
229
|
+
Copyright (C) 2017-2025 Leander Kotzur (FZJ IEK-3), Maximilian Hoffmann (FZJ IEK-3), Peter Markewitz (FZJ IEK-3), Martin Robinius (FZJ IEK-3), Detlef Stolten (FZJ IEK-3)
|
|
186
230
|
|
|
187
231
|
You should have received a copy of the MIT License along with this program.
|
|
188
232
|
If not, see https://opensource.org/licenses/MIT
|
|
@@ -222,5 +266,3 @@ The publications about time series aggregation for energy system optimization mo
|
|
|
222
266
|
This work is supported by the Helmholtz Association under the Joint Initiative ["Energy System 2050 A Contribution of the Research Field Energy"](https://www.helmholtz.de/en/research/energy/energy_system_2050/) and the program ["Energy System Design"](https://www.esd.kit.edu/index.php) and within the [BMWi/BMWk](https://www.bmwk.de/Navigation/DE/Home/home.html) funded project [**METIS**](http://www.metis-platform.net/).
|
|
223
267
|
|
|
224
268
|
<a href="https://www.helmholtz.de/en/"><img src="https://www.helmholtz.de/fileadmin/user_upload/05_aktuelles/Marke_Design/logos/HG_LOGO_S_ENG_RGB.jpg" alt="Helmholtz Logo" width="200px" style="float:right"></a>
|
|
225
|
-
|
|
226
|
-
|