Mobt 496 enforce forecast consistency

improver/calibration/reliability_calibration.py

@@ -49,7 +49,6 @@
     create_unified_frt_coord,
     filter_non_matching_cubes,
 )
-from improver.cube_combiner import Combine
 from improver.metadata.probabilistic import (
     find_threshold_coordinate,
     probability_is_above_or_below,
@@ -1442,70 +1441,3 @@ def process(
         calibrated_forecast.data = calibrated_forecast.data.astype("float32")
 
         return calibrated_forecast
-
-
-class EnforceConsistentProbabilities(PostProcessingPlugin):
-    """Reduces the probabilities of a forecast to make it consistent
-    with another provided reference forecast, such that at any grid square the
-    probability of the forecast is less than the reference forecast. As an example, to
-    reduce the probability of a low cloud forecast to be less than the probability of the
-    reference forecast of total cloud.
-    """
-
-    def __init__(self, diff_for_warning: float = None) -> None:
-        """
-        Initialise class for enforcing probabilities between two forecasts.
-
-        Args:
-            diff_for_warning:
-                A float between 0 and 1. If assigned, the plugin will raise a warning
-                if the forecast probabilities are decreased by more than this value.
-        """
-        self.diff_for_warning = diff_for_warning
-
-    def process(self, forecast_cube: Cube, ref_forecast: Cube) -> Cube:
-        """
-        Lowers the probabilities of the forecast_cube to make it consistent with
-        the reference forecast. This is done by lowering the probabilities of the forecast cube,
-        to be equal to the reference forecast if they are higher than the reference forecast.
-        If the probability is already less than or equal to the reference forecast then the
-        probability is not altered.
-
-        Args:
-            forecast_cube:
-                A forecast cube of probabilities
-            ref_forecast:
-                A cube of probabilities that is used as an upper limit for
-                the forecast_cube probabilities. It must have the same dimensions
-                as the forecast_cube.
-
-        Returns:
-            A forecast cube of probabilities that has identical metadata to forecast_cube but
-            with reduced probabilities to make it consistent with ref_forecast
-        """
-
-        # re-name ref_forecast's threshold coordinate to ensure the coordinate names match for
-        # the combine plugin
-        forecast_threshold = find_threshold_coordinate(forecast_cube)
-        ref_forecast_threshold = find_threshold_coordinate(ref_forecast)
-
-        ref_forecast_threshold.standard_name = forecast_threshold.standard_name
-        ref_forecast_threshold.long_name = forecast_threshold.long_name
-
-        diff = Combine(operation="-")([ref_forecast, forecast_cube])
-
-        # clip the positive values such that only negative values or zeroes remain.
-        # These differences will be added to the forecast_cube probabilities.
-        diff.data = np.clip(diff.data, None, 0)
-
-        new_forecast = Combine(operation="+")([forecast_cube, diff])
-
-        largest_change = abs(np.amin(diff.data))
-        if self.diff_for_warning is not None and largest_change > self.diff_for_warning:
-            warnings.warn(
-                f"Inconsistency between forecast {forecast_cube.name} and {ref_forecast.name}"
-                f"is greater than {self.diff_for_warning}. Maximum absolute difference reported"
-                f"was {largest_change}"
-            )
-
-        return new_forecast

improver/cli/enforce_consistent_forecasts.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# -----------------------------------------------------------------------------
+# (C) British Crown copyright. The Met Office.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+"""CLI to enforce consistency between two forecasts."""
+
+from improver import cli
+
+
+@cli.clizefy
+@cli.with_output
+def process(
+    *cubes: cli.inputcubelist,
+    ref_name: str = None,
+    additive_amount: float = 0.0,
+    multiplicative_amount: float = 1.0,
+    comparison_operator: str = ">=",
+    diff_for_warning: float = None,
+):
+    """
+    Module to enforce that the values in the forecast cube are not less than or not
+    greater than a linear function of the corresponding values in the
+    reference forecast.
+
+    Args:
+        cubes (iris.cube.CubeList or list of iris.cube.Cube):
+            containing:
+                forecast_cube (iris.cube.Cube):
+                    Cube of forecasts to be updated by using the reference forecast to
+                    create a bound on the value of the forecasts
+                ref_forecast (iris.cube.Cube)
+                    Cube of forecasts used to create a bound for the values in
+                    forecast_cube. It must be the same shape as forecast_cube but have
+                    a different name.
+        ref_name (str): Name of ref_forecast cube
+        additive_amount: The amount to be added to the reference forecast prior to
+            enforcing consistency between the forecast and reference forecast. If
+            both an additive_amount and multiplicative_amount are specified then
+            addition occurs after multiplication.
+        multiplicative_amount: The amount to multiply the reference forecast by
+            prior to enforcing consistency between the forecast and reference
+            forecast. If both an additive_amount and multiplicative_amount are
+            specified then addition occurs after multiplication.
+        comparison_operator: Determines whether the forecast is enforced to be not
+            less than or not greater than the reference forecast. Valid choices are
+            ">=", for not less than, and "<=" for not greater than.
+        diff_for_warning: If assigned, the plugin will raise a warning if any
+            absolute change in forecast value is greater than this value.
+
+    Returns:
+        iris.cube.Cube:
+            A forecast cube with identical metadata to forecast but the forecasts are
+            enforced to be not less than or not greater than a linear function of
+            reference_forecast.
+    """
+    from iris.cube import CubeList
+
+    from improver.utilities.enforce_consistency import EnforceConsistentForecasts
+    from improver.utilities.flatten import flatten
+
+    cubes = flatten(cubes)
+
+    if len(cubes) != 2:
+        raise ValueError(
+            f"Exactly two cubes should be provided but received {len(cubes)}"
+        )
+
+    ref_forecast = CubeList(cubes).extract_cube(ref_name)
+    cubes.remove(ref_forecast)
+
+    forecast_cube = cubes[0]
+
+    plugin = EnforceConsistentForecasts(
+        additive_amount=additive_amount,
+        multiplicative_amount=multiplicative_amount,
+        comparison_operator=comparison_operator,
+        diff_for_warning=diff_for_warning,
+    )
+
+    return plugin(forecast_cube, ref_forecast)

improver/utilities/enforce_consistency.py

@@ -0,0 +1,130 @@
+# -*- coding: utf-8 -*-
+# -----------------------------------------------------------------------------
+# (C) British Crown copyright. The Met Office.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+# * Neither the name of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+"""Provides utilities for enforcing consistency between forecasts."""
+import warnings
+
+import numpy as np
+from iris.cube import Cube
+
+from improver import PostProcessingPlugin
+
+
+class EnforceConsistentForecasts(PostProcessingPlugin):
+    """Enforce that the forecasts provided are no less than or no greater than some
+    linear function of a reference forecast. For example, wind speed forecasts may be
+    provided as the reference forecast for wind gust forecasts with a requirement that
+    wind gusts are not less than 110% of the corresponding wind speed forecast. Wind
+    speed forecasts of 10 m/s will mean that the resulting wind gust forecast will be
+    at least 11 m/s.
+    """
+
+    def __init__(
+        self,
+        additive_amount: float = 0.0,
+        multiplicative_amount: float = 1.0,
+        comparison_operator: str = ">=",
+        diff_for_warning: float = None,
+    ) -> None:
+        """
+        Initialise class for enforcing consistency between a forecast and a linear
+        function of a reference forecast.
+
+        Args:
+            additive_amount: The amount to be added to the reference forecast prior to
+                enforcing consistency between the forecast and reference forecast. If
+                both an additive_amount and multiplicative_amount are specified then
+                addition occurs after multiplication.
+            multiplicative_amount: The amount to multiply the reference forecast by
+                prior to enforcing consistency between the forecast and reference
+                forecast. If both an additive_amount and multiplicative_amount are
+                specified then addition occurs after multiplication.
+            comparison_operator: Determines whether the forecast is enforced to be not
+                less than or not greater than the reference forecast. Valid choices are
+                ">=", for not less than, and "<=" for not greater than.
+            diff_for_warning: If assigned, the plugin will raise a warning if any
+                absolute change in forecast value is greater than this value.
+        """
+
+        self.additive_amount = additive_amount
+        self.multiplicative_amount = multiplicative_amount
+        self.comparison_operator = comparison_operator
+        self.diff_for_warning = diff_for_warning
+
+    def process(self, forecast: Cube, reference_forecast: Cube) -> Cube:
+        """
+        Function to enforce that the values in forecast_cube are not less than or not
+        greater than a linear function of the corresponding values in
+        reference_forecast.
+
+        Args:
+            forecast: A forecast cube of probabilities or percentiles
+            reference_forecast: A reference forecast cube used to determine the bound
+                of the forecast cube.
+
+        Returns:
+            A forecast cube with identical metadata to forecast but the forecasts are
+            enforced to be not less than or not greater than a linear function of
+            reference_forecast.
+        """
+        # calculate forecast_bound by applying specified linear transformation to
+        # reference_forecast
+        forecast_bound = reference_forecast.copy()
+        forecast_bound.data = self.multiplicative_amount * forecast_bound.data
+        forecast_bound.data = self.additive_amount + forecast_bound.data
+
+        # assign forecast_bound to be either an upper or lower bound depending on input
+        # comparison_operator
+        lower_bound = None
+        upper_bound = None
+        if self.comparison_operator == ">=":
+            lower_bound = forecast_bound.data
+        elif self.comparison_operator == "<=":
+            upper_bound = forecast_bound.data
+        else:
+            msg = (
+                f"comparison_operator must be either '>=' or '<=', not "
+                f"{self.comparison_operator}."
+            )
+            raise ValueError(msg)
+
+        new_forecast = forecast.copy()
+        new_forecast.data = np.clip(new_forecast.data, lower_bound, upper_bound)
+
+        diff = new_forecast.data - forecast.data
+        max_abs_diff = np.max(np.abs(diff))
+        if self.diff_for_warning is not None and max_abs_diff > self.diff_for_warning:
+            warnings.warn(
+                f"Inconsistency between forecast {forecast.name} and "
+                f"{reference_forecast.name} is greater than {self.diff_for_warning}. "
+                f"Maximum absolute difference reported was {max_abs_diff}"
+            )
+
+        return new_forecast

improver_tests/acceptance/SHA256SUMS

@@ -170,9 +170,12 @@ b946c7687cb9ed02a12a934429a31306004ad45214cf4b451468b077018c0911  ./convection-r
 d3efbc6014743793fafed512a8017a7b75e4f0ffa7fd202cd4f1b4a1086b2583  ./create-grid-with-halo/basic/kgo.nc
 fee00437131d2367dc317e5b0fff44e65e03371b8f096bf1ac0d4cc7253693c9  ./create-grid-with-halo/basic/source_grid.nc
 bf7e42be7897606682c3ecdaeb27bf3d3b6ab13a9a88b46c88ae6e92801c6245  ./create-grid-with-halo/halo_size/kgo.nc
-5474c4c2309dcc0991355007f20869eb6d1d234d721bdf37542cddb0570d7217  ./enforce-consistent-probabilities/hybrid_total_cloud.nc
-7e435c2db5e792b71bb5170140fbe1e37cc03d96bd88f73ce7196f9469ba3e13  ./enforce-consistent-probabilities/kgo.nc
-764833f16f1ed5939ba82130fa73961fdecacceebcf2b4cdb2970cb670e2ee3e  ./enforce-consistent-probabilities/total_cloud.nc
+f5085e98e23fc903395372f2e0e6a2bc028f7fa44cc212d49690782cd2dd275a  ./enforce-consistent-forecasts/percentile_forecast.nc
+1de3227751ff46a7cf39a0b7bcd4156717814809c3a02153fcd35ee4adfb5668  ./enforce-consistent-forecasts/percentile_kgo.nc
+3876dcc20a45fdc6d6c775d6970903f06b1f75e6bcbdfb7436acd4d383aa816a  ./enforce-consistent-forecasts/percentile_reference.nc
+5474c4c2309dcc0991355007f20869eb6d1d234d721bdf37542cddb0570d7217  ./enforce-consistent-forecasts/probability_forecast.nc
+7e435c2db5e792b71bb5170140fbe1e37cc03d96bd88f73ce7196f9469ba3e13  ./enforce-consistent-forecasts/probability_kgo.nc
+764833f16f1ed5939ba82130fa73961fdecacceebcf2b4cdb2970cb670e2ee3e  ./enforce-consistent-forecasts/probability_reference.nc
 9b48f3eabeed93a90654a5e6a2f06fcb7297cdba40f650551d99a5e310cf27dd  ./estimate-emos-coefficients-from-table/altitude.nc
 93e0c05333bc93ca252027ee5e2da12ee93fac5bbff4bab00b9c334ad83141e2  ./estimate-emos-coefficients-from-table/forecast_table/_common_metadata
 037e1cfc55c703a30cdbc1dee78da47020a598683247dc29a8ef88e65b53dfb1  ./estimate-emos-coefficients-from-table/forecast_table/_metadata
@@ -297,6 +300,8 @@ d442c0ec20cd8de5e3a929827428ed09fa6e05ec05aec1d972aee0b314612c65  ./generate-oro
 34efbac81d20f8cbae8f7881d984ce7fc9fb59d3f54e478611a914bf94b80dfc  ./generate-orographic-smoothing-coefficients/orography.nc
 9bb6be36c7ecb41b9f72bc6d46a7566af16863685b8e4f78a59e1666ce8cba22  ./generate-percentiles/basic/input.nc
 431f094a771afc72804039d49c72efdbd22e95b4ff88bf4e6e8f37b6b1b19f2f  ./generate-percentiles/basic/kgo.nc
+5e7d6304b1e88826905eea962b361a2285e60c21012253973f212323d48e1ee3  ./generate-percentiles/basic/rebadging/flat_rank_histogram_percentiles_kgo.nc
+760eb2428656f80933c3f9c4a179e724f8de92c85b8ae1a54ea468e42b8f1e55  ./generate-percentiles/basic/rebadging/optimal_crps_percentiles_kgo.nc
 056e0ab74400b19c60d05410abbed6c8fd59cf44f5b3136c58c4d4706ec53e29  ./generate-percentiles/ecc_bounds_warning/input.nc
 a57f0db9012544e71e4ef322012bf5a4d03b4b84a2b03223446c66a9afe52a31  ./generate-percentiles/ecc_bounds_warning/kgo.nc
 602ec07949687b8cc4295199f92e02863749349dc750b63dfed478c0b00b706e  ./generate-percentiles/probability_convert/multi_realization.nc