Metadata-Version: 2.4
Name: tsam_xarray
Version: 0.4.0
Summary: Lightweight xarray wrapper for tsam time series aggregation
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: bottleneck>=1.4
Requires-Dist: tsam>=3.3.0
Requires-Dist: xarray>=2024.1
Provides-Extra: plot
Requires-Dist: plotly>=5; extra == 'plot'
Description-Content-Type: text/markdown

# tsam_xarray

[![PyPI](https://img.shields.io/pypi/v/tsam-xarray)](https://pypi.org/project/tsam-xarray/)
[![Python](https://img.shields.io/pypi/pyversions/tsam-xarray)](https://pypi.org/project/tsam-xarray/)
[![CI](https://github.com/FBumann/tsam_xarray/actions/workflows/ci.yaml/badge.svg)](https://github.com/FBumann/tsam_xarray/actions/workflows/ci.yaml)
[![codecov](https://codecov.io/gh/FBumann/tsam_xarray/graph/badge.svg)](https://codecov.io/gh/FBumann/tsam_xarray)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://tsam-xarray.readthedocs.io/)

Lightweight [xarray](https://xarray.dev/) wrapper for [tsam](https://github.com/FZJ-IEK3-VSA/tsam) time series aggregation.

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

## Installation

```bash
pip install tsam_xarray
```

## Quick start

```python
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

```python
# 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

```python
# 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()](https://github.com/FZJ-IEK3-VSA/tsam) keyword arguments pass through:

```python
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](https://tsam-xarray.readthedocs.io/)
