tsam 2.3.9__tar.gz → 3.0.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.
Files changed (72) hide show
  1. {tsam-2.3.9 → tsam-3.0.0}/LICENSE.txt +21 -21
  2. {tsam-2.3.9 → tsam-3.0.0}/MANIFEST.in +3 -3
  3. {tsam-2.3.9/src/tsam.egg-info → tsam-3.0.0}/PKG-INFO +124 -81
  4. {tsam-2.3.9 → tsam-3.0.0}/README.md +191 -167
  5. tsam-3.0.0/environment.yml +30 -0
  6. tsam-3.0.0/pyproject.toml +137 -0
  7. tsam-3.0.0/src/tsam/__init__.py +79 -0
  8. tsam-3.0.0/src/tsam/api.py +602 -0
  9. tsam-3.0.0/src/tsam/config.py +852 -0
  10. tsam-3.0.0/src/tsam/exceptions.py +17 -0
  11. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/hyperparametertuning.py +289 -245
  12. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/periodAggregation.py +140 -141
  13. tsam-3.0.0/src/tsam/plot.py +513 -0
  14. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/representations.py +177 -167
  15. tsam-3.0.0/src/tsam/result.py +397 -0
  16. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/timeseriesaggregation.py +1446 -1361
  17. tsam-3.0.0/src/tsam/tuning.py +1038 -0
  18. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/utils/durationRepresentation.py +229 -223
  19. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/utils/k_maxoids.py +138 -145
  20. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/utils/k_medoids_contiguity.py +139 -140
  21. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/utils/k_medoids_exact.py +232 -239
  22. tsam-3.0.0/src/tsam/utils/segmentation.py +232 -0
  23. {tsam-2.3.9 → tsam-3.0.0/src/tsam.egg-info}/PKG-INFO +124 -81
  24. {tsam-2.3.9 → tsam-3.0.0}/src/tsam.egg-info/SOURCES.txt +12 -12
  25. tsam-3.0.0/src/tsam.egg-info/requires.txt +33 -0
  26. {tsam-2.3.9 → tsam-3.0.0}/test/test_accuracyIndicators.py +57 -63
  27. {tsam-2.3.9 → tsam-3.0.0}/test/test_adjacent_periods.py +38 -42
  28. {tsam-2.3.9 → tsam-3.0.0}/test/test_aggregate_hiearchical.py +393 -402
  29. tsam-3.0.0/test/test_api_equivalence.py +565 -0
  30. {tsam-2.3.9 → tsam-3.0.0}/test/test_assert_raises.py +231 -234
  31. {tsam-2.3.9 → tsam-3.0.0}/test/test_averaging.py +53 -57
  32. {tsam-2.3.9 → tsam-3.0.0}/test/test_cluster_order.py +130 -132
  33. tsam-3.0.0/test/test_clustering_e2e.py +498 -0
  34. {tsam-2.3.9 → tsam-3.0.0}/test/test_durationCurve.py +59 -63
  35. {tsam-2.3.9 → tsam-3.0.0}/test/test_durationRepresentation.py +140 -148
  36. {tsam-2.3.9 → tsam-3.0.0}/test/test_extremePeriods.py +87 -93
  37. {tsam-2.3.9 → tsam-3.0.0}/test/test_hierarchical.py +79 -78
  38. {tsam-2.3.9 → tsam-3.0.0}/test/test_hypertuneAggregation.py +175 -170
  39. {tsam-2.3.9 → tsam-3.0.0}/test/test_k_maxoids.py +60 -59
  40. {tsam-2.3.9 → tsam-3.0.0}/test/test_k_medoids.py +56 -53
  41. {tsam-2.3.9 → tsam-3.0.0}/test/test_k_medoids_contiguity.py +79 -83
  42. {tsam-2.3.9 → tsam-3.0.0}/test/test_minmaxRepresentation.py +66 -70
  43. tsam-3.0.0/test/test_new_api.py +665 -0
  44. {tsam-2.3.9 → tsam-3.0.0}/test/test_preprocess.py +31 -43
  45. {tsam-2.3.9 → tsam-3.0.0}/test/test_properties.py +204 -208
  46. tsam-3.0.0/test/test_reconstruct_samemean_segmentation.py +111 -0
  47. {tsam-2.3.9 → tsam-3.0.0}/test/test_samemean.py +46 -49
  48. tsam-3.0.0/test/test_segmentation.py +114 -0
  49. {tsam-2.3.9 → tsam-3.0.0}/test/test_subhourlyResolution.py +50 -54
  50. {tsam-2.3.9 → tsam-3.0.0}/test/test_subhourly_periods.py +39 -41
  51. {tsam-2.3.9 → tsam-3.0.0}/test/test_weightingFactors.py +64 -70
  52. tsam-2.3.9/examples/results/paretoOptimalAggregation.csv +0 -389
  53. tsam-2.3.9/examples/results/preprocessed_wind.csv +0 -368
  54. tsam-2.3.9/examples/results/testperiods_hierarchical.csv +0 -241
  55. tsam-2.3.9/examples/results/testperiods_kmeans.csv +0 -193
  56. tsam-2.3.9/examples/results/testperiods_kmedoids.csv +0 -1345
  57. tsam-2.3.9/examples/results/testperiods_predefClusterOrder.csv +0 -193
  58. tsam-2.3.9/examples/results/testperiods_predefClusterOrderAndClusterCenters.csv +0 -193
  59. tsam-2.3.9/examples/results/testperiods_segmentation.csv +0 -241
  60. tsam-2.3.9/examples/testdata.csv +0 -8761
  61. tsam-2.3.9/pyproject.toml +0 -53
  62. tsam-2.3.9/requirements.txt +0 -7
  63. tsam-2.3.9/requirements.yml +0 -6
  64. tsam-2.3.9/requirements_dev.txt +0 -12
  65. tsam-2.3.9/src/tsam/utils/segmentation.py +0 -118
  66. tsam-2.3.9/src/tsam.egg-info/requires.txt +0 -16
  67. tsam-2.3.9/test/test_segmentation.py +0 -109
  68. {tsam-2.3.9 → tsam-3.0.0}/setup.cfg +0 -0
  69. /tsam-2.3.9/src/tsam/__init__.py → /tsam-3.0.0/src/tsam/py.typed +0 -0
  70. {tsam-2.3.9 → tsam-3.0.0}/src/tsam/utils/__init__.py +0 -0
  71. {tsam-2.3.9 → tsam-3.0.0}/src/tsam.egg-info/dependency_links.txt +0 -0
  72. {tsam-2.3.9 → tsam-3.0.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 requirements.yml
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: 2.3.9
3
+ Version: 3.0.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,52 @@ 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.14,>=3.9
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>=0.0
44
- Requires-Dist: pandas>=2.0.3
45
- Requires-Dist: numpy>=1.20.0
46
- Requires-Dist: pyomo>=6.4.3
47
- Requires-Dist: networkx
48
- Requires-Dist: tqdm
49
- Requires-Dist: highspy
50
- Provides-Extra: dev
51
- Requires-Dist: pytest; extra == "dev"
52
- Requires-Dist: pytest-cov; extra == "dev"
53
- Requires-Dist: codecov; extra == "dev"
54
- Requires-Dist: sphinx; extra == "dev"
55
- Requires-Dist: sphinx-autobuild; extra == "dev"
56
- Requires-Dist: sphinx_book_theme; extra == "dev"
57
- Requires-Dist: twine; extra == "dev"
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.1,>=4.21.0
53
+ Requires-Dist: highspy<=1.12.0,>=1.7.2
54
+ Provides-Extra: plot
55
+ Requires-Dist: plotly>=5.0.0; extra == "plot"
56
+ Provides-Extra: notebooks
57
+ Requires-Dist: notebook>=7.5.0; extra == "notebooks"
58
+ Requires-Dist: plotly>=5.0.0; extra == "notebooks"
59
+ Requires-Dist: matplotlib; extra == "notebooks"
60
+ Provides-Extra: develop
61
+ Requires-Dist: pytest; extra == "develop"
62
+ Requires-Dist: pytest-cov; extra == "develop"
63
+ Requires-Dist: pytest-xdist; extra == "develop"
64
+ Requires-Dist: codecov; extra == "develop"
65
+ Requires-Dist: sphinx; extra == "develop"
66
+ Requires-Dist: sphinx-autobuild; extra == "develop"
67
+ Requires-Dist: sphinx_book_theme; extra == "develop"
68
+ Requires-Dist: twine; extra == "develop"
69
+ Requires-Dist: nbval; extra == "develop"
70
+ Requires-Dist: ruff; extra == "develop"
71
+ Requires-Dist: mypy; extra == "develop"
72
+ Requires-Dist: pandas-stubs; extra == "develop"
73
+ Requires-Dist: pre-commit; extra == "develop"
74
+ Requires-Dist: plotly>=5.0.0; extra == "develop"
75
+ Requires-Dist: notebook>=7.5.0; extra == "develop"
76
+ Requires-Dist: matplotlib; extra == "develop"
58
77
  Dynamic: license-file
59
78
 
60
- [![daily pytest](https://github.com/FZJ-IEK3-VSA/tsam/actions/workflows/daily_tests.yml/badge.svg?branch=master)](https://github.com/FZJ-IEK3-VSA/tsam/actions) [![Version](https://img.shields.io/pypi/v/tsam.svg)](https://pypi.python.org/pypi/tsam) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/tsam.svg)](https://anaconda.org/conda-forge/tsam) [![Documentation Status](https://readthedocs.org/projects/tsam/badge/?version=latest)](https://tsam.readthedocs.io/en/latest/) [![PyPI - License](https://img.shields.io/pypi/l/tsam)]((https://github.com/FZJ-IEK3-VSA/tsam/blob/master/LICENSE.txt)) [![codecov](https://codecov.io/gh/FZJ-IEK3-VSA/tsam/branch/master/graph/badge.svg)](https://codecov.io/gh/FZJ-IEK3-VSA/tsam)
79
+ [![Version](https://img.shields.io/pypi/v/tsam.svg)](https://pypi.python.org/pypi/tsam) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/tsam.svg)](https://anaconda.org/conda-forge/tsam) [![Documentation Status](https://readthedocs.org/projects/tsam/badge/?version=latest)](https://tsam.readthedocs.io/en/latest/) [![PyPI - License](https://img.shields.io/pypi/l/tsam)]((https://github.com/FZJ-IEK3-VSA/tsam/blob/master/LICENSE.txt)) [![codecov](https://codecov.io/gh/FZJ-IEK3-VSA/tsam/branch/master/graph/badge.svg)](https://codecov.io/gh/FZJ-IEK3-VSA/tsam)
61
80
  [![badge](https://img.shields.io/badge/launch-binder-579aca.svg?logo=data:image/png;base64,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)](https://mybinder.org/v2/gh/FZJ-IEK3-VSA/voila-tsam/HEAD?urlpath=voila/render/Time-Series-Aggregation-Module.ipynb)
62
81
 
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>
82
+ <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
83
 
65
84
  # tsam - Time Series Aggregation Module
66
85
  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 +91,135 @@ The documentation of the tsam code can be found [**here**](https://tsam.readthed
72
91
  * flexible handling of multidimensional time-series via the pandas module
73
92
  * 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
93
  * 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
94
+ * novel representation methods, keeping statistical attributes, such as the distribution
76
95
  * flexible integration of extreme periods as own cluster centers
77
96
  * weighting for the case of multidimensional time-series to represent their relevance
78
97
 
79
98
 
80
99
  ## 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
100
 
91
- mamba activate tsam_env
101
+ 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
102
 
93
- Directly install via pip from pypi as follows:
103
+ **Quick Install with uv**
94
104
 
95
- pip install tsam
105
+ ```bash
106
+ uv venv tsam_env
107
+ uv pip install tsam
108
+ ```
96
109
 
97
- or install from conda forge with the following command:
110
+ Or from conda-forge:
98
111
 
99
- conda install tsam -c conda-forge
112
+ ```bash
113
+ conda create -n tsam_env -c conda-forge tsam
114
+ ```
100
115
 
101
- ### Local Installation for Development
102
- Alternatively, clone a local copy of the repository to your computer
116
+ conda and mamba can be used interchangeably
103
117
 
104
- git clone https://github.com/FZJ-IEK3-VSA/tsam.git
118
+ ### Development Installation
105
119
 
106
- Change the directory of your shell into the root folder of the repository
120
+ ```bash
121
+ git clone https://github.com/FZJ-IEK3-VSA/tsam.git
122
+ cd tsam
123
+ ```
107
124
 
108
- cd tsam
125
+ # Using uv (recommended)
126
+ ```bash
127
+ uv venv
128
+ source .venv/bin/activate # On Windows: .venv\Scripts\activate
129
+ uv pip install -e ".[develop]"
130
+ ```
109
131
 
110
- For development, it is recommended to install tsam into its own environment using conda e.g.
132
+ # Using conda-forge
111
133
 
112
- conda env create --file=requirement.yml
134
+ ```bash
135
+ conda env create -n tsam_env --file=environment.yml
136
+ conda activate tsam_env
137
+ pip install -e . --no-deps
138
+ ```
113
139
 
114
- Afterward activate the environment
140
+ # Set up pre-commit hooks
141
+ ```bash
142
+ pre-commit install
143
+ ```
115
144
 
116
- conda activate tsam_env
145
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
117
146
 
118
- Then install tsam via pip as follows
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.
147
+ ### MILP Solver for k-medoids
125
148
 
126
- ### Developer installation
149
+ [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
150
 
128
- In order to setup a virtual environment in Linux, correct the python name in the Makefile and call
129
151
 
130
- make setup_venv
131
-
132
-
133
152
  ## Examples
134
153
 
135
154
  ### Basic workflow
136
155
 
137
- A small example how tsam can be used is decribed as follows
156
+ A small example how tsam can be used is described as follows:
138
157
  ```python
139
- import pandas as pd
140
- import tsam.timeseriesaggregation as tsam
158
+ import pandas as pd
159
+ import tsam
141
160
  ```
142
161
 
143
162
 
144
163
  Read in the time series data set with pandas
145
164
  ```python
146
- raw = pd.read_csv('testdata.csv', index_col = 0)
165
+ raw = pd.read_csv('testdata.csv', index_col=0, parse_dates=True)
147
166
  ```
148
167
 
149
- Initialize an aggregation object and define the length of a single period, the number of typical periods, the number of segments in each period, the aggregation method and the representation method - here duration/distribution representation which contains the minimum and maximum value of the original time series
168
+ Run the aggregation - specify the number of typical periods and configure clustering/segmentation options:
150
169
  ```python
151
- aggregation = tsam.TimeSeriesAggregation(raw,
152
- noTypicalPeriods = 8,
153
- hoursPerPeriod = 24,
154
- segmentation = True,
155
- noSegments = 8,
156
- representationMethod = "distributionAndMinMaxRepresentation",
157
- distributionPeriodWise = False
158
- clusterMethod = 'hierarchical'
159
- )
170
+ from tsam import aggregate, ClusterConfig, SegmentConfig
171
+
172
+ result = tsam.aggregate(
173
+ raw,
174
+ n_clusters=8,
175
+ period_duration='24h', # or 24, '1d'
176
+ cluster=ClusterConfig(
177
+ method='hierarchical',
178
+ representation='distribution_minmax',
179
+ ),
180
+ segments=SegmentConfig(n_segments=8),
181
+ )
160
182
  ```
161
183
 
162
- Run the aggregation to typical periods
184
+ Access the results:
163
185
  ```python
164
- typPeriods = aggregation.createTypicalPeriods()
186
+ # Get the typical periods DataFrame
187
+ cluster_representatives = result.cluster_representatives
188
+
189
+ # Check accuracy metrics
190
+ print(f"RMSE: {result.accuracy.rmse.mean():.4f}")
191
+
192
+ # Reconstruct the original time series from typical periods
193
+ reconstructed = result.reconstructed
194
+
195
+ # Save results
196
+ cluster_representatives.to_csv('cluster_representatives.csv')
165
197
  ```
166
198
 
167
- Store the results as .csv file
168
-
199
+ ### Legacy API
200
+
201
+ For backward compatibility, the class-based API of TSAM Version 2 is still available.
169
202
  ```python
170
- typPeriods.to_csv('typperiods.csv')
203
+ import tsam.timeseriesaggregation as tsam_legacy
204
+
205
+ aggregation = tsam_legacy.TimeSeriesAggregation(
206
+ raw,
207
+ noTypicalPeriods=8,
208
+ hoursPerPeriod=24,
209
+ segmentation=True,
210
+ noSegments=8,
211
+ representationMethod="distributionAndMinMaxRepresentation",
212
+ clusterMethod='hierarchical'
213
+ )
214
+ cluster_representatives = aggregation.createTypicalPeriods()
171
215
  ```
172
216
 
173
217
  ### Detailed examples
218
+ Detailed examples can be found at:/docs/source/examples_notebooks/
174
219
 
175
- A [**first example**](/examples/aggregation_example.ipynb) shows the capabilites of tsam as jupyter notebook.
220
+ A [**first example**](/docs/source/examples_notebooks/aggregation_example.ipynb) shows the capabilites of tsam as jupyter notebook.
176
221
 
177
- A [**second example**](/examples/aggregation_optiinput.ipynb) shows in more detail how to access the relevant aggregation results required for paramtrizing e.g. an optimization.
222
+ A [**second example**](/docs/source/examples_notebooks/aggregation_optiinput.ipynb) shows in more detail how to access the relevant aggregation results required for paramtrizing e.g. an optimization.
178
223
 
179
224
  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
225
 
@@ -182,7 +227,7 @@ The example time series are based on a department [publication](https://www.mdpi
182
227
 
183
228
  MIT License
184
229
 
185
- Copyright (C) 2016-2022 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)
230
+ 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
231
 
187
232
  You should have received a copy of the MIT License along with this program.
188
233
  If not, see https://opensource.org/licenses/MIT
@@ -222,5 +267,3 @@ The publications about time series aggregation for energy system optimization mo
222
267
  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
268
 
224
269
  <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
-