TSAM Notebook Workflows

This repository provides a reusable ETHOS.TSAM workflow and command-line interface for energy time-series aggregation. The primary workflow validates input data, aggregates monthly working and non-working days, and exports stable CSV artifacts, reproducibility metadata, and offline interactive charts.

Two Jupyter notebooks remain available as optional interactive and educational interfaces. The grouped notebook is a thin client over the reusable package; the CLI is the preferred path for reproducible runs and exports.

Upstream TSAM

• Original repository: https://github.com/FZJ-IEK3-VSA/tsam
• Documentation: https://tsam.readthedocs.io/
• Upstream example notebooks: basic example and visualization example

Installation

Install uv using its standalone installer or a platform package manager. Then install the CLI and its runtime dependencies with:

uv sync --locked

To use or execute the notebooks, install the optional notebook dependencies:

uv sync --locked --extra notebooks

CLI Quick Start

Run the built-in grouped workflow with its original 5-working/2-non-working representative configuration:

uv run tsam-workflows grouped --output-dir outputs/approach_1

The command uses the checked-in datasets from data/, year 2025, all available countries, hierarchical clustering, and 5 working-day plus 2 non-working-day clusters by default. Pass --overwrite when replacing a non-empty output directory.

Each successful run writes:

• reduced_hourly_df.csv, representative_days.csv, and day_assignments_df.csv;
• manifest.json with the effective configuration and dataset metadata; and
• charts/index.html plus its offline chart assets.

Open <output-dir>/charts/index.html after the run. The command prints its direct local URL, and the page provides a responsive sidebar for every chart in one workspace.

Use --help to inspect every supported option:

uv run tsam-workflows grouped --help

The equivalent explicit configuration is:

uv run tsam-workflows grouped \
  --data-dir data \
  --output-dir outputs/approach_1 \
  --year 2025 \
  --countries ALL \
  --working-clusters 5 \
  --non-working-clusters 2 \
  --cluster-method hierarchical \
  --overwrite

Custom YAML Configuration

Use the optional YAML configuration for custom input files, CSV separators, timestamp parsing, feature labels, chart feature groups, calendar rules, and mean-preserved representatives:

uv run tsam-workflows grouped \
  --config examples/grouped-workflow.yaml \
  --output-dir outputs/custom \
  --overwrite

Relative dataset paths resolve from the YAML file's directory. Omitting countries or setting countries: ALL selects every available country; use a list such as countries: [DE, FR] for a subset. Explicit CLI options such as --year, --countries, and cluster counts override YAML values.

Each dataset's feature becomes the canonical output token, for example raw column DE with feature: solar becomes DE_solar_2025. feature_group organizes related features in chart selectors and does not change clustering. unit_interval: true validates that every value is between zero and one; it does not normalize the data.

The grouped workflow always creates representative 24-hour days. Sampling frequency is inferred from timestamps, must be regular and identical across datasets, and is recorded in manifest.json. Enabling preserve_column_means exports TSAM's rescaled synthetic representatives while retaining each selected medoid date as provenance.

Notebooks

• src/approach_1_ALL.ipynb is an optional interactive thin client for the reusable grouped workflow. It provides notebook widgets, representative-day outputs, and group-level diagnostics; use the CLI for reproducible exports.
• src/quickstart.ipynb is a separate, notebook-only annual baseline with validation, diagnostics, plotting, output inspection, and saved results.

Start JupyterLab:

uv run --extra notebooks jupyter lab

Or start Jupyter Notebook:

uv run --extra notebooks jupyter notebook

Then open either notebook from src/.

Data

Checked-in sample CSV files live in data/. The grouped CLI uses them by default, and both notebooks use them through relative paths. A YAML configuration may reference other datasets; relative paths resolve from the configuration file's directory.

Acknowledgement

This work was prepared for Helmholtz-Zentrum Berlin für Materialien und Energie (HZB), a member of the Helmholtz Association, in the context of the Green Deal Ukraïna project.