tsam-xarray 0.6.0__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.0 → tsam_xarray-0.6.2}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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)
+
+
+### Features
+
+* add cluster_on to select which coordinates drive clustering ([#89](https://github.com/FBumann/tsam_xarray/issues/89)) ([ddff73b](https://github.com/FBumann/tsam_xarray/commit/ddff73b24243e53d5a182b9e8c794e2b57a8d1b7))
+* validate extremes options against cluster_on ([#91](https://github.com/FBumann/tsam_xarray/issues/91)) ([2fa5a91](https://github.com/FBumann/tsam_xarray/commit/2fa5a91c5222f8b6dd6932d9572dec62e90f595b))
+
 ## [0.6.0](https://github.com/FBumann/tsam_xarray/compare/v0.5.2...v0.6.0) (2026-05-27)
 
 

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

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

{tsam_xarray-0.6.0 → 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.0 → tsam_xarray-0.6.2}/docs/examples/multi-dim.ipynb

@@ -11,7 +11,7 @@
     "- **`cluster_dim`** — dimensions clustered together (shared clustering)\n",
     "- **Auto-slicing** — remaining dimensions get independent clusterings\n",
     "\n",
-    "This notebook covers stacking, slicing, and weights."
+    "This notebook covers stacking, slicing, weights, and selecting what to cluster on."
    ]
   },
   {
@@ -212,6 +212,44 @@
     ")\n",
     "result_w2.accuracy.rmse.to_dataframe(\"RMSE\")"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Selecting what to cluster on\n",
+    "\n",
+    "Sometimes a variable should be *carried through* the aggregation without\n",
+    "influencing how the clusters are formed — e.g. a price or demand series you\n",
+    "want on the representative grid, but that shouldn't drive period selection.\n",
+    "\n",
+    "Use `cluster_on` to restrict the clustering to specific coordinates. Everything\n",
+    "else is still aggregated and reconstructed from the resulting clusters, but has\n",
+    "no effect on the cluster distances. This differs from a small `weights` value:\n",
+    "`cluster_on` fully removes the coordinate from the distance metric.\n",
+    "\n",
+    "Here we cluster on `solar` and `wind` only, while `demand` is carried along."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Cluster on solar + wind only; demand is carried along but doesn't\n",
+    "# influence cluster selection.\n",
+    "result_on = tsam_xarray.aggregate(\n",
+    "    da_single,\n",
+    "    time_dim=\"time\",\n",
+    "    cluster_dim=[\"variable\", \"region\"],\n",
+    "    n_clusters=4,\n",
+    "    cluster_on={\"variable\": [\"solar\", \"wind\"]},\n",
+    ")\n",
+    "# demand is still present in the output, aggregated from the same clusters\n",
+    "print(\"Variables:\", list(result_on.cluster_representatives.coords[\"variable\"].values))\n",
+    "result_on.accuracy.rmse.to_dataframe(\"RMSE\")"
+   ]
   }
  ],
  "metadata": {

{tsam_xarray-0.6.0 → 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
 
@@ -14,6 +15,7 @@ import xarray as xr
 from tsam_xarray._result import AccuracyMetrics, AggregationResult
 
 Weights = dict[str, float] | dict[str, dict[str, float]] | None
+ClusterOn = str | Sequence[str] | dict[str, Sequence[str]] | None
 
 
 def aggregate(
@@ -23,6 +25,7 @@ def aggregate(
     cluster_dim: Sequence[str] | str,
     n_clusters: int,
     weights: Weights = None,
+    cluster_on: ClusterOn = None,
     **tsam_kwargs: Any,
 ) -> AggregationResult:
     """Aggregate an xarray DataArray using tsam.
@@ -55,6 +58,37 @@ def aggregate(
               e.g. ``("solar", "north")`` gets weight
               ``2.0 * 1.5 = 3.0``.
 
+        cluster_on: Restrict which coordinates drive the
+            clustering. Coordinates not selected are still
+            aggregated and reconstructed from the resulting
+            clusters, but have no influence on how the clusters
+            are formed. ``None`` (default) clusters on
+            everything. Mirrors the ``weights`` formats:
+
+            - **List** (single ``cluster_dim``)::
+
+                  cluster_on=["solar", "wind"]
+
+            - **Dict** (multiple ``cluster_dim``)::
+
+                  cluster_on={"variable": ["solar", "wind"]}
+
+              A dim omitted from the dict is unrestricted (all
+              its coordinates are eligible). When several dims
+              are listed, a column must match on *all* of them
+              to be clustered on. At least one column must
+              remain selected.
+
+              Not compatible with ``ExtremeConfig(method=
+              "replace")`` — the carried columns are filled by
+              transferring the clustering, which cannot
+              reproduce the hybrid 'replace' representative. Use
+              a low ``weights`` value to de-emphasise a column
+              instead of excluding it. An ``ExtremeConfig`` also
+              may not reference an excluded coordinate, since
+              extreme periods are identified only on the
+              clustered-on columns.
+
         **tsam_kwargs: Additional keyword arguments passed to
             ``tsam.aggregate()``.
     """
@@ -65,10 +99,18 @@ def aggregate(
     da = _validate_data(da, time_dim, col_dims, slice_dims)
     _validate_no_cluster_config_weights(tsam_kwargs)
     per_dim_weights = _normalize_weights(weights, da, col_dims)
+    active_coords = _normalize_cluster_on(cluster_on, da, col_dims)
+    _validate_extremes_with_cluster_on(tsam_kwargs, active_coords, da)
 
     if not slice_dims:
         return _aggregate_single(
-            da, n_clusters, time_dim, col_dims, per_dim_weights, tsam_kwargs
+            da,
+            n_clusters,
+            time_dim,
+            col_dims,
+            per_dim_weights,
+            active_coords,
+            tsam_kwargs,
         )
 
     slice_coords = {d: da.coords[d].values for d in slice_dims}
@@ -80,7 +122,13 @@ def aggregate(
         sel = dict(zip(slice_dims, key, strict=True))
         da_slice = da.sel(sel)
         r = _aggregate_single(
-            da_slice, n_clusters, time_dim, col_dims, per_dim_weights, tsam_kwargs
+            da_slice,
+            n_clusters,
+            time_dim,
+            col_dims,
+            per_dim_weights,
+            active_coords,
+            tsam_kwargs,
         )
         results.append(r)
 
@@ -129,6 +177,68 @@ def _validate_no_cluster_config_weights(
         raise ValueError(msg)
 
 
+def _validate_extremes_with_cluster_on(
+    tsam_kwargs: dict[str, Any],
+    active_coords: dict[str, set[str]] | None,
+    da: xr.DataArray,
+) -> None:
+    """Reject extremes settings incompatible with the cluster_on transfer.
+
+    cluster_on clusters on the active subset and transfers the result to the
+    carried columns via ``ClusteringResult.apply()``. Two extremes settings
+    don't survive that transfer:
+
+    - ``method="replace"`` builds a hybrid representative (some columns from the
+      medoid, some from the extreme period) that apply() cannot reproduce — tsam
+      silently falls back to the medoid. Rather than degrade quietly, error and
+      point to ``weights``, which de-emphasises a column without excluding it
+      (tsam clamps a low weight to a minimal one, so the column stays in the
+      single aggregation pass and 'replace' remains reproducible).
+    - An ExtremeConfig that references a coordinate cluster_on excluded: those
+      columns never enter the clustering, so tsam can't identify extremes on
+      them (it would raise a misleading "not found in data"). Surface the real
+      cause instead.
+    """
+    if active_coords is None:
+        return
+    extremes = tsam_kwargs.get("extremes")
+    if extremes is None:
+        return
+
+    if getattr(extremes, "method", None) == "replace":
+        msg = (
+            "extremes method 'replace' is not supported together with "
+            "cluster_on. cluster_on fully excludes the carried columns and "
+            "transfers the clustering to them, which cannot reproduce the "
+            "hybrid 'replace' representative. To reduce a column's influence "
+            "without excluding it, give it a low 'weights' value instead of "
+            "using cluster_on (weights never removes a column entirely, so "
+            "'replace' stays reproducible)."
+        )
+        raise ValueError(msg)
+
+    passive_coords: set[str] = set()
+    for dim, active_set in active_coords.items():
+        all_coords = {str(c) for c in da.coords[dim].values}
+        passive_coords |= all_coords - active_set
+
+    referenced = (
+        set(extremes.max_value)
+        | set(extremes.min_value)
+        | set(extremes.max_period)
+        | set(extremes.min_period)
+    )
+    excluded = referenced & passive_coords
+    if excluded:
+        msg = (
+            f"extremes references coordinates {excluded} that cluster_on "
+            "excluded from the clustering. Extreme periods can only be "
+            "identified on clustered-on columns — add these coordinates to "
+            "cluster_on, or remove them from the ExtremeConfig."
+        )
+        raise ValueError(msg)
+
+
 def _validate(
     da: xr.DataArray,
     time_dim: str,
@@ -171,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,
@@ -265,7 +373,7 @@ def _representatives_to_da(
     df = df.copy()
     # With segmentation, index has 3 levels: (cluster, segment_step, segment_duration)
     # Without: 2 levels: (cluster, timestep)
-    if df.index.nlevels == 3:
+    if isinstance(df.index, pd.MultiIndex) and df.index.nlevels == 3:
         df.index = df.index.droplevel(2)  # drop segment_duration
     df.index.names = ["cluster", "timestep"]
 
@@ -339,6 +447,36 @@ def _metric_to_da(
     return xr.DataArray(series.to_xarray())
 
 
+def _validate_dim_coord_mapping(
+    mapping: dict[str, Any],
+    da: xr.DataArray,
+    col_dims: list[str],
+    label: str,
+) -> None:
+    """Validate a ``{dim: coords}`` mapping references real dims and coords.
+
+    ``coords`` may be any iterable of coordinate names (a list, or the keys
+    of a ``{coord: weight}`` dict). Shared by ``weights`` and ``cluster_on``.
+    """
+    extra_dims = set(mapping.keys()) - set(col_dims)
+    if extra_dims:
+        msg = (
+            f"{label} has unknown dims {extra_dims}, "
+            f"must be subset of cluster_dim {col_dims}"
+        )
+        raise ValueError(msg)
+
+    for dim_name, coords in mapping.items():
+        valid_coords = set(str(c) for c in da.coords[dim_name].values)
+        unknown = set(str(c) for c in coords) - valid_coords
+        if unknown:
+            msg = (
+                f"{label} has unknown coords {unknown} for dim {dim_name!r}, "
+                f"valid coords: {sorted(valid_coords)}"
+            )
+            raise ValueError(msg)
+
+
 def _normalize_weights(
     weights: dict[str, float] | dict[str, dict[str, float]] | None,
     da: xr.DataArray,
@@ -370,27 +508,51 @@ def _normalize_weights(
             raise ValueError(msg)
         per_dim_weights = {col_dims[0]: weights}  # type: ignore[dict-item]
 
-    # Validate dim names exist in cluster_dim
-    extra_dims = set(per_dim_weights.keys()) - set(col_dims)
-    if extra_dims:
-        msg = (
-            f"weights has unknown dims {extra_dims}, "
-            f"must be subset of cluster_dim {col_dims}"
-        )
-        raise ValueError(msg)
+    _validate_dim_coord_mapping(per_dim_weights, da, col_dims, "weights")
+    return per_dim_weights
 
-    # Validate coord values exist in the DataArray
-    for dim_name, coord_weights in per_dim_weights.items():
-        valid_coords = set(str(c) for c in da.coords[dim_name].values)
-        unknown = set(coord_weights.keys()) - valid_coords
-        if unknown:
+
+def _normalize_cluster_on(
+    cluster_on: ClusterOn,
+    da: xr.DataArray,
+    col_dims: list[str],
+) -> dict[str, set[str]] | None:
+    """Normalize cluster_on to a per-dim set of eligible coords.
+
+    A list/str form requires a single cluster_dim. Returns ``None``
+    when nothing is restricted (cluster on everything).
+    """
+    if cluster_on is None:
+        return None
+
+    if isinstance(cluster_on, dict):
+        per_dim: dict[str, list[str]] = {
+            k: [str(c) for c in v] for k, v in cluster_on.items()
+        }
+    else:
+        if len(col_dims) != 1:
             msg = (
-                f"weights has unknown coords {unknown} for dim {dim_name!r}, "
-                f"valid coords: {sorted(valid_coords)}"
+                "List-form cluster_on requires a single cluster_dim. "
+                "For multiple cluster_dim, use a dict: "
+                '{"dim_name": ["coord", ...]}.'
             )
             raise ValueError(msg)
+        coords = [cluster_on] if isinstance(cluster_on, str) else list(cluster_on)
+        per_dim = {col_dims[0]: [str(c) for c in coords]}
 
-    return per_dim_weights
+    _validate_dim_coord_mapping(per_dim, da, col_dims, "cluster_on")
+
+    # An empty coord list for any restricted dim leaves no column to cluster
+    # on (the stacked columns are the full coordinate grid). Fail here, before
+    # any aggregation runs, rather than deep in the per-slice loop.
+    if any(not coords for coords in per_dim.values()):
+        msg = (
+            "cluster_on selected no columns — nothing to cluster on. "
+            "Select at least one coordinate present in the data."
+        )
+        raise ValueError(msg)
+
+    return {d: set(cs) for d, cs in per_dim.items()}
 
 
 def _translate_weights(
@@ -414,30 +576,111 @@ def _translate_weights(
     return flat
 
 
+# tsam.aggregate() kwargs that ClusteringResult.apply() also accepts. Only
+# these are forwarded to apply() when re-aggregating passive columns onto a
+# clustering built from the active subset; the rest (period_duration, cluster,
+# segments, extremes, ...) are already baked into the stored clustering.
+_APPLY_KWARGS = frozenset(
+    {"temporal_resolution", "round_decimals", "numerical_tolerance"}
+)
+
+
+def _active_columns(
+    df: pd.DataFrame,
+    active_coords: dict[str, set[str]] | None,
+    col_dims: list[str],
+) -> list[Hashable]:
+    """Columns that drive the clustering, given a cluster_on selection.
+
+    A column is active only if, for every restricted dim, its coordinate is
+    in that dim's eligible set; unrestricted dims impose no constraint. With
+    no restriction (``active_coords is None``) every column is active. The
+    remaining columns are *passive*: still aggregated and reconstructed, but
+    excluded from the cluster distances.
+    """
+    if active_coords is None:
+        return list(df.columns)
+
+    def is_active(col: Hashable) -> bool:
+        pairs = (
+            zip(col_dims, col, strict=True)
+            if isinstance(col, tuple)
+            else [(col_dims[0], col)]
+        )
+        return all(
+            str(coord) in active_coords[dim]
+            for dim, coord in pairs
+            if dim in active_coords
+        )
+
+    return [col for col in df.columns if is_active(col)]
+
+
 def _aggregate_single(
     da: xr.DataArray,
     n_clusters: int,
     time_dim: str,
     col_dims: list[str],
     weights: dict[str, dict[str, float]] | None,
+    active_coords: dict[str, set[str]] | None,
     tsam_kwargs: dict[str, Any],
 ) -> AggregationResult:
-    """Run a single tsam aggregation on a DataArray."""
+    """Run a single tsam aggregation on a DataArray.
+
+    When ``cluster_on`` restricts the clustering, the clustering runs on
+    the active subset only, then is applied back to the full frame so the
+    passive columns still get representatives and reconstruction.
+    """
     df = _to_dataframe(da, time_dim, col_dims)
 
     tsam_weights: dict[Hashable, float] | None = None
     if weights is not None:
         tsam_weights = _translate_weights(weights, df, col_dims)
 
-    tsam_result = tsam.aggregate(
-        df,
-        n_clusters,
-        weights=tsam_weights,  # type: ignore[arg-type]
-        **tsam_kwargs,
-    )
+    active_cols = _active_columns(df, active_coords, col_dims)
 
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message=".*sorted alphabetically.*",
+            category=FutureWarning,
+        )
+        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)
+
+
+def _result_from_tsam(
+    tsam_result: Any,
+    da: xr.DataArray,
+    df: pd.DataFrame,
+    time_dim: str,
+    col_dims: list[str],
+) -> AggregationResult:
+    """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.0 → 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.0 → 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.0'
-__version_tuple__ = version_tuple = (0, 6, 0)
+__version__ = version = '0.6.2'
+__version_tuple__ = version_tuple = (0, 6, 2)
 
 __commit_id__ = commit_id = None

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

@@ -306,6 +306,169 @@ class TestWeights:
             )
 
 
+@pytest.fixture
+def da_3var() -> xr.DataArray:
+    """Single cluster_dim: solar/wind/price over time (region dropped)."""
+    return _make_da(variables=["solar", "wind", "price"]).isel(region=0, drop=True)
+
+
+@pytest.fixture
+def da_3var_region() -> xr.DataArray:
+    """Multi cluster_dim: solar/wind/price over time and region."""
+    return _make_da(variables=["solar", "wind", "price"])
+
+
+class TestClusterOn:
+    """cluster_on restricts which coords drive clustering, keeping the rest."""
+
+    @pytest.mark.parametrize(
+        ("cluster_dim", "cluster_on", "subset"),
+        [
+            ("variable", ["solar", "wind"], ["solar", "wind"]),
+            ("variable", "solar", ["solar"]),
+            (
+                ["variable", "region"],
+                {"variable": ["solar", "wind"]},
+                ["solar", "wind"],
+            ),
+        ],
+        ids=["list", "string", "dict-multi"],
+    )
+    def test_matches_subset_clustering(
+        self,
+        da_3var: xr.DataArray,
+        da_3var_region: xr.DataArray,
+        cluster_dim: list[str] | str,
+        cluster_on: object,
+        subset: list[str],
+    ):
+        """cluster_on gives the same clustering as aggregating the subset alone,
+        while carried coords still appear in the output."""
+        da = da_3var if cluster_dim == "variable" else da_3var_region
+        restricted = tsam_xarray.aggregate(
+            da,
+            time_dim="time",
+            cluster_dim=cluster_dim,
+            n_clusters=4,
+            cluster_on=cluster_on,
+        )
+        reference = tsam_xarray.aggregate(
+            da.sel(variable=subset),
+            time_dim="time",
+            cluster_dim=cluster_dim,
+            n_clusters=4,
+        )
+        np.testing.assert_array_equal(
+            restricted.clustering.cluster_assignments.values,
+            reference.clustering.cluster_assignments.values,
+        )
+        reps = restricted.cluster_representatives
+        assert "price" in reps.coords["variable"].values
+        assert "price" in restricted.reconstructed.coords["variable"].values
+
+    def test_including_var_would_change_clustering(self, da_3var: xr.DataArray):
+        """Sanity: clustering on everything gives different assignments."""
+        restricted = tsam_xarray.aggregate(
+            da_3var,
+            time_dim="time",
+            cluster_dim="variable",
+            n_clusters=4,
+            cluster_on=["solar", "wind"],
+        )
+        full = tsam_xarray.aggregate(
+            da_3var, time_dim="time", cluster_dim="variable", n_clusters=4
+        )
+        assert (
+            restricted.clustering.cluster_assignments.values
+            != full.clustering.cluster_assignments.values
+        ).any()
+
+    def test_composes_with_weights(self, da_3var: xr.DataArray):
+        """cluster_on and weights coexist; weights apply to the active subset."""
+        result = tsam_xarray.aggregate(
+            da_3var,
+            time_dim="time",
+            cluster_dim="variable",
+            n_clusters=4,
+            cluster_on=["solar", "wind"],
+            weights={"solar": 5.0, "wind": 1.0},
+        )
+        assert result.n_clusters == 4
+        assert "price" in result.cluster_representatives.coords["variable"].values
+
+    def test_replace_extremes_rejected(self, da_3var: xr.DataArray):
+        """extremes='replace' can't survive the cluster_on transfer — error,
+        and steer users to weights instead of full exclusion."""
+        import tsam
+
+        with pytest.raises(ValueError, match=r"replace.*not supported.*cluster_on"):
+            tsam_xarray.aggregate(
+                da_3var,
+                time_dim="time",
+                cluster_dim="variable",
+                n_clusters=4,
+                cluster_on=["solar", "wind"],
+                extremes=tsam.ExtremeConfig(method="replace", max_value=["solar"]),
+            )
+
+    def test_extremes_on_excluded_column_rejected(self, da_3var: xr.DataArray):
+        """An ExtremeConfig referencing a cluster_on-excluded coord errors with
+        a clear cause, not tsam's misleading 'not found in data'."""
+        import tsam
+
+        with pytest.raises(ValueError, match=r"cluster_on excluded"):
+            tsam_xarray.aggregate(
+                da_3var,
+                time_dim="time",
+                cluster_dim="variable",
+                n_clusters=4,
+                cluster_on=["solar", "wind"],
+                extremes=tsam.ExtremeConfig(method="append", max_value=["price"]),
+            )
+
+    def test_append_extremes_allowed(self, da_3var: xr.DataArray):
+        """extremes='append' on an active column composes with cluster_on."""
+        import tsam
+
+        result = tsam_xarray.aggregate(
+            da_3var,
+            time_dim="time",
+            cluster_dim="variable",
+            n_clusters=4,
+            cluster_on=["solar", "wind"],
+            extremes=tsam.ExtremeConfig(method="append", max_value=["solar"]),
+        )
+        assert "price" in result.cluster_representatives.coords["variable"].values
+
+    @pytest.mark.parametrize(
+        ("cluster_dim", "cluster_on", "match"),
+        [
+            (["variable", "region"], ["solar"], "single cluster_dim"),
+            (["variable", "region"], {"scenario": ["low"]}, "unknown dims"),
+            ("variable", ["nuclear"], "unknown coords"),
+            ("variable", {"variable": []}, "nothing to cluster on"),
+        ],
+        ids=["list-multi", "unknown-dim", "unknown-coord", "empty"],
+    )
+    def test_invalid_cluster_on_raises(
+        self,
+        da_3var: xr.DataArray,
+        da_3var_region: xr.DataArray,
+        cluster_dim: list[str] | str,
+        cluster_on: object,
+        match: str,
+    ):
+        da = da_3var if cluster_dim == "variable" else da_3var_region
+        with pytest.raises(ValueError, match=match):
+            tsam_xarray.aggregate(
+                da,
+                time_dim="time",
+                cluster_dim=cluster_dim,
+                n_clusters=4,
+                cluster_on=cluster_on,
+            )
+
+
 class TestWeightTranslation:
     """Verify weight values are correctly translated."""
 
@@ -1366,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.0/.release-please-manifest.json

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