tsam-xarray 0.5.0

Lightweight xarray wrapper for tsam time series aggregation

tsam_xarray

Lightweight xarray wrapper for tsam time series aggregation.

DataArray in, DataArray out — no manual DataFrame conversions, no MultiIndex wrangling, no loop-and-concat boilerplate.

Installation

pip install tsam_xarray

Quick start

import numpy as np
import pandas as pd
import xarray as xr
import tsam_xarray

# Create sample data: 30 days of hourly solar and wind data
time = pd.date_range("2020-01-01", periods=30 * 24, freq="h")
da = xr.DataArray(
    np.random.default_rng(42).random((len(time), 2)),
    dims=["time", "variable"],
    coords={"time": time, "variable": ["solar", "wind"]},
)

# Aggregate to 4 typical days
result = tsam_xarray.aggregate(
    da, time_dim="time", cluster_dim="variable", n_clusters=4,
)

result.cluster_representatives   # (cluster, timestep, variable)
result.cluster_weights   # (cluster,) — days each cluster represents
result.accuracy.rmse     # (variable,) — per-variable RMSE
result.reconstructed     # same shape as input

Multi-dimensional data

# Cluster variable x region together; scenario is sliced independently
result = tsam_xarray.aggregate(
    da,
    time_dim="time",
    cluster_dim=["variable", "region"],
    n_clusters=8,
)

result.cluster_representatives  # (scenario, cluster, timestep, variable, region)

Weights

# Single cluster_dim — simple dict
result = tsam_xarray.aggregate(
    da, time_dim="time", cluster_dim="variable", n_clusters=8,
    weights={"solar": 2.0, "wind": 1.0},
)

# Multiple cluster_dim — dict-of-dicts
result = tsam_xarray.aggregate(
    da, time_dim="time", cluster_dim=["variable", "region"], n_clusters=8,
    weights={"variable": {"solar": 2.0}, "region": {"north": 1.5}},
)

tsam passthrough

All tsam.aggregate() keyword arguments pass through:

from tsam import ClusterConfig, SegmentConfig

result = tsam_xarray.aggregate(
    da,
    time_dim="time",
    cluster_dim="variable",
    n_clusters=8,
    cluster=ClusterConfig(method="kmeans"),
    segments=SegmentConfig(n_segments=6),
)

Documentation

Full docs with interactive examples: tsam-xarray.readthedocs.io