diff --git a/lib/iris/analysis/__init__.py b/lib/iris/analysis/__init__.py index 83ae07d350..91bb5b94a4 100644 --- a/lib/iris/analysis/__init__.py +++ b/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 diff --git a/lib/iris/analysis/_area_weighted.py b/lib/iris/analysis/_area_weighted.py index af07b5e069..bba7e01f4a 100644 --- a/lib/iris/analysis/_area_weighted.py +++ b/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. diff --git a/lib/iris/analysis/_grid_angles.py b/lib/iris/analysis/_grid_angles.py index 109e83d73b..62bf148f45 100644 --- a/lib/iris/analysis/_grid_angles.py +++ b/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, ). 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, ). @@ -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. diff --git a/lib/iris/analysis/calculus.py b/lib/iris/analysis/calculus.py index aaee22d9c8..560b9b1d5c 100644 --- a/lib/iris/analysis/calculus.py +++ b/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`. """ diff --git a/lib/iris/aux_factory.py b/lib/iris/aux_factory.py index f447537b7d..61b7c7ef46 100644 --- a/lib/iris/aux_factory.py +++ b/lib/iris/aux_factory.py @@ -81,7 +81,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. @@ -97,9 +97,9 @@ def update(self, old_coord, new_coord=None): Parameters ---------- - old_coord: + old_coord : The coordinate to be removed/replaced. - new_coord: optional + new_coord : optional If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord. @@ -131,7 +131,7 @@ def derived_dims(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. @@ -161,7 +161,7 @@ def updated(self, new_coord_mapping): Parameters ---------- - new_coord_mapping: + new_coord_mapping : A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead. @@ -207,7 +207,8 @@ def _nd_bounds(coord, dims, ndim): dims == [3] ndim == 5 - results in: + results in:: + nd_bounds.shape == (1, 1, 1, 70, 1, 2) """ @@ -471,7 +472,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. @@ -546,11 +547,11 @@ def __init__(self, delta=None, sigma=None, orography=None): Parameters ---------- - delta: Coord, optional + delta : Coord, optional The coordinate providing the `a` term. - sigma: Coord, optional + sigma : Coord, optional The coordinate providing the `b` term. - orography: Coord, optional + orography : Coord, optional The coordinate providing the `orog` term. """ @@ -615,7 +616,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. @@ -678,9 +679,9 @@ def update(self, old_coord, new_coord=None): Parameters ---------- - old_coord: + old_coord : The coordinate to be removed/replaced. - new_coord: optional + new_coord : optional If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord. @@ -720,11 +721,11 @@ def __init__(self, delta=None, sigma=None, surface_air_pressure=None): Parameters ---------- - delta: Coord, optional + delta : Coord, optional The coordinate providing the `ap` term. - sigma: Coord, optional + sigma : Coord, optional The coordinate providing the `b` term. - surface_air_pressure: Coord, optional + surface_air_pressure : Coord, optional The coordinate providing the `ps` term. """ @@ -821,7 +822,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. @@ -1083,7 +1084,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. @@ -1245,7 +1246,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. @@ -1428,7 +1429,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. @@ -1619,7 +1620,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. @@ -1809,7 +1810,7 @@ def make_coord(self, coord_dims_func): Parameters ---------- - coord_dims_func: + coord_dims_func : A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. diff --git a/lib/iris/fileformats/pp.py b/lib/iris/fileformats/pp.py index fa95d0dab1..9a205fb1be 100644 --- a/lib/iris/fileformats/pp.py +++ b/lib/iris/fileformats/pp.py @@ -1355,7 +1355,7 @@ def coord_system(self): Returns ------- - :class:`~iris.coord_systems.GeogCS` or class:`~iris.coord_systems.RotatedGeogCS`. + :class:`~iris.coord_systems.GeogCS` or :class:`~iris.coord_systems.RotatedGeogCS`. """ geog_cs = iris.coord_systems.GeogCS(EARTH_RADIUS) diff --git a/lib/iris/fileformats/rules.py b/lib/iris/fileformats/rules.py index bf6ae4de34..aa3d4696bc 100644 --- a/lib/iris/fileformats/rules.py +++ b/lib/iris/fileformats/rules.py @@ -100,9 +100,9 @@ def scalar_cell_method(cube, method, coord_name): def has_aux_factory(cube, aux_factory_class): - """Determine class:`~iris.aux_factory.AuxCoordFactory` availability within cube. + """Determine :class:`~iris.aux_factory.AuxCoordFactory` availability within cube. - Try to find an class:`~iris.aux_factory.AuxCoordFactory` instance of the + Try to find an :class:`~iris.aux_factory.AuxCoordFactory` instance of the specified type on the cube. """ @@ -113,9 +113,9 @@ def has_aux_factory(cube, aux_factory_class): def aux_factory(cube, aux_factory_class): - """Retrieve class:`~iris.aux_factory.AuxCoordFactory` instance from cube. + """Retrieve :class:`~iris.aux_factory.AuxCoordFactory` instance from cube. - Return the class:`~iris.aux_factory.AuxCoordFactory` instance of the + Return the :class:`~iris.aux_factory.AuxCoordFactory` instance of the specified type from a cube. """ diff --git a/lib/iris/io/__init__.py b/lib/iris/io/__init__.py index b944b51978..2b667cfab6 100644 --- a/lib/iris/io/__init__.py +++ b/lib/iris/io/__init__.py @@ -147,7 +147,7 @@ def expand_filespecs(file_specs, files_expected=True): ---------- file_specs : iterable of str File paths which may contain ``~`` elements or wildcards. - files_expected : bool, optional, default=True + files_expected : bool, default=True Whether file is expected to exist (i.e. for load). Returns diff --git a/lib/iris/io/format_picker.py b/lib/iris/io/format_picker.py index 2a056c788c..d5e54d231a 100644 --- a/lib/iris/io/format_picker.py +++ b/lib/iris/io/format_picker.py @@ -189,7 +189,7 @@ def __init__( priority: int Integer giving a priority for considering this specification where higher priority means sooner consideration. - constraint_aware_handler: optional, default=False + constraint_aware_handler: default=False """ if not isinstance(file_element, FileElement): raise ValueError( @@ -279,7 +279,7 @@ def __init__(self, requires_fh=True): Parameters ---------- - requires_fh : optional + requires_fh : bool, default=True Whether this FileElement needs a file buffer. """