tsam

A Python package which uses different machine learning algorithms for the aggregation of time series.
https://github.com/fzj-iek3-vsa/tsam

Category: Energy Systems
Sub Category: Energy System Modeling Frameworks

Keywords

aggregation clustering energy-system optimization python time-series timeseries typical-periods

Keywords from Contributors

energy-system-modeling renewable-energy geospatial-analysis optimisation pyomo climate-change energy-systems renewables modelling-framework linopy

Last synced: about 12 hours ago
JSON representation

Repository metadata

Time series aggregation module (tsam). Determines typical operation periods or decreases the temporal resolution. Accelerates model or experiment runs.

Host: GitHub
URL: https://github.com/fzj-iek3-vsa/tsam
Owner: FZJ-IEK3-VSA
License: mit
Created: 2017-05-15T08:36:11.000Z (over 9 years ago)
Default Branch: develop
Last Pushed: 2026-08-10T09:17:14.000Z (5 days ago)
Last Synced: 2026-08-10T14:08:29.422Z (5 days ago)
Topics: aggregation, clustering, energy-system, optimization, python, time-series, timeseries, typical-periods
Language: Python
Homepage: https://tsam.readthedocs.io/
Size: 243 MB
Stars: 177
Watchers: 7
Forks: 40
Open Issues: 33
Releases: 35
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Agents: AGENTS.md
- Claude: CLAUDE.md

ETHOS.TSAM - Time Series Aggregation Module

Time series aggregation for large optimization models — and any other time series.

📖 Read the full documentation at tsam.readthedocs.io.

ETHOS.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.
ETHOS.TSAM was originally designed for reducing the computational load for large-scale energy system optimization models by aggregating their input data, but is applicable for all types of time series, e.g., weather data, load data, both simultaneously or other arbitrary groups of time series.

ETHOS.TSAM is part of the Energy Transformation PatHway Optimization Suite (ETHOS) at ICE-2. It is tightly integrated into ETHOS.FINE to reduce the temporal complexity of energy system models.

Features

flexible handling of multidimensional time-series via the pandas module
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
hypertuning of aggregation parameters to find the optimal combination of the number of segments inside a period and the number of typical periods
novel representation methods, keeping statistical attributes, such as the distribution
flexible integration of extreme periods as own cluster centers
weighting for the case of multidimensional time-series to represent their relevance

Installation

To avoid dependency conflicts, it is recommended that you install ETHOS.TSAM in its own environment. You can use either uv or conda/mamba to manage environments and installations. Before proceeding, you must install either UV or Conda/Mamba, or both.

Quick Install with uv

uv venv tsam_env
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install tsam

Or from conda-forge:

conda create -n tsam_env -c conda-forge tsam

conda and mamba can be used interchangeably

Development Installation

git clone https://github.com/FZJ-IEK3-VSA/tsam.git
cd tsam

Using uv (recommended)

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[develop]"

Using conda-forge

conda env create -n tsam_env --file=environment.yml
conda activate tsam_env
pip install -e . --no-deps

Set up pre-commit hooks

pre-commit install

See CONTRIBUTING.md for detailed development guidelines.

MILP Solver for k-medoids

HiGHS is installed by default. For better performance on large problems, commercial solvers (Gurobi, CPLEX) are recommended if you have a license

Getting Started

Basic workflow

A small example how ETHOS.TSAM can be used is described as follows:

import pandas as pd
import tsam

Read in the time series data set with pandas

raw = pd.read_csv('testdata.csv', index_col=0, parse_dates=True)

Run the aggregation - specify the number of typical periods and configure clustering/segmentation options:

from tsam import aggregate, ClusterConfig, SegmentConfig

result = tsam.aggregate(
    raw,
    n_clusters=8,
    period_duration='24h',  # or 24, '1d'
    cluster=ClusterConfig(
        method='hierarchical',
        representation='distribution_minmax',
    ),
    segments=SegmentConfig(n_segments=8),
)

Access the results:

# Get the typical periods DataFrame
cluster_representatives = result.cluster_representatives

# Check accuracy metrics
print(f"RMSE: {result.accuracy.rmse.mean():.4f}")

# Reconstruct the original time series from typical periods
reconstructed = result.reconstructed

# Save results
cluster_representatives.to_csv('cluster_representatives.csv')

Coming from version 2 or 3?

The class-based TimeSeriesAggregation API has been removed in version 4 — use
tsam.aggregate() as shown above. The
migration guide maps every old
parameter, method, and default to its replacement.

Detailed examples

The documentation is built around runnable notebooks:

Your first aggregation — the whole workflow end to end, as a Jupyter notebook.
Optimization workflow — how to access the aggregation results needed to parameterize e.g. an optimization.

The example time series are based on a department publication and the test reference years of the DWD.

Citation

If you want to use ETHOS.TSAM in a published work, please kindly cite:

Hoffmann et al. (2022):
The Pareto-Optimal Temporal Aggregation of Energy System Models

Contributions and Support

All contributions are welcome:

If you have a question, want to report a bug, or have a feature request, please open an Issue. We will then take care of the issue as soon as possible.
If you want to contribute with additional features or code improvements, open a Pull request.

See CONTRIBUTING.md for development guidelines.

License

MIT License

About Us

We are the Institute of Climate and Energy Systems – Jülich Systems Analysis (ICE-2) at the Forschungszentrum Jülich.
Our work focuses on independent, interdisciplinary research in energy, bioeconomy, infrastructure, and sustainability. We support a just, greenhouse gas–neutral transformation through open models and policy-relevant science.

Code of Conduct

Please respect our code of conduct.

Acknowledgments

This work is supported by the Helmholtz Association under the Joint Initiative "Energy System 2050 – A Contribution of the Research Field Energy" and the program "Energy System Design" and within the BMWi/BMWk funded project METIS.

Owner metadata

Name: Forschungszentrum Jülich - Jülich Systems Analysis
Login: FZJ-IEK3-VSA
Email:
Kind: organization
Description: Institute of Climate and Energy Systems (ICE)
Website: https://www.fz-juelich.de/iek/iek-3/EN/Home/home_node.html
Location: Forschungszentrum Jülich
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/28654423?v=4
Repositories: 16
Last ynced at: 2024-12-23T04:12:17.721Z
Profile URL: https://github.com/FZJ-IEK3-VSA

GitHub Events

Total

Release event: 1
Delete event: 27
Pull request event: 59
Fork event: 4
Issues event: 17
Watch event: 22
Issue comment event: 56
Push event: 193
Pull request review comment event: 17
Pull request review event: 24
Create event: 72

Last Year

Delete event: 27
Pull request event: 54
Issues event: 13
Watch event: 6
Issue comment event: 46
Push event: 188
Pull request review comment event: 17
Pull request review event: 20
Create event: 69

Committers metadata

Last synced: 3 days ago

Total Commits: 626
Total Committers: 30
Avg Commits per committer: 20.867
Development Distribution Score (DDS): 0.754

Commits in past year: 302
Committers in past year: 11
Avg Commits per committer in past year: 27.455
Development Distribution Score (DDS) in past year: 0.49

Name	Email	Commits
FBumann	1****n	154
l-kotzur	l**r@f**e	139
maximilian-hoffmann	m**n@f**e	98
renovate[bot]	2****]	79
Julian Belina	5****a	39
Leander Kotzur	l**r@r**e	26
j.belina	j**a@f**e	19
j.schoenau	j**u@f**e	10
jo-omoyele	j**e@g**m	10
Julian Schönau	6****e	7
fzj-iek3-vsa-release-bot[bot]	2****]	5
Cord Kaldemeyer	c**r@f**e	4
Fabian Neumann	f**n@o**e	4
Samuel Letellier-Duchesne	s**e@m**m	4
Robert Schwarz	r**t@d**l	3
dependabot[bot]	4****]	3
github-actions[bot]	4****]	3
Amedeo Paolo Ceruti	g**z@m**e	3
Lars Schellhas	l**s@o**m	2
Philipp Dunkel	8****j	2
andreas smolenko	a**o@f**e	2
simnh	s**t@u**e	2
Amedeo Ceruti	a**i@t**e	1
Francesco Witte	g**b@w**h	1
Sai Asish Y	s**5@g**m	1
Vincent Gao	g**0@g**m	1
ar-fu	a**s@r**e	1
Dilara Gulcin Caglayan	d**n@f**e	1
noah80	n****0	1
rodo	r**d@d**m	1

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 57
Total pull requests: 197
Average time to close issues: 5 months
Average time to close pull requests: 12 days
Total issue authors: 23
Total pull request authors: 26
Average comments per issue: 2.04
Average comments per pull request: 0.95
Merged pull request: 136
Bot issues: 1
Bot pull requests: 45

Past year issues: 18
Past year pull requests: 125
Past year average time to close issues: 18 days
Past year average time to close pull requests: 5 days
Past year issue authors: 6
Past year pull request authors: 9
Past year average comments per issue: 1.33
Past year average comments per pull request: 0.82
Past year merged pull request: 82
Past year bot issues: 1
Past year bot pull requests: 45

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/fzj-iek3-vsa/tsam

Top Issue Authors

FBumann (9)
julian-belina (9)
ckaldemeyer (7)
l-kotzur (6)
l-welder (4)
phil-fzj (3)
adbuerger (2)
sbruche (2)
curiousleo (1)
jacob-mannhardt (1)
jo-omoyele (1)
alicia-le (1)
mfleschutz (1)
renovate[bot] (1)
fneum (1)

Top Pull Request Authors

FBumann (65)
renovate[bot] (39)
l-kotzur (28)
julian-belina (16)
maximilian-hoffmann (7)
OfficialCodexplosive (7)
jo-omoyele (4)
larsschellhas (3)
phil-fzj (3)
ddceruti (3)
fzj-iek3-vsa-release-bot[bot] (3)
fneum (2)
github-actions[bot] (2)
ar-fu (2)
samuelduchesne (2)

Top Issue Labels

bug (4)
enhancement (3)

Top Pull Request Labels

dependencies (40)
performance (9)
enhancement (3)
bug (2)
github-actions (2)
documentation (2)
determinism (2)
autorelease: tagged (2)
autorelease: pending (1)

Package metadata

Total packages: 4
Total downloads:
- pypi: 60,861 last-month
Total dependent packages: 7 (may contain duplicates)
Total dependent repositories: 29 (may contain duplicates)
Total versions: 96
Total maintainers: 5

pypi.org: tsam

Time series aggregation module (tsam) to create typical periods

Homepage:
Documentation: https://tsam.readthedocs.io/
Licenses: MIT License
Latest release: 4.0.0 (published 12 days ago)
Last Synced: 2026-08-13T17:31:18.987Z (1 day ago)
Versions: 41
Dependent Packages: 6
Dependent Repositories: 29
Downloads: 60,861 Last month
Rankings:
- Dependent packages count: 1.596%
- Dependent repos count: 2.716%
- Average: 4.737%
- Downloads: 6.188%
- Stargazers count: 6.257%
- Forks count: 6.928%
Maintainers (5)
- l.kotzur
- machaitch1993
- t-gross
- j.belina
- j-weinand

proxy.golang.org: github.com/fzj-iek3-vsa/tsam

Homepage:
Documentation: https://pkg.go.dev/github.com/fzj-iek3-vsa/tsam#section-documentation
Licenses: mit
Latest release: v4.0.0+incompatible (published 12 days ago)
Last Synced: 2026-08-13T17:30:53.706Z (1 day ago)
Versions: 27
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 6.999%
- Average: 8.173%
- Dependent repos count: 9.346%

proxy.golang.org: github.com/FZJ-IEK3-VSA/tsam

Homepage:
Documentation: https://pkg.go.dev/github.com/FZJ-IEK3-VSA/tsam#section-documentation
Licenses: mit
Latest release: v4.0.0+incompatible (published 12 days ago)
Last Synced: 2026-08-13T17:31:34.098Z (1 day ago)
Versions: 27
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 6.999%
- Average: 8.173%
- Dependent repos count: 9.346%

conda-forge.org: tsam

Homepage: https://github.com/FZJ-IEK3-VSA/tsam
Licenses: MIT
Latest release: 2.0.1 (published over 4 years ago)
Last Synced: 2026-04-02T15:47:50.344Z (4 months ago)
Versions: 1
Dependent Packages: 1
Dependent Repositories: 0
Rankings:
- Dependent packages count: 28.82%
- Stargazers count: 29.339%
- Forks count: 29.863%
- Average: 30.512%
- Dependent repos count: 34.025%

Dependencies

.github/workflows/coverage.yaml actions

actions/checkout v7 composite
actions/setup-python v7 composite
astral-sh/setup-uv v9.0.0 composite
codecov/codecov-action v7 composite

.github/workflows/pr-title.yaml actions

amannn/action-semantic-pull-request v6 composite

.github/workflows/pre-commit-autofix.yaml actions

actions/checkout v7 composite
actions/setup-python v7 composite
astral-sh/setup-uv v9.0.0 composite
peter-evans/create-pull-request v8 composite
pre-commit/action v3.0.1 composite

.github/workflows/push_to_jugit.yml actions

.github/workflows/ci-master.yaml actions

actions/checkout v7 composite
actions/setup-python v7 composite
astral-sh/setup-uv v9.0.0 composite
pre-commit/action v3.0.1 composite

.github/workflows/release.yaml actions

actions/checkout v7 composite
actions/create-github-app-token v3 composite
googleapis/release-please-action v5 composite

.github/workflows/publish.yaml actions

actions/checkout v7 composite
actions/setup-python v7 composite
astral-sh/setup-uv v9.0.0 composite
pypa/gh-action-pypi-publish release/v1 composite

.github/workflows/ci-develop.yaml actions

actions/checkout v7 composite
actions/setup-python v7 composite
astral-sh/setup-uv v9.0.0 composite
pre-commit/action v3.0.1 composite

environment.yml conda

codecov <=2.1.13
d2
highspy >=1.7.2,<=1.15.1
mkdocs >=1.6,<=1.6.1
mkdocs-gen-files >=0.5,<=0.6.1
mkdocs-jupyter >=0.25,<=0.25.1
mkdocs-literate-nav >=0.6,<=0.6.3
mkdocs-material >=9.5,<=9.7.7
mkdocstrings-python >=0.27,<=2.0.5
mypy <=2.3.0
nbval <=0.11.0
notebook >=7.5.0,<=7.6.1
numpy >=1.22.4,<=2.4.6
pandas >=2.2.0,<=3.0.5
pandas-stubs <=3.0.5.260730
pip
plotly >=5.0.0,<=6.9.0
pre-commit <=4.6.1
pyomo >=6.4.3,<=6.10.1
pytest <=9.1.1
pytest-cov <=7.1.0
pytest-xdist <=3.8.0
python >=3.10,<=3.14.6
ruff <=0.16.2
scikit-learn >=1.3.0,<=1.9.0
tqdm >=4.21.0,<=4.70.0

pyproject.toml pypi

highspy >=1.7.2,<=1.15.1
numpy >=1.22.4,<=2.4.6
pandas >=2.2.0,<=3.0.5
pyomo >=6.4.8,<=6.10.1
scikit-learn >=1.3.0,<=1.9.0
scipy >=1.9.0,<=1.18.0
tqdm >=4.21.0,<=4.70.0

Score: 19.765326206260863