Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

Recent Releases of tsam

tsam - v3.4.1

3.4.1 (2026-05-31)

Bug Fixes

  • warn that aggregate() column order will change in v4 (#330) (97f6e6d)

Energy Systems - Energy System Modeling Frameworks - Python
Published by fzj-iek3-vsa-release-bot[bot] 26 days ago

tsam - v3.4.0

3.4.0 (2026-05-15)

Features

  • preserve DatetimeIndex through aggregate/disaggregate round-trip (#267) (8d0240a)

Bug Fixes

  • ci: gracefully skip GitHub release when already created by release-please (#260) (6fc668d)
  • handle missing columns in weightDict in accuracyIndicators (#288) (a475570)

Energy Systems - Energy System Modeling Frameworks - Python
Published by fzj-iek3-vsa-release-bot[bot] about 1 month ago

tsam - v3.3.0

3.3.0 (2026-03-30)

Features

  • AccuracyMetrics now exposes weighted_rmse, weighted_mae, and weighted_rmse_duration as pre-computed scalars (#238) (b70b819)
  • add disaggregate() method (#245) (b24e32e)

Bug Fixes

  • make LegacyAPIWarning visible by default before v4 removal (#236) (#237) (37ff3d8)

Energy Systems - Energy System Modeling Frameworks - Python
Published by fzj-iek3-vsa-release-bot[bot] 3 months ago

tsam - v3.2.1

3.2.1 (2026-03-25)

Bug Fixes

  • use column weights in tuning RMSE objective (#227) (1ceee5c), closes #226

Full Changelog: https://github.com/FZJ-IEK3-VSA/tsam/compare/v3.2.0...v3.2.1

Energy Systems - Energy System Modeling Frameworks - Python
Published by github-actions[bot] 3 months ago

tsam - v3.2.0

3.2.0 (2026-03-24)

This release moves the weights argument out of ClusterConfigand into aggregate (and similar methods), while deprecating the old usage inside ClusterConfig. The Parameter affects all aggregation steps and is now placed accordingly. Further, we added a new plotting method that allows you to inspect cluster members and their representation.

Features

  • Interactive cluster member visualization (#159) (61c6296)
  • Move weights to top-level aggregate() parameter (#195) (4f177d0)

Documentation

  • Add ETHOS.TSAM branding, FZJ theme, and documentation update (#194) (d24a0a3)
  • extract glossary into standalone file (d24a0a3)
  • improve codeblock in Getting Started: (d24a0a3)
  • remove integrated software section and update legal notice (#218) (4c9cc71)
  • update images to README_assets v1.0.0 and add missing publication (#215) (e56a686)

Energy Systems - Energy System Modeling Frameworks - Python
Published by github-actions[bot] 3 months ago

tsam - v3.2.0rc0

What's Changed

New Contributors

Full Changelog: https://github.com/FZJ-IEK3-VSA/tsam/compare/v3.1.1...v3.2.0rc0

Energy Systems - Energy System Modeling Frameworks - Python
Published by github-actions[bot] 3 months ago

tsam - v3.1.2

What's Changed

Full Changelog: https://github.com/FZJ-IEK3-VSA/tsam/compare/v3.1.1...v3.1.2

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 4 months ago

tsam - v3.1.1

TSAM v3.1.1 is the first stable v3 release. Versions 3.0.0 and 3.1.0 were removed from PyPI.
It introduces a modern functional API and makes significant improvements to performance,
Plotting, hyperparameter tuning, and overall code quality have also been improved.

For further details, see the migration guide: https://tsam.readthedocs.io/en/latest/migrationGuideDoc.html.

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 4 months ago

tsam - v.3.1.0

  • Added preserve_n_clusters option to ExtremeConfig. When set to True, extreme periods
    count toward n_clusters instead of being added on top, giving exact control over the final
    number of representative periods. Default behavior is unchanged.

  • Removed matplotlib dependency; all plotting and notebooks now use plotly

  • The tdqm test pipeline has been reduced due to the number of versions and the maturity of the library.

  • Renamed the examples for more clarity

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 5 months ago

tsam - v3.0.0

Summary

  • New Features

    • Redesigned API with functional aggregate() function and structured configuration objects (ClusterConfig, SegmentConfig, ExtremeConfig)
    • New AggregationResult object providing:
      • cluster_representatives, cluster_weights, cluster_assignments properties
      • reconstruct() method for time series reconstruction
      • accuracy metrics (RMSE, MAE, etc.)
      • Built-in plotting via result.plot.*
    • ClusteringResult for clustering transfer and persistence:
      • Save/load clustering with to_json() / from_json()
      • Apply saved clustering to new data with apply()
      • All clustering state bundled in one immutable object
    • Interactive Plotly-based visualizations (tsam.plot.*): heatmaps, duration curves, time slices, comparisons
    • New cluster_assignments() plot to visualize which cluster each period belongs to
    • Hyperparameter tuning with find_optimal_combination():
      • Sparse Pareto frontier exploration (faster than exhaustive search)
      • Parallel execution with file-based data passing (memory safe)
    • Segment transfer: ability to reuse segment configurations across aggregations

  • Documentation

    • Comprehensive getting started guide with new API examples
    • 10 example notebooks moved to docs/source/examples_notebooks/ for Sphinx integration
    • New notebooks: tuning_example.ipynb, aggregation_method_showcase.ipynb

  • Chores

    • Version bump to 3.0.0
    • Made Matplotlib optional; added Plotly (>=5.0.0) as primary plotting backend
    • Reorganized test fixtures to test/data/
    • Added GitHub issue templates (bug report, feature request)

  • Breaking Changes

    • The new API is additive - existing TimeSeriesAggregation class remains unchanged
    • Notebooks moved from examples/ to docs/source/examples_notebooks/

New Modules

Module Purpose
src/tsam/api.py Functional aggregate() entry point
src/tsam/config.py ClusterConfig, SegmentConfig, ExtremeConfig, ClusteringResult dataclasses
src/tsam/result.py AggregationResult with reconstruction & metrics
src/tsam/plot.py Plotly-based visualization functions
src/tsam/tuning.py find_optimal_combination() with parallelization

New vs Old API Comparison

# Old API
aggregation = tsam.TimeSeriesAggregation(
    raw, noTypicalPeriods=8, hoursPerPeriod=24,
    clusterMethod='hierarchical',
    extremePeriodMethod='new_cluster',
    addPeakMin=['T'], addPeakMax=['Load']
)
aggregation.createTypicalPeriods()
typical = aggregation.typicalPeriods

# New API
result = tsam.aggregate(
    raw, n_clusters=8, period_duration=24,  # or '24h', '1d'
    cluster=ClusterConfig(method="hierarchical"),
    extremes=ExtremeConfig(
        method="new_cluster",
        min_value=["T"],
        max_value=["Load"]
    )
)
typical = result.cluster_representatives

Clustering Transfer

# Run aggregation on subset of data
result = tsam.aggregate(df_wind, n_clusters=8)

# Save clustering for later use
result.clustering.to_json("clustering.json")

# Load and apply to different data - all parameters come from the file
clustering = ClusteringResult.from_json("clustering.json")
result2 = clustering.apply(df_all)

# Visualize cluster assignments
result.plot.cluster_assignments()

API Naming Conventions

v2 → v3 Parameter Mapping

Old (v2) New (v3) Reason
noTypicalPeriods n_clusters Clearer terminology: we create clusters, each with one representative.
hoursPerPeriod period_duration Accepts int/float (hours) or pandas Timedelta strings ('24h', '1d').
resolution timestep_duration More explicit about what "resolution" refers to.
typicalPeriods cluster_representatives Renamed to reflect that each cluster has one representative period.
clusterPeriodNoOccur cluster_weights Clearer: weights indicate how often each cluster occurs.
clusterOrder cluster_assignments "Assignments" better describes mapping periods to clusters.

Naming Patterns

Pattern Usage Examples
n_* Count parameters n_clusters, n_segments, n_timesteps_per_period
*_assignments Mapping arrays (which cluster/segment each item belongs to) cluster_assignments, segment_assignments
*_centers Representative indices cluster_centers
*_durations Duration/length arrays segment_durations
*_duration Time length parameters (accept int/float hours or pandas strings) period_duration, timestep_duration
find_* Search/optimization functions find_optimal_combination, find_pareto_front
*Config Configuration dataclasses ClusterConfig, SegmentConfig, ExtremeConfig

Glossary

Note: The new API uses "cluster representative" instead of "typical period" to better reflect that each cluster is represented by one period.

Concept Description
Period A fixed-length time window (e.g., 24 hours = 1 day). The original time series is divided into periods for clustering.
Cluster A group of similar periods. Each cluster has one representative period (cluster_representatives).
Segment A subdivision within a period. Consecutive timesteps are grouped into segments to reduce temporal resolution.
Timestep A single time point within a period (e.g., one hour in a 24-hour period).
Duration Curve A sorted representation of values within a period (highest to lowest). Used with use_duration_curves=True or representation="distribution".

Motivation and Context

The tsam API is quite complex and doesn't follow modern Python best practices (naming conventions like lower_case_with_underscores). The large number of parameters makes it hard to discover related options. I grouped parameters into small dataclasses (ClusterConfig, SegmentConfig, ExtremeConfig) for better discoverability and IDE autocomplete.

The same applies to results - I found it unintuitive to retrieve results and relevant metrics. The new AggregationResult object provides a clean interface with properties and methods.

I added Plotly-based plotting methods for quick interactive inspection.

The hyperparameter tuning was useful but unnecessarily slow. I added:

  • Sparse Pareto frontier search (explores promising configurations first)
  • Parallel execution with file-based data passing (avoids pickling large DataFrames)

I also was missing the option to predefine segments and transfer clustering results between datasets. The new ClusteringResult class with to_json()/from_json() and apply() methods addresses this.

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina 5 months ago

tsam - v.2.3.9

Improve time series aggregation speed with segmentation, mentioned in issue https://github.com/FZJ-IEK3-VSA/tsam/issues/96 by @phil-fzj
Fix issue #99 reported by @adbuerger

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina about 1 year ago

tsam - Improve time series aggregation speed with segmentation

Improve time series aggregation speed with segmentation, mentioned in issue #96 by @phil-fzj

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina about 1 year ago

tsam - 2.3.7

Added Python 3.13 to the action matrix
Updated the Python requirement in the setup.py to incorporate 3.13
Updated ubuntu-20.4 to ubuntu-22.04 in workflow due to deprecation
Removed macos-12 due to slow runs
Solved issue invalid escape sequence '(' https://github.com/FZJ-IEK3-VSA/tsam/issues/90

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina about 1 year ago

tsam - 2.3.6

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina over 1 year ago

tsam - 2.3.5

Replaces 2.3.4 due to differences between github and pypi

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina over 1 year ago

tsam - 2.3.4

  • Extend the reporting if time series tolerances are exceeded and add the option to silence them with a tolerance value.

  • set default tolerance value to 1e-13

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina almost 2 years ago

tsam - Version 2.3.3

Drop support for Python<3.9 and fix some depreciation warnings.

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 2 years ago

tsam - Version 2.3.2

The pandas version is limited to be less than 3.0 as, some commands will be deprecated in the requirements. a new release in the setup, 2.3.2, and warning silence. Deprecation warnings are silenced.

Energy Systems - Energy System Modeling Frameworks - Python
Published by julian-belina almost 2 years ago

tsam - Version 2.3.1

  • accelerate rescale cluster periods
  • update documentation and include autodeployment

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 3 years ago

tsam - Version 2.3.0

  • Fix depreciated pandas functions
  • fix sum for distribution representation incl. min max vals - now mean value of representation equals mean value of original time series
  • add possibility to define segment representation
  • extend the default example
  • switch from travis to github workflow for ci

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 3 years ago

tsam - Version 2.2.2

  • Fix Hypertuning class
  • Set high as new default MILP solver
  • Rework README

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 3 years ago

tsam - Version 2.1.0

Following functionality was added:

  • a hyperparameter tuning meta class which is able to identify the optimal combination of typical periods and segments for a given time series dataset

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 4 years ago

tsam - Version 2.0.1

tsam release (2.0.1) includes the following new functionalities:

  • Changed dependency of scikit-learn to make tsam conda-forge runnable.

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive about 4 years ago

tsam - Version 2.0.0

In tsam’s latest release (2.0.0) the following functionalities were included:

  • A new comprehensive structure that allows for free cross-combination of clustering algorithms and cluster representations, e.g. centroids or medoids.
  • A novel cluster representation method that precisely replicates the original time series value distribution in the aggregated time series based on “Hoffmann, Kotzur and Stolten (2021): The Pareto-Optimal Temporal Aggregation of Energy System Models (https://arxiv.org/abs/2111.12072)”
  • Maxoids as representation algorithm which represents time series by outliers only based on “Sifa and Bauckhage (2017): Online k-Maxoids clustering”
  • K-medoids contiguity: An algorithm based on “Oehrlein and Hauner (2017): A cutting-plane method for adjacency-constrained spatial aggregation” that accounts for contiguity constraints to e.g. cluster only time series in neighboring regions

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive over 4 years ago

tsam - Version 1.1.2

This tsam release (1.1.2) includes the following new functionalities

  • Added first version of the k-medoid contiguity algorithm

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive almost 5 years ago

tsam - Version 1.1.1

This tsam release (1.1.1) includes

  • Significantly increased test coverage
  • Separation between clustering and representation, i.e. for clustering algorithms like Ward’s hierarchical clustering algorithm the representation by medoids or centroids can now freely be chosen.

Energy Systems - Energy System Modeling Frameworks - Python
Published by OfficialCodexplosive almost 5 years ago

tsam - Include build testing

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 7 years ago

tsam - First pypi release

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur about 8 years ago

tsam - Clarify aggregation output structure

  • add second example which illustrates the output of the aggregation
  • add the second publication about storage modeling in readme
  • modify usable attributes to properties

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 8 years ago

tsam -

  • Improvement of extreme periods
  • Move to MIT license

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur over 8 years ago

tsam - v0.9.3

Patch to first public version with minor bug fixes

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur almost 9 years ago

tsam -

First public release

Features:

  • different aggregation methods implemented (averaging, k-mean, exact k-medoid, hierarchical), which are based on scikit-learn or pyomo
  • flexible integration of extreme periods as own cluster centers
  • weighting for the case of multidimensional time-series to represent their relevance

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur about 9 years ago

tsam -

First public release of tsam

Energy Systems - Energy System Modeling Frameworks - Python
Published by l-kotzur about 9 years ago