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.
Files changed (73) hide show
  1. {tsam-2.3.9 → tsam-3.1.0}/LICENSE.txt +21 -21
  2. {tsam-2.3.9 → tsam-3.1.0}/MANIFEST.in +3 -3
  3. {tsam-2.3.9/src/tsam.egg-info → tsam-3.1.0}/PKG-INFO +123 -81
  4. {tsam-2.3.9 → tsam-3.1.0}/README.md +191 -167
  5. tsam-3.1.0/environment.yml +30 -0
  6. tsam-3.1.0/pyproject.toml +137 -0
  7. tsam-3.1.0/src/tsam/__init__.py +79 -0
  8. tsam-3.1.0/src/tsam/api.py +603 -0
  9. tsam-3.1.0/src/tsam/config.py +891 -0
  10. tsam-3.1.0/src/tsam/exceptions.py +17 -0
  11. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/hyperparametertuning.py +289 -245
  12. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/periodAggregation.py +140 -141
  13. tsam-3.1.0/src/tsam/plot.py +513 -0
  14. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/representations.py +177 -167
  15. tsam-3.1.0/src/tsam/result.py +397 -0
  16. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/timeseriesaggregation.py +1526 -1361
  17. tsam-3.1.0/src/tsam/tuning.py +1038 -0
  18. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/durationRepresentation.py +229 -223
  19. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/k_maxoids.py +138 -145
  20. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/k_medoids_contiguity.py +139 -140
  21. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/k_medoids_exact.py +232 -239
  22. tsam-3.1.0/src/tsam/utils/segmentation.py +232 -0
  23. {tsam-2.3.9 → tsam-3.1.0/src/tsam.egg-info}/PKG-INFO +123 -81
  24. {tsam-2.3.9 → tsam-3.1.0}/src/tsam.egg-info/SOURCES.txt +12 -12
  25. tsam-3.1.0/src/tsam.egg-info/requires.txt +32 -0
  26. {tsam-2.3.9 → tsam-3.1.0}/test/test_accuracyIndicators.py +57 -63
  27. {tsam-2.3.9 → tsam-3.1.0}/test/test_adjacent_periods.py +38 -42
  28. {tsam-2.3.9 → tsam-3.1.0}/test/test_aggregate_hiearchical.py +393 -402
  29. tsam-3.1.0/test/test_api_equivalence.py +565 -0
  30. {tsam-2.3.9 → tsam-3.1.0}/test/test_assert_raises.py +231 -234
  31. {tsam-2.3.9 → tsam-3.1.0}/test/test_averaging.py +53 -57
  32. {tsam-2.3.9 → tsam-3.1.0}/test/test_cluster_order.py +130 -132
  33. tsam-3.1.0/test/test_clustering_e2e.py +498 -0
  34. {tsam-2.3.9 → tsam-3.1.0}/test/test_durationCurve.py +59 -63
  35. {tsam-2.3.9 → tsam-3.1.0}/test/test_durationRepresentation.py +140 -148
  36. tsam-3.1.0/test/test_extremePeriods.py +237 -0
  37. {tsam-2.3.9 → tsam-3.1.0}/test/test_hierarchical.py +79 -78
  38. {tsam-2.3.9 → tsam-3.1.0}/test/test_hypertuneAggregation.py +175 -170
  39. {tsam-2.3.9 → tsam-3.1.0}/test/test_k_maxoids.py +60 -59
  40. {tsam-2.3.9 → tsam-3.1.0}/test/test_k_medoids.py +56 -53
  41. {tsam-2.3.9 → tsam-3.1.0}/test/test_k_medoids_contiguity.py +79 -83
  42. {tsam-2.3.9 → tsam-3.1.0}/test/test_minmaxRepresentation.py +66 -70
  43. tsam-3.1.0/test/test_new_api.py +665 -0
  44. {tsam-2.3.9 → tsam-3.1.0}/test/test_preprocess.py +31 -43
  45. {tsam-2.3.9 → tsam-3.1.0}/test/test_properties.py +204 -208
  46. tsam-3.1.0/test/test_reconstruct_samemean_segmentation.py +111 -0
  47. {tsam-2.3.9 → tsam-3.1.0}/test/test_samemean.py +46 -49
  48. tsam-3.1.0/test/test_segmentation.py +114 -0
  49. {tsam-2.3.9 → tsam-3.1.0}/test/test_subhourlyResolution.py +50 -54
  50. {tsam-2.3.9 → tsam-3.1.0}/test/test_subhourly_periods.py +39 -41
  51. {tsam-2.3.9 → tsam-3.1.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_extremePeriods.py +0 -93
  68. tsam-2.3.9/test/test_segmentation.py +0 -109
  69. {tsam-2.3.9 → tsam-3.1.0}/setup.cfg +0 -0
  70. /tsam-2.3.9/src/tsam/__init__.py → /tsam-3.1.0/src/tsam/py.typed +0 -0
  71. {tsam-2.3.9 → tsam-3.1.0}/src/tsam/utils/__init__.py +0 -0
  72. {tsam-2.3.9 → tsam-3.1.0}/src/tsam.egg-info/dependency_links.txt +0 -0
  73. {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 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.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.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.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
- [![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)
78
+ [![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
79
  [![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
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
- mamba activate tsam_env
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
- Directly install via pip from pypi as follows:
102
+ **Quick Install with uv**
94
103
 
95
- pip install tsam
104
+ ```bash
105
+ uv venv tsam_env
106
+ uv pip install tsam
107
+ ```
96
108
 
97
- or install from conda forge with the following command:
109
+ Or from conda-forge:
98
110
 
99
- conda install tsam -c conda-forge
111
+ ```bash
112
+ conda create -n tsam_env -c conda-forge tsam
113
+ ```
100
114
 
101
- ### Local Installation for Development
102
- Alternatively, clone a local copy of the repository to your computer
115
+ conda and mamba can be used interchangeably
103
116
 
104
- git clone https://github.com/FZJ-IEK3-VSA/tsam.git
117
+ ### Development Installation
105
118
 
106
- Change the directory of your shell into the root folder of the repository
119
+ ```bash
120
+ git clone https://github.com/FZJ-IEK3-VSA/tsam.git
121
+ cd tsam
122
+ ```
107
123
 
108
- cd tsam
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
- For development, it is recommended to install tsam into its own environment using conda e.g.
131
+ # Using conda-forge
111
132
 
112
- conda env create --file=requirement.yml
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
- Afterward activate the environment
139
+ # Set up pre-commit hooks
140
+ ```bash
141
+ pre-commit install
142
+ ```
115
143
 
116
- conda activate tsam_env
144
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.
117
145
 
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.
146
+ ### MILP Solver for k-medoids
125
147
 
126
- ### Developer installation
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 decribed as follows
155
+ A small example how tsam can be used is described as follows:
138
156
  ```python
139
- import pandas as pd
140
- import tsam.timeseriesaggregation as tsam
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
- raw = pd.read_csv('testdata.csv', index_col = 0)
164
+ raw = pd.read_csv('testdata.csv', index_col=0, parse_dates=True)
147
165
  ```
148
166
 
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
167
+ Run the aggregation - specify the number of typical periods and configure clustering/segmentation options:
150
168
  ```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
- )
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
- Run the aggregation to typical periods
183
+ Access the results:
163
184
  ```python
164
- typPeriods = aggregation.createTypicalPeriods()
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
- Store the results as .csv file
168
-
198
+ ### Legacy API
199
+
200
+ For backward compatibility, the class-based API of TSAM Version 2 is still available.
169
201
  ```python
170
- typPeriods.to_csv('typperiods.csv')
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 [**first example**](/examples/aggregation_example.ipynb) shows the capabilites of tsam as jupyter notebook.
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**](/examples/aggregation_optiinput.ipynb) shows in more detail how to access the relevant aggregation results required for paramtrizing e.g. an optimization.
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) 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)
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
-