ETHOS.TSAM¶
Time series aggregation for large optimization models — and any other time series.
ETHOS.TSAM compresses long, high-resolution time series into a small set of typical periods (e.g. 8 typical days standing in for a whole year) and, optionally, into coarser timesteps within each period. The result preserves key statistical characteristics and recurring patterns of the original data as closely as possible, while substantially reducing the number of time steps.
It is designed to shrink the temporal complexity of energy system optimization models, but it works on any time series — weather, prices, load, behavior, or all of them at once.
How this documentation is organized¶
It follows the Diátaxis framework, which splits documentation by what you came for:
| Section | Use it to |
|---|---|
| Tutorials | Learn tsam by working through a complete example. |
| How-to guides | Get one specific task done. |
| Explanation | Understand the algorithms, the architecture, and the decisions behind them. |
| Reference | Look up the API, the notation, Glossary and implementation details. |
Main features¶
- One function, many methods.
aggregateis the single entry point. Choose between k-means, k-medoids, k-maxoids, hierarchical, contiguous, and averaging clustering — backed by scikit-learn or solved exactly with an MILP solver. - Two aggregation dimensions, freely combined. Reduce the number of periods (typical days) and/or the temporal resolution within them, via how small you can go.
- Representations that preserve what matters. Beyond means and medoids, keep the value distribution (duration curve), per-timestep min/max, or force extreme periods so peaks survive aggregation.
- Built-in evaluation and plotting. Every result carries accuracy metrics and
an interactive
.plotaccessor (Plotly) — see the Quickstart. - Automatic hyperparameter tuning. Let tsam find the period/segment combination that hits a target data reduction, or map the full Pareto front.
- Built for downstream models. Hand the representatives, counts, and assignments to an optimization, then map results back — see the optimization workflow.
Where to start¶
| If you want to… | Go to |
|---|---|
| Install the package | Installation |
| Run your first aggregation | Quickstart |
| Solve a specific task | How-to guides |
| See an end-to-end optimization workflow | Optimization workflow |
| Understand how aggregation works | How aggregation works |
| Look up an equation or symbol | Notation and equations |
| Look up a function or class | API Reference |
| Upgrade from v2 or v3 | Migration guide |
About¶
ETHOS.TSAM is open source and developed on GitHub — contributions, questions, and issues are welcome. It is part of the Energy Transformation PatHway Optimization Suite (ETHOS) at ICE-2 and is tightly integrated with ETHOS.FINE.
If you use or reference ETHOS.TSAM in scientific work, please cite one of our publications.