tsam-xarray 0.5.1__tar.gz → 0.5.2__tar.gz

{tsam_xarray-0.5.1 → tsam_xarray-0.5.2}/.github/workflows/ci.yaml

@@ -66,7 +66,7 @@ jobs:
       - name: Run tests
         run: uv run pytest -n auto --cov=src/tsam_xarray --cov-report=xml --cov-report=term-missing
 
-      - uses: codecov/codecov-action@v5
+      - uses: codecov/codecov-action@v6
         if: matrix.python-version == '3.12'
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

tsam_xarray-0.5.2/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.2"
+}

{tsam_xarray-0.5.1 → tsam_xarray-0.5.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.2](https://github.com/FBumann/tsam_xarray/compare/v0.5.1...v0.5.2) (2026-04-01)
+
+
+### Features
+
+* compact time_coords serialization in ClusteringResult JSON ([#79](https://github.com/FBumann/tsam_xarray/issues/79)) ([bac9fd1](https://github.com/FBumann/tsam_xarray/commit/bac9fd17ee28a48fd6f51ce16fea0df883cccb99))
+
 ## [0.5.1](https://github.com/FBumann/tsam_xarray/compare/v0.5.0...v0.5.1) (2026-03-31)
 
 

tsam_xarray-0.5.2/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: tsam_xarray
+Version: 0.5.2
+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/)
+
+**DataArray in, DataArray out** — multi-dimensional time series aggregation with [tsam](https://github.com/FZJ-IEK3-VSA/tsam) and [xarray](https://xarray.dev/).
+
+## The problem
+
+Energy system data is multi-dimensional — variables, regions, scenarios, years. Some dimensions should be **clustered together** (solar and wind profiles in the same region should see the same typical days), while others need **independent clustering** (each scenario has its own weather patterns).
+
+![Multi-dimensional input data](docs/assets/multi-dim-input.png)
+
+tsam works on flat DataFrames. With multi-dimensional data, you end up writing boilerplate: loop over scenarios, convert to DataFrame, aggregate, extract results, convert back, concatenate, hope the dims line up. Accuracy metrics come back as unlabeled `pd.Series`. Saving a clustering means managing raw dicts.
+
+## The solution
+
+```python
+import tsam_xarray
+
+result = tsam_xarray.aggregate(
+    da,                                    # (time, variable, region, scenario)
+    time_dim="time",
+    cluster_dim=["variable", "region"],    # clustered together
+    n_clusters=4,
+)
+# scenario is sliced independently — each gets its own clustering
+```
+
+Everything comes back as labeled xarray objects:
+
+```python
+result.cluster_representatives   # (scenario, cluster, timestep, variable, region)
+result.reconstructed             # same shape as input
+result.cluster_assignments       # (scenario, period)
+```
+
+Accuracy metrics preserve all dimensions — see exactly where the approximation is good or bad:
+
+![Per-column RMSE across all dimensions](docs/assets/multi-dim-metrics.png)
+
+```python
+result.accuracy.rmse             # DataArray (scenario, variable, region)
+result.accuracy.weighted_rmse    # DataArray (scenario,) — per-slice summary
+```
+
+## Save, load, reuse
+
+```python
+# Save clustering (not the data — just the mapping)
+result.clustering.to_json("clustering.json")
+
+# Load and inspect — no original data needed
+clustering = tsam_xarray.load_clustering("clustering.json")
+clustering.n_clusters              # 4
+clustering.cluster_assignments     # DataArray (scenario, period)
+clustering.cluster_occurrences     # DataArray (scenario, cluster)
+
+# Apply to new data or disaggregate optimization results
+new_result = clustering.apply(new_da)
+full_timeseries = clustering.disaggregate(optimized_data)
+```
+
+## Tuning
+
+Find optimal hyperparameters across all slices:
+
+```python
+grid = tsam_xarray.grid_search(
+    da,
+    time_dim="time",
+    cluster_dim=["variable", "region"],
+    timesteps=np.geomspace(2, 48, num=12, dtype=int),  # sparse search
+)
+grid.summary_matrix["rmse"]        # heatmap-ready (n_clusters, n_segments)
+grid.accuracy["weighted_rmse"]     # per-slice weighted RMSE for every config
+```
+
+## Installation
+
+```bash
+pip install tsam-xarray
+```
+
+## Documentation
+
+Full docs with interactive examples: **[tsam-xarray.readthedocs.io](https://tsam-xarray.readthedocs.io/)**

tsam_xarray-0.5.2/README.md

@@ -0,0 +1,91 @@
+# 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/)
+
+**DataArray in, DataArray out** — multi-dimensional time series aggregation with [tsam](https://github.com/FZJ-IEK3-VSA/tsam) and [xarray](https://xarray.dev/).
+
+## The problem
+
+Energy system data is multi-dimensional — variables, regions, scenarios, years. Some dimensions should be **clustered together** (solar and wind profiles in the same region should see the same typical days), while others need **independent clustering** (each scenario has its own weather patterns).
+
+![Multi-dimensional input data](docs/assets/multi-dim-input.png)
+
+tsam works on flat DataFrames. With multi-dimensional data, you end up writing boilerplate: loop over scenarios, convert to DataFrame, aggregate, extract results, convert back, concatenate, hope the dims line up. Accuracy metrics come back as unlabeled `pd.Series`. Saving a clustering means managing raw dicts.
+
+## The solution
+
+```python
+import tsam_xarray
+
+result = tsam_xarray.aggregate(
+    da,                                    # (time, variable, region, scenario)
+    time_dim="time",
+    cluster_dim=["variable", "region"],    # clustered together
+    n_clusters=4,
+)
+# scenario is sliced independently — each gets its own clustering
+```
+
+Everything comes back as labeled xarray objects:
+
+```python
+result.cluster_representatives   # (scenario, cluster, timestep, variable, region)
+result.reconstructed             # same shape as input
+result.cluster_assignments       # (scenario, period)
+```
+
+Accuracy metrics preserve all dimensions — see exactly where the approximation is good or bad:
+
+![Per-column RMSE across all dimensions](docs/assets/multi-dim-metrics.png)
+
+```python
+result.accuracy.rmse             # DataArray (scenario, variable, region)
+result.accuracy.weighted_rmse    # DataArray (scenario,) — per-slice summary
+```
+
+## Save, load, reuse
+
+```python
+# Save clustering (not the data — just the mapping)
+result.clustering.to_json("clustering.json")
+
+# Load and inspect — no original data needed
+clustering = tsam_xarray.load_clustering("clustering.json")
+clustering.n_clusters              # 4
+clustering.cluster_assignments     # DataArray (scenario, period)
+clustering.cluster_occurrences     # DataArray (scenario, cluster)
+
+# Apply to new data or disaggregate optimization results
+new_result = clustering.apply(new_da)
+full_timeseries = clustering.disaggregate(optimized_data)
+```
+
+## Tuning
+
+Find optimal hyperparameters across all slices:
+
+```python
+grid = tsam_xarray.grid_search(
+    da,
+    time_dim="time",
+    cluster_dim=["variable", "region"],
+    timesteps=np.geomspace(2, 48, num=12, dtype=int),  # sparse search
+)
+grid.summary_matrix["rmse"]        # heatmap-ready (n_clusters, n_segments)
+grid.accuracy["weighted_rmse"]     # per-slice weighted RMSE for every config
+```
+
+## Installation
+
+```bash
+pip install tsam-xarray
+```
+
+## Documentation
+
+Full docs with interactive examples: **[tsam-xarray.readthedocs.io](https://tsam-xarray.readthedocs.io/)**

tsam_xarray-0.5.2/scripts/generate_readme_images.py

@@ -0,0 +1,68 @@
+"""Generate images for README.md."""
+
+from pathlib import Path
+
+import xarray_plotly  # noqa: F401
+
+import tsam_xarray
+from tsam_xarray._sample_data import sample_energy_data
+
+ASSETS = Path("docs/assets")
+
+
+def generate_input_plot() -> None:
+    """Multi-dimensional input data plot."""
+    da = sample_energy_data(n_days=30)
+    fig = da.plotly.line(
+        x="time", color="variable", facet_row="scenario", facet_col="region"
+    )
+    fig.update_layout(
+        height=400,
+        width=850,
+        margin=dict(t=40, b=25, l=50, r=20),
+        template="plotly_white",
+        font=dict(size=11),
+        title_text=("Input: 3 variables x 3 regions x 2 scenarios x 720 hours"),
+        title_x=0.5,
+        title_font_size=13,
+    )
+    fig.update_xaxes(tickformat="%b %d")
+    fig.update_traces(line_width=0.8)
+    fig.write_image(ASSETS / "multi-dim-input.png", scale=2)
+    print(f"Saved {ASSETS / 'multi-dim-input.png'}")
+
+
+def generate_metrics_plot() -> None:
+    """Per-column RMSE heatmap across all dimensions."""
+    da = sample_energy_data(n_days=30)
+    r = tsam_xarray.aggregate(
+        da,
+        time_dim="time",
+        cluster_dim="variable",
+        n_clusters=4,
+    )
+    fig = r.accuracy.rmse.plotly.imshow(
+        x="variable",
+        y="region",
+        facet_col="scenario",
+        text_auto=".2f",
+        color_continuous_scale="YlOrRd",
+    )
+    fig.update_layout(
+        height=280,
+        width=650,
+        margin=dict(t=40, b=20, l=60, r=20),
+        template="plotly_white",
+        font=dict(size=12),
+        title_text=("Per-column RMSE — faceted by scenario (independent clustering)"),
+        title_x=0.5,
+        title_font_size=13,
+    )
+    fig.write_image(ASSETS / "multi-dim-metrics.png", scale=2)
+    print(f"Saved {ASSETS / 'multi-dim-metrics.png'}")
+
+
+if __name__ == "__main__":
+    ASSETS.mkdir(parents=True, exist_ok=True)
+    generate_input_plot()
+    generate_metrics_plot()

{tsam_xarray-0.5.1 → tsam_xarray-0.5.2}/src/tsam_xarray/_clustering.py

@@ -21,6 +21,25 @@ from tsam_xarray._core import (
 )
 
 
+def _time_coords_to_dict(tc: pd.DatetimeIndex) -> dict[str, Any] | list[str]:
+    """Serialize a DatetimeIndex compactly when possible.
+
+    Regular indices are stored as ``{start, periods, freq}`` (~3 values).
+    Irregular indices fall back to a full ISO string list.
+    """
+    freq = pd.infer_freq(tc)
+    if freq is not None:
+        return {"start": tc[0].isoformat(), "periods": len(tc), "freq": freq}
+    return [t.isoformat() for t in tc]
+
+
+def _time_coords_from_dict(raw: dict[str, Any] | list[str]) -> pd.DatetimeIndex:
+    """Deserialize a DatetimeIndex from either compact or list format."""
+    if isinstance(raw, dict):
+        return pd.date_range(raw["start"], periods=raw["periods"], freq=raw["freq"])
+    return pd.DatetimeIndex(raw)
+
+
 @dataclass(frozen=True, repr=False)
 class ClusteringResult:
     """Reusable clustering result with xarray dimension metadata.
@@ -467,7 +486,7 @@ class ClusteringResult:
             "clusterings": entries,
         }
         if self.time_coords is not None:
-            data["time_coords"] = [t.isoformat() for t in self.time_coords]
+            data["time_coords"] = _time_coords_to_dict(self.time_coords)
         return data
 
     def to_json(self, path: str | Path, **json_kwargs: Any) -> None:
@@ -498,7 +517,7 @@ class ClusteringResult:
 
         time_coords: pd.DatetimeIndex | None = None
         if "time_coords" in data:
-            time_coords = pd.DatetimeIndex(data["time_coords"])
+            time_coords = _time_coords_from_dict(data["time_coords"])
 
         return cls(
             time_dim=data["time_dim"],

{tsam_xarray-0.5.1 → tsam_xarray-0.5.2}/src/tsam_xarray/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.1'
-__version_tuple__ = version_tuple = (0, 5, 1)
+__version__ = version = '0.5.2'
+__version_tuple__ = version_tuple = (0, 5, 2)
 
 __commit_id__ = commit_id = None

{tsam_xarray-0.5.1 → tsam_xarray-0.5.2}/test/test_aggregate.py

@@ -1353,7 +1353,10 @@ class TestClusteringDisaggregate:
         with open(path) as f:
             data = json.load(f)
         assert "time_coords" in data
-        assert len(data["time_coords"]) == da_flat.sizes["time"]
+        tc = data["time_coords"]
+        # Regular index → compact dict format
+        assert isinstance(tc, dict)
+        assert tc["periods"] == da_flat.sizes["time"]
 
     def test_time_coords_roundtrip(self, tmp_path):
         """time_coords survive JSON round-trip."""

{tsam_xarray-0.5.1 → tsam_xarray-0.5.2}/test/test_parametrized.py

@@ -505,3 +505,61 @@ class TestClusteringIORoundtrip:
         clustering = tsam_xarray.load_clustering(str(path))
         new_result = clustering.apply(agg_case.da)
         assert new_result.is_transferred
+
+
+class TestTimeCoordsSerialization:
+    """Compact time_coords serialization helpers."""
+
+    def test_regular_index_compact(self):
+        """Regular DatetimeIndex is stored as {start, periods, freq}."""
+        import pandas as pd
+
+        from tsam_xarray._clustering import _time_coords_to_dict
+
+        tc = pd.date_range("2025-01-01", periods=8760, freq="h")
+        d = _time_coords_to_dict(tc)
+        assert isinstance(d, dict)
+        assert set(d) == {"start", "periods", "freq"}
+        assert d["periods"] == 8760
+
+    def test_regular_index_roundtrip(self):
+        """Compact format round-trips exactly."""
+        import pandas as pd
+
+        from tsam_xarray._clustering import (
+            _time_coords_from_dict,
+            _time_coords_to_dict,
+        )
+
+        tc = pd.date_range("2025-01-01", periods=8760, freq="h")
+        restored = _time_coords_from_dict(_time_coords_to_dict(tc))
+        pd.testing.assert_index_equal(tc, restored)
+
+    def test_irregular_index_fallback(self):
+        """Irregular DatetimeIndex falls back to list of ISO strings."""
+        import pandas as pd
+
+        from tsam_xarray._clustering import (
+            _time_coords_from_dict,
+            _time_coords_to_dict,
+        )
+
+        tc = pd.DatetimeIndex(["2025-01-01", "2025-01-03", "2025-01-07"])
+        d = _time_coords_to_dict(tc)
+        assert isinstance(d, list)
+        restored = _time_coords_from_dict(d)
+        pd.testing.assert_index_equal(tc, restored)
+
+    def test_old_list_format_still_loads(self):
+        """List format (pre-compact) is still accepted by from_dict."""
+        from tsam_xarray._clustering import _time_coords_from_dict
+
+        raw = ["2025-01-01T00:00:00", "2025-01-01T01:00:00"]
+        restored = _time_coords_from_dict(raw)
+        assert len(restored) == 2
+
+    def test_dict_roundtrip_uses_compact(self, agg_case: AggregateCase):
+        """to_dict uses compact format for regular time indices."""
+        result = _aggregate(agg_case)
+        d = result.clustering.to_dict()
+        assert isinstance(d["time_coords"], dict)

tsam_xarray-0.5.1/.release-please-manifest.json

@@ -1,3 +0,0 @@
-{
-  ".": "0.5.1"
-}

tsam_xarray-0.5.1/PKG-INFO

@@ -1,117 +0,0 @@
-Metadata-Version: 2.4
-Name: tsam_xarray
-Version: 0.5.1
-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/)

tsam_xarray-0.5.1/README.md

@@ -1,96 +0,0 @@
-# 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/)