diff --git a/.github/workflows/ci-manifest.yml b/.github/workflows/ci-manifest.yml index 33e1fd9e09..0868811ac6 100644 --- a/.github/workflows/ci-manifest.yml +++ b/.github/workflows/ci-manifest.yml @@ -23,4 +23,4 @@ concurrency: jobs: manifest: name: "check-manifest" - uses: scitools/workflows/.github/workflows/ci-manifest.yml@2024.01.0 + uses: scitools/workflows/.github/workflows/ci-manifest.yml@2024.02.0 diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml index 2c2a083050..5f1b2397ef 100644 --- a/.github/workflows/ci-tests.yml +++ b/.github/workflows/ci-tests.yml @@ -140,5 +140,5 @@ jobs: nox --session ${{ matrix.session }} -- --verbose ${{ matrix.coverage }} - name: Upload coverage report - uses: codecov/codecov-action@v3 + uses: codecov/codecov-action@v4 if: ${{ matrix.coverage }} diff --git a/.github/workflows/refresh-lockfiles.yml b/.github/workflows/refresh-lockfiles.yml index 0dc392979e..082aed2cb1 100644 --- a/.github/workflows/refresh-lockfiles.yml +++ b/.github/workflows/refresh-lockfiles.yml @@ -14,5 +14,5 @@ on: jobs: refresh_lockfiles: - uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2024.01.0 + uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2024.02.0 secrets: inherit diff --git a/docs/src/conf.py b/docs/src/conf.py index 0fa493bde1..a988fe24c4 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -195,9 +195,17 @@ def _dotv(version): # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html todo_include_todos = True -# api generation configuration -autodoc_member_order = "alphabetical" -autodoc_default_flags = ["show-inheritance"] +# sphinx.ext.autodoc configuration -------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_default_options +autodoc_default_options = { + "members": True, + "member-order": "alphabetical", + "undoc-members": True, + "private-members": False, + "special-members": False, + "inherited-members": True, + "show-inheritance": True, +} # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_typehints autodoc_typehints = "none" @@ -292,6 +300,7 @@ def _dotv(version): "footer_start": ["copyright", "sphinx-version"], "footer_end": ["custom_footer"], "navigation_depth": 3, + "show_toc_level": 2, "show_prev_next": True, "navbar_align": "content", # removes the search box from the top bar @@ -319,7 +328,6 @@ def _dotv(version): }, ], "use_edit_page_button": True, - "show_toc_level": 1, # Omit `theme-switcher` from navbar_end below to disable it # Info: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/light-dark.html#configure-default-theme-mode # "navbar_end": ["navbar-icon-links"], diff --git a/docs/src/further_topics/filtering_warnings.rst b/docs/src/further_topics/filtering_warnings.rst index fb1e09e98e..e4ded0bf88 100644 --- a/docs/src/further_topics/filtering_warnings.rst +++ b/docs/src/further_topics/filtering_warnings.rst @@ -49,7 +49,7 @@ Warnings: ... iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance. warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning) - iris/coord_systems.py:782: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy. + iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy. warnings.warn( Warnings can be suppressed using the Python warnings filter with the ``ignore`` @@ -130,7 +130,7 @@ Or you can target Warnings raised by specific lines of specific modules, e.g. ... iris/coord_systems.py:442: IrisUserWarning: Setting inverse_flattening does not affect other properties of the GeogCS object. To change other properties set them explicitly or create a new GeogCS instance. warnings.warn(wmsg, category=iris.exceptions.IrisUserWarning) - iris/coord_systems.py:782: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy. + iris/coord_systems.py:768: IrisDefaultingWarning: Discarding false_easting and false_northing that are not used by Cartopy. warnings.warn( :: diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index ae06070f67..b528349b47 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -172,6 +172,9 @@ This document explains the changes made to Iris for this release #. `@tkknight`_ added ruff documentation in the :ref:`developer_testing_ci` of the :ref:`developers_guide`. (:pull:`5701`) +#. `@tkknight`_ configured the API documentation to show 2 levels + for the ToC (Table of Contents) for each page. (:pull:`5714`) + 💼 Internal =========== diff --git a/lib/iris/_lazy_data.py b/lib/iris/_lazy_data.py index 2ab41ecb45..36c0825ad8 100644 --- a/lib/iris/_lazy_data.py +++ b/lib/iris/_lazy_data.py @@ -252,7 +252,7 @@ def as_lazy_data( Notes ----- The result chunk size is a multiple of 'chunks', if given, up to the - dask default chunksize, i.e. `dask.config.get('array.chunk-size'), + dask default chunksize, i.e. `dask.config.get('array.chunk-size')`, or the full data shape if that is smaller. If 'chunks' is not given, the result has chunks of the full data shape, but reduced by a factor if that exceeds the dask default chunksize. diff --git a/lib/iris/_merge.py b/lib/iris/_merge.py index de36cb3aa1..85012c0ef8 100644 --- a/lib/iris/_merge.py +++ b/lib/iris/_merge.py @@ -5,7 +5,7 @@ """Automatic collation of cubes into higher-dimensional cubes. Typically the cube merge process is handled by -:method:`iris.cube.CubeList.merge`. +:meth:`iris.cube.CubeList.merge`. """ diff --git a/lib/iris/_representation/cube_printout.py b/lib/iris/_representation/cube_printout.py index 47c0b8b631..3c418bde64 100644 --- a/lib/iris/_representation/cube_printout.py +++ b/lib/iris/_representation/cube_printout.py @@ -58,7 +58,7 @@ def add_row(self, cols, aligns, i_col_unlimited=None): Per-column content. Length must match the other rows (if any). aligns : list of {'left', 'right'} Per-column alignments. Length must match 'cols'. - i_col_unlimited : int or None, optional + i_col_unlimited : int, optional Column beyond which content does not affect the column widths. ( meaning contents will print without limit ). @@ -325,10 +325,10 @@ def to_string(self, oneline=False, name_padding=35): Parameters ---------- - oneline : bool, optional, default=False + oneline : bool, default=False If set, produce a one-line summary. Default is False = produce full (multiline) summary. - name_padding int, optional, default=35 + name_padding : int, default=35 The minimum width for the "name" (#0) column. Returns diff --git a/lib/iris/common/lenient.py b/lib/iris/common/lenient.py index 4822d88b92..b26e0f1763 100644 --- a/lib/iris/common/lenient.py +++ b/lib/iris/common/lenient.py @@ -60,7 +60,7 @@ def func(): wrapped by the decorator. This is automatically populated by Python through the decorator interface. No argument requires to be manually provided. - services : callable or str or iterable of callable/str, optional, default=None + services : callable or str or iterable of callable/str, optional Zero or more function/methods, or equivalent fully qualified string names, of lenient service function/methods. @@ -227,7 +227,7 @@ def __init__(self, **kwargs): Parameters ---------- - **kwargs : dict + **kwargs : dict, optional Mapping of lenient key/value options to enable/disable. Note that, only the lenient "maths" options is available, which controls lenient/strict cube arithmetic. @@ -298,7 +298,6 @@ def context(self, **kwargs): applied. On exit from the context manager, the previous lenient option state is restored. - For example:: with iris.common.Lenient.context(maths=False): @@ -555,7 +554,7 @@ def register_client(self, func, services, append=False): services : callable or str or iterable of callable/str One or more service function/methods or fully qualified string names of the required service function/method. - append : bool, optional + append : bool, default=False If True, append the lenient services to any pre-registered lenient services for the provided lenient client. Default is False. diff --git a/lib/iris/common/metadata.py b/lib/iris/common/metadata.py index 92c3d34f3e..403436496f 100644 --- a/lib/iris/common/metadata.py +++ b/lib/iris/common/metadata.py @@ -583,7 +583,7 @@ def combine(self, other, lenient=None): ---------- other : metadata A metadata instance of the same type. - lenient : bool + lenient : bool, optional Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled. @@ -694,7 +694,7 @@ def name(self, default=None, token=False): default : optional The fall-back string representing the default name. Defaults to the string 'unknown'. - token : bool, optional + token : bool, default=False If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is @@ -1574,7 +1574,7 @@ def metadata_manager_factory(cls, **kwargs): cls : A subclass of :class:`~iris.common.metadata.BaseMetadata`, defining the metadata to be managed. - **kwargs : + **kwargs : dict, optional Initial values for the manufactured metadata instance. Unspecified fields will default to a value of 'None'. diff --git a/lib/iris/common/resolve.py b/lib/iris/common/resolve.py index 1ded7e2603..5a96b52a02 100644 --- a/lib/iris/common/resolve.py +++ b/lib/iris/common/resolve.py @@ -245,9 +245,9 @@ def __init__(self, lhs=None, rhs=None): Parameters ---------- - lhs : :class:`~iris.cube.Cube` + lhs : :class:`~iris.cube.Cube`, optional The left-hand-side :class:`~iris.cube.Cube` operand. - rhs : :class:`~iris.cube.Cube` + rhs : :class:`~iris.cube.Cube`, optional The right-hand-side :class:`~iris.cube.Cube` operand. Examples @@ -698,15 +698,15 @@ def _create_prepared_item( The dimensions that the ``coord`` spans on the resulting resolved :class:`~iris.cube.Cube`. (Can also be a single dimension number). - src_metadata : + src_metadata : optional The coordinate metadata from the ``src`` :class:`~iris.cube.Cube`. - tgt_metadata : + tgt_metadata : optional The coordinate metadata from the ``tgt`` :class:`~iris.cube.Cube`. - points : + points : optional Override points array. When not given, use coord.points. - bounds : + bounds : optional Override bounds array. When not given, use coord.bounds. - container : + container : optional Override coord type (class constructor). When not given, use type(coord). @@ -1145,34 +1145,40 @@ def _metadata_coverage(self): def _metadata_mapping(self): """Identify equivalent dimensions using metadata. - Ensure that each ``src`` :class:`~iris.cube.Cube` dimension is mapped to an associated - ``tgt`` :class:`~iris.cube.Cube` dimension using the common dim and aux coordinate metadata. + Ensure that each ``src`` :class:`~iris.cube.Cube` dimension is mapped to an + associated ``tgt`` :class:`~iris.cube.Cube` dimension using the common dim + and aux coordinate metadata. - If the common metadata does not result in a full mapping of ``src`` to ``tgt`` dimensions - then free dimensions are analysed to determine whether the mapping can be completed. + If the common metadata does not result in a full mapping of ``src`` to ``tgt`` + dimensions then free dimensions are analysed to determine whether the mapping + can be completed. - Once the ``src`` has been mapped to the ``tgt``, the cubes are checked to ensure that they - will successfully broadcast, and the ``src`` :class:`~iris.cube.Cube` is transposed appropriately, - if necessary. + Once the ``src`` has been mapped to the ``tgt``, the cubes are checked to + ensure that they will successfully broadcast, and the ``src`` + :class:`~iris.cube.Cube` is transposed appropriately, if necessary. - The :attr:`~iris.common.resolve.Resolve._broadcast_shape` is set, along with the - :attr:`~iris.common.resolve.Resolve._src_cube_resolved` and :attr:`~iris.common.resolve.Resolve._tgt_cube_resolved`, + The :attr:`~iris.common.resolve.Resolve._broadcast_shape` is set, along with + the :attr:`~iris.common.resolve.Resolve._src_cube_resolved` and + :attr:`~iris.common.resolve.Resolve._tgt_cube_resolved`, which are the broadcast/transposed ``src`` and ``tgt``. .. note:: - An exception will be raised if a ``src`` dimension cannot be mapped to a ``tgt`` dimension. + An exception will be raised if a ``src`` dimension cannot be mapped to + a ``tgt`` dimension. .. note:: - An exception will be raised if the full mapped ``src`` :class:`~iris.cube.Cube` cannot be - broadcast or transposed with the ``tgt`` :class:`~iris.cube.Cube`. + An exception will be raised if the full mapped ``src`` + :class:`~iris.cube.Cube` cannot be broadcast or transposed with the + ``tgt`` :class:`~iris.cube.Cube`. .. note:: - The ``src`` and ``tgt`` may be swapped in the case where they both have equal dimensionality and - the ``tgt`` does have the same shape as the resolved broadcast shape (and the ``src`` does) or - the ``tgt`` has more free dimensions than the ``src``. + The ``src`` and ``tgt`` may be swapped in the case where they both have + equal dimensionality and the ``tgt`` does have the same shape as the + resolved broadcast shape (and the ``src`` does) or the ``tgt`` has more + free dimensions than the ``src``. """ # Initialise the state. @@ -1629,11 +1635,11 @@ def _get_prepared_item( The :class:`~iris.common.resolve._CategoryItems` containing the local metadata of either the ``src`` or ``tgt`` :class:`~iris.cube.Cube`. See ``from_local``. - from_src : bool, optional + from_src : bool, default=True Boolean stating whether the ``metadata`` is from the ``src`` (``True``) or ``tgt`` :class:`~iris.cube.Cube`. Defaults to ``True``. - from_local: bool, optional + from_local: bool, default=False Boolean controlling whether the ``metadata`` is used to search the ``category_local`` (``True``) or the :attr:`~iris.common.resolve.Resolve.prepared_category`. Defaults to ``False``. @@ -1710,7 +1716,7 @@ def _prepare_factory_payload(self, cube, category_local, from_src=True): category_local : :class:`~iris.common.resolve._CategoryItems` The :class:`~iris.common.resolve._CategoryItems` of all metadata local to the provided ``cube``. - from_src : bool, optional, default=True + from_src : bool, default=True Boolean stating whether the provided ``cube`` is either a ``src`` or ``tgt`` :class:`~iris.cube.Cube` - used to retrieve the appropriate metadata from a :class:`~iris.common.resolve._PreparedMetadata`. @@ -2301,7 +2307,7 @@ def cube(self, data, in_place=False): The data payload for the resultant :class:`~iris.cube.Cube`, which **must match** the expected resolved :attr:`~iris.common.resolve.Resolve.shape`. - in_place : optional + in_place : bool, default=False If ``True``, the ``data`` is inserted into the ``tgt`` :class:`~iris.cube.Cube`. The existing metadata of the ``tgt`` :class:`~iris.cube.Cube` is replaced with the resolved metadata from diff --git a/lib/iris/coord_categorisation.py b/lib/iris/coord_categorisation.py index 96407632c5..f4c3aa6cb4 100644 --- a/lib/iris/coord_categorisation.py +++ b/lib/iris/coord_categorisation.py @@ -40,7 +40,7 @@ def add_categorised_coord(cube, name, from_coord, category_function, units="1"): category_function : callable function(coordinate, value), returning a category value for a coordinate point-value - units : str, optional, default="1" + units : str, default="1" units of the category value, typically 'no_unit' or '1'. """ # Interpret coord, if given as a name @@ -303,7 +303,7 @@ def add_season(cube, coord, name="season", seasons=("djf", "mam", "jja", "son")) it. coord : :class:`iris.coords.Coord` or str Coordinate in 'cube', or its name, representing time. - name : str, optional + name : str, default="season" Name of the created coordinate. Defaults to "season". seasons : :class:`list` of str, optional List of seasons defined by month abbreviations. Each month must @@ -341,7 +341,7 @@ def add_season_number( it. coord : :class:`iris.coords.Coord` or str Coordinate in 'cube', or its name, representing time. - name : str, optional + name : str, default="season" Name of the created coordinate. Defaults to "season_number". seasons : :class:`list` of str, optional List of seasons defined by month abbreviations. Each month must @@ -425,7 +425,7 @@ def add_season_membership(cube, coord, season, name="season_membership"): Coordinate in 'cube', or its name, representing time. season : str Season defined by month abbreviations. - name : str, optional + name : str, default="season_membership" Name of the created coordinate. Defaults to "season_membership". """ diff --git a/lib/iris/coord_systems.py b/lib/iris/coord_systems.py index adc9895ed9..5b4e593d83 100644 --- a/lib/iris/coord_systems.py +++ b/lib/iris/coord_systems.py @@ -157,12 +157,12 @@ def __init__( Parameters ---------- - * semi_major_axis, semi_minor_axis: + semi_major_axis, semi_minor_axis : optional Axes of ellipsoid, in metres. At least one must be given (see note below). - * inverse_flattening: + inverse_flattening : optional Can be omitted if both axes given (see note below). Default 0.0 - * longitude_of_prime_meridian: + longitude_of_prime_meridian : optional Specifies the prime meridian on the ellipsoid, in degrees. Default 0.0 Notes @@ -498,24 +498,21 @@ def __init__( ): """Construct a coordinate system with rotated pole, on an optional :class:`GeogCS`. - Args: - - * grid_north_pole_latitude: + Parameters + ---------- + grid_north_pole_latitude : The true latitude of the rotated pole in degrees. - - * grid_north_pole_longitude: + grid_north_pole_longitude : The true longitude of the rotated pole in degrees. - - Kwargs: - - * north_pole_grid_longitude: + north_pole_grid_longitude : optional Longitude of true north pole in rotated grid, in degrees. - Defaults to 0.0 . - - * ellipsoid (:class:`GeogCS`): + Defaults to 0.0. + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. - Examples:: + Examples + -------- + :: rotated_cs = RotatedGeogCS(30, 30) another_cs = RotatedGeogCS(30, 30, @@ -606,34 +603,29 @@ def __init__( ): """Construct a TransverseMercator object. - Args: - - * latitude_of_projection_origin: - True latitude of planar origin in degrees. - - * longitude_of_central_meridian: - True longitude of planar origin in degrees. - - Kwargs: - - * false_easting: - X offset from planar origin in metres. - Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. - Defaults to 0.0 . - - * scale_factor_at_central_meridian: - Reduces the cylinder to slice through the ellipsoid - (secant form). Used to provide TWO longitudes of zero - distortion in the area of interest. - Defaults to 1.0 . - - * ellipsoid (:class:`GeogCS`): + Parameters + ---------- + latitude_of_projection_origin : + True latitude of planar origin in degrees. + longitude_of_central_meridian : + True longitude of planar origin in degrees. + false_easting : optional + X offset from planar origin in metres. + Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. + Defaults to 0.0. + scale_factor_at_central_meridian : optional + Reduces the cylinder to slice through the ellipsoid + (secant form). Used to provide TWO longitudes of zero + distortion in the area of interest. + Defaults to 1.0 . + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. - Example:: + Examples + -------- + :: airy1830 = GeogCS(6377563.396, 6356256.909) osgb = TransverseMercator(49, -2, 400000, -100000, 0.9996012717, @@ -727,23 +719,17 @@ def __init__( ): """Construct an Orthographic coord system. - Args: - - * latitude_of_projection_origin: + Parameters + ---------- + latitude_of_projection_origin : True latitude of planar origin in degrees. - - * longitude_of_projection_origin: + longitude_of_projection_origin : True longitude of planar origin in degrees. - - Kwargs: - - * false_easting: - X offset from planar origin in metres. Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. Defaults to 0.0 . - - * ellipsoid (:class:`GeogCS`): + false_easting : optional + X offset from planar origin in metres. Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. Defaults to 0.0. + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. """ @@ -811,27 +797,20 @@ def __init__( ): """Construct a Vertical Perspective coord system. - Args: - - * latitude_of_projection_origin: + Parameters + ---------- + latitude_of_projection_origin : True latitude of planar origin in degrees. - - * longitude_of_projection_origin: + longitude_of_projection_origin : True longitude of planar origin in degrees. - - * perspective_point_height: + perspective_point_height : Altitude of satellite in metres above the surface of the ellipsoid. - - Kwargs: - - * false_easting: - X offset from planar origin in metres. Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. Defaults to 0.0 . - - * ellipsoid (:class:`GeogCS`): + false_easting : optional + X offset from planar origin in metres. Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. Defaults to 0.0. + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. """ @@ -903,29 +882,21 @@ def __init__( ): """Construct a Geostationary coord system. - Args: - - * latitude_of_projection_origin: + Parameters + ---------- + latitude_of_projection_origin : True latitude of planar origin in degrees. - - * longitude_of_projection_origin: + longitude_of_projection_origin : True longitude of planar origin in degrees. - - * perspective_point_height: + perspective_point_height : Altitude of satellite in metres above the surface of the ellipsoid. - - * sweep_angle_axis (string): + sweep_angle_axis : str The axis along which the satellite instrument sweeps - 'x' or 'y'. - - Kwargs: - - * false_easting: - X offset from planar origin in metres. Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. Defaults to 0.0 . - - * ellipsoid (:class:`GeogCS`): + false_easting : optional + X offset from planar origin in metres. Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. Defaults to 0.0. + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. """ @@ -1011,28 +982,23 @@ def __init__( ---------- central_lat : float The latitude of the pole. - central_lon : float The central longitude, which aligns with the y axis. - false_easting : float, optional X offset from planar origin in metres. - false_northing : float, optional Y offset from planar origin in metres. - true_scale_lat : float, optional Latitude of true scale. - scale_factor_at_projection_origin : float, optional Scale factor at the origin of the projection - ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. Notes ----- - It is only valid to provide one of true_scale_lat and scale_factor_at_projection_origin + It is only valid to provide one of true_scale_lat and + scale_factor_at_projection_origin """ #: True latitude of planar origin in degrees. @@ -1054,7 +1020,7 @@ def __init__( scale_factor_at_projection_origin, None, cast_as=_float_or_None ) # N.B. the way we use these parameters, we need them to default to None, - # and *not* to 0.0 . + # and *not* to 0.0. if ( self.true_scale_lat is not None @@ -1123,22 +1089,16 @@ def __init__( ---------- central_lat : {90, -90} The latitude of the pole. - central_lon : float The central longitude, which aligns with the y axis. - false_easting : float, optional X offset from planar origin in metres. - false_northing : float, optional Y offset from planar origin in metres. - true_scale_lat : float, optional Latitude of true scale. - scale_factor_at_projection_origin : float, optional Scale factor at the origin of the projection - ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. @@ -1179,27 +1139,24 @@ def __init__( ): """Construct a LambertConformal coord system. - Kwargs: - - * central_lat: - The latitude of "unitary scale". Defaults to 39.0 . - - * central_lon: - The central longitude. Defaults to -96.0 . - - * false_easting: - X offset from planar origin in metres. Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. Defaults to 0.0 . - - * secant_latitudes (number or iterable of 1 or 2 numbers): - Latitudes of secant intersection. One or two. - Defaults to (33.0, 45.0). - - * ellipsoid (:class:`GeogCS`): + Parameters + ---------- + central_lat : optional + The latitude of "unitary scale". Defaults to 39.0 . + central_lon : optional + The central longitude. Defaults to -96.0 . + false_easting : optional + X offset from planar origin in metres. Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. Defaults to 0.0. + secant_latitudes : number or iterable of 1 or 2 numbers, optional + Latitudes of secant intersection. One or two. + Defaults to (33.0, 45.0). + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. + Notes + ----- .. note: Default arguments are for the familiar USA map: @@ -1285,31 +1242,27 @@ def __init__( ): """Construct a Mercator coord system. - Kwargs: - - * longitude_of_projection_origin: - True longitude of planar origin in degrees. Defaults to 0.0 . - - * ellipsoid (:class:`GeogCS`): + Parameters + ---------- + longitude_of_projection_origin : optional + True longitude of planar origin in degrees. Defaults to 0.0. + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. - - * standard_parallel: - The latitude where the scale is 1. Defaults to 0.0 . - - * scale_factor_at_projection_origin: + standard_parallel : optional + The latitude where the scale is 1. Defaults to 0.0. + scale_factor_at_projection_origin : optional Scale factor at natural origin. Defaults to unused. - - * false_easting: + false_easting : optional X offset from the planar origin in metres. Defaults to 0.0. - - * false_northing: + false_northing : optional Y offset from the planar origin in metres. Defaults to 0.0. - - * datum: + datum : optional If given, specifies the datumof the coordinate system. Only respected if iris.Future.daum_support is set. - Note: Only one of ``standard_parallel`` and + Notes + ----- + Only one of ``standard_parallel`` and ``scale_factor_at_projection_origin`` should be included. """ @@ -1390,21 +1343,17 @@ def __init__( ): """Construct a Lambert Azimuthal Equal Area coord system. - Kwargs: - - * latitude_of_projection_origin: - True latitude of planar origin in degrees. Defaults to 0.0 . - - * longitude_of_projection_origin: - True longitude of planar origin in degrees. Defaults to 0.0 . - - * false_easting: - X offset from planar origin in metres. Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. Defaults to 0.0 . - - * ellipsoid (:class:`GeogCS`): + Parameters + ---------- + latitude_of_projection_origin : optional + True latitude of planar origin in degrees. Defaults to 0.0. + longitude_of_projection_origin : optional + True longitude of planar origin in degrees. Defaults to 0.0. + false_easting : optional + X offset from planar origin in metres. Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. Defaults to 0.0. + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. """ @@ -1471,26 +1420,21 @@ def __init__( ): """Construct a Albers Conical Equal Area coord system. - Kwargs: - - * latitude_of_projection_origin: - True latitude of planar origin in degrees. Defaults to 0.0 . - - * longitude_of_central_meridian: + Parameters + ---------- + latitude_of_projection_origin : optional + True latitude of planar origin in degrees. Defaults to 0.0. + longitude_of_central_meridian : optional True longitude of planar central meridian in degrees. - Defaults to 0.0 . - - * false_easting: - X offset from planar origin in metres. Defaults to 0.0 . - - * false_northing: - Y offset from planar origin in metres. Defaults to 0.0 . - - * standard_parallels (number or iterable of 1 or 2 numbers): + Defaults to 0.0. + false_easting : optional + X offset from planar origin in metres. Defaults to 0.0. + false_northing : optional + Y offset from planar origin in metres. Defaults to 0.0. + standard_parallels : number or iterable of 1 or 2 numbers, optional The one or two latitudes of correct scale. Defaults to (20.0, 50.0). - - * ellipsoid (:class:`GeogCS`): + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. """ @@ -1587,14 +1531,14 @@ def __init__( The true latitude of the planar origin in degrees. false_easting: float, optional X offset from the planar origin in metres. - Defaults to 0.0 . + Defaults to 0.0. false_northing: float, optional Y offset from the planar origin in metres. - Defaults to 0.0 . + Defaults to 0.0. scale_factor_at_projection_origin: float, optional Scale factor at the central meridian. Defaults to 1.0 . - ellipsoid: :class:`GeogCS`, optional + ellipsoid : :class:`GeogCS`, optional If given, defines the ellipsoid. Examples @@ -1699,10 +1643,10 @@ def __init__( The true latitude of the planar origin in degrees. false_easting: float, optional X offset from the planar origin in metres. - Defaults to 0.0 . + Defaults to 0.0. false_northing: float, optional Y offset from the planar origin in metres. - Defaults to 0.0 . + Defaults to 0.0. scale_factor_at_projection_origin: float, optional Scale factor at the central meridian. Defaults to 1.0 . diff --git a/lib/iris/coords.py b/lib/iris/coords.py index d4d070921c..a9eae6e2ac 100644 --- a/lib/iris/coords.py +++ b/lib/iris/coords.py @@ -73,16 +73,16 @@ def __init__( ---------- values : The values of the dimensional metadata. - standard_name : optional, default=None + standard_name : optional CF standard name of the dimensional metadata. - long_name : optional, default=None + long_name : optional Descriptive name of the dimensional metadata. - var_name : optional, default=None + var_name : optional The netCDF variable name for the dimensional metadata. - units : optional, default=None + units : optional The :class:`~cf_units.Unit` of the dimensional metadata's values. Can be a string, which will be converted to a Unit object. - attributes : optional, default=None + attributes : optional A dictionary containing other cf and user-defined attributes. """ @@ -263,26 +263,26 @@ def summary( Parameters ---------- - shorten : bool, default = False + shorten : bool, default=False If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines. - max_values : int or None, default = None + max_values : int or None If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if :attr:`shorten`\ =True, or 15 otherwise. This overrides ``numpy.get_printoptions['threshold']``\ . - linewidth : int or None, default = None + linewidth : int or None Character-width controlling line splitting of array outputs. If unset, defaults to ``numpy.get_printoptions['linewidth']``\ . edgeitems : int, default=2 Controls truncated array output. Overrides ``numpy.getprintoptions['edgeitems']``\ . - precision : int or None, default = None + precision : int or None Controls number decimal formatting. When :attr:`shorten`\ =True this is defaults to 3, in which case it overrides ``numpy.get_printoptions()['precision']``\ . - convert_dates : bool, default = True + convert_dates : bool, default=True If the units has a calendar, then print array values as date strings instead of the actual numbers. @@ -914,16 +914,16 @@ def __init__( ---------- data : The values of the ancillary variable. - standard_name : optional, default=None + standard_name : optional CF standard name of the ancillary variable. - long_name : optional, default=None + long_name : optional Descriptive name of the ancillary variable. - var_name : optional, default=None + var_name : optional The netCDF variable name for the ancillary variable. - units : optional, default=None + units : optional The :class:`~cf_units.Unit` of the ancillary variable's values. Can be a string, which will be converted to a Unit object. - attributes : optional, default=None + attributes : optional A dictionary containing other cf and user-defined attributes. """ @@ -1014,16 +1014,16 @@ def __init__( The values of the measure for each cell. Either a 'real' array (:class:`numpy.ndarray`) or a 'lazy' array (:class:`dask.array.Array`). - standard_name : optional, default=None + standard_name : optional CF standard name of the coordinate. - long_name : optional, default=None + long_name : optional Descriptive name of the coordinate. - var_name : optional, default=None + var_name : optional The netCDF variable name for the coordinate. - units : optional, default=None + units : optional The :class:`~cf_units.Unit` of the coordinate's values. Can be a string, which will be converted to a Unit object. - attributes : optional, default=None + attributes : optional A dictionary containing other CF and user-defined attributes. measure : optional A string describing the type of measure. Supported values are @@ -1125,10 +1125,10 @@ def __new__( The minimum value of the range to select. maximum : The maximum value of the range to select. - min_inclusive : optional + min_inclusive : bool, default=True If True, coordinate values equal to `minimum` will be included in the selection. Default is True. - max_inclusive : optional + max_inclusive : bool, default=True If True, coordinate values equal to `maximum` will be included in the selection. Default is True. @@ -1452,16 +1452,16 @@ def __init__( points : The values (or value in the case of a scalar coordinate) for each cell of the coordinate. - standard_name : optional, default=None + standard_name : optional CF standard name of the coordinate. - long_name : optional, default=None + long_name : optional Descriptive name of the coordinate. - var_name : optional, default=None + var_name : optional The netCDF variable name for the coordinate. - units : optional, default=None + units : optional The :class:`~cf_units.Unit` of the coordinate's values. Can be a string, which will be converted to a Unit object. - bounds : optional, default=None + bounds : optional An array of values describing the bounds of each cell. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1D coordinate with 100 points @@ -1469,13 +1469,13 @@ def __init__( (100, 2) Note if the data is a climatology, `climatological` should be set. - attributes : optional, default=None + attributes : optional A dictionary containing other CF and user-defined attributes. - coord_system : optional, default=None + coord_system : optional A :class:`~iris.coord_systems.CoordSystem` representing the coordinate system of the coordinate, e.g., a :class:`~iris.coord_systems.GeogCS` for a longitude coordinate. - climatological : bool, optional, default=False + climatological : bool, default=False When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a 'climatology' attribute and will create a boundary variable called @@ -1512,11 +1512,11 @@ def __init__( def copy(self, points=None, bounds=None): """Return a copy of this coordinate. - points : + points : optional A points array for the new coordinate. This may be a different shape to the points of the coordinate being copied. - bounds : + bounds : optional A bounds array for the new coordinate. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1d coordinate @@ -1830,10 +1830,10 @@ def _sanity_check_bounds(self): def _discontiguity_in_bounds(self, rtol=1e-5, atol=1e-8): """Check that the bounds of the coordinate are contiguous. - rtol : float, optional + rtol : float, default=1e-5 Relative tolerance that is used when checking contiguity. Defaults to 1e-5. - atol : float, optional + atol : float, default=1e-8 Absolute tolerance that is used when checking contiguity. Defaults to 1e-8. @@ -1933,9 +1933,9 @@ def is_contiguous(self, rtol=1e-05, atol=1e-08): Parameters ---------- - rtol : optional + rtol : float, default=1e-05 The relative tolerance parameter (default is 1e-05). - atol : optional + atol : float, default=1e-08 The absolute tolerance parameter (default is 1e-08). Returns @@ -2196,7 +2196,7 @@ def _guess_bounds(self, bound_position=0.5): Parameters ---------- - bound_position : optional, default=0.5 + bound_position : float, default=0.5 The desired position of the bounds relative to the position of the points. @@ -2268,7 +2268,7 @@ def guess_bounds(self, bound_position=0.5): Parameters ---------- - bound_position : optional, default=0.5 + bound_position : float, default=0.5 The desired position of the bounds relative to the position of the points. @@ -2296,7 +2296,7 @@ def intersect(self, other, return_indices=False): Parameters ---------- - return_indices : optional, default=False + return_indices : bool, default=False If True, changes the return behaviour to return the intersection indices for the "self" coordinate. @@ -2500,7 +2500,7 @@ def from_regular( The numeric difference between successive point values. count : The number of point values. - with_bounds : optional + with_bounds : bool, default=False If True, the resulting DimCoord will possess bound values which are equally spaced around the points. Otherwise no bounds values will be defined. Defaults to False. @@ -2554,16 +2554,16 @@ def __init__( 1D numpy array-like of values (or single value in the case of a scalar coordinate) for each cell of the coordinate. The values must be strictly monotonic and masked values are not allowed. - standard_name : optional, default=None + standard_name : optional CF standard name of the coordinate. - long_name : optional, default=None + long_name : optional Descriptive name of the coordinate. - var_name : optional, default=None + var_name : optional The netCDF variable name for the coordinate. - units : :class:`~cf_units.Unit`, optional, default=None + units : :class:`~cf_units.Unit`, optional The :class:`~cf_units.Unit` of the coordinate's values. Can be a string, which will be converted to a Unit object. - bounds : optional, default=None + bounds : optional An array of values describing the bounds of each cell. Given n bounds and m cells, the shape of the bounds array should be (m, n). For each bound, the values must be strictly monotonic along @@ -2574,16 +2574,16 @@ def __init__( in the same direction. Masked values are not allowed. Note if the data is a climatology, `climatological` should be set. - attributes : optional, default=None + attributes : optional A dictionary containing other CF and user-defined attributes. - coord_system : :class:`~iris.coord_systems.CoordSystem`, optional, default=None + coord_system : :class:`~iris.coord_systems.CoordSystem`, optional A :class:`~iris.coord_systems.CoordSystem` representing the coordinate system of the coordinate, e.g., a :class:`~iris.coord_systems.GeogCS` for a longitude coordinate. - circular : bool, optional, default=False + circular : bool, default=False Whether the coordinate wraps by the :attr:`~iris.coords.DimCoord.units.modulus` i.e., the longitude coordinate wraps around the full great circle. - climatological : bool, optional, default=False + climatological : bool, default=False When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a 'climatology' attribute and will create a boundary variable called diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 5997eaacf5..f868c2a082 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -76,7 +76,7 @@ def merged(self, unique=False): Parameters ---------- - unique : bool, optional, default=False + unique : bool, default=False If True, raises `iris.exceptions.DuplicateDataError` if duplicate cubes are detected. @@ -117,7 +117,7 @@ def merged(self, unique=False): Parameters ---------- - unique : bool, optional, default=False + unique : bool, default=False If True, raises `iris.exceptions.DuplicateDataError` if duplicate cubes are detected. @@ -250,7 +250,7 @@ def extract(self, constraints): Parameters ---------- - constraints : :class:`~iris.Constraint` or iterable of constraints + constraints : :class:`~iris.Constraint` or iterable of constraints A single constraint or an iterable. """ @@ -405,7 +405,7 @@ def merge(self, unique=True): Parameters ---------- - unique : bool, optional, default=True + unique : bool, default=True If True, raises `iris.exceptions.DuplicateDataError` if duplicate cubes are detected. @@ -511,20 +511,20 @@ def concatenate_cube( Parameters ---------- - check_aux_coords : bool, optional, default=True + check_aux_coords : bool, default=True Checks if the points and bounds of auxiliary coordinates of the cubes match. This check is not applied to auxiliary coordinates that span the dimension the concatenation is occurring along. Defaults to True. - check_cell_measures : bool, optional, default=True + check_cell_measures : bool, default=True Checks if the data of cell measures of the cubes match. This check is not applied to cell measures that span the dimension the concatenation is occurring along. Defaults to True. - check_ancils : bool, optional, default=True + check_ancils : bool, default=True Checks if the data of ancillary variables of the cubes match. This check is not applied to ancillary variables that span the dimension the concatenation is occurring along. Defaults to True. - check_derived_coords : bool, optional, default=True + check_derived_coords : bool, default=True Checks if the points and bounds of derived coordinates of the cubes match. This check is not applied to derived coordinates that span the dimension the concatenation is occurring along. Note that @@ -584,20 +584,20 @@ def concatenate( Parameters ---------- - check_aux_coords : bool, optional, default=True + check_aux_coords : bool, default=True Checks if the points and bounds of auxiliary coordinates of the cubes match. This check is not applied to auxiliary coordinates that span the dimension the concatenation is occurring along. Defaults to True. - check_cell_measures : bool, optional, default=True + check_cell_measures : bool, default=True Checks if the data of cell measures of the cubes match. This check is not applied to cell measures that span the dimension the concatenation is occurring along. Defaults to True. - check_ancils : bool, optional, default=True + check_ancils : bool, default=True Checks if the data of ancillary variables of the cubes match. This check is not applied to ancillary variables that span the dimension the concatenation is occurring along. Defaults to True. - check_derived_coords : bool, optional, default=True + check_derived_coords : bool, default=True Checks if the points and bounds of derived coordinates of the cubes match. This check is not applied to derived coordinates that span the dimension the concatenation is occurring along. Note that @@ -1199,33 +1199,33 @@ def __init__( array_like (as described in :func:`numpy.asarray`). See :attr:`Cube.data`. - standard_name : optional, default=None + standard_name : optional The standard name for the Cube's data. - long_name : optional, default=None + long_name : optional An unconstrained description of the cube. - var_name : optional, default=None + var_name : optional The NetCDF variable name for the cube. - units : optional, default=None + units : optional The unit of the cube, e.g. ``"m s-1"`` or ``"kelvin"``. - attributes : optional, default=None + attributes : optional A dictionary of cube attributes - cell_methods : optional, default=None + cell_methods : optional A tuple of CellMethod objects, generally set by Iris, e.g. ``(CellMethod("mean", coords='latitude'), )``. - dim_coords_and_dims : optional, default=None + dim_coords_and_dims : optional A list of coordinates with scalar dimension mappings, e.g ``[(lat_coord, 0), (lon_coord, 1)]``. - aux_coords_and_dims : optional, default=None + aux_coords_and_dims : optional A list of coordinates with dimension mappings, e.g ``[(lat_coord, 0), (lon_coord, (0, 1))]``. See also :meth:`Cube.add_dim_coord()` and :meth:`Cube.add_aux_coord()`. - aux_factories : optional, default=None + aux_factories : optional A list of auxiliary coordinate factories. See :mod:`iris.aux_factory`. - cell_measures_and_dims : optional, default=None + cell_measures_and_dims : optional A list of CellMeasures with dimension mappings. - ancillary_variables_and_dims : optional, default=None + ancillary_variables_and_dims : optional A list of AncillaryVariables with dimension mappings. Examples @@ -1381,7 +1381,7 @@ def is_compatible(self, other, ignore=None): other : An instance of :class:`iris.cube.Cube` or :class:`iris.cube.CubeMetadata`. - ignore : optional, default=None + ignore : optional A single attribute key or iterable of attribute keys to ignore when comparing the cubes. Default is None. To ignore all attributes set this to other.attributes. @@ -1472,7 +1472,7 @@ def add_aux_coord(self, coord, data_dims=None): coord : The :class:`iris.coords.DimCoord` or :class:`iris.coords.AuxCoord` instance to add to the cube. - data_dims : optional, default=None + data_dims : optional Integer or iterable of integers giving the data dimensions spanned by the coordinate. @@ -1613,7 +1613,7 @@ def add_cell_measure(self, cell_measure, data_dims=None): cell_measure : The :class:`iris.coords.CellMeasure` instance to add to the cube. - data_dims : optional, default=None + data_dims : optional Integer or iterable of integers giving the data dimensions spanned by the coordinate. @@ -1646,7 +1646,7 @@ def add_ancillary_variable(self, ancillary_variable, data_dims=None): ancillary_variable : The :class:`iris.coords.AncillaryVariable` instance to be added to the cube - data_dims : optional, default=None + data_dims : optional Integer or iterable of integers giving the data dimensions spanned by the ancillary variable. @@ -1686,7 +1686,7 @@ def add_dim_coord(self, dim_coord, data_dim): See Also -------- - See also :meth:`Cube.remove_coord()`. + :meth:`Cube.remove_coord()`. """ if self.coords(dim_coord): @@ -1960,15 +1960,15 @@ def aux_factory(self, name=None, standard_name=None, long_name=None, var_name=No Parameters ---------- - name : optional, default=None + name : optional If not None, matches against factory.name(). - standard_name : optional, default=None + standard_name : optional The CF standard name of the desired coordinate factory. If None, does not check for standard name. - long_name : optional, default=None + long_name : optional An unconstrained description of the coordinate factory. If None, does not check for long_name. - var_name : optional, default=None + var_name : optional The NetCDF variable name of the desired coordinate factory. If None, does not check for var_name. @@ -2036,7 +2036,7 @@ def coords( Parameters ---------- - name_or_coord : optional, default=None + name_or_coord : optional Either, * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`, @@ -2047,39 +2047,39 @@ def coords( * a coordinate or metadata instance equal to that of the desired coordinate e.g., :class:`~iris.coords.DimCoord` or :class:`~iris.common.metadata.CoordMetadata`. - standard_name : optional, default=None + standard_name : optional The CF standard name of the desired coordinate. If ``None``, does not check for ``standard name``. - long_name : optional, default=None + long_name : optional An unconstrained description of the coordinate. If ``None``, does not check for ``long_name``. - var_name : optional, default=None + var_name : optional The NetCDF variable name of the desired coordinate. If ``None``, does not check for ``var_name``. - attributes : optional, default=None + attributes : optional A dictionary of attributes desired on the coordinates. If ``None``, does not check for ``attributes``. - axis : optional, default=None + axis : optional The desired coordinate axis, see :func:`iris.util.guess_coord_axis`. If ``None``, does not check for ``axis``. Accepts the values ``X``, ``Y``, ``Z`` and ``T`` (case-insensitive). - contains_dimension : optional, default=None + contains_dimension : optional The desired coordinate contains the data dimension. If ``None``, does not check for the dimension. - dimensions : optional, default=None + dimensions : optional The exact data dimensions of the desired coordinate. Coordinates with no data dimension can be found with an empty ``tuple`` or ``list`` i.e., ``()`` or ``[]``. If ``None``, does not check for dimensions. - coord_system : optional, default=None + coord_system : optional Whether the desired coordinates have a coordinate system equal to the given coordinate system. If ``None``, no check is done. - dim_coords : optional, default=None + dim_coords : optional Set to ``True`` to only return coordinates that are the cube's dimension coordinates. Set to ``False`` to only return coordinates that are the cube's auxiliary, mesh and derived coordinates. If ``None``, returns all coordinates. - mesh_coords : optional, default=None + mesh_coords : optional Set to ``True`` to return only coordinates which are :class:`~iris.experimental.ugrid.MeshCoord`\'s. Set to ``False`` to return only non-mesh coordinates. @@ -2192,7 +2192,7 @@ def coord( Parameters ---------- - name_or_coord : optional, default=None + name_or_coord : optional Either, * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`, @@ -2203,39 +2203,39 @@ def coord( * a coordinate or metadata instance equal to that of the desired coordinate e.g., :class:`~iris.coords.DimCoord` or :class:`~iris.common.metadata.CoordMetadata`. - standard_name : optional, default=None + standard_name : optional The CF standard name of the desired coordinate. If ``None``, does not check for ``standard name``. - long_name : optional, default=None + long_name : optional An unconstrained description of the coordinate. If ``None``, does not check for ``long_name``. - var_name : optional, default=None + var_name : optional The NetCDF variable name of the desired coordinate. If ``None``, does not check for ``var_name``. - attributes : optional, default=None + attributes : optional A dictionary of attributes desired on the coordinates. If ``None``, does not check for ``attributes``. - axis : optional, default=None + axis : optional The desired coordinate axis, see :func:`iris.util.guess_coord_axis`. If ``None``, does not check for ``axis``. Accepts the values ``X``, ``Y``, ``Z`` and ``T`` (case-insensitive). - contains_dimension : optional, default=None + contains_dimension : optional The desired coordinate contains the data dimension. If ``None``, does not check for the dimension. - dimensions : optional, default=None + dimensions : optional The exact data dimensions of the desired coordinate. Coordinates with no data dimension can be found with an empty ``tuple`` or ``list`` i.e., ``()`` or ``[]``. If ``None``, does not check for dimensions. - coord_system : optional, default=None + coord_system : optional Whether the desired coordinates have a coordinate system equal to the given coordinate system. If ``None``, no check is done. - dim_coords : optional, default=None + dim_coords : optional Set to ``True`` to only return coordinates that are the cube's dimension coordinates. Set to ``False`` to only return coordinates that are the cube's auxiliary, mesh and derived coordinates. If ``None``, returns all coordinates. - mesh_coords : optional, default=None + mesh_coords : optional Set to ``True`` to return only coordinates which are :class:`~iris.experimental.ugrid.MeshCoord`\'s. Set to ``False`` to return only non-mesh coordinates. @@ -2303,7 +2303,7 @@ def coord_system(self, spec=None): Parameters ---------- - spec : optional, default=None + spec : optional The the name or type of a coordinate system subclass. E.g. :: @@ -2421,7 +2421,7 @@ def cell_measures(self, name_or_cell_measure=None): Parameters ---------- - name_or_cell_measure : optional, default=None + name_or_cell_measure : optional Either * (a) a :attr:`standard_name`, :attr:`long_name`, or @@ -2508,7 +2508,7 @@ def ancillary_variables(self, name_or_ancillary_variable=None): Parameters ---------- - name_or_ancillary_variable : optional, default=None + name_or_ancillary_variable : optional Either * (a) a :attr:`standard_name`, :attr:`long_name`, or @@ -2784,11 +2784,11 @@ def summary(self, shorten=False, name_padding=35): Parameters ---------- - shorten : bool + shorten : bool, default=False If set, produce a one-line summary of minimal width, showing only the cube name, units and dimensions. When not set (default), produces a full multi-line summary string. - name_padding : int + name_padding : int, default=35 Control the *minimum* width of the cube name + units, i.e. the indent of the dimension map section. @@ -3448,7 +3448,7 @@ def slices(self, ref_to_slice, ordered=True): the dimensions that are not iterated over). A mix of input types can also be provided. They must all be orthogonal (i.e. point to different dimensions). - ordered : bool, optional + ordered : bool, default=True if True, the order which the coords to slice or data_dims are given will be the order in which they represent the data in the resulting cube slices. If False, the order will follow that of @@ -3764,7 +3764,7 @@ def copy(self, data=None): Parameters ---------- - data : optional, default=None + data : optional Replace the data of the cube copy with provided data payload. Returns @@ -4197,7 +4197,7 @@ def aggregated_by(self, coords, aggregator, climatological=False, **kwargs): performed. aggregator : :class:`iris.analysis.Aggregator` Aggregator to be applied to each group. - 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 @@ -4680,7 +4680,7 @@ def interpolate(self, sample_points, scheme, collapse_scalar=True): * :class:`iris.analysis.Linear`, and * :class:`iris.analysis.Nearest`. - collapse_scalar : bool, optional + collapse_scalar : bool, default=True Whether to collapse the dimension of scalar sample points in the resulting cube. Default is True. diff --git a/lib/iris/experimental/regrid.py b/lib/iris/experimental/regrid.py index 74b356722f..1bea933fbf 100644 --- a/lib/iris/experimental/regrid.py +++ b/lib/iris/experimental/regrid.py @@ -92,7 +92,7 @@ def regrid_area_weighted_rectilinear_src_and_grid(src_cube, grid_cube, mdtol=0): grid_cube : :class:`iris.cube.Cube` An instance of :class:`iris.cube.Cube` that supplies the desired horizontal grid definition. - mdtol : int, optional, default=0 + mdtol : int, default=0 Tolerance of missing data. The value returned in each element of the returned cube's data array will be masked if the fraction of masked data in the overlapping cells of the source cube exceeds mdtol. This diff --git a/lib/iris/experimental/regrid_conservative.py b/lib/iris/experimental/regrid_conservative.py index 07b076b57e..e15b1c29a5 100644 --- a/lib/iris/experimental/regrid_conservative.py +++ b/lib/iris/experimental/regrid_conservative.py @@ -65,6 +65,7 @@ def _make_esmpy_field(x_coord, y_coord, ref_name="field", data=None, mask=None): x_coord, y_coord : :class:`iris.coords.Coord` One-dimensional coordinates of shape (nx,) and (ny,). Their contiguous bounds define an ESMF.Grid of shape (nx, ny). + ref_name : stre, default="field" data : :class:`numpy.ndarray`, shape (nx,ny), optional Set the Field data content. mask : :class:`numpy.ndarray`, bool, shape (nx,ny), optional diff --git a/lib/iris/experimental/representation.py b/lib/iris/experimental/representation.py index 0b98c24395..4ffe176e3a 100644 --- a/lib/iris/experimental/representation.py +++ b/lib/iris/experimental/representation.py @@ -207,18 +207,24 @@ def _make_shapes_row(self): def _make_row(self, title, body=None, col_span=0): """Produce one row for the table body. - For example:: + Parameters + ---------- + body : str, optional + Contains the content for each cell not in the left-most (title) column. + If None, indicates this row is a title row (see below). + title : stre, optional + Contains the row heading. If `body` is None, indicates + that the row contains a sub-heading; + e.g. 'Dimension coordinates:'. + col_span : int, default=0 + Indicates how many columns the string should span. + + Examples + -------- + :: Coord namex-.... - * `body` contains the content for each cell not in the left-most (title) - column. - If None, indicates this row is a title row (see below). - * `title` contains the row heading. If `body` is None, indicates - that the row contains a sub-heading; - e.g. 'Dimension coordinates:'. - * `col_span` indicates how many columns the string should span. - """ row = [''] template = " {content}" diff --git a/lib/iris/experimental/stratify.py b/lib/iris/experimental/stratify.py index 3e5fb1da9f..50f8c21dcf 100644 --- a/lib/iris/experimental/stratify.py +++ b/lib/iris/experimental/stratify.py @@ -20,10 +20,8 @@ def _copy_coords_without_z_dim(src, tgt, z_dim): ---------- src : :class:`~iris.cube.Cube` Incoming cube containing the coordinates to be copied from. - tgt : :class:`~iris.cube.Cube` Outgoing cube for the coordinates to be copied to. - z_dim : int Dimension within the `src` cube that is the z-dimension. This dimension will not be copied. For example, the incoming @@ -67,27 +65,23 @@ def relevel(cube, src_levels, tgt_levels, axis=None, interpolator=None): ---------- cube : :class:`~iris.cube.Cube` The phenomenon data to be re-levelled. - - src_levels : :class:`~iris.cube.Cube`, :class:`~iris.coord.Coord` or string + src_levels : :class:`~iris.cube.Cube`, :class:`~iris.coord.Coord` or str Describes the source levels of the `cube` that will be interpolated over. The `src_levels` must be in the same system as the `tgt_levels`. The dimensions of `src_levels` must be broadcastable to the dimensions of the `cube`. Note that, the coordinate name containing the source levels in the `cube` may be provided. - tgt_levels : array-like Describes the target levels of the `cube` to be interpolated to. The `tgt_levels` must be in the same system as the `src_levels`. The dimensions of the `tgt_levels` must be broadcastable to the dimensions of the `cube`, except in the nominated axis of interpolation. - - axis : int, :class:`~iris.coords.Coord` or string + axis : int, :class:`~iris.coords.Coord` or str, optional The axis of interpolation. Defaults to the first dimension of the `cube`, which is typically the z-dimension. Note that, the coordinate name specifying the z-dimension of the `cube` may be provided. - - interpolator : callable or None + interpolator : callable or None, optional The interpolator to use when computing the interpolation. The function will be passed the following positional arguments:: diff --git a/lib/iris/experimental/ugrid/load.py b/lib/iris/experimental/ugrid/load.py index b8665a499e..b431f1ca96 100644 --- a/lib/iris/experimental/ugrid/load.py +++ b/lib/iris/experimental/ugrid/load.py @@ -127,10 +127,10 @@ def load_mesh(uris, var_name=None): ---------- uris : str or iterable of str One or more filenames/URI's. Filenames can include wildcards. Any URI's - must support OpenDAP. + must support OpenDAP. var_name : str, optional Only return a :class:`~iris.experimental.ugrid.mesh.Mesh` if its - var_name matches this value. + var_name matches this value. Returns ------- @@ -153,17 +153,17 @@ def load_meshes(uris, var_name=None): ---------- uris : str or iterable of str One or more filenames/URI's. Filenames can include wildcards. Any URI's - must support OpenDAP. + must support OpenDAP. var_name : str, optional Only return :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es that have - var_names matching this value. + var_names matching this value. Returns ------- dict A dictionary mapping each mesh-containing file path/URL in the input - ``uris`` to a list of the - :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es returned from each. + ``uris`` to a list of the + :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es returned from each. """ # TODO: rationalise UGRID/mesh handling once experimental.ugrid is folded diff --git a/lib/iris/experimental/ugrid/mesh.py b/lib/iris/experimental/ugrid/mesh.py index 147b1fd513..2494998e4c 100644 --- a/lib/iris/experimental/ugrid/mesh.py +++ b/lib/iris/experimental/ugrid/mesh.py @@ -313,7 +313,7 @@ def indices_by_location(self, indices=None): Parameters ---------- - indices : array + indices : array, optional The array on which to operate. If ``None``, will operate on :attr:`indices`. Default is ``None``. @@ -1260,17 +1260,17 @@ def add_coords( Parameters ---------- - node_x (object) : optional, default=None + node_x : optional The ``x-axis`` like ``node`` :class:`~iris.coords.AuxCoord`. - node_y (object): optional, default=None + node_y : optional The ``y-axis`` like ``node`` :class:`~iris.coords.AuxCoord`. - edge_x (object): optional, default=None + edge_x : optional The ``x-axis`` like ``edge`` :class:`~iris.coords.AuxCoord`. - edge_y (object): optional, default=None + edge_y : optional The ``y-axis`` like ``edge`` :class:`~iris.coords.AuxCoord`. - face_x (object): optional, default=None + face_x : optional The ``x-axis`` like ``face`` :class:`~iris.coords.AuxCoord`. - face_y (object): optional, default=None + face_y : optional The ``y-axis`` like ``face`` :class:`~iris.coords.AuxCoord`. """ @@ -1326,23 +1326,23 @@ def connectivities( the desired objects e.g., :class:`~iris.experimental.ugrid.mesh.Connectivity` or :class:`~iris.experimental.ugrid.metadata.ConnectivityMetadata`. - standard_name : str, optional, default=None + standard_name : str, optional The CF standard name of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``standard_name``. - long_name : str, optional, default=None + long_name : str, optional An unconstrained description of the :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``long_name``. - var_name : str, optional, default=None + var_name : str, optional The NetCDF variable name of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``var_name``. - attributes : dict, optional, default=None + attributes : dict, optional A dictionary of attributes desired on the :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``attributes``. - cf_role : str, optional, default=None + cf_role : str, optional The UGRID ``cf_role`` of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. contains_node : bool, optional @@ -1422,23 +1422,23 @@ def connectivity( the desired object e.g., :class:`~iris.experimental.ugrid.mesh.Connectivity` or :class:`~iris.experimental.ugrid.metadata.ConnectivityMetadata`. - standard_name : str, optional, default=None + standard_name : str, optional The CF standard name of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``standard_name``. - long_name : str, optional, default=None + long_name : str, optional An unconstrained description of the :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``long_name``. - var_name : str, optional, default=None + var_name : str, optional The NetCDF variable name of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``var_name``. - attributes : dict, optional, default=None + attributes : dict, optional A dictionary of attributes desired on the :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``attributes``. - cf_role : str, optional, default=None + cf_role : str, optional The UGRID ``cf_role`` of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. contains_node : bool, optional @@ -1505,7 +1505,7 @@ def coord( Parameters ---------- - item : str or object, optional, default=None + item : str or object, optional Either, * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`, @@ -1516,19 +1516,19 @@ def coord( * a coordinate or metadata instance equal to that of the desired coordinate e.g., :class:`~iris.coords.AuxCoord` or :class:`~iris.common.metadata.CoordMetadata`. - standard_name : str, optional, default=None + standard_name : str, optional The CF standard name of the desired coordinate. If ``None``, does not check for ``standard_name``. - long_name : str, optional, default=None + long_name : str, optional An unconstrained description of the coordinate. If ``None``, does not check for ``long_name``. - var_name : str, optional, default=None + var_name : str, optional The NetCDF variable name of the desired coordinate. If ``None``, does not check for ``var_name``. - attributes : dict, optional, default=None + attributes : dict, optional A dictionary of attributes desired on the coordinates. If ``None``, does not check for ``attributes``. - axis : str, optional, default=None + axis : str, optional The desired coordinate axis, see :func:`~iris.util.guess_coord_axis`. If ``None``, does not check for ``axis``. Accepts the values ``X``, ``Y``, ``Z`` and ``T`` (case-insensitive). @@ -1585,7 +1585,7 @@ def coords( Parameters ---------- - item : str or object, optional, default=None + item : str or object, optional Either, * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`, @@ -1596,19 +1596,19 @@ def coords( * a coordinate or metadata instance equal to that of the desired coordinates e.g., :class:`~iris.coords.AuxCoord` or :class:`~iris.common.metadata.CoordMetadata`. - standard_name : str, optional, default=None + standard_name : str, optional The CF standard name of the desired coordinate. If ``None``, does not check for ``standard_name``. - long_name : str, optional, default=None + long_name : str, optional An unconstrained description of the coordinate. If ``None``, does not check for ``long_name``. - var_name : str, optional, default=None + var_name : str, optional The NetCDF variable name of the desired coordinate. If ``None``, does not check for ``var_name``. - attributes : dict, optional, default=None + attributes : dict, optional A dictionary of attributes desired on the coordinates. If ``None``, does not check for ``attributes``. - axis : str, optional, default=None + axis : str, optional The desired coordinate axis, see :func:`~iris.util.guess_coord_axis`. If ``None``, does not check for ``axis``. Accepts the values ``X``, ``Y``, ``Z`` and ``T`` (case-insensitive). @@ -1661,7 +1661,7 @@ def remove_connectivities( Parameters ---------- - item : str or object, optional, default=None + item : str or object, optional Either, * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`, @@ -1673,23 +1673,23 @@ def remove_connectivities( the desired objects e.g., :class:`~iris.experimental.ugrid.mesh.Connectivity` or :class:`~iris.experimental.ugrid.metadata.ConnectivityMetadata`. - standard_name : str, optional, default=None + standard_name : str, optional The CF standard name of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``standard_name``. - long_name : str, optional, default=None + long_name : str, optional An unconstrained description of the :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``long_name``. - var_name : str, optional, default=None + var_name : str, optional The NetCDF variable name of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``var_name``. - attributes : dict, optional, default=None + attributes : dict, optional A dictionary of attributes desired on the :class:`~iris.experimental.ugrid.mesh.Connectivity`. If ``None``, does not check for ``attributes``. - cf_role : str, optional, default=None + cf_role : str, optional The UGRID ``cf_role`` of the desired :class:`~iris.experimental.ugrid.mesh.Connectivity`. contains_node : bool, optional @@ -1747,7 +1747,7 @@ def remove_coords( Parameters ---------- - item : str or object, optional, default=None + item : str or object, optional Either, * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`, @@ -1758,19 +1758,19 @@ def remove_coords( * a coordinate or metadata instance equal to that of the desired coordinates e.g., :class:`~iris.coords.AuxCoord` or :class:`~iris.common.metadata.CoordMetadata`. - standard_name : str, optional, default=None + standard_name : str, optional The CF standard name of the desired coordinate. If ``None``, does not check for ``standard_name``. - long_name : str, optional, default=None + long_name : str, optional An unconstrained description of the coordinate. If ``None``, does not check for ``long_name``. - var_name : str, optional, default=None + var_name : str, optional The NetCDF variable name of the desired coordinate. If ``None``, does not check for ``var_name``. - attributes : dict, optional, default=None + attributes : dict, optional A dictionary of attributes desired on the coordinates. If ``None``, does not check for ``attributes``. - axis : str, optional, default=None + axis : str, optional The desired coordinate axis, see :func:`~iris.util.guess_coord_axis`. If ``None``, does not check for ``axis``. Accepts the values ``X``, ``Y``, ``Z`` and ``T`` (case-insensitive). @@ -1908,10 +1908,10 @@ def dimension_names_reset(self, node=False, edge=False, face=False): node : bool, optional, default=False Reset the name of the ``node`` dimension if ``True``. Default is ``False``. - edge : bool, optional, default=False + edge : bool, default=False Reset the name of the ``edge`` dimension if ``True``. Default is ``False``. - face : bool, optional, default=False + face : bool, default=False Reset the name of the ``face`` dimension if ``True``. Default is ``False``. @@ -1930,13 +1930,13 @@ def dimension_names(self, node=None, edge=None, face=None): Parameters ---------- - node : str, optional, default=None + node : str, optional The name to be used for the NetCDF variable representing the ``node`` dimension. - edge : str, optional, default=None + edge : str, optional The name to be used for the NetCDF variable representing the ``edge`` dimension. - face : str, optional, default=None + face : str, optional The name to be used for the NetCDF variable representing the ``face`` dimension. @@ -2842,7 +2842,7 @@ def copy(self, points=None, bounds=None): Parameters ---------- - points, bounds : array) + points, bounds : array, optional Provided solely for signature compatibility with other types of :class:`~iris.coords.Coord`. In this case, if either is not 'None', an error is raised. diff --git a/lib/iris/experimental/ugrid/save.py b/lib/iris/experimental/ugrid/save.py index c78289fe26..40d1c42e90 100644 --- a/lib/iris/experimental/ugrid/save.py +++ b/lib/iris/experimental/ugrid/save.py @@ -16,17 +16,13 @@ def save_mesh(mesh, filename, netcdf_format="NETCDF4"): """Save mesh(es) to a netCDF file. - Args: - - * mesh (:class:`iris.experimental.ugrid.Mesh` or iterable): - mesh(es) to save. - - * filename (string): + Parameters + ---------- + mesh : :class:`iris.experimental.ugrid.Mesh` or iterable + Mesh(es) to save. + filename : str Name of the netCDF file to create. - - Kwargs: - - * netcdf_format (string): + netcdf_format : str, default="NETCDF4" Underlying netCDF file format, one of 'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC' or 'NETCDF3_64BIT'. Default is 'NETCDF4' format. diff --git a/lib/iris/fileformats/_ff.py b/lib/iris/fileformats/_ff.py index 301a45736e..d2ce1bcefb 100644 --- a/lib/iris/fileformats/_ff.py +++ b/lib/iris/fileformats/_ff.py @@ -184,7 +184,7 @@ def vectors(self, subgrid): Returns ------- - A 2-tuple of X-vector, Y-vector. + A 2-tuple of X-vector, Y-vector. """ x_p, x_u = self._x_vectors() @@ -223,7 +223,7 @@ def regular_x(self, subgrid): Returns ------- - A 2-tuple of BZX, BDX. + A 2-tuple of BZX, BDX. """ bdx = self.ew_spacing @@ -245,7 +245,7 @@ def regular_y(self, subgrid): Returns ------- - A 2-tuple of BZY, BDY. + A 2-tuple of BZY, BDY. """ bdy = self.ns_spacing @@ -307,6 +307,7 @@ def __init__(self, filename, word_depth=DEFAULT_FF_WORD_DEPTH): ---------- filename : str Specify the name of the FieldsFile. + word_depth : int, default=DEFAULT_FF_WORD_DEPTH Returns ------- @@ -445,9 +446,10 @@ def __init__(self, filename, read_data=False, word_depth=DEFAULT_FF_WORD_DEPTH): ---------- filename : str Specify the name of the FieldsFile. - read_data : bool, optional + read_data : bool, default=False Specify whether to read the associated PPField data within the FieldsFile. Default value is False. + word_depth : int, default=DEFAULT_FF_WORD_DEPTH Returns ------- diff --git a/lib/iris/fileformats/_nc_load_rules/actions.py b/lib/iris/fileformats/_nc_load_rules/actions.py index 8f408716e6..fefa58ad10 100644 --- a/lib/iris/fileformats/_nc_load_rules/actions.py +++ b/lib/iris/fileformats/_nc_load_rules/actions.py @@ -7,6 +7,7 @@ For now, we are still emulating various aspects of how our original Pyke-based code used the Pyke 'engine' to hold translation data, both Pyke-specific and not : + 1) basic details from the iris.fileformats.cf analysis of the file are recorded before translating each output cube, using "engine.assert_case_specific_fact(name, args)". diff --git a/lib/iris/fileformats/_nc_load_rules/helpers.py b/lib/iris/fileformats/_nc_load_rules/helpers.py index f656667e63..98357c1f26 100644 --- a/lib/iris/fileformats/_nc_load_rules/helpers.py +++ b/lib/iris/fileformats/_nc_load_rules/helpers.py @@ -154,7 +154,6 @@ CF_ATTR_GRID_SCALE_FACTOR_AT_PROJ_ORIGIN = "scale_factor_at_projection_origin" CF_ATTR_GRID_SCALE_FACTOR_AT_CENT_MERIDIAN = "scale_factor_at_central_meridian" CF_ATTR_GRID_LON_OF_CENT_MERIDIAN = "longitude_of_central_meridian" -CF_ATTR_GRID_STANDARD_PARALLEL = "standard_parallel" CF_ATTR_GRID_PERSPECTIVE_HEIGHT = "perspective_point_height" CF_ATTR_GRID_SWEEP_ANGLE_AXIS = "sweep_angle_axis" CF_ATTR_GRID_AZIMUTH_CENT_LINE = "azimuth_of_central_line" @@ -268,7 +267,7 @@ def _split_cell_methods(nc_cell_methods: str) -> List[re.Match]: Parameters ---------- - nc_cell_methods : + nc_cell_methods : str The value of the cell methods attribute to be split. Returns @@ -342,6 +341,7 @@ def parse_cell_methods(nc_cell_methods, cf_name=None): ---------- nc_cell_methods : str The value of the cell methods attribute to be parsed. + cf_name : optional Returns ------- @@ -1331,8 +1331,10 @@ def build_ancil_var(engine, cf_av_var): def _is_lat_lon(cf_var, ud_units, std_name, std_name_grid, axis_name, prefixes): """Determine whether the CF coordinate variable is a latitude/longitude variable. - Ref: [CF] Section 4.1 Latitude Coordinate. - [CF] Section 4.2 Longitude Coordinate. + Ref: + + * [CF] Section 4.1 Latitude Coordinate. + * [CF] Section 4.2 Longitude Coordinate. """ is_valid = False diff --git a/lib/iris/fileformats/abf.py b/lib/iris/fileformats/abf.py index 76f3573882..6dd8dfd14f 100644 --- a/lib/iris/fileformats/abf.py +++ b/lib/iris/fileformats/abf.py @@ -65,11 +65,14 @@ class ABFField: def __init__(self, filename): """Create an ABFField object from the given filename. - Args: + Parameters + ---------- + filename : str + An ABF filename. - * filename - An ABF filename. - - Example:: + Examples + -------- + :: field = ABFField("AVHRRBUVI01.1985feba.abl") @@ -194,14 +197,15 @@ def to_cube(self): def load_cubes(filespecs, callback=None): """Load cubes from a list of ABF filenames. - Args: - - * filenames - list of ABF filenames to load - - Kwargs: - - * callback - a function that can be passed to :func:`iris.io.run_callback` + Parameters + ---------- + filenames : + List of ABF filenames to load + callback : optional + A function that can be passed to :func:`iris.io.run_callback` + Notes + ----- .. note:: The resultant cubes may not be in the same order as in the file. diff --git a/lib/iris/fileformats/cf.py b/lib/iris/fileformats/cf.py index d6dab22305..5a0230d5eb 100644 --- a/lib/iris/fileformats/cf.py +++ b/lib/iris/fileformats/cf.py @@ -119,11 +119,11 @@ def identify(self, variables, ignore=None, target=None, warn=True): ---------- variables : Dictionary of netCDF4.Variable instance by variable name. - ignore : optional, default=None + ignore : optional List of variable names to ignore. - target : optional, default=None + target : optional Name of a single variable to check. - warn : optional, default=None + warn : bool, default=True Issue a warning if a missing variable is referenced. Returns @@ -300,8 +300,10 @@ class CFAuxiliaryCoordinateVariable(CFVariable): Identified by the CF-netCDF variable attribute 'coordinates'. Also see :class:`iris.fileformats.cf.CFLabelVariable`. - Ref: [CF] Chapter 5. Coordinate Systems. - [CF] Section 6.2. Alternative Coordinates. + Ref: + + * [CF] Chapter 5. Coordinate Systems. + * [CF] Section 6.2. Alternative Coordinates. """ @@ -554,8 +556,10 @@ class _CFFormulaTermsVariable(CFVariable): Identified by the CF-netCDF variable attribute 'formula_terms'. - Ref: [CF] Section 4.3.2. Dimensional Vertical Coordinate. - [CF] Appendix D. Dimensionless Vertical Coordinates. + Ref: + + * [CF] Section 4.3.2. Dimensional Vertical Coordinate. + * [CF] Appendix D. Dimensionless Vertical Coordinates. """ @@ -628,8 +632,10 @@ class CFGridMappingVariable(CFVariable): Identified by the CF-netCDF variable attribute 'grid_mapping'. - Ref: [CF] Section 5.6. Horizontal Coordinate Reference Systems, Grid Mappings, and Projections. - [CF] Appendix F. Grid Mappings. + Ref: + + * [CF] Section 5.6. Horizontal Coordinate Reference Systems, Grid Mappings, and Projections. + * [CF] Appendix F. Grid Mappings. """ diff --git a/lib/iris/fileformats/dot.py b/lib/iris/fileformats/dot.py index daa3f2fd61..53f85794c6 100644 --- a/lib/iris/fileformats/dot.py +++ b/lib/iris/fileformats/dot.py @@ -58,7 +58,7 @@ def save(cube, target): Parameters ---------- cube: :class:`iris.cube.Cube`. - target + target : A filename or open file handle. See Also @@ -94,9 +94,8 @@ def save_png(source, target, launch=False): target : A filename or open file handle. If passing a file handle, take care to open it for binary output. - **kwargs : - * launch - Display the image. Default is False. + launch : bool, default=False + Display the image. Default is False. See Also -------- @@ -342,6 +341,7 @@ def _dot_node(indent, id, name, attributes): The visual name of the node. attributes : An iterable of (name, value) attribute pairs. + """ # noqa: D410, D411 attributes = r"\n".join("%s: %s" % item for item in attributes) template = """%(indent)s"%(id)s" [ diff --git a/lib/iris/fileformats/netcdf/loader.py b/lib/iris/fileformats/netcdf/loader.py index 6f69b6e64d..1dcf026d84 100644 --- a/lib/iris/fileformats/netcdf/loader.py +++ b/lib/iris/fileformats/netcdf/loader.py @@ -562,10 +562,8 @@ def load_cubes(file_sources, callback=None, constraints=None): file_sources : str or list One or more NetCDF filenames/OPeNDAP URLs to load from. OR open datasets. - callback : function, optional Function which can be passed on to :func:`iris.io.run_callback`. - constraints : optional Returns @@ -801,6 +799,7 @@ def as_dask(self) -> None: Notes ----- This function acts as a context manager, for use in a ``with`` block. + """ old_mode = self.mode old_var_dim_chunksizes = deepcopy(self.var_dim_chunksizes) diff --git a/lib/iris/fileformats/netcdf/saver.py b/lib/iris/fileformats/netcdf/saver.py index b35b85bbae..a607d7de97 100644 --- a/lib/iris/fileformats/netcdf/saver.py +++ b/lib/iris/fileformats/netcdf/saver.py @@ -182,9 +182,9 @@ def append(self, name, coord): Parameters ---------- - name: + name : CF name of the associated coordinate. - coord: + coord : The coordinate of the associated CF name. Returns @@ -209,7 +209,7 @@ def name(self, coord): Parameters ---------- - coord: + coord : The coordinate of the associated CF name. Returns @@ -229,12 +229,13 @@ def coord(self, name): Parameters ---------- - name: + name : CF name of the associated coordinate, or None if not recognised. Returns ------- CF name or None. + """ result = None for pair in self._map: @@ -338,7 +339,7 @@ def _fillvalue_report(fill_info, is_masked, contains_fill_value, warn=False): whether the data array was masked contains_fill_value : bool whether the data array contained the fill-value - warn : bool, optional + warn : bool, default=False if True, also issue any resulting warning immediately. Returns @@ -390,11 +391,9 @@ def __init__(self, filename, netcdf_format, compute=True): filename : str or netCDF4.Dataset Name of the netCDF file to save the cube. OR a writeable object supporting the :class:`netCF4.Dataset` api. - netcdf_format : str Underlying netCDF file format, one of 'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC' or 'NETCDF3_64BIT'. Default is 'NETCDF4' format. - compute : bool, default=True If ``True``, delayed variable saves will be completed on exit from the Saver context (after first closing the target file), equivalent to @@ -404,7 +403,7 @@ def __init__(self, filename, netcdf_format, compute=True): variables for which the source data was lazy. These writes can be completed later, see :meth:`delayed_completion`. - .. Note:: + .. note:: If ``filename`` is an open dataset, rather than a filepath, then the caller must specify ``compute=False``, **close the dataset**, and complete delayed saving afterwards. @@ -543,39 +542,38 @@ def write( ---------- cube : :class:`iris.cube.Cube` A :class:`iris.cube.Cube` to be saved to a netCDF file. - local_keys : iterable of str + local_keys : iterable of str, optional An interable of cube attribute keys. Any cube attributes with matching keys will become attributes on the data variable rather than global attributes. - .. Note:: + .. note:: Has no effect if :attr:`iris.FUTURE.save_split_attrs` is ``True``. - - unlimited_dimensions : iterable of str and/or :class:`iris.coords.Coord` + unlimited_dimensions : iterable of str and/or :class:`iris.coords.Coord`, optional List of coordinate names (or coordinate objects) corresponding to coordinate dimensions of `cube` to save with the NetCDF dimension variable length 'UNLIMITED'. By default, no unlimited dimensions are saved. Only the 'NETCDF4' format supports multiple 'UNLIMITED' dimensions. - zlib : bool + zlib : bool, default=False If `True`, the data will be compressed in the netCDF file using gzip compression (default `False`). - complevel : int + complevel : int, default=4 An integer between 1 and 9 describing the level of compression desired (default 4). Ignored if `zlib=False`. - shuffle : bool + shuffle : bool, default=True If `True`, the HDF5 shuffle filter will be applied before compressing the data (default `True`). This significantly improves compression. Ignored if `zlib=False`. - fletcher32 : bool + fletcher32 : bool, default=False If `True`, the Fletcher32 HDF5 checksum algorithm is activated to detect errors. Default `False`. - contiguous : bool + contiguous : bool, default=False If `True`, the variable data is stored contiguously on disk. Default `False`. Setting to `True` for a variable with an unlimited dimension will trigger an error. - chunksizes : tuple of int + chunksizes : tuple of int, optional Used to manually specify the HDF5 chunksizes for each dimension of the variable. A detailed discussion of HDF chunking and I/O performance is available @@ -583,7 +581,7 @@ def write( Basically, you want the chunk size for each dimension to match as closely as possible the size of the data block that users will read from the file. `chunksizes` cannot be set if `contiguous=True`. - endian : str + endian : str, default="native" Used to control whether the data is stored in little or big endian format on disk. Possible values are 'little', 'big' or 'native' (default). The library will automatically handle endian conversions @@ -591,7 +589,7 @@ def write( on a computer with the opposite format as the one used to create the file, there may be some performance advantage to be gained by setting the endian-ness. - least_significant_digit : int + least_significant_digit : int, optional If `least_significant_digit` is specified, variable data will be truncated (quantized). In conjunction with `zlib=True` this produces 'lossy', but significantly more efficient compression. For @@ -603,7 +601,7 @@ def write( "least_significant_digit -- power of ten of the smallest decimal place in unpacked data that is a reliable value". Default is `None`, or no quantization, or 'lossless' compression. - packing : type or str or dict or list + packing : type or str or dict or list, optional A numpy integer datatype (signed or unsigned) or a string that describes a numpy integer dtype(i.e. 'i2', 'short', 'u4') or a dict of packing parameters as described below. This provides @@ -618,7 +616,7 @@ def write( manually using a dict to avoid this. The default is `None`, in which case the datatype is determined from the cube and no packing will occur. - fill_value: + fill_value : optional The value to use for the `_FillValue` attribute on the netCDF variable. If `packing` is specified the value of `fill_value` should be in the domain of the packed data. @@ -783,7 +781,7 @@ def update_global_attributes(self, attributes=None, **kwargs): Parameters ---------- - attributes : dict or iterable of key, value pairs + attributes : dict or iterable of key, value pairs, optional CF global attributes to be updated. """ # TODO: when when iris.FUTURE.save_split_attrs is removed, this routine will @@ -807,12 +805,14 @@ def _create_cf_dimensions(self, cube, dimension_names, unlimited_dimensions=None ---------- cube : :class:`iris.cube.Cube` A :class:`iris.cube.Cube` in which to lookup coordinates. + dimension_names : unlimited_dimensions : iterable of strings and/or :class:`iris.coords.Coord` objects): List of coordinates to make unlimited (None by default). Returns ------- None. + """ unlimited_dim_names = [] if unlimited_dimensions is not None: @@ -1497,7 +1497,7 @@ def _create_cf_bounds(self, coord, cf_var, cf_name): ---------- coord : :class:`iris.coords.Coord` A coordinate of a cube. - cf_var: + cf_var : CF-netCDF variable cf_name : str name of the CF-NetCDF variable. @@ -1763,12 +1763,12 @@ def _create_generic_cf_array_var( An Iris :class:`iris.coords._DimensionalMetadata`, belonging to the cube. Provides data, units and standard/long/var names. Not used if 'element_dims' is not None. - element_dims : list of str, or None + element_dims : list of str, optionsl If set, contains the variable dimension (names), otherwise these are taken from `element.cube_dims[cube]`. For Mesh components (element coordinates and connectivities), this *must* be passed in, as "element.cube_dims" does not function. - fill_value : number or None + fill_value : number, optional If set, create the variable with this fill-value, and fill any masked data points with this value. If not set, standard netcdf4-python behaviour : the variable has no @@ -2207,6 +2207,8 @@ def _create_cf_data_variable( fill_value : optional See :func:`iris.fileformats.netcdf.Saver.write` + Notes + ----- All other keywords are passed through to the dataset's `createVariable` method. @@ -2619,7 +2621,7 @@ def save( When saving to a dataset, ``compute`` **must** be ``False`` : See the ``compute`` parameter. - netcdf_format : str + netcdf_format : str, default="NETCDF" Underlying netCDF file format, one of 'NETCDF4', 'NETCDF4_CLASSIC', 'NETCDF3_CLASSIC' or 'NETCDF3_64BIT'. Default is 'NETCDF4' format. local_keys : iterable of str, optional @@ -2637,20 +2639,20 @@ def save( variable length 'UNLIMITED'. By default, no unlimited dimensions are saved. Only the 'NETCDF4' format supports multiple 'UNLIMITED' dimensions. - zlib : bool, optional + zlib : bool, default=False If `True`, the data will be compressed in the netCDF file using gzip compression (default `False`). - complevel : int + complevel : int, default=4 An integer between 1 and 9 describing the level of compression desired (default 4). Ignored if `zlib=False`. - shuffle : bool, optional + shuffle : bool, default=True If `True`, the HDF5 shuffle filter will be applied before compressing the data (default `True`). This significantly improves compression. Ignored if `zlib=False`. - fletcher32 : bool, optional + fletcher32 : bool, default=False If `True`, the Fletcher32 HDF5 checksum algorithm is activated to detect errors. Default `False`. - contiguous : bool, optional + contiguous : bool, default=False If `True`, the variable data is stored contiguously on disk. Default `False`. Setting to `True` for a variable with an unlimited dimension will trigger an error. @@ -2662,7 +2664,7 @@ def save( Basically, you want the chunk size for each dimension to match as closely as possible the size of the data block that users will read from the file. `chunksizes` cannot be set if `contiguous=True`. - endian : str + endian : str, default="native" Used to control whether the data is stored in little or big endian format on disk. Possible values are 'little', 'big' or 'native' (default). The library will automatically handle endian conversions @@ -2707,7 +2709,7 @@ def save( same number of elements as `cube` if `cube` is a :class:`iris.cube.CubeList`, or a single element, and each element of this argument will be applied to each cube separately. - compute : bool, optional + compute : bool, default=True Default is ``True``, meaning complete the file immediately, and return ``None``. When ``False``, create the output file but don't write any lazy array content to @@ -2717,12 +2719,12 @@ def save( Several such data saves can be performed in parallel, by passing a list of them into a :func:`dask.compute` call. - .. Note:: + .. note:: when computed, the returned :class:`dask.delayed.Delayed` object returns a list of :class:`Warning` : These are any warnings which *would* have been issued in the save call, if ``compute`` had been ``True``. - .. Note:: + .. note:: If saving to an open dataset instead of a filepath, then the caller **must** specify ``compute=False``, and complete delayed saves **after closing the dataset**. @@ -2732,7 +2734,7 @@ def save( Returns ------- - result: None or dask.delayed.Delayed + result : None or dask.delayed.Delayed If `compute=True`, returns `None`. Otherwise returns a :class:`dask.delayed.Delayed`, which implements delayed writing to fill in the variables data. diff --git a/lib/iris/fileformats/nimrod.py b/lib/iris/fileformats/nimrod.py index 009535dc8f..55927df3ef 100644 --- a/lib/iris/fileformats/nimrod.py +++ b/lib/iris/fileformats/nimrod.py @@ -171,9 +171,9 @@ class NimrodField: References ---------- - Met Office (2003): Met Office Rain Radar Data from the NIMROD System. - NCAS British Atmospheric Data Centre, date of citation. - https://catalogue.ceda.ac.uk/uuid/82adec1f896af6169112d09cc1174499 + Met Office (2003): Met Office Rain Radar Data from the NIMROD System. + NCAS British Atmospheric Data Centre, date of citation. + https://catalogue.ceda.ac.uk/uuid/82adec1f896af6169112d09cc1174499 """ @@ -296,7 +296,7 @@ def load_cubes(filenames, callback=None): ---------- filenames : List of NIMROD filenames to load - callback : + callback : optional A function which can be passed on to :func:`iris.io.run_callback` Notes diff --git a/lib/iris/fileformats/nimrod_load_rules.py b/lib/iris/fileformats/nimrod_load_rules.py index 3c4c56bc3b..5ca9ef4be3 100644 --- a/lib/iris/fileformats/nimrod_load_rules.py +++ b/lib/iris/fileformats/nimrod_load_rules.py @@ -890,11 +890,10 @@ def time_averaging(cube, field): def run(field, handle_metadata_errors=True): """Convert a NIMROD field to an Iris cube. - Args - ---- - field: :class:`~iris.fileformats.nimrod.NimrodField` - - handle_metadata_errors + Parameters + ---------- + field : :class:`~iris.fileformats.nimrod.NimrodField` + handle_metadata_errors : bool, default=True Set to False to omit handling of known meta-data deficiencies in Nimrod-format data @@ -902,6 +901,7 @@ def run(field, handle_metadata_errors=True): ------- :class:`~iris.cube.Cube` A new :class:`~iris.cube.Cube`, created from the NimrodField. + """ cube = iris.cube.Cube(field.data) diff --git a/lib/iris/fileformats/pp.py b/lib/iris/fileformats/pp.py index 9a205fb1be..2780c52625 100644 --- a/lib/iris/fileformats/pp.py +++ b/lib/iris/fileformats/pp.py @@ -275,8 +275,8 @@ class STASH(collections.namedtuple("STASH", "model section item")): def __new__(cls, model, section, item): """Create namedtuple STASH instance. - Args - ---- + Parameters + ---------- model : A positive integer less than 100, or None. section : @@ -370,28 +370,27 @@ class SplittableInt: Notes ----- - No support for negative numbers + No support for negative numbers. """ def __init__(self, value, name_mapping_dict=None): """Build a SplittableInt given the positive integer value provided. - Args - ---- - **kwargs - * name_mapping_dict - (dict) - A special mapping to provide name based access to specific - integer positions: + Parameters + ---------- + name_mapping_dict : dict + A special mapping to provide name based access to specific + integer positions: - >>> a = SplittableInt(1234, {'hundreds': 2}) - >>> print(a.hundreds) - 2 - >>> a.hundreds = 9 - >>> print(a.hundreds) - 9 - >>> print(a) - 1934 + >>> a = SplittableInt(1234, {'hundreds': 2}) + >>> print(a.hundreds) + 2 + >>> a.hundreds = 9 + >>> print(a.hundreds) + 9 + >>> print(a) + 1934 """ @@ -1617,17 +1616,16 @@ def make_pp_field(header): def load(filename, read_data=False, little_ended=False): """Return an iterator of PPFields given a filename. - Args - ---- - filename + Parameters + ---------- + filename : str string of the filename to load. - **kwargs - * read_data - boolean - Flag whether or not the data should be read, if False an empty - data manager will be provided which can subsequently load the data - on demand. Default False. - * little_ended - boolean - If True, file contains all little-ended words (header and data). + read_data : bool, default=False + Flag whether or not the data should be read, if False an empty + data manager will be provided which can subsequently load the data + on demand. Default False. + little_ended : bool, default=False + If True, file contains all little-ended words (header and data). Notes ----- @@ -2007,11 +2005,10 @@ def load_cubes(filenames, callback=None, constraints=None): ---------- filenames : list of pp filenames to load - **kwargs : - * constraints - a list of Iris constraints - * callback - a function which can be passed on to :func:`iris.io.run_callback` + constraints : optional + A list of Iris constraints + callback : optional + A function which can be passed on to :func:`iris.io.run_callback` Notes ----- @@ -2028,21 +2025,20 @@ def load_cubes(filenames, callback=None, constraints=None): def load_cubes_little_endian(filenames, callback=None, constraints=None): """Load cubes from a list of pp filenames containing little-endian data. - Args - ---- - filenames + Parameters + ---------- + filenames : list of pp filenames to load - **kwargs - * constraints - a list of Iris constraints - * callback - a function which can be passed on to :func:`iris.io.run_callback` + constraints : optional + a list of Iris constraints + callback : optional + a function which can be passed on to :func:`iris.io.run_callback` Notes ----- The resultant cubes may not be in the order that they are in the file (order is not preserved when there is a field with orography - references) + references). """ return _load_cubes_variable_loader( @@ -2057,9 +2053,9 @@ def load_cubes_little_endian(filenames, callback=None, constraints=None): def load_pairs_from_fields(pp_fields): r"""Convert an iterable of PP fields into an iterable of tuples of (Cubes, PPField). - Args - ---- - pp_fields: + Parameters + ---------- + pp_fields : An iterable of :class:`iris.fileformats.pp.PPField`. Returns @@ -2152,27 +2148,24 @@ def _load_cubes_variable_loader( def save(cube, target, append=False, field_coords=None): """Use the PP saving rules (and any user rules) to save a cube to a PP file. - Args - ---- - cube: :class:`iris.cube.Cube` - + Parameters + ---------- + cube : :class:`iris.cube.Cube` target A filename or open file handle. - - **kwargs - * append - Whether to start a new file afresh or add the cube(s) - to the end of the file. - Only applicable when target is a filename, not a file - handle. - Default is False. - * field_coords - list of 2 coords or coord names which are to be used - for reducing the given cube into 2d slices, - which will ultimately determine the x and y - coordinates of the resulting fields. - If None, the final two dimensions are chosen - for slicing. + append : bool, default=False + Whether to start a new file afresh or add the cube(s) + to the end of the file. + Only applicable when target is a filename, not a file + handle. + Default is False. + field_coords : optional + list of 2 coords or coord names which are to be used + for reducing the given cube into 2d slices, + which will ultimately determine the x and y + coordinates of the resulting fields. + If None, the final two dimensions are chosen + for slicing. Notes ----- @@ -2191,18 +2184,17 @@ def save_pairs_from_cube(cube, field_coords=None, target=None): Use the PP saving rules to convert a cube or iterable of cubes to an iterable of (2D cube, PP field) pairs. - Args - ---- - cube: + Parameters + ---------- + cube : A :class:`iris.cube.Cube` - **kwargs - * field_coords: - List of 2 coords or coord names which are to be used for - reducing the given cube into 2d slices, which will ultimately - determine the x and y coordinates of the resulting fields. - If None, the final two dimensions are chosen for slicing. - * target: - A filename or open file handle. + field_coords : optional + List of 2 coords or coord names which are to be used for + reducing the given cube into 2d slices, which will ultimately + determine the x and y coordinates of the resulting fields. + If None, the final two dimensions are chosen for slicing. + target : optional + A filename or open file handle. """ # Open issues @@ -2309,18 +2301,16 @@ def as_fields(cube, field_coords=None, target=None): Use the PP saving rules (and any user rules) to convert a cube to an iterable of PP fields. - Args - ---- - cube - A :class:`iris.cube.Cube` - **kwargs : - * field_coords: - List of 2 coords or coord names which are to be used for - reducing the given cube into 2d slices, which will ultimately - determine the x and y coordinates of the resulting fields. - If None, the final two dimensions are chosen for slicing. - * target: - A filename or open file handle. + Parameters + ---------- + cube : :class:`iris.cube.Cube` + field_coords : optional + List of 2 coords or coord names which are to be used for + reducing the given cube into 2d slices, which will ultimately + determine the x and y coordinates of the resulting fields. + If None, the final two dimensions are chosen for slicing. + target : optional + A filename or open file handle. """ return ( @@ -2331,21 +2321,20 @@ def as_fields(cube, field_coords=None, target=None): ) -def save_fields(fields, target, append=False): +def save_fields(fields, target, append: bool = False): """Save an iterable of PP fields to a PP file. - Args - ---- - fields: + Parameters + ---------- + fields : An iterable of PP fields. - target: + target : A filename or open file handle. - **kwargs : - * append: - Whether to start a new file afresh or add the cube(s) to the end - of the file. - Only applicable when target is a filename, not a file handle. - Default is False. + append : bool, default=False + Whether to start a new file afresh or add the cube(s) to the end + of the file. + Only applicable when target is a filename, not a file handle. + Default is False. See Also -------- diff --git a/lib/iris/fileformats/pp_load_rules.py b/lib/iris/fileformats/pp_load_rules.py index f93f177ba8..8343afab40 100644 --- a/lib/iris/fileformats/pp_load_rules.py +++ b/lib/iris/fileformats/pp_load_rules.py @@ -354,7 +354,7 @@ def _collapse_degenerate_points_and_bounds(points, bounds=None, rtol=1.0e-7): ---------- points : :class:`numpy.ndarray` Array of points values. - bounds : :class:`numpy.ndarray`, optional, default=None + bounds : :class:`numpy.ndarray`, optional Array of bounds values. This array should have an additional vertex dimension (typically of length 2) when compared to the points array i.e. bounds.shape = points.shape + (nvertex,) @@ -463,12 +463,12 @@ def _new_coord_and_dims( Standard name of coordinate. units : str or cf_unit.Unit Units of coordinate. - lower_and_upper_bounds : pair of array-like or None, optional, default=None + lower_and_upper_bounds : pair of array-like or None, optional Corresponding bounds values (lower, upper), if any. Returns ------- - a new (coordinate, dims) pair. + A new (coordinate, dims) pair. """ bounds = lower_and_upper_bounds @@ -813,7 +813,7 @@ def _model_level_number(lblev): Returns ------- - Model level number (int). + Model level number (int). """ # See Word no. 33 (LBLEV) in section 4 of UM Model Docs (F3). diff --git a/lib/iris/fileformats/pp_save_rules.py b/lib/iris/fileformats/pp_save_rules.py index 9bcfd8d92f..20ed0bd618 100644 --- a/lib/iris/fileformats/pp_save_rules.py +++ b/lib/iris/fileformats/pp_save_rules.py @@ -489,9 +489,9 @@ def _non_std_cross_section_rules(cube, pp): Parameters ---------- - cube: + cube : The cube being saved as a series of PP fields. - pp: + pp : The current PP field having save rules applied. Returns @@ -622,9 +622,9 @@ def _lbproc_rules(cube, pp): Parameters ---------- - cube: + cube : The cube being saved as a series of PP fields. - pp: + pp : The current PP field having save rules applied. Returns diff --git a/lib/iris/fileformats/um/_fast_load_structured_fields.py b/lib/iris/fileformats/um/_fast_load_structured_fields.py index 6b09227491..976819ffd5 100644 --- a/lib/iris/fileformats/um/_fast_load_structured_fields.py +++ b/lib/iris/fileformats/um/_fast_load_structured_fields.py @@ -280,14 +280,6 @@ def group_structured_fields( **collation_kwargs : dict Additional constructor keywords for collation creation. - Implicitly, within each result group, *all* other metadata components - should be either: - - * the same for all fields, - * completely irrelevant, or - * used by a vectorised rule function (such as - :func:`iris.fileformats.pp_load_rules._convert_time_coords`). - Returns ------- Generator of 'collation_class' objects @@ -296,6 +288,14 @@ def group_structured_fields( Notes ----- + Implicitly, within each result group, *all* other metadata components + should be either: + + * the same for all fields, + * completely irrelevant, or + * used by a vectorised rule function (such as + :func:`iris.fileformats.pp_load_rules._convert_time_coords`). + The function sorts and collates on phenomenon-relevant metadata only, defined as the field components: 'lbuser[3]' (stash), 'lbproc' (statistic), 'lbuser[6]' (model). diff --git a/lib/iris/fileformats/um/_ff_replacement.py b/lib/iris/fileformats/um/_ff_replacement.py index ee40bacafa..52afe343c3 100644 --- a/lib/iris/fileformats/um/_ff_replacement.py +++ b/lib/iris/fileformats/um/_ff_replacement.py @@ -23,10 +23,10 @@ def um_to_pp(filename, read_data=False, word_depth=None): ---------- filename : str Specify the name of the FieldsFile. - read_data : bool, optional, default=read_data + read_data : bool, default=False Specify whether to read the associated PPField data within the FieldsFile. Default value is False. - word_depth : optional, default=None + word_depth : optional Returns ------- @@ -57,10 +57,10 @@ def load_cubes(filenames, callback, constraints=None, _loader_kwargs=None): ---------- filenames : list of filenames to load - callback : + callback : optional A function which can be passed on to :func:`iris.io.run_callback` - constraints : optional, default=None - _loader_kwargs : optional, default=None + constraints : optional + _loader_kwargs : optional Notes ----- diff --git a/lib/iris/fileformats/um/_optimal_array_structuring.py b/lib/iris/fileformats/um/_optimal_array_structuring.py index 64f4e8fad2..7d006ebeff 100644 --- a/lib/iris/fileformats/um/_optimal_array_structuring.py +++ b/lib/iris/fileformats/um/_optimal_array_structuring.py @@ -65,8 +65,7 @@ def optimal_array_structure(ordering_elements, actual_values_elements=None): structure. The order of this is significant, in that earlier elements get priority when associating dimensions with specific elements. - - actual_values_elements : iterable of (name, 1-d array), optional, default=None + actual_values_elements : iterable of (name, 1-d array), optional The 'real' values used to construct the result arrays, if different from 'ordering_elements'. Must contain all the same names (but not necessarily in the same order). diff --git a/lib/iris/pandas.py b/lib/iris/pandas.py index dd7d0d31fc..0c75208bd0 100644 --- a/lib/iris/pandas.py +++ b/lib/iris/pandas.py @@ -147,8 +147,8 @@ def as_cube( Example usage:: - as_cube(series, calendars={0: cf_units.CALENDAR_360_DAY}) - as_cube(data_frame, calendars={1: cf_units.CALENDAR_STANDARD}) + 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. @@ -583,8 +583,6 @@ 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. """ @@ -626,7 +624,7 @@ def as_data_frame( Parameters ---------- - cube: :class:`~iris.cube.Cube` + cube : :class:`~iris.cube.Cube` The :class:`~iris.cube.Cube` to be converted to a :class:`pandas.DataFrame`. copy : bool, default=True Whether the :class:`pandas.DataFrame` is a copy of the the Cube @@ -638,7 +636,7 @@ def as_data_frame( add_cell_measures : bool, default=False If True, add :attr:`~iris.cube.Cube.cell_measures` to the returned :class:`pandas.DataFrame`. - add_ancillary_variables: bool, default=False + add_ancillary_variables : bool, default=False If True, add :attr:`~iris.cube.Cube.ancillary_variables` to the returned :class:`pandas.DataFrame`. diff --git a/lib/iris/plot.py b/lib/iris/plot.py index 57e338c86a..a6c1a03b2d 100644 --- a/lib/iris/plot.py +++ b/lib/iris/plot.py @@ -257,14 +257,16 @@ def ticker_func(tick_location, _): def _invert_yaxis(v_coord, axes=None): """Inverts the y-axis of the current plot based on conditions. - * If the y-axis is already inverted we don't want to re-invert it. - * If v_coord is None then it will not have any attributes. - * If neither of the above are true then invert y if v_coord has - attribute 'positive' set to 'down'. + * If the y-axis is already inverted we don't want to re-invert it. + * If v_coord is None then it will not have any attributes. + * If neither of the above are true then invert y if v_coord has + attribute 'positive' set to 'down'. - Args: - - * v_coord - the coord to be plotted on the y-axis + Parameters + ---------- + v_coord : + The coord to be plotted on the y-axis + axes : optional """ axes = axes if axes else plt.gca() @@ -288,18 +290,20 @@ def _check_bounds_contiguity_and_mask(coord, data, atol=None, rtol=None): If a discontiguity occurs where the data is *not* masked, an error is raised. - Args: - coord: (iris.coord.Coord) - Coordinate the bounds of which will be checked for contiguity - data: (array) - Data of the the cube we are plotting - atol: - Absolute tolerance when checking the contiguity. Defaults to None. - If an absolute tolerance is not set, 1D coords are not checked (so - as to not introduce a breaking change without a major release) but - 2D coords are always checked, by calling - :meth:`iris.coords.Coord._discontiguity_in_bounds` with its default - tolerance. + Parameters + ---------- + coord : iris.coord.Coord + Coordinate the bounds of which will be checked for contiguity + data : array + Data of the the cube we are plotting + atol : optional + Absolute tolerance when checking the contiguity. Defaults to None. + If an absolute tolerance is not set, 1D coords are not checked (so + as to not introduce a breaking change without a major release) but + 2D coords are always checked, by calling + :meth:`iris.coords.Coord._discontiguity_in_bounds` with its default + tolerance. + rtol : optional """ kwargs = {} @@ -1049,21 +1053,20 @@ def _map_common(draw_method_name, arg_func, mode, cube, plot_defn, *args, **kwar def contour(cube, *args, **kwargs): """Draws contour lines based on the given Cube. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names, optional Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - See :func:`matplotlib.pyplot.contour` for details of other valid - keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.contour` for details of other valid + keyword arguments. Notes ----- @@ -1078,20 +1081,19 @@ def contour(cube, *args, **kwargs): def contourf(cube, *args, **kwargs): """Draws filled contours based on the given Cube. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names, optional Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - See :func:`matplotlib.pyplot.contourf` for details of other valid - keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.contourf` for details of other valid + keyword arguments. Notes ----- @@ -1182,12 +1184,13 @@ def default_projection(cube): def default_projection_extent(cube, mode=iris.coords.POINT_MODE): """Return the cube's extents ``(x0, x1, y0, y1)`` in its default projection. - Keyword arguments: - - * mode: Either ``iris.coords.POINT_MODE`` or ``iris.coords.BOUND_MODE`` - Triggers whether the extent should be representative of the cell - points, or the limits of the cell's bounds. - The default is iris.coords.POINT_MODE. + Parameters + ---------- + mode : + Either ``iris.coords.POINT_MODE`` or ``iris.coords.BOUND_MODE`` + Triggers whether the extent should be representative of the cell + points, or the limits of the cell's bounds. + The default is iris.coords.POINT_MODE. Notes ----- @@ -1296,24 +1299,21 @@ def horiz_plot(v_coord, orography, style_args): def outline(cube, coords=None, color="k", linewidth=None, axes=None): """Draws cell outlines based on the given Cube. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * color: None or mpl color + color : mpl color, default="k" The color of the cell outlines. If None, the matplotlibrc setting patch.edgecolor is used by default. - - * linewidth: None or number + linewidth : number, optional The width of the lines showing the cell outlines. If None, the default width in patch.linewidth in matplotlibrc is used. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`,voptional The axes to use for drawing. Defaults to the current axes if none provided. @@ -1343,25 +1343,23 @@ def pcolor(cube, *args, **kwargs): The cube must have either two 1-dimensional coordinates or two 2-dimensional coordinates with contiguous bounds to plot the cube against. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names, optional Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - * contiguity_tolerance: float + contiguity_tolerance : float, optional The absolute tolerance used when checking for contiguity between the bounds of the cells. Defaults to None. - - See :func:`matplotlib.pyplot.pcolor` for details of other valid - keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.pcolor` for details of other valid + keyword arguments. Notes ----- @@ -1382,24 +1380,22 @@ def pcolormesh(cube, *args, **kwargs): 2-dimensional coordinates with contiguous bounds to plot against each other. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names, optional Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - * contiguity_tolerance: float + contiguity_tolerance : float, optional The absolute tolerance used when checking for contiguity between the bounds of the cells. Defaults to None. - - See :func:`matplotlib.pyplot.pcolormesh` for details of other - valid keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.pcolormesh` for details of other + valid keyword arguments. Notes ----- @@ -1414,21 +1410,20 @@ def pcolormesh(cube, *args, **kwargs): def points(cube, *args, **kwargs): """Draws sample point positions based on the given Cube. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names, optional Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - See :func:`matplotlib.pyplot.scatter` for details of other valid - keyword arguments. + **kwargs :dict + See :func:`matplotlib.pyplot.scatter` for details of other valid + keyword arguments. Notes ----- @@ -1489,16 +1484,29 @@ def barbs(u_cube, v_cube, *args, **kwargs): Draws a barb plot from two vector component cubes. Triangles, full-lines and half-lines represent increments of 50, 10 and 5 respectively. - Args: - - * u_cube, v_cube : (:class:`~iris.cube.Cube`) + Parameters + ---------- + u_cube, v_cube : :class:`~iris.cube.Cube` u and v vector components. Must have same shape and units. If the cubes have geographic coordinates, the values are treated as true distance differentials, e.g. windspeeds, and *not* map coordinate vectors. The components are aligned with the North and East of the cube coordinate system. + coords : list of :class:`~iris.coords.Coord` or str, optional + Coordinates or coordinate names. Use the given coordinates as the axes + for the plot. The order of the given coordinates indicates which axis + to use for each, where the first element is the horizontal + axis of the plot and the second element is the vertical axis + of the plot. + axes : :class:`matplotlib.axes.Axes`, optional + Defaults to the current axes if none provided. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.barbs` for details of other valid + keyword arguments. - .. Note:: + Notes + ----- + .. note:: At present, if u_cube and v_cube have geographic coordinates, then they must be in a lat-lon coordinate system, though it may be a rotated one. @@ -1509,23 +1517,6 @@ def barbs(u_cube, v_cube, *args, **kwargs): the :meth:`~cartopy.crs.CRS.transform_points` method of :class:`cartopy.crs.CRS`. - Kwargs: - - * coords: (list of :class:`~iris.coords.Coord` or string) - Coordinates or coordinate names. Use the given coordinates as the axes - for the plot. The order of the given coordinates indicates which axis - to use for each, where the first element is the horizontal - axis of the plot and the second element is the vertical axis - of the plot. - - * axes: the :class:`matplotlib.axes.Axes` to use for drawing. - Defaults to the current axes if none provided. - - 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`. @@ -1542,16 +1533,30 @@ def barbs(u_cube, v_cube, *args, **kwargs): def quiver(u_cube, v_cube, *args, **kwargs): """Draws an arrow plot from two vector component cubes. - Args: - - * u_cube, v_cube : :class:`~iris.cube.Cube` + Parameters + ---------- + u_cube, v_cube : :class:`~iris.cube.Cube` u and v vector components. Must have same shape and units. If the cubes have geographic coordinates, the values are treated as true distance differentials, e.g. windspeeds, and *not* map coordinate vectors. The components are aligned with the North and East of the cube coordinate system. + coords : list of :class:`~iris.coords.Coord` or str, optional + Coordinates or coordinate names. Use the given coordinates as the axes + for the plot. The order of the given coordinates indicates which axis + to use for each, where the first element is the horizontal + axis of the plot and the second element is the vertical axis + of the plot. + axes : :class:`matplotlib.axes.Axes`, optional + The axes to use for drawing. Defaults to the current axes if none + provided. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.quiver` for details of other valid + keyword arguments. - .. Note:: + Notes + ----- + .. note:: At present, if u_cube and v_cube have geographic coordinates, then they must be in a lat-lon coordinate system, though it may be a rotated one. @@ -1562,24 +1567,6 @@ def quiver(u_cube, v_cube, *args, **kwargs): the :meth:`~cartopy.crs.CRS.transform_points` method of :class:`cartopy.crs.CRS`. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` or string - Coordinates or coordinate names. Use the given coordinates as the axes - for the plot. The order of the given coordinates indicates which axis - to use for each, where the first element is the horizontal - axis of the plot and the second element is the vertical axis - of the plot. - - * axes: :class:`matplotlib.axes.Axes` - The axes to use for drawing. Defaults to the current axes if none - provided. - - 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`. @@ -1596,6 +1583,22 @@ def quiver(u_cube, v_cube, *args, **kwargs): def plot(*args, **kwargs): """Draws a line plot based on the given cube(s) or coordinate(s). + Parameters + ---------- + axes : :class:`matplotlib.axes.Axes`, optional + The axes to use for drawing. Defaults to the current axes if none + provided. + **kwargs : dict, optional + 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`. + + Examples + -------- The first one or two arguments may be cubes or coordinates to plot. Each of the following is valid:: @@ -1619,20 +1622,6 @@ def plot(*args, **kwargs): # plot two 1d cubes against one-another plot(cube1, cube2) - Kwargs: - - * axes: :class:`matplotlib.axes.Axes` - The axes to use for drawing. Defaults to the current axes if none - provided. - - 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( @@ -1647,22 +1636,18 @@ def plot(*args, **kwargs): def scatter(x, y, *args, **kwargs): """Draws a scatter plot based on the given cube(s) or coordinate(s). - Args: - - * x: :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` + Parameters + ---------- + x : :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` A cube or a coordinate to plot on the x-axis. - - * y: :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` + y : :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` A cube or a coordinate to plot on the y-axis. - - Kwargs: - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - See :func:`matplotlib.pyplot.scatter` for details of additional - valid keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.scatter` for details of additional + valid keyword arguments. Notes ----- @@ -1683,25 +1668,20 @@ def scatter(x, y, *args, **kwargs): def fill_between(x, y1, y2, *args, **kwargs): """Plot y1 and y2 against x, and fills the space between them. - Args: - - * x: :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` + Parameters + ---------- + x : :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` A cube or a coordinate to plot on the x-axis. - - * y1: :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` + y1 : :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` First cube or a coordinate to plot on the y-axis. - - * y2: :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` + y2 : :class:`~iris.cube.Cube` or :class:`~iris.coords.Coord` Second cube or a coordinate to plot on the y-axis. - - Kwargs: - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - See :func:`matplotlib.pyplot.fill_between` for details of additional valid - keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.fill_between` for details of additional valid + keyword arguments. Notes ----- @@ -1724,18 +1704,18 @@ def fill_between(x, y1, y2, *args, **kwargs): def hist(x, *args, **kwargs): """Compute and plot a histogram. - Args: - - * x: + Parameters + ---------- + x : A :class:`~iris.cube.Cube`, :class:`~iris.coords.Coord`, :class:`~iris.coords.CellMeasure`, or :class:`~iris.coords.AncillaryVariable` that will be used as the values that will be used to create the histogram. Note that if a coordinate is given, the points are used, ignoring the bounds. - - See :func:`matplotlib.pyplot.hist` for details of additional valid - keyword arguments. + **kwargs : dict, optional + See :func:`matplotlib.pyplot.hist` for details of additional valid + keyword arguments. Notes ----- @@ -1763,27 +1743,20 @@ def symbols(x, y, symbols, size, axes=None, units="inches"): See :mod:`iris.symbols` for available symbols. - Args: - - * x: iterable + Parameters + ---------- + x : iterable The x coordinates where the symbols will be plotted. - - * y: iterable + y : iterable The y coordinates where the symbols will be plotted. - - * symbols: iterable + symbols : iterable The symbols (from :mod:`iris.symbols`) to plot. - - * size: float + size : float The symbol size in `units`. - - Kwargs: - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. - - * units: ['inches', 'points'] + units : ['inches', 'points'], default="inches" The unit for the symbol size. Notes @@ -1835,17 +1808,13 @@ def citation(text, figure=None, axes=None): Places an anchored text citation in the bottom right hand corner of the plot. - Args: - - * text: str + Parameters + ---------- + text : str Citation text to be plotted. - - Kwargs: - - * figure::class:`matplotlib.figure.Figure` + figure : :class:`matplotlib.figure.Figure`, optional Target figure instance. Defaults to the current figure if none provided. - - * axes: :class:`matplotlib.axes.Axes` + axes : :class:`matplotlib.axes.Axes`, optional The axes to use for drawing. Defaults to the current axes if none provided. diff --git a/lib/iris/quickplot.py b/lib/iris/quickplot.py index 1c1eaf5a56..14380019f3 100644 --- a/lib/iris/quickplot.py +++ b/lib/iris/quickplot.py @@ -198,19 +198,17 @@ def contourf(cube, *args, **kwargs): def outline(cube, coords=None, color="k", linewidth=None, axes=None): """Draws cell outlines on a labelled plot based on the given Cube. - Kwargs: - - * coords: list of :class:`~iris.coords.Coord` objects or coordinate names + Parameters + ---------- + coords : list of :class:`~iris.coords.Coord` objects or coordinate names, optional Use the given coordinates as the axes for the plot. The order of the given coordinates indicates which axis to use for each, where the first element is the horizontal axis of the plot and the second element is the vertical axis of the plot. - - * color: None or mpl color + color : str, default="k" The color of the cell outlines. If None, the matplotlibrc setting patch.edgecolor is used by default. - - * linewidth: None or number + linewidth : number, optional The width of the lines showing the cell outlines. If None, the default width in patch.linewidth in matplotlibrc is used.