Why this package?
Energy system models, capacity expansion studies, and other time-series-heavy applications often need to reduce a full year (or even multi-year horizon) of hourly data to a small set of representative periods (days, weeks, months, or years) without losing what matters.
There are plenty of methods for this (k-means, k-medoids, MILP-based selection, genetic algorithms, ...), but they tend to bundle several decisions into one procedure: how to represent data, what to optimize, how to search. This project helps you understand the problem of representative period selection, provides a unified framework that untangles these decisions, and gives you modular tools to mix, compare, and adapt methods to your specific problem.
A Unified Framework
Breaks down any time-series aggregation method into five interchangeable components. Every established methodology is just a specific combination of these building blocks, which gives you a common language for describing, comparing, and mixing methods.
Read the Unified FrameworkA Modular Python Package
Implements the framework as a library of composable, protocol-based modules. Pick one implementation per component, wire them together, and run. Want to add a new algorithm or score metric? Just implement one protocol, while everything else can stay the same.
Browse all modulesThe Five Components
Any time-series aggregation method decomposes into these five pillars. Mix and match implementations to build the exact workflow you need.
Feature Space
How raw time-series are transformed into comparable representations
Objective
How candidate selections are scored for quality
Selection Space
What is being selected (historical subsets, synthetic archetypes, etc.)
Representation Model
How selected periods represent the full dataset
Search Algorithm
The engine that finds optimal selections
How It Works
Define your problem, pick one implementation per component, wire them into a workflow, and run. The result contains the selected periods, their weights, and all objective scores.
Implemented Modules
A growing library of composable components. Each implements a protocol — swap any module without touching the rest of your pipeline.
Feature Engineering
StandardStatsFeatureEngineer
PCAFeatureEngineer
FeaturePipeline
Transform raw time-series into statistical summaries, PCA projections, or chained multi-step feature pipelines.
Score Components
WassersteinFidelity
CorrelationFidelity
DurationCurveFidelity
DiversityReward
...
Evaluate candidate selections on distribution similarity, correlation preservation, diversity, and more. 10 components and counting.
Combination Generators
ExhaustiveCombiGen
GroupQuotaCombiGen
HierarchicalCombiGen
Define the selection space: enumerate all k-of-n combinations, enforce group quotas (e.g. one per season), or compose hierarchically.
Representation Models
UniformRepresentationModel
KMedoidsClustersizeRepresentation
BlendedRepresentationModel
Assign responsibility weights: equal 1/k, cluster-membership proportional, or soft blended assignment where every period contributes.
Search Algorithms
ObjectiveDrivenCombinatorialSearchAlgorithm
WeightedSumPolicy
ParetoMaxMinStrategy
Generate-and-test search with pluggable selection policies: weighted sum, Pareto front, or custom strategies.
Explore hands-on examples
Worked examples showcasing different configurations — from a minimal "hello world" to multi-objective optimization and hierarchical seasonal workflows.
Browse all examplesEx 1: Getting Started
Minimal end-to-end workflow — single objective, uniform weights, 4 representative months.
Ex 2: Feature Space Exploration
PCA features, Pareto selection, cluster-size weights, and the full suite of diagnostics.
Ex 3: Hierarchical Selection
Seasonal constraints via hierarchical combination generation — one month per season.
Ex 4: Representation Models
Same selection, three weight models compared: uniform, cluster-size, and blended.
Ex 5: Multi-Objective
Four objectives, Pareto vs. weighted-sum policies — exploring the trade-off frontier.
Ex 6: K-Medoids Clustering
Demonstration of K-Medoids Clustering.
Ex 7: Constructive Algorithms
Demonstration of Hull Clustering, CTPC, and Snippet algorithm.
Project Family
All open-source projects by Helge Esch for energy system analysis, scenario comparison, and modeling support.
A Pythonic framework for energy scenario comparison and quantitative analysis. Platform-agnostic, fully modular, and built to extend.
A unified framework and modular Python package for representative period selection in multi-variate time-series spaces.
Create beautiful, customizable, animated SVG arrows for web interfaces with just a few lines of Python code.