Add quantile mapping and associated tests #2264

maxwhitemet · 2025-12-09T15:07:16Z

Addresses #1007

This PR implements quantile mapping into the IMPROVER repo, adding a quantile mapping module, CLI, unit tests, and acceptance tests.

A demonstration of the plugin's functionality is available here.

Testing:

Ran tests and they passed OK
Added new tests for the new feature(s)

codecov · 2025-12-09T16:31:04Z

Codecov Report

❌ Patch coverage is 96.10390% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.19%. Comparing base (84a8944) to head (ae2a5ad).
⚠️ Report is 154 commits behind head on master.

Files with missing lines	Patch %	Lines
improver/calibration/quantile_mapping.py	96.10%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2264      +/-   ##
==========================================
- Coverage   98.39%   95.19%   -3.20%     
==========================================
  Files         124      150      +26     
  Lines       12212    15323    +3111     
==========================================
+ Hits        12016    14587    +2571     
- Misses        196      736     +540

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

gavinevans

Thanks @maxwhitemet 👍

I've added some comments below.

improver/calibration/quantile_mapping.py

gavinevans · 2025-12-15T16:47:59Z

improver/calibration/quantile_mapping.py

+    return np.interp(quantiles, empirical_quantiles, sorted_values)
+
+
+def quantile_mapping(


I think it might be good to name this something else to avoid a quantile_mapping function and a QuantileMapping class in the same file.

Thank you.

I have changed the name to 'map_quantiles'. Please let me know if this needs changing.

gavinevans · 2025-12-15T17:03:32Z

improver/calibration/quantile_mapping.py

+        # Create a copy of the forecast_cube or forecast_to_calibrate cube to hold
+        # output data and preserve metadata.
+        output_cube = (
+            forecast_cube.copy()
+            if forecast_to_calibrate is None
+            else forecast_to_calibrate.copy()
+        )
+
+        # Extract data, handling masked arrays
+        if np.ma.is_masked(reference_cube.data):
+            reference_data_flat = reference_cube.data.filled().flatten()
+        else:
+            reference_data_flat = reference_cube.data.flatten()
+
+        if np.ma.is_masked(forecast_cube.data):
+            forecast_data_flat = forecast_cube.data.filled().flatten()
+        else:
+            forecast_data_flat = forecast_cube.data.flatten()
+
+        # Determine values to map and output shape
+        if forecast_to_calibrate is None:
+            # Use forecast_cube data
+            if np.ma.is_masked(output_cube.data):
+                values_to_map_flat = output_cube.data.filled().flatten()
+            else:
+                values_to_map_flat = output_cube.data.flatten()
+            output_shape = forecast_cube.shape
+            output_mask = (
+                forecast_cube.data.mask if np.ma.is_masked(forecast_cube.data) else None
+            )
+        else:
+            # Use provided cube's data
+            output_cube = forecast_to_calibrate.copy()
+            if np.ma.is_masked(forecast_to_calibrate.data):
+                values_to_map_flat = forecast_to_calibrate.data.filled().flatten()
+            else:
+                values_to_map_flat = forecast_to_calibrate.data.flatten()
+            output_shape = forecast_to_calibrate.shape
+            output_mask = (
+                forecast_to_calibrate.data.mask
+                if np.ma.is_masked(forecast_to_calibrate.data)
+                else None
+            )


I think that you could put this into a separate method / function, so that the process method is simpler. You even put the pattern below into a method / function, given that you re-use a number of times:

if np.ma.is_masked(forecast_cube.data): forecast_data_flat = forecast_cube.data.filled().flatten() else: forecast_data_flat = forecast_cube.data.flatten()

I have now removed the use of .filled() as I was concerned this would introduce changes to the statistics. Instead, the code now only processes unmasked data points, and later reinserts the mask where it was.

improver/calibration/quantile_mapping.py

improver_tests/calibration/test_QuantileMapping.py

gavinevans · 2025-12-16T11:20:16Z

improver_tests/calibration/test_QuantileMapping.py

I think that you may as well move these tests into a quantile_mapping directory to match the pattern of the other tests for calibration methods.

- Move functionality into QuantileMapping class - Remove redundancy - Increase variable name clarity - Refactor into smaller functions 2. Additions: - Improved readability experience of docstrings - Fixed improper masked array handling

…nts.

maxwhitemet

In addition to the feedback received, I have implemented the below modifications:

Made lots of changes to docstrings, such that now:
- More extensive documentation has moved from private to public methods
- Removed redundant Args sections in private methods, defined elsewhere.
Masked arrays
- I was concerned about what would happen if the reference cube and the post-processed forecast cube had differing mask locations. Thus I have added handling that may require further discussion: combine the masks such that only points that are valid in both cubes are used to build the CDFs.
- Removed redundant use of np.where for non-masked arrays as I discovered this is implicitly handled in np.ma.where

improver/calibration/quantile_mapping.py

maxwhitemet · 2025-12-29T11:00:34Z

improver/calibration/quantile_mapping.py

+    return np.interp(quantiles, empirical_quantiles, sorted_values)
+
+
+def quantile_mapping(


Thank you.

I have changed the name to 'map_quantiles'. Please let me know if this needs changing.

maxwhitemet · 2025-12-29T11:34:53Z

improver/cli/quantile_mapping.py

+    *,
+    mapping_method: str = "floor",
+    preservation_threshold: float = None,
+    forecast_to_calibrate: cli.inputcube = None,


I have removed the option to provide the third cube from the plugin and this CLI script. Thank you.

maxwhitemet · 2025-12-29T14:19:59Z

improver/calibration/quantile_mapping.py

+        # Create a copy of the forecast_cube or forecast_to_calibrate cube to hold
+        # output data and preserve metadata.
+        output_cube = (
+            forecast_cube.copy()
+            if forecast_to_calibrate is None
+            else forecast_to_calibrate.copy()
+        )
+
+        # Extract data, handling masked arrays
+        if np.ma.is_masked(reference_cube.data):
+            reference_data_flat = reference_cube.data.filled().flatten()
+        else:
+            reference_data_flat = reference_cube.data.flatten()
+
+        if np.ma.is_masked(forecast_cube.data):
+            forecast_data_flat = forecast_cube.data.filled().flatten()
+        else:
+            forecast_data_flat = forecast_cube.data.flatten()
+
+        # Determine values to map and output shape
+        if forecast_to_calibrate is None:
+            # Use forecast_cube data
+            if np.ma.is_masked(output_cube.data):
+                values_to_map_flat = output_cube.data.filled().flatten()
+            else:
+                values_to_map_flat = output_cube.data.flatten()
+            output_shape = forecast_cube.shape
+            output_mask = (
+                forecast_cube.data.mask if np.ma.is_masked(forecast_cube.data) else None
+            )
+        else:
+            # Use provided cube's data
+            output_cube = forecast_to_calibrate.copy()
+            if np.ma.is_masked(forecast_to_calibrate.data):
+                values_to_map_flat = forecast_to_calibrate.data.filled().flatten()
+            else:
+                values_to_map_flat = forecast_to_calibrate.data.flatten()
+            output_shape = forecast_to_calibrate.shape
+            output_mask = (
+                forecast_to_calibrate.data.mask
+                if np.ma.is_masked(forecast_to_calibrate.data)
+                else None
+            )


I have now removed the use of .filled() as I was concerned this would introduce changes to the statistics. Instead, the code now only processes unmasked data points, and later reinserts the mask where it was.

improver/calibration/quantile_mapping.py

maxwhitemet · 2025-12-29T15:59:43Z

improver/cli/quantile_mapping.py

+    reference_cube: cli.inputcube,
+    forecast_cube: cli.inputcube,


I have implemented your suggestion though excluded the portion of the 'cubes' docstring on land-sea masking handled by the estimate_emos_coefficients plugin here.

Please could you let me know if I should add this?

maxwhitemet force-pushed the mobt_1007_quantile_mapping_plugin branch from 1c47068 to 73363ed Compare December 9, 2025 16:20

maxwhitemet mentioned this pull request Dec 9, 2025

Add test data for quantile mapping acceptance tests metoppv/improver_test_data#116

Open

maxwhitemet force-pushed the mobt_1007_quantile_mapping_plugin branch from 73363ed to ae2a5ad Compare December 10, 2025 16:11

gavinevans requested changes Dec 16, 2025

View reviewed changes

maxwhitemet added 6 commits December 29, 2025 09:51

Add quantile mapping and associated tests

65d76f7

Recreate checksums

8883cfe

Remove unused @njit decorators

7b665ea

Implement basic review feedback

5490ae7

1. Implement reviewer feedback:

618d78a

- Move functionality into QuantileMapping class - Remove redundancy - Increase variable name clarity - Refactor into smaller functions 2. Additions: - Improved readability experience of docstrings - Fixed improper masked array handling

Implement reviewer feedback: support agnostic ordering of cube argume…

6ec215f

…nts.

maxwhitemet force-pushed the mobt_1007_quantile_mapping_plugin branch from ae2a5ad to 6ec215f Compare December 29, 2025 16:22

maxwhitemet commented Dec 29, 2025

View reviewed changes

maxwhitemet added 3 commits December 30, 2025 17:09

Update unit tests to reflect changes to plugin

477f1d1

Reflect changes to quantile mapping plugin in CLI

4c869cf

Update testing to reflect plugin changes

ba2359a

		return np.interp(quantiles, empirical_quantiles, sorted_values)


		def quantile_mapping(

Add quantile mapping and associated tests #2264

Are you sure you want to change the base?

Add quantile mapping and associated tests #2264

Uh oh!

Conversation

maxwhitemet commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

gavinevans left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maxwhitemet left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

maxwhitemet commented Dec 9, 2025 •

edited

Loading

codecov bot commented Dec 9, 2025 •

edited

Loading

maxwhitemet left a comment •

edited

Loading