tsam-xarray 0.6.1__tar.gz → 0.6.2__tar.gz

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

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

{tsam_xarray-0.6.1 → tsam_xarray-0.6.2}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.6.2](https://github.com/FBumann/tsam_xarray/compare/v0.6.1...v0.6.2) (2026-07-21)
+
+
+### Features
+
+* first-class original-vs-reconstructed comparison on AggregationResult ([#93](https://github.com/FBumann/tsam_xarray/issues/93)) ([b3fd174](https://github.com/FBumann/tsam_xarray/commit/b3fd174cdbe379eb1de586aba5bfb75c0e4d21bb))
+
+
+### Bug Fixes
+
+* align reconstructed coordinate order with input (+ comparison recipe) ([#97](https://github.com/FBumann/tsam_xarray/issues/97)) ([afd6818](https://github.com/FBumann/tsam_xarray/commit/afd6818715704822bacfad6edfa5c6595e9f8fc4))
+
 ## [0.6.1](https://github.com/FBumann/tsam_xarray/compare/v0.6.0...v0.6.1) (2026-07-09)
 
 

{tsam_xarray-0.6.1 → tsam_xarray-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsam_xarray
-Version: 0.6.1
+Version: 0.6.2
 Summary: Lightweight xarray wrapper for tsam time series aggregation
 License-Expression: MIT
 License-File: LICENSE

{tsam_xarray-0.6.1 → tsam_xarray-0.6.2}/docs/examples/getting-started.ipynb

@@ -124,7 +124,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Reconstructed vs original"
+    "## Reconstructed vs original\n",
+    "\n",
+    "`result.compare()` stacks `original` and `reconstructed` along a `variant`\n",
+    "dimension (on the original time axis), so the comparison plots directly with\n",
+    "`color=\"variant\"` — no manual `concat`/`melt`. Pass a coordinate selection\n",
+    "(e.g. `variable=\"solar\"`) to focus on one column. `result.original` and\n",
+    "`result.reconstructed` share the same dim order, so they always line up."
    ]
   },
   {
@@ -133,14 +139,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import xarray as xr\n",
-    "\n",
-    "comparison = xr.concat(\n",
-    "    [da_simple.sel(variable=\"solar\"), result.reconstructed.sel(variable=\"solar\")],\n",
-    "    dim=\"source\",\n",
-    ").assign_coords(source=[\"original\", \"reconstructed\"])\n",
-    "comparison.plotly.line(\n",
-    "    x=\"time\", color=\"source\", title=\"Original vs reconstructed (solar)\"\n",
+    "result.compare(variable=\"solar\").plotly.line(\n",
+    "    x=\"time\", color=\"variant\", title=\"Original vs reconstructed (solar)\"\n",
     ")"
    ]
   },
@@ -153,6 +153,38 @@
     "result.residuals.plotly.line(x=\"time\", facet_col=\"variable\", title=\"Residuals\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Because `to_dataframe()` returns tidy long-form data, richer comparisons are a\n",
+    "few lines in the plotting library of your choice — no bespoke helper needed.\n",
+    "For example, load-duration curves (each series sorted descending, Original\n",
+    "dotted / Reconstructed solid):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tidy = result.to_dataframe()\n",
+    "tidy[\"rank\"] = (\n",
+    "    tidy.groupby([\"variant\", \"variable\"])[\"energy\"]\n",
+    "    .rank(method=\"first\", ascending=False)\n",
+    "    .astype(int)\n",
+    ")\n",
+    "duration = tidy.set_index([\"rank\", \"variant\", \"variable\"])[\"energy\"].to_xarray()\n",
+    "duration.plotly.line(\n",
+    "    x=\"rank\",\n",
+    "    color=\"variable\",\n",
+    "    line_dash=\"variant\",\n",
+    "    line_dash_map={\"original\": \"dot\", \"reconstructed\": \"solid\"},\n",
+    "    title=\"Load-duration curves: original vs reconstructed\",\n",
+    ")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -195,6 +227,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import xarray as xr\n",
+    "\n",
     "disaggregated = result.disaggregate(result.cluster_representatives)\n",
     "\n",
     "comparison = xr.concat(\n",

{tsam_xarray-0.6.1 → tsam_xarray-0.6.2}/src/tsam_xarray/_core.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import itertools
+import warnings
 from collections.abc import Hashable, Sequence
 from typing import Any
 
@@ -280,8 +281,6 @@ def _validate_data(
 
     # Dask arrays — compute before other checks
     if hasattr(da.data, "dask"):
-        import warnings
-
         warnings.warn(
             "DataArray is backed by dask. Computing eagerly for tsam.",
             stacklevel=3,
@@ -640,28 +639,33 @@ def _aggregate_single(
 
     active_cols = _active_columns(df, active_coords, col_dims)
 
-    if len(active_cols) == len(df.columns):
-        # Nothing carried passively — cluster on the full frame directly.
-        tsam_result = tsam.aggregate(
-            df,
-            n_clusters,
-            weights=tsam_weights,  # type: ignore[arg-type]
-            **tsam_kwargs,
-        )
-    else:
-        # Cluster on the active subset, then apply that clustering back to the
-        # full frame so passive columns get representatives and reconstruction.
-        active_weights = (
-            None if tsam_weights is None else {c: tsam_weights[c] for c in active_cols}
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message=".*sorted alphabetically.*",
+            category=FutureWarning,
         )
-        clustering = tsam.aggregate(
-            df[active_cols],
-            n_clusters,
-            weights=active_weights,  # type: ignore[arg-type]
-            **tsam_kwargs,
-        ).clustering
-        apply_kwargs = {k: v for k, v in tsam_kwargs.items() if k in _APPLY_KWARGS}
-        tsam_result = clustering.apply(df, **apply_kwargs)
+        if len(active_cols) == len(df.columns):
+            tsam_result = tsam.aggregate(
+                df,
+                n_clusters,
+                weights=tsam_weights,  # type: ignore[arg-type]
+                **tsam_kwargs,
+            )
+        else:
+            active_weights = (
+                None
+                if tsam_weights is None
+                else {c: tsam_weights[c] for c in active_cols}
+            )
+            clustering = tsam.aggregate(
+                df[active_cols],
+                n_clusters,
+                weights=active_weights,  # type: ignore[arg-type]
+                **tsam_kwargs,
+            ).clustering
+            apply_kwargs = {k: v for k, v in tsam_kwargs.items() if k in _APPLY_KWARGS}
+            tsam_result = clustering.apply(df, **apply_kwargs)
 
     return _result_from_tsam(tsam_result, da, df, time_dim, col_dims)
 
@@ -676,6 +680,7 @@ def _result_from_tsam(
     """Build an AggregationResult from a tsam aggregation result."""
     typical = _representatives_to_da(tsam_result.cluster_representatives, col_dims)
     reconstructed = _reconstructed_to_da(tsam_result.reconstructed, time_dim, col_dims)
+    reconstructed = reconstructed.transpose(*da.dims).reindex_like(da)
 
     cw = tsam_result.cluster_weights
     cluster_ids = np.array(sorted(cw.keys()))

{tsam_xarray-0.6.1 → tsam_xarray-0.6.2}/src/tsam_xarray/_result.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+import pandas as pd
 import xarray as xr
 
 if TYPE_CHECKING:
@@ -71,7 +72,7 @@ class AggregationResult:
             *slice_dims)``.
         accuracy: Per-column and weighted accuracy metrics.
         reconstructed: Reconstructed time series
-            (same shape as input).
+            (same shape and dim order as ``original``).
         original: The input data.
         clustering: Reusable clustering metadata.
             See `ClusteringResult`.
@@ -121,9 +122,66 @@ class AggregationResult:
 
     @property
     def residuals(self) -> xr.DataArray:
-        """Difference between original and reconstructed data."""
+        """Difference between original and reconstructed data.
+
+        Shares the dim order of ``original`` and ``reconstructed``.
+        """
         return self.original - self.reconstructed
 
+    def compare(self, **sel: object) -> xr.DataArray:
+        """Stack ``original`` and ``reconstructed`` along a ``variant`` dim.
+
+        Returns a single DataArray on the original time axis with a new
+        ``variant`` coordinate ``["original", "reconstructed"]``, ready to
+        plot directly with a ``color=``/``hue="variant"`` grouping — no
+        ``melt`` step. This is the canonical way to eyeball aggregation
+        quality per column and per slice dim.
+
+        Args:
+            **sel: Optional label-based selection applied to both arrays
+                before stacking, e.g. ``compare(variable="solar")`` to
+                compare a single column.
+
+        Returns:
+            DataArray with dims ``("variant", *original.dims)``.
+
+        Examples:
+            >>> agg.compare(variable="solar").plotly.line(
+            ...     x="time", color="variant"
+            ... )
+        """
+        original = self.original
+        reconstructed = self.reconstructed
+        if sel:
+            original = original.sel(sel)
+            reconstructed = reconstructed.sel(sel)
+        variant = pd.Index(["original", "reconstructed"], name="variant")
+        combined = xr.concat([original, reconstructed], dim=variant)
+        combined.name = self.original.name
+        return combined
+
+    def to_dataframe(self, **sel: object) -> pd.DataFrame:
+        """Tidy/long-form ``original`` vs ``reconstructed`` DataFrame.
+
+        A flat DataFrame with a ``variant`` column
+        (``"original"``/``"reconstructed"``), the ``time`` axis, every
+        cluster and slice dim, and a value column — ready to hand
+        straight to a plotting library.
+
+        Args:
+            **sel: Optional label-based selection forwarded to
+                `compare` (e.g. ``variable="solar"``).
+
+        Returns:
+            Long-form DataFrame with a ``variant`` column and one value
+            column (named after the input DataArray, or ``"value"``).
+        """
+        combined = self.compare(**sel)
+        name = combined.name
+        if name is None or str(name) == "variant":
+            name = "value"
+        return combined.to_dataframe(name=str(name)).reset_index()
+
     def disaggregate(self, data: xr.DataArray) -> xr.DataArray:
         """Map data on ``(cluster, timestep)`` back to original time.
 

{tsam_xarray-0.6.1 → tsam_xarray-0.6.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.6.1'
-__version_tuple__ = version_tuple = (0, 6, 1)
+__version__ = version = '0.6.2'
+__version_tuple__ = version_tuple = (0, 6, 2)
 
 __commit_id__ = commit_id = None

{tsam_xarray-0.6.1 → tsam_xarray-0.6.2}/test/test_aggregate.py

@@ -1529,3 +1529,127 @@ class TestSliceEdgeCases:
         _validate_consistent_cluster_counts(
             [r1, r2], [("low",), ("high",)]
         )  # should not raise
+
+
+def _make_time_last_da() -> xr.DataArray:
+    """DataArray with time as the LAST dim (the #92 papercut case)."""
+    time = pd.date_range("2020-01-01", periods=10 * 24, freq="h")
+    rng = np.random.default_rng(0)
+    return xr.DataArray(
+        rng.random((2, 2, len(time))),
+        dims=["scenario", "variable", "time"],
+        coords={
+            "scenario": ["a", "b"],
+            "variable": ["solar", "wind"],
+            "time": time,
+        },
+        name="power",
+    )
+
+
+class TestDimOrderConsistency:
+    """original / reconstructed / residuals must share dim order (#92)."""
+
+    def test_time_last_input_aligned(self):
+        da = _make_time_last_da()
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        assert result.original.dims == da.dims
+        assert result.reconstructed.dims == result.original.dims
+        assert result.residuals.dims == result.original.dims
+
+    def test_time_first_input_aligned(self):
+        da = _make_da(scenarios=["low", "high"])
+        result = tsam_xarray.aggregate(
+            da,
+            time_dim="time",
+            cluster_dim=["variable", "region"],
+            n_clusters=4,
+        )
+        assert result.reconstructed.dims == result.original.dims
+        assert result.residuals.dims == result.original.dims
+
+    def test_single_dim_no_slice(self):
+        da = _make_time_last_da().isel(scenario=0).drop_vars("scenario")
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        assert result.reconstructed.dims == result.original.dims == da.dims
+
+    def test_non_alphabetical_coord_order_preserved(self):
+        """reconstructed keeps the input's coord order, not tsam's sorted one."""
+        time = pd.date_range("2020-01-01", periods=5 * 24, freq="h")
+        rng = np.random.default_rng(0)
+        da = xr.DataArray(
+            rng.random((len(time), 3)),
+            dims=["time", "variable"],
+            coords={"time": time, "variable": ["wind", "solar", "demand"]},
+            name="p",
+        )
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=3
+        )
+        assert list(result.reconstructed["variable"].values) == [
+            "wind",
+            "solar",
+            "demand",
+        ]
+        assert not bool(result.reconstructed.isnull().any())
+
+
+class TestCompare:
+    """AggregationResult.compare() and .to_dataframe() (#92)."""
+
+    def test_compare_adds_variant_dim(self):
+        da = _make_time_last_da()
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        cmp = result.compare()
+        assert cmp.dims == ("variant", *result.original.dims)
+        assert list(cmp["variant"].values) == ["original", "reconstructed"]
+        assert cmp.name == "power"
+        xr.testing.assert_equal(cmp.sel(variant="original", drop=True), result.original)
+        xr.testing.assert_equal(
+            cmp.sel(variant="reconstructed", drop=True), result.reconstructed
+        )
+
+    def test_compare_with_selection(self):
+        da = _make_time_last_da()
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        cmp = result.compare(variable="solar")
+        assert "variable" not in cmp.dims
+        assert cmp.sizes["variant"] == 2
+
+    def test_to_dataframe_is_long_form(self):
+        da = _make_time_last_da()
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        df = result.to_dataframe(variable="solar")
+        assert "variant" in df.columns
+        assert "power" in df.columns
+        assert set(df["variant"].unique()) == {"original", "reconstructed"}
+        n_time = da.sizes["time"]
+        assert len(df) == 2 * da.sizes["scenario"] * n_time
+
+    def test_to_dataframe_unnamed_uses_value(self):
+        da = _make_time_last_da().rename(None)
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        df = result.to_dataframe()
+        assert "value" in df.columns
+
+    def test_to_dataframe_name_collision_with_variant(self):
+        """An input named 'variant' falls back to 'value' (no insert clash)."""
+        da = _make_time_last_da().rename("variant")
+        result = tsam_xarray.aggregate(
+            da, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        df = result.to_dataframe(variable="solar")
+        assert "value" in df.columns
+        assert list(df.columns).count("variant") == 1

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

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