diff --git a/docs/src/user_manual/explanation/temporal_coordinates.rst b/docs/src/user_manual/explanation/temporal_coordinates.rst index c85980d700..a680e4899c 100644 --- a/docs/src/user_manual/explanation/temporal_coordinates.rst +++ b/docs/src/user_manual/explanation/temporal_coordinates.rst @@ -12,8 +12,8 @@ Temporal Coordinates .. readingtime:: -Here we provide some handy patterns and tips for working with temporal -coordinates i.e., ``time`` coordinates. +This page provides practical patterns and tips for working with temporal +coordinates, that is, ``time`` coordinates. Introduction @@ -46,10 +46,10 @@ individual components: * ``time`` - This is the *name* of the coordinate. The name is derived firstly from the coordinate ``standard_name``. Failing that, the ``long_name`` is used, otherwise the ``var_name`` before defaulting to a value of ``unknown``. -* ``hours since 1970-01-01 00:00:00`` - This tells us the coordinates temporal +* ``hours since 1970-01-01 00:00:00`` - This tells us the coordinate's temporal units of measure (``hours``) relative to its epoch (``1970-01-01 00:00:00``). * ``[...]`` - Represents the temporal ``points``, the values of which are not - displayed in this shortend summary. However, note that if the coordinate had + displayed in this shortened summary. However, if the coordinate had ``bounds`` this would be represented as ``[...]+bounds``. * ``shape(6,)`` - Tells us that the coordinate has one dimension containing ``6`` points. @@ -60,7 +60,7 @@ We can easily inspect the ``points`` contained within our ``tcoord``:: array([347926.16666667, 347926.33333333, 347926.5 , 347926.66666667, 347926.83333333, 347927. ]) -However, these raw values are pretty meaningless on their own. As hinted to above, +However, these raw values are difficult to interpret on their own. As noted above, these ``points`` are measured in units of ``hours`` relative to the epoch ``1970-01-01 00:00:00``. The metadata defining all this information is available from the ``units`` attribute of the :class:`coordinate `:: @@ -74,7 +74,7 @@ from the ``units`` attribute of the :class:`coordinate `:: their ``units``. In this case our ``tcoord`` has a ``standard`` (or ``gregorian``) calendar and -we can convert its hard to understand raw values into meaningful **date**/**time** +we can convert its hard-to-interpret raw values into meaningful **date**/**time** (``YYYY-MM-DD HH:MM:SS``) representations relative to its ``calendar`` and epoch:: @@ -87,8 +87,8 @@ epoch:: dtype: float64 standard_name: 'time' -Now we can clearly see that our ``tcoord`` time interval commences on ``2009-09-09`` -at ``22:10:00`` with samples that are each ``10`` minutes apart. +Now we can clearly see that the ``tcoord`` interval starts on ``2009-09-09`` at +``22:10:00`` with samples spaced ``10`` minutes apart. Note that our ``tcoord`` does not have any ``bounds`` associated with it:: @@ -127,7 +127,7 @@ its :meth:`~iris.coords.Coord.guess_bounds` method:: Indexing -------- -:class:`Coordinates ` are *first-class-citizens* and may be +:class:`Coordinates ` are *first-class citizens* and may be indexed akin to other ``python`` built-in types such as `lists`_ or `tuples`_. As an example, let's index the **last** sample of the ``tcoord``:: @@ -157,8 +157,8 @@ In the above example, indexing the ``tcoord`` yields a scalar A **lighter-weight** indexing solution is to leverage the :meth:`~iris.coords.Coord.cell` method instead:: - >> tcell = tcoord.cell(-1) - >> tcell + >>> tcell = tcoord.cell(-1) + >>> tcell Cell(point=cftime.DatetimeGregorian(2009, 9, 9, 23, 0, 0, 0, has_year_zero=False), bound=(cftime.DatetimeGregorian(2009, 9, 9, 22, 55, 0, 0, has_year_zero=False), cftime.DatetimeGregorian(2009, 9, 9, 23, 5, 0, 0, has_year_zero=False))) This returns a :class:`~iris.coords.Cell` object rather than a @@ -206,7 +206,7 @@ To convert these ``points`` and ``bounds`` into equivalent ``tcell`` Iteration --------- -Akin to :ref:`indexing `, we can also +As with :ref:`indexing `, we can also iterate over :class:`coordinates ` just as you would naturally with other ``python`` built-in types such as `lists`_ or `tuples`_. @@ -302,15 +302,14 @@ Depending on your workflow, you may wish to deal directly with either :class:`~datetime.datetime` objects rather than raw temporal values within the ``points``/``bounds`` of a :class:`coordinate `. -There are several different ways to convert raw temporal values, so let's -consolidating our understanding and enumerate the various options -available to us. +There are several ways to convert raw temporal values, so let's consolidate +our understanding and enumerate the options available to us. ``cftime`` ~~~~~~~~~~ -The direct approach is to leverage either of the :meth:`~iris.coords.Coord.cell` -or :meth:`~iris.coords.Coord.cells` methods. Both of which provide one or more +The direct approach is to use either :meth:`~iris.coords.Coord.cell` +or :meth:`~iris.coords.Coord.cells`. Both provide one or more :class:`~iris.coords.Cell` objects. By default a temporal :class:`~iris.coords.Cell` will always contain @@ -451,7 +450,7 @@ For example: Native ``matplotlib`` only supports ``python`` :class:`~datetime.datetime` compatible objects. -Note that, :mod:`iris.plot` and :mod:`iris.quickplot` provide the convenience +Note that :mod:`iris.plot` and :mod:`iris.quickplot` provide the convenience of also understanding ``iris`` objects, such as coordinates and cubes. However they also use the `nc-time-axis`_ package, which provides support for a `cftime`_ axis in `matplotlib`_. diff --git a/docs/src/user_manual/tutorial/plotting_examples/cube_brewer_contourf.py b/docs/src/user_manual/tutorial/plotting_examples/cube_brewer_contourf.py index 94692c924c..af6f05dba7 100644 --- a/docs/src/user_manual/tutorial/plotting_examples/cube_brewer_contourf.py +++ b/docs/src/user_manual/tutorial/plotting_examples/cube_brewer_contourf.py @@ -1,6 +1,6 @@ """Plot a cube with a Brewer colour palette using iris.quickplot.contourf().""" -import matplotlib.cm as mpl_cm +import matplotlib as mpl import matplotlib.pyplot as plt import iris @@ -10,7 +10,7 @@ temperature_cube = iris.load_cube(fname) # Load a Cynthia Brewer palette. -brewer_cmap = mpl_cm.get_cmap("brewer_OrRd_09") +brewer_cmap = mpl.colormaps["brewer_OrRd_09"] # Draw the contours, with n-levels set for the map colours (9). # NOTE: needed as the map is non-interpolated, but matplotlib does not provide diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index f50657fc04..87180d7c39 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -132,10 +132,16 @@ This document explains the changes made to Iris for this release :func:`iris.analysis.cartography.area_weights` requires 1-dimensional lat and lon coordinates on the input :class:`~iris.cube.Cube`. (:pull:`7118`) +#. :user:`bjlittle` Added an explanation section for :ref:`explanation-temporal-coordinates`. + (:pull:`7131`) + #. :user:`bjlittle` Added the custom `sphinx`_ ``readingtime`` directive to automatically estimate the audiance reading time of a page and render a branded banner in-situ. (:pull:`7150`) +#. :user:`bjlittle` Updated the :ref:`explanation-temporal-coordinates` section. + (:pull:`7159`) + 💼 Internal ===========