Finalises Lazy Data documentation (#5137)

* cube and io lazy data notes added

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Added comments within analysis, as well as palette and iterate, and what's new

* fixed docstrings as requested in @trexfeathers review

* reverted cube.py for time being

* fixed flake8 issue

* Lazy data second batch

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* updated lastest what'snew

* I almost hope this wasn't the fix, I'm such a moron

* adressed review changes

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Bill Little <bill.james.little@gmail.com>

Author: 3 people

docs/src/whatsnew/latest.rst

@@ -135,6 +135,8 @@ This document explains the changes made to Iris for this release
 
 #. `@HGWright`_ fixed some typo's from Gitwash. (:pull:`5145`)
 
+#. `@Esadek-MO`_ added notes to function docstrings to
+   to clarify if the function preserves laziness or not. (:pull:`5137`)
 
 💼 Internal
 ===========

lib/iris/analysis/__init__.py

@@ -2036,6 +2036,7 @@ def interp_order(length):
 
     result = cube.collapsed('longitude', iris.analysis.MEDIAN)
 
+
 This aggregator handles masked data, but NOT lazy data.  For lazy aggregation,
 please try :obj:`~.PERCENTILE`.
 

lib/iris/pandas.py

@@ -159,6 +159,8 @@ def as_cube(
             as_cube(series, calendars={0: cf_units.CALENDAR_360_DAY})
             as_cube(data_frame, calendars={1: cf_units.CALENDAR_STANDARD})
 
+    Since this function converts to/from a Pandas object, laziness will not be preserved.
+
     """
     message = (
         "iris.pandas.as_cube has been deprecated, and will be removed in a "
@@ -240,6 +242,8 @@ def as_cubes(
 
     :class:`dask.dataframe.DataFrame`\\ s are not supported.
 
+    Since this function converts to/from a Pandas object, laziness will not be preserved.
+
     Examples
     --------
     >>> from iris.pandas import as_cubes
@@ -599,6 +603,10 @@ def as_series(cube, copy=True):
     If you have a large array that cannot be copied,
     make sure it is not masked and use copy=False.
 
+    Notes
+    ------
+    Since this function converts to/from a Pandas object, laziness will not be preserved.
+
     """
     message = (
         "iris.pandas.as_series has been deprecated, and will be removed in a "
@@ -809,6 +817,10 @@ def as_data_frame(
     419903    298.995148
     Name: surface_temperature, Length: 419904, dtype: float32
 
+    Notes
+    ------
+    Since this function converts to/from a Pandas object, laziness will not be preserved.
+
     """
 
     def merge_metadata(meta_var_list):

lib/iris/plot.py

@@ -1112,6 +1112,11 @@ def contour(cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.contour` for details of other valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     result = _draw_2d_from_points("contour", None, cube, *args, **kwargs)
     return result
@@ -1136,6 +1141,11 @@ def contourf(cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.contourf` for details of other valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     coords = kwargs.get("coords")
     kwargs.setdefault("antialiased", True)
@@ -1200,6 +1210,11 @@ def default_projection(cube):
         import matplotlib.pyplot as plt
         ax = plt.ax(projection=default_projection(cube))
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     # XXX logic seems flawed, but it is what map_setup did...
     cs = cube.coord_system("CoordSystem")
@@ -1218,6 +1233,11 @@ def default_projection_extent(cube, mode=iris.coords.POINT_MODE):
             points, or the limits of the cell's bounds.
             The default is iris.coords.POINT_MODE.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     extents = cartography._xy_range(cube, mode)
     xlim = extents[0]
@@ -1255,7 +1275,13 @@ def _fill_orography(cube, coords, mode, vert_plot, horiz_plot, style_args):
 
 
 def orography_at_bounds(cube, facecolor="#888888", coords=None, axes=None):
-    """Plots orography defined at cell boundaries from the given Cube."""
+    """Plots orography defined at cell boundaries from the given Cube.
+
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+    """
 
     # XXX Needs contiguous orography corners to work.
     raise NotImplementedError(
@@ -1288,7 +1314,13 @@ def horiz_plot(v_coord, orography, style_args):
 
 
 def orography_at_points(cube, facecolor="#888888", coords=None, axes=None):
-    """Plots orography defined at sample points from the given Cube."""
+    """Plots orography defined at sample points from the given Cube.
+
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+    """
 
     style_args = {"facecolor": facecolor}
 
@@ -1334,6 +1366,11 @@ def outline(cube, coords=None, color="k", linewidth=None, axes=None):
         The axes to use for drawing.  Defaults to the current axes if none
         provided.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     result = _draw_2d_from_bounds(
         "pcolormesh",
@@ -1376,6 +1413,11 @@ def pcolor(cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.pcolor` for details of other valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     kwargs.setdefault("antialiased", True)
     kwargs.setdefault("snap", False)
@@ -1410,6 +1452,11 @@ def pcolormesh(cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.pcolormesh` for details of other
     valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     result = _draw_2d_from_bounds("pcolormesh", cube, *args, **kwargs)
     return result
@@ -1435,6 +1482,11 @@ def points(cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.scatter` for details of other valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
 
     def _scatter_args(u, v, data, *args, **kwargs):
@@ -1526,6 +1578,11 @@ def barbs(u_cube, v_cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.barbs` for details of other valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     #
     # TODO: check u + v cubes for compatibility.
@@ -1576,6 +1633,11 @@ def quiver(u_cube, v_cube, *args, **kwargs):
     See :func:`matplotlib.pyplot.quiver` for details of other valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     #
     # TODO: check u + v cubes for compatibility.
@@ -1622,6 +1684,11 @@ def plot(*args, **kwargs):
     See :func:`matplotlib.pyplot.plot` for details of additional valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     if "coords" in kwargs:
         raise TypeError(
@@ -1654,6 +1721,11 @@ def scatter(x, y, *args, **kwargs):
     See :func:`matplotlib.pyplot.scatter` for details of additional
     valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     # here we are more specific about argument types than generic 1d plotting
     if not isinstance(x, (iris.cube.Cube, iris.coords.Coord)):
@@ -1689,6 +1761,11 @@ def fill_between(x, y1, y2, *args, **kwargs):
     See :func:`matplotlib.pyplot.fill_between` for details of additional valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     # here we are more specific about argument types than generic 1d plotting
     if not isinstance(x, (iris.cube.Cube, iris.coords.Coord)):
@@ -1721,6 +1798,11 @@ def hist(x, *args, **kwargs):
     See :func:`matplotlib.pyplot.hist` for details of additional valid
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     if isinstance(x, iris.cube.Cube):
         data = x.data
@@ -1767,6 +1849,11 @@ def symbols(x, y, symbols, size, axes=None, units="inches"):
     * units: ['inches', 'points']
         The unit for the symbol size.
 
+    Notes
+    ------
+    This function does maintain laziness when called; it doesn't realise data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     if axes is None:
         axes = plt.gca()
@@ -1892,6 +1979,11 @@ def animate(cube_iterator, plot_func, fig=None, **kwargs):
     >>> ani = iplt.animate(cube_iter, qplt.contourf)
     >>> iplt.show()
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     kwargs.setdefault("interval", 100)
     coords = kwargs.pop("coords", None)

lib/iris/quickplot.py

@@ -174,6 +174,11 @@ def contour(cube, *args, **kwargs):
 
     See :func:`iris.plot.contour` for details of valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
@@ -201,6 +206,10 @@ def contourf(cube, *args, **kwargs):
 
     See :func:`iris.plot.contourf` for details of valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
@@ -229,6 +238,11 @@ def outline(cube, coords=None, color="k", linewidth=None, axes=None):
         The width of the lines showing the cell outlines. If None, the default
         width in patch.linewidth in matplotlibrc is used.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     result = iplt.outline(
         cube, color=color, linewidth=linewidth, coords=coords, axes=axes
@@ -244,6 +258,10 @@ def pcolor(cube, *args, **kwargs):
 
     See :func:`iris.plot.pcolor` for details of valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
@@ -258,6 +276,11 @@ def pcolormesh(cube, *args, **kwargs):
 
     See :func:`iris.plot.pcolormesh` for details of valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
@@ -272,6 +295,11 @@ def points(cube, *args, **kwargs):
 
     See :func:`iris.plot.points` for details of valid keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     coords = kwargs.get("coords")
     axes = kwargs.get("axes")
@@ -288,6 +316,11 @@ def plot(*args, **kwargs):
     See :func:`iris.plot.plot` for details of valid arguments and
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     axes = kwargs.get("axes")
     result = iplt.plot(*args, **kwargs)
@@ -303,6 +336,11 @@ def scatter(x, y, *args, **kwargs):
     See :func:`iris.plot.scatter` for details of valid arguments and
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
+
     """
     axes = kwargs.get("axes")
     result = iplt.scatter(x, y, *args, **kwargs)
@@ -317,6 +355,10 @@ def fill_between(x, y1, y2, *args, **kwargs):
     See :func:`iris.plot.fill_between` for details of valid arguments and
     keyword arguments.
 
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
     """
     axes = kwargs.get("axes")
     result = iplt.fill_between(x, y1, y2, *args, **kwargs)
@@ -330,6 +372,11 @@ def hist(x, *args, **kwargs):
 
     See :func:`iris.plot.hist` for details of valid arguments and
     keyword arguments.
+
+    Notes
+    ------
+    This function does not maintain laziness when called; it realises data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
     """
     axes = kwargs.get("axes")
     result = iplt.hist(x, *args, **kwargs)