tsam 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

tsam/api.py

@@ -536,6 +536,7 @@ def _build_old_params(
         params["addPeakMin"] = extremes.min_value
         params["addMeanMax"] = extremes.max_period
         params["addMeanMin"] = extremes.min_period
+        params["extremePreserveNumClusters"] = extremes._effective_preserve_n_clusters
     else:
         params["extremePeriodMethod"] = "None"
 

tsam/config.py

@@ -606,9 +606,10 @@ class ClusteringResult:
         ):
             warnings.warn(
                 "The 'replace' extreme method creates a hybrid cluster representation "
-                "(some columns from the medoid, some from the extreme period) that cannot "
-                "be perfectly reproduced during transfer. The transferred result will use "
-                "the medoid representation for all columns instead of the hybrid values. "
+                "(some columns from the cluster representative, some from the extreme period) "
+                "that cannot be perfectly reproduced during transfer. The transferred result "
+                "will use the stored cluster center periods directly, without the extreme "
+                "value injection that was applied during the original aggregation. "
                 "For exact transfer, use 'append' or 'new_cluster' extreme methods.",
                 UserWarning,
                 stacklevel=2,
@@ -785,6 +786,18 @@ class ExtremeConfig:
     min_period : list[str], optional
         Column names where the period with minimum total should be preserved.
         Example: ["wind_generation"] to preserve lowest wind day.
+
+    preserve_n_clusters : bool, optional
+        Whether extreme periods count toward n_clusters.
+        - True: Extremes are included in n_clusters
+          (e.g., n_clusters=10 with 2 extremes = 8 from clustering + 2 extremes)
+        - False: Extremes are added on top of n_clusters (old api behaviour)
+          (e.g., n_clusters=10 + 2 extremes = 12 final clusters)
+        Only affects "append" or "new_cluster" methods ("replace" never changes n_clusters).
+
+        .. deprecated::
+            The default will change from False to True in a future release.
+            Set explicitly to silence the FutureWarning.
     """
 
     method: ExtremeMethod = "append"
@@ -792,6 +805,18 @@ class ExtremeConfig:
     min_value: list[str] = field(default_factory=list)
     max_period: list[str] = field(default_factory=list)
     min_period: list[str] = field(default_factory=list)
+    preserve_n_clusters: bool | None = None
+
+    def __post_init__(self) -> None:
+        """Emit FutureWarning if preserve_n_clusters is not explicitly set."""
+        if self.preserve_n_clusters is None and self.has_extremes():
+            warnings.warn(
+                "preserve_n_clusters currently defaults to False to match behaviour of the old api, "
+                "but will default to True in a future release. Set preserve_n_clusters explicitly "
+                "to silence this warning.",
+                FutureWarning,
+                stacklevel=3,
+            )
 
     def has_extremes(self) -> bool:
         """Check if any extreme periods are configured."""
@@ -799,6 +824,17 @@ class ExtremeConfig:
             self.max_value or self.min_value or self.max_period or self.min_period
         )
 
+    @property
+    def _effective_preserve_n_clusters(self) -> bool:
+        """Get the effective value for preserve_n_clusters.
+
+        Returns False if not explicitly set (current default behavior).
+        In a future release, the default will change to True.
+        """
+        if self.preserve_n_clusters is None:
+            return False  # Current default, will change to True in future
+        return self.preserve_n_clusters
+
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for JSON serialization."""
         result: dict[str, Any] = {}
@@ -812,6 +848,8 @@ class ExtremeConfig:
             result["max_period"] = self.max_period
         if self.min_period:
             result["min_period"] = self.min_period
+        if self.preserve_n_clusters is not None:
+            result["preserve_n_clusters"] = self.preserve_n_clusters
         return result
 
     @classmethod
@@ -823,6 +861,7 @@ class ExtremeConfig:
             min_value=data.get("min_value", []),
             max_period=data.get("max_period", []),
             min_period=data.get("min_period", []),
+            preserve_n_clusters=data.get("preserve_n_clusters"),
         )
 
 

tsam/timeseriesaggregation.py

@@ -132,6 +132,7 @@ class TimeSeriesAggregation:
         weightDict=None,
         segmentation=False,
         extremePeriodMethod="None",
+        extremePreserveNumClusters=False,
         representationMethod=None,
         representationDict=None,
         distributionPeriodWise=True,
@@ -318,6 +319,8 @@ class TimeSeriesAggregation:
 
         self.extremePeriodMethod = extremePeriodMethod
 
+        self.extremePreserveNumClusters = extremePreserveNumClusters
+
         self.evalSumPeriods = evalSumPeriods
 
         self.sortValues = sortValues
@@ -683,6 +686,46 @@ class TimeSeriesAggregation:
 
         return unnormalizedTimeSeries
 
+    def _countExtremePeriods(self, groupedSeries):
+        """
+        Count unique extreme periods without modifying any state.
+
+        Used by extremePreserveNumClusters to determine how many clusters
+        to reserve for extreme periods before clustering.
+
+        Note: The extreme-finding logic (idxmax/idxmin on peak/mean) must
+        stay in sync with _addExtremePeriods. This is intentionally separate
+        because _addExtremePeriods also filters out periods that are already
+        cluster centers (not known at count time).
+        """
+        extremePeriodIndices = set()
+
+        # Only iterate over columns that are actually in extreme lists
+        extreme_columns = (
+            set(self.addPeakMax)
+            | set(self.addPeakMin)
+            | set(self.addMeanMax)
+            | set(self.addMeanMin)
+        )
+
+        for column in extreme_columns:
+            col_data = groupedSeries[column]
+
+            if column in self.addPeakMax:
+                extremePeriodIndices.add(col_data.max(axis=1).idxmax())
+            if column in self.addPeakMin:
+                extremePeriodIndices.add(col_data.min(axis=1).idxmin())
+
+            # Compute mean only once if needed for either addMeanMax or addMeanMin
+            if column in self.addMeanMax or column in self.addMeanMin:
+                mean_series = col_data.mean(axis=1)
+                if column in self.addMeanMax:
+                    extremePeriodIndices.add(mean_series.idxmax())
+                if column in self.addMeanMin:
+                    extremePeriodIndices.add(mean_series.idxmin())
+
+        return len(extremePeriodIndices)
+
     def _addExtremePeriods(
         self,
         groupedSeries,
@@ -983,7 +1026,7 @@ class TimeSeriesAggregation:
         # Reshape back to 2D: (n_clusters, n_cols * n_timesteps)
         return arr.reshape(n_clusters, -1)
 
-    def _clusterSortedPeriods(self, candidates, n_init=20):
+    def _clusterSortedPeriods(self, candidates, n_init=20, n_clusters=None):
         """
         Runs the clustering algorithms for the sorted profiles within the period
         instead of the original profiles. (Duration curve clustering)
@@ -1001,13 +1044,16 @@ class TimeSeriesAggregation:
             n_periods, -1
         )
 
+        if n_clusters is None:
+            n_clusters = self.noTypicalPeriods
+
         (
             _altClusterCenters,
             self.clusterCenterIndices,
             clusterOrders_C,
         ) = aggregatePeriods(
             sortedClusterValues,
-            n_clusters=self.noTypicalPeriods,
+            n_clusters=n_clusters,
             n_iter=30,
             solver=self.solver,
             clusterMethod=self.clusterMethod,
@@ -1052,6 +1098,41 @@ class TimeSeriesAggregation:
         """
         self._preProcessTimeSeries()
 
+        # Warn if extremePreserveNumClusters is ignored due to predefined cluster order
+        if (
+            self.predefClusterOrder is not None
+            and self.extremePreserveNumClusters
+            and self.extremePeriodMethod not in ("None", "replace_cluster_center")
+        ):
+            warnings.warn(
+                "extremePreserveNumClusters=True is ignored when predefClusterOrder "
+                "is set. Extreme periods will be appended via _addExtremePeriods "
+                "without reserving clusters upfront. To avoid this warning, set "
+                "extremePreserveNumClusters=False or remove predefClusterOrder.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        # Count extreme periods upfront if include_in_count is True
+        # Note: replace_cluster_center doesn't add new clusters, so skip
+        n_extremes = 0
+        if (
+            self.extremePreserveNumClusters
+            and self.extremePeriodMethod not in ("None", "replace_cluster_center")
+            and self.predefClusterOrder is None  # Don't count for predefined
+        ):
+            n_extremes = self._countExtremePeriods(self.normalizedPeriodlyProfiles)
+
+            if self.noTypicalPeriods <= n_extremes:
+                raise ValueError(
+                    f"n_clusters ({self.noTypicalPeriods}) must be greater than "
+                    f"the number of extreme periods ({n_extremes}) when "
+                    "preserve_n_clusters=True"
+                )
+
+        # Compute effective number of clusters for the clustering algorithm
+        effective_n_clusters = self.noTypicalPeriods - n_extremes
+
         # check for additional cluster parameters
         if self.evalSumPeriods:
             evaluationValues = (
@@ -1096,7 +1177,7 @@ class TimeSeriesAggregation:
                     self._clusterOrder,
                 ) = aggregatePeriods(
                     candidates,
-                    n_clusters=self.noTypicalPeriods,
+                    n_clusters=effective_n_clusters,
                     n_iter=100,
                     solver=self.solver,
                     clusterMethod=self.clusterMethod,
@@ -1107,7 +1188,7 @@ class TimeSeriesAggregation:
                 )
             else:
                 self.clusterCenters, self._clusterOrder = self._clusterSortedPeriods(
-                    candidates
+                    candidates, n_clusters=effective_n_clusters
                 )
             self.clusteringDuration = time.time() - cluster_duration
 
@@ -1117,7 +1198,6 @@ class TimeSeriesAggregation:
             self.clusterPeriods.append(cluster_center[:delClusterParams])
 
         if not self.extremePeriodMethod == "None":
-            # overwrite clusterPeriods and clusterOrder
             (
                 self.clusterPeriods,
                 self._clusterOrder,

{tsam-3.0.0.dist-info → tsam-3.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsam
-Version: 3.0.0
+Version: 3.1.0
 Summary: Time series aggregation module (tsam) to create typical periods
 Author-email: Leander Kotzur <leander.kotzur@googlemail.com>, Maximilian Hoffmann <maximilian.hoffmann@julumni.fz-juelich.de>
 Maintainer-email: Julian Belina <j.belina@fz-juelich.de>
@@ -49,14 +49,8 @@ Requires-Dist: pandas<=3.0.0,>=2.2.0
 Requires-Dist: numpy<=2.4.1,>=1.22.4
 Requires-Dist: pyomo<=6.95,>=6.4.8
 Requires-Dist: networkx<=3.6.1,>=2.5
-Requires-Dist: tqdm<=4.67.1,>=4.21.0
+Requires-Dist: tqdm<=4.67.2,>=4.21.0
 Requires-Dist: highspy<=1.12.0,>=1.7.2
-Provides-Extra: plot
-Requires-Dist: plotly>=5.0.0; extra == "plot"
-Provides-Extra: notebooks
-Requires-Dist: notebook>=7.5.0; extra == "notebooks"
-Requires-Dist: plotly>=5.0.0; extra == "notebooks"
-Requires-Dist: matplotlib; extra == "notebooks"
 Provides-Extra: develop
 Requires-Dist: pytest; extra == "develop"
 Requires-Dist: pytest-cov; extra == "develop"
@@ -65,6 +59,7 @@ Requires-Dist: codecov; extra == "develop"
 Requires-Dist: sphinx; extra == "develop"
 Requires-Dist: sphinx-autobuild; extra == "develop"
 Requires-Dist: sphinx_book_theme; extra == "develop"
+Requires-Dist: nbsphinx; extra == "develop"
 Requires-Dist: twine; extra == "develop"
 Requires-Dist: nbval; extra == "develop"
 Requires-Dist: ruff; extra == "develop"
@@ -73,7 +68,11 @@ Requires-Dist: pandas-stubs; extra == "develop"
 Requires-Dist: pre-commit; extra == "develop"
 Requires-Dist: plotly>=5.0.0; extra == "develop"
 Requires-Dist: notebook>=7.5.0; extra == "develop"
-Requires-Dist: matplotlib; extra == "develop"
+Provides-Extra: plot
+Requires-Dist: plotly>=5.0.0; extra == "plot"
+Provides-Extra: notebooks
+Requires-Dist: notebook>=7.5.0; extra == "notebooks"
+Requires-Dist: plotly>=5.0.0; extra == "notebooks"
 Dynamic: license-file
 
 [![Version](https://img.shields.io/pypi/v/tsam.svg)](https://pypi.python.org/pypi/tsam) [![Conda Version](https://img.shields.io/conda/vn/conda-forge/tsam.svg)](https://anaconda.org/conda-forge/tsam) [![Documentation Status](https://readthedocs.org/projects/tsam/badge/?version=latest)](https://tsam.readthedocs.io/en/latest/) [![PyPI - License](https://img.shields.io/pypi/l/tsam)]((https://github.com/FZJ-IEK3-VSA/tsam/blob/master/LICENSE.txt)) [![codecov](https://codecov.io/gh/FZJ-IEK3-VSA/tsam/branch/master/graph/badge.svg)](https://codecov.io/gh/FZJ-IEK3-VSA/tsam)
@@ -217,9 +216,9 @@ cluster_representatives = aggregation.createTypicalPeriods()
 ### Detailed examples
 Detailed examples can be found at:/docs/source/examples_notebooks/
 
-A [**first example**](/docs/source/examples_notebooks/aggregation_example.ipynb) shows the capabilites of tsam as jupyter notebook.
+A [**quickstart example**](/docs/source/examples_notebooks/quickstart.ipynb) shows the capabilities of tsam as a Jupyter notebook.
 
-A [**second example**](/docs/source/examples_notebooks/aggregation_optiinput.ipynb) shows in more detail how to access the relevant aggregation results required for paramtrizing e.g. an optimization.
+A [**second example**](/docs/source/examples_notebooks/optimization_input.ipynb) shows in more detail how to access the relevant aggregation results required for parameterizing e.g. an optimization.
 
 The example time series are based on a department [publication](https://www.mdpi.com/1996-1073/10/3/361) and the [test reference years of the DWD](https://www.dwd.de/DE/leistungen/testreferenzjahre/testreferenzjahre.html).
 

{tsam-3.0.0.dist-info → tsam-3.1.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 tsam/__init__.py,sha256=l5PQB_p-OCSQK2daCTc2k4VP6ZtFwOXE_QSVUTCsbV0,2236
-tsam/api.py,sha256=FvXzpFScwzypgHOAfCaZmaetWv_P6pqpTTcpRLxDU2E,22575
-tsam/config.py,sha256=2povXN55P2VoVHK13MiN6M3bJZVgcY3jn-maCBOhBWY,33523
+tsam/api.py,sha256=YisjYhfsZRRngBzHyw-u_JHeRMpYmuYCXk83oPO15PA,22662
+tsam/config.py,sha256=4gbwfh3aeCW7y5NIKgtNjtRq7afhMP9fdWWvZ8vO3PM,35438
 tsam/exceptions.py,sha256=arCs6OQ3r5MIcwO7aHRjB8Joy2rFHWN80vvEr_hKnqY,509
 tsam/hyperparametertuning.py,sha256=S4tCjf4wgKXrX7MCtJGUJXnm26sHHB4qWA1UEmNlTM4,11225
 tsam/periodAggregation.py,sha256=ppEEWpxBh0x5nQGJiywkPPHOvl0uAphdoroqxYfIJmQ,5306
@@ -8,7 +8,7 @@ tsam/plot.py,sha256=gBnMkiCp7EfVhBn9b4ywM_qOP2CFzTG9T-aQTKUa2qU,15701
 tsam/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tsam/representations.py,sha256=MKJJtClMkacOkItbRwreFo1d0Vr6gEAItq4-OwqTfAE,7053
 tsam/result.py,sha256=0eckXhXZl3dqe24pNlhIDrG9c6CEnIoxExPSFCSH3tM,13707
-tsam/timeseriesaggregation.py,sha256=8Xy65KmYxCV96N1t-zz8GMc4S4r8w-NZqUQQP0sP0b8,59351
+tsam/timeseriesaggregation.py,sha256=UxdNYqKVr4Ydom4wIvu49080Nr4AeArl8Pm1Enukl7I,62807
 tsam/tuning.py,sha256=7yhh6BgxYCdFOJELZU8artR-TuG1oZDRoPfIF9Q9p4Q,35822
 tsam/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tsam/utils/durationRepresentation.py,sha256=ESPXhSuHplRig9uOEJGgEOdbzaa0zo-1tPW7o_N0_yk,9791
@@ -16,8 +16,8 @@ tsam/utils/k_maxoids.py,sha256=hUnqkOgH-nTjzH8B6Ho7oF9iWfXaKiJeWa0aDOlshvI,4241
 tsam/utils/k_medoids_contiguity.py,sha256=ZK09BkwWaub-JwtXbOuLx2OhE8mYkkNbCmmYO6ylb4A,5920
 tsam/utils/k_medoids_exact.py,sha256=p3nd2madMrOGau6sWE7i3jADXVQkUGF66CPTV2QyYr0,6999
 tsam/utils/segmentation.py,sha256=qY8jEVB8Rj6tZNwF-mz-mldmsSkaaPOrWoDM_hgEe8M,11094
-tsam-3.0.0.dist-info/licenses/LICENSE.txt,sha256=YO7oiTI8iS0QbTaumTaIr8QkVgZPrgqiBKO-s4eiwik,1210
-tsam-3.0.0.dist-info/METADATA,sha256=BLpBzrhvz3oJ5eModR0EMK9smnQrBzGAfvfe9Fzor0M,16097
-tsam-3.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-tsam-3.0.0.dist-info/top_level.txt,sha256=MFI15PnPuMv8F1hTAOXbjGu41z-l6dJbnK69WlIQNcM,5
-tsam-3.0.0.dist-info/RECORD,,
+tsam-3.1.0.dist-info/licenses/LICENSE.txt,sha256=YO7oiTI8iS0QbTaumTaIr8QkVgZPrgqiBKO-s4eiwik,1210
+tsam-3.1.0.dist-info/METADATA,sha256=hVNAm38MZgPw8zw4_uKyWT-ioWW7WVOluPoJ6JZKoY4,16044
+tsam-3.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+tsam-3.1.0.dist-info/top_level.txt,sha256=MFI15PnPuMv8F1hTAOXbjGu41z-l6dJbnK69WlIQNcM,5
+tsam-3.1.0.dist-info/RECORD,,