DOCS: numpydocs 4

lib/iris/analysis/__init__.py

@@ -227,7 +227,7 @@ def _dimensional_metadata_comparison(*cubes, object_get=None):
 
     Returns
     -------
-    result (dict mapping string: list of _CoordGroup):
+    result : dict mapping str,  list of _CoordGroup
         A dictionary whose keys are match categories and values are groups of
         coordinates, cell-measures or ancillary-variables.
 
@@ -243,42 +243,42 @@ def _dimensional_metadata_comparison(*cubes, object_get=None):
 
     Returned Keys:
 
-    * grouped_coords
-       A list of coordinate groups of all the coordinates grouped together
-       by their coordinate definition
-    * ungroupable
-       A list of coordinate groups which contain at least one None,
-       meaning not all Cubes provide an equivalent coordinate
-    * not_equal
-       A list of coordinate groups of which not all are equal
-       (superset of ungroupable)
-    * no_data_dimension
-       A list of coordinate groups of which all have no data dimensions on
-       their respective cubes
-    * scalar
-       A list of coordinate groups of which all have shape (1, )
-    * non_equal_data_dimension
-       A list of coordinate groups of which not all have the same
-       data dimension on their respective cubes
-    * non_equal_shape
-       A list of coordinate groups of which not all have the same shape
-    * equal_data_dimension
-       A list of coordinate groups of which all have the same data dimension
-       on their respective cubes
-    * equal
-       A list of coordinate groups of which all are equal
-    * ungroupable_and_dimensioned
-       A list of coordinate groups of which not all cubes had an equivalent
-       (in metadata) coordinate which also describe a data dimension
-    * dimensioned
-       A list of coordinate groups of which all describe a data dimension on
-       their respective cubes
-    * ignorable
-       A list of scalar, ungroupable non_equal coordinate groups
-    * resamplable
-        A list of equal, different data dimensioned coordinate groups
-    * transposable
-       A list of non equal, same data dimensioned, non scalar coordinate groups
+    * **grouped_coords**.
+      A list of coordinate groups of all the coordinates grouped together
+      by their coordinate definition
+    * **ungroupable**.
+      A list of coordinate groups which contain at least one None,
+      meaning not all Cubes provide an equivalent coordinate
+    * **not_equal**.
+      A list of coordinate groups of which not all are equal
+      (superset of ungroupable)
+    * **no_data_dimension**>
+      A list of coordinate groups of which all have no data dimensions on
+      their respective cubes
+    * **scalar**>
+      A list of coordinate groups of which all have shape (1, )
+    * **non_equal_data_dimension**.
+      A list of coordinate groups of which not all have the same
+      data dimension on their respective cubes
+    * **non_equal_shape**.
+      A list of coordinate groups of which not all have the same shape
+    * **equal_data_dimension**.
+      A list of coordinate groups of which all have the same data dimension
+      on their respective cubes
+    * **equal**.
+      A list of coordinate groups of which all are equal
+    * **ungroupable_and_dimensioned**.
+      A list of coordinate groups of which not all cubes had an equivalent
+      (in metadata) coordinate which also describe a data dimension
+    * **dimensioned**.
+      A list of coordinate groups of which all describe a data dimension on
+      their respective cubes
+    * **ignorable**.
+      A list of scalar, ungroupable non_equal coordinate groups
+    * **resamplable**.
+      A list of equal, different data dimensioned coordinate groups
+    * **transposable**.
+      A list of non equal, same data dimensioned, non scalar coordinate groups
 
     Example usage::
 
@@ -511,11 +511,11 @@ def lazy_aggregate(self, data, axis, **kwargs):
         ----------
         data : :class:`dask.array.Array`
             A lazy array.
-        axis: int or list of int
+        axis : int or list of int
             The dimensions to aggregate over -- note that this is defined
             differently to the 'aggregate' method 'axis' argument, which only
             accepts a single dimension index.
-        **kwargs:
+        **kwargs :
             All keyword arguments are passed through to the data aggregation
             function.
 
@@ -555,7 +555,7 @@ def aggregate(self, data, axis, **kwargs):
             mdtol.  mdtol=0 means no missing data is tolerated while mdtol=1
             will return the resulting value from the aggregation function.
             Defaults to 1.
-        **kwargs:
+        **kwargs :
             All keyword arguments apart from those specified above, are
             passed through to the data aggregation function.
 
@@ -635,8 +635,9 @@ def aggregate_shape(self, **kwargs):
 
         Parameters
         ----------
-        This function is intended to be used in conjunction with aggregate()
-        and should be passed the same keywords.
+        **kwargs :
+            This function is intended to be used in conjunction with aggregate()
+            and should be passed the same keywords.
 
         Returns
         -------
@@ -890,7 +891,7 @@ def __init__(self, units_func=None, lazy_func=None, **kwargs):
 
         Parameters
         ----------
-        units_func : callable
+        units_func : callable or None
             | *Call signature*: ``(units, **kwargs)``.
 
             If provided, called to convert a cube's units.
@@ -1063,7 +1064,7 @@ def __init__(
             An alternative to :data:`call_func` implementing a lazy
             aggregation. Note that, it need not support all features of the
             main operation, but should raise an error in unhandled cases.
-        ** kwargs :
+        **kwargs :
             Passed through to :data:`call_func`, :data:`lazy_func`, and
             :data:`units_func`.
 
@@ -1461,7 +1462,7 @@ def _weighted_percentile(data, axis, weights, percent, returned=False, **kwargs)
         array with the weights.  Must have same shape as data
     percent : float or sequence of floats
         Percentile rank/s at which to extract value/s.
-    returned : bool, optional
+    returned : bool, default=False
         Default False.  If True, returns a tuple with the percentiles as the
         first element and the sum of the weights as the second element.
 
@@ -2286,7 +2287,7 @@ def __init__(
             One or more coordinates (including multidimensional coordinates)
             that share the same group-by coordinate axis.  The `int` identifies
             which dimension of the coord is on the group-by coordinate axis.
-        climatological : bool
+        climatological : bool, default=False
             Indicates whether the output is expected to be climatological. For
             any aggregated time coord(s), this causes the climatological flag to
             be set and the point for each cell to equal its first bound, thereby

lib/iris/analysis/_area_weighted.py

@@ -221,6 +221,7 @@ def _get_bounds_in_units(coord, units, dtype):
     """Return a copy of coord's bounds in the specified units and dtype.
 
     Return as contiguous bounds.
+
     """
     # The bounds are cast to dtype before conversion to prevent issues when
     # mixing float32 and float64 types.

lib/iris/analysis/_grid_angles.py

@@ -19,9 +19,9 @@
 def _3d_xyz_from_latlon(lon, lat):
     """Return locations of (lon, lat) in 3D space.
 
-    Args:
-
-    * lon, lat: (float array)
+    Parameters
+    ----------
+    lon, lat: float array
         Arrays of longitudes and latitudes, in degrees.
         Both the same shape.
 
@@ -48,9 +48,9 @@ def _3d_xyz_from_latlon(lon, lat):
 def _latlon_from_xyz(xyz):
     """Return arrays of lons+lats angles from xyz locations.
 
-    Args:
-
-    * xyz: (array)
+    Parameters
+    ----------
+    xyz : array
         Array of 3-D cartesian coordinates.
         Shape (3, <input_points_dimensions>).
         x / y / z values are in xyz[0 / 1 / 2],
@@ -76,10 +76,13 @@ def _angle(p, q, r):
     grid row, but at increasing column (grid-Eastward) positions.
 
     {P, Q, R} are locations of consecutive points in the same grid row.
-    These could be successive points in a single grid,
-        e.g. {T(i-1,j), T(i,j), T(i+1,j)}
-    or a mixture of U/V and T gridpoints if row positions are aligned,
-        e.g. {v(i,j), f(i,j), v(i+1,j)}.
+    These could be successive points in a single grid, e.g.::
+
+        {T(i-1,j), T(i,j), T(i+1,j)}
+
+    or a mixture of U/V and T gridpoints if row positions are aligned, e.g::
+
+        {v(i,j), f(i,j), v(i+1,j)}.
 
     Method:
 
@@ -89,7 +92,7 @@ def _angle(p, q, r):
         Discriminate between +/- angles by comparing latitudes of P and R.
         Return NaN where any P-->R are zero.
 
-        .. NOTE::
+        .. note::
 
             This method assumes that the vector PR is parallel to the surface
             at the longitude of Q, as it uses the length of PR as the basis for
@@ -101,9 +104,9 @@ def _angle(p, q, r):
             gridcell-orientation-angle arrays found in files output by the CICE
             model, which presumably uses an equivalent calculation.
 
-    Args:
-
-    * p, q, r : (float array)
+    Parameters
+    ----------
+    p, q, r : float array
         Arrays of angles, in degrees.
         All the same shape.
         Shape is (2, <input_points_dimensions>).
@@ -148,34 +151,28 @@ def gridcell_angles(x, y=None, cell_angle_boundpoints="mid-lhs, mid-rhs"):
     Input can be either two arrays, two coordinates, or a single cube
     containing two suitable coordinates identified with the 'x' and 'y' axes.
 
-    Args:
-
-    The inputs (x [,y]) can be any of the following :
+    The inputs (x [,y]) can be different, see the parameters section.
 
-    * x (:class:`~iris.cube.Cube`):
+    Parameters
+    ----------
+    x : :class:`~iris.cube.Cube`
         a grid cube with 2D X and Y coordinates, identified by 'axis'.
         The coordinates must be 2-dimensional with the same shape.
         The two dimensions represent grid dimensions in the order Y, then X.
-
-    * x, y (:class:`~iris.coords.Coord`):
+    x, y : :class:`~iris.coords.Coord`
         X and Y coordinates, specifying grid locations on the globe.
         The coordinates must be 2-dimensional with the same shape.
         The two dimensions represent grid dimensions in the order Y, then X.
         If there is no coordinate system, they are assumed to be true
         longitudes and latitudes.  Units must convertible to 'degrees'.
-
-    * x, y (2-dimensional arrays of same shape (ny, nx)):
+    x, y : 2-dimensional arrays of same shape (ny, nx)
         longitude and latitude cell center locations, in degrees.
         The two dimensions represent grid dimensions in the order Y, then X.
-
-    * x, y (3-dimensional arrays of same shape (ny, nx, 4)):
+    x, y : 3-dimensional arrays of same shape (ny, nx, 4)
         longitude and latitude cell bounds, in degrees.
         The first two dimensions are grid dimensions in the order Y, then X.
         The last index maps cell corners anticlockwise from bottom-left.
-
-    Optional Args:
-
-    * cell_angle_boundpoints (string):
+    cell_angle_boundpoints : str, default="mid-lhs, mid-rhs"
         Controls which gridcell bounds locations are used to calculate angles,
         if the inputs are bounds or bounded coordinates.
         Valid values are 'lower-left, lower-right', which takes the angle from
@@ -397,7 +394,7 @@ def rotate_grid_vectors(u_cube, v_cube, grid_angles_cube=None, grid_angles_kwarg
 
     Can also rotate by arbitrary angles, if they are passed in.
 
-    .. Note::
+    .. note::
 
         This operation overlaps somewhat in function with
         :func:`iris.analysis.cartography.rotate_winds`.
@@ -409,21 +406,17 @@ def rotate_grid_vectors(u_cube, v_cube, grid_angles_cube=None, grid_angles_kwarg
         complex meshes defined by two-dimensional coordinates, such as most
         ocean grids.
 
-    Args:
-
-    * u_cube, v_cube : (cube)
+    Parameters
+    ----------
+    u_cube, v_cube : cube
         Cubes of grid-u and grid-v vector components.
         Units should be differentials of true-distance, e.g. 'm/s'.
-
-    Optional args:
-
-    * grid_angles_cube : (cube)
+    grid_angles_cube : cube, optional
         gridcell orientation angles.
         Units must be angular, i.e. can be converted to 'radians'.
         If not provided, grid angles are estimated from 'u_cube' using the
         :func:`gridcell_angles` method.
-
-    * grid_angles_kwargs : (dict or None)
+    **grid_angles_kwargs : dict or None
         Additional keyword args to be passed to the :func:`gridcell_angles`
         method, if it is used.
 

lib/iris/analysis/calculus.py

@@ -144,6 +144,8 @@ def cube_delta(cube, coord):
 
         change_in_temperature_wrt_pressure = cube_delta(temperature_cube, 'pressure')
 
+    Notes
+    -----
     .. note:: Missing data support not yet implemented.
 
     .. note::
@@ -770,8 +772,8 @@ def spatial_vectors_with_phenom_name(i_cube, j_cube, k_cube=None):
 
     Notes
     -----
-            This function maintains laziness when called; it does not realise data.
-            See more at :doc:`/userguide/real_and_lazy_data`.
+    This function maintains laziness when called; it does not realise data.
+    See more at :doc:`/userguide/real_and_lazy_data`.
 
 
     """