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/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.