Adds basic CFAD calculation and tests

Fixes #1010

Author: daflack

src/CSET/operators/plot.py

@@ -1393,6 +1393,60 @@ def _validate_cubes_coords(
         )
 
 
+def _calculate_CFAD(
+    cube: iris.cube.Cube, vertical_coordinate: str, bin_edges: list[float]
+) -> iris.cube.Cube:
+    """Calculate a Contour Frequency by Altitude Diagram (CFAD).
+
+    Parameters
+    ----------
+    cube: iris.cube.Cube
+        A cube of the data to be turned into a CFAD. It should be a minimum
+        of two dimensions with one being a user specified vertical coordinate.
+    vertical_coordinate: str
+        The vertical coordinate of the cube for the CFAD to be calculated over.
+    bin_edges: list[float]
+        The bin edges for the histogram. The bins need to be specified to
+        ensure consistency across the CFAD, otherwise it cannot be interpreted.
+    """
+    # Setup empty array for containing the CFAD data.
+    CFAD_values = np.zeros(
+        (len(cube.coord(vertical_coordinate).points), len(bin_edges) - 1)
+    )
+
+    # Set iterator for CFAD values.
+    i = 0
+
+    # Calculate the CFAD as a histogram summing to one for each level.
+    for level_cube in cube.slices_over(vertical_coordinate):
+        # Note setting density to True does not produce the correct
+        # normalization for a CFAD, where each row must sum to one.
+        CFAD_values[i, :] = (
+            np.histogram(level_cube.data.reshape(level_cube.data.size), bins=bin_edges)[
+                0
+            ]
+            / level_cube.data.size
+        )
+        i += 1
+    # calculate central points for bins
+    bins = (np.array(bin_edges[:-1]) + np.array(bin_edges[1:])) / 2.0
+    bin_bounds = np.array((bin_edges[:-1], bin_edges[1:])).T
+    # Now construct the coordinates for the cube.
+    vert_coord = cube.coord(vertical_coordinate)
+    bin_coord = iris.coords.DimCoord(
+        bins, bounds=bin_bounds, standard_name=cube.standard_name, units=cube.units
+    )
+    # Now construct the cube that is to be output.
+    CFAD = iris.cube.Cube(
+        CFAD_values,
+        dim_coords_and_dims=[(vert_coord, 0), (bin_coord, 1)],
+        standard_name=cube.standard_name,
+        units="1",
+    )
+    CFAD.attributes["type"] = "Contour Frequency by Altitude Diagram (CFAD)"
+    return CFAD
+
+
 ####################
 # Public functions #
 ####################

tests/operators/test_plots.py

@@ -27,6 +27,12 @@
 from CSET.operators import collapse, plot
 
 
+@pytest.fixture()
+def xwind() -> iris.cube.Cube:
+    """Get regridded xwind to run tests on."""
+    return iris.load_cube("tests/test_data/ageofair/aoa_in_rgd.nc", "x_wind")
+
+
 def test_check_single_cube():
     """Conversion to a single cube, and rejection where not possible."""
     cube = iris.cube.Cube([0.0])
@@ -779,3 +785,24 @@ def test_append_to_plot_index_case_aggregation_no_datetime(
     with open("meta.json", "rt") as fp:
         meta = json.load(fp)
     assert "case_date" not in meta
+
+
+def test_calculate_CFAD(xwind):
+    """Test calculating a CFAD."""
+    bins = np.array([-50, -40, -30, -20, -10, 0, 10, 20, 30, 40, 50])
+    calculated_CFAD = np.zeros((len(xwind.coord("pressure").points), len(bins) - 1))
+    j = 0
+    for level_cube in xwind.slices_over("pressure"):
+        calculated_CFAD[j, :] = (
+            np.histogram(level_cube.data.reshape(level_cube.data.size), bins=bins)[0]
+            / level_cube.data.size
+        )
+        j += 1
+    assert np.allclose(
+        plot._calculate_CFAD(
+            xwind, "pressure", [-50, -40, -30, -20, -10, 0, 10, 20, 30, 40, 50]
+        ).data,
+        calculated_CFAD,
+        rtol=1e-06,
+        atol=1e-02,
+    )