From 10eae0b623bec0235ffd128e1ccfc71818deeec1 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Fri, 16 Feb 2024 14:41:07 +0000 Subject: [PATCH 1/3] regrid docs update --- docs/src/conf.py | 3 +- .../further_topics/which_regridder_to_use.rst | 297 ++++++++++-------- 2 files changed, 168 insertions(+), 132 deletions(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index a87a8a46a6..ee168a1806 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -193,7 +193,8 @@ def _dotv(version): # sphinx.ext.todo configuration ----------------------------------------------- # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html -todo_include_todos = True +todo_include_todos = False +todo_emit_warnings = True # api generation configuration autodoc_member_order = "alphabetical" diff --git a/docs/src/further_topics/which_regridder_to_use.rst b/docs/src/further_topics/which_regridder_to_use.rst index 542174486b..4c1b8864bb 100644 --- a/docs/src/further_topics/which_regridder_to_use.rst +++ b/docs/src/further_topics/which_regridder_to_use.rst @@ -1,11 +1,13 @@ +.. include:: ../common_links.inc + .. _which_regridder_to_use: ====================== Which Regridder to Use ====================== -This section compares all the regridding schemes which exist in iris, and -externally in iris-esmf-regrid with a view to helping you to choose the right +This section compares all the regridding schemes which exist in `Iris`_, and +externally in `iris-esmf-regrid`_ with a view to helping you to choose the right regridder for your workflow. The choice of regridder is usually limited by the kind of data you are going from and to, but there are also factors of performance and numerical accuracy to consider. This section @@ -22,131 +24,145 @@ Regridder Comparison We will highlight here some of the properties of each regridder in a table of the following form: -+-----------------+-------------------------------------------------------+ -| API | Link to API documentation. | -+-----------------+-------------------------------------------------------+ -| Method | The type of algorithm used to calculate the result. | -| | See section on `comparing methods`_. | -+-----------------+-------------------------------------------------------+ -| Source grid | The type of coordinates required on the source cube. | -+-----------------+-------------------------------------------------------+ -| Target grid | The type of coordinates required on the target cube. | -+-----------------+-------------------------------------------------------+ -| Coord system | The type of coordinate system required on the | -| | source/target coordinates. | -+-----------------+-------------------------------------------------------+ -| Lazy regridding | If the result is calculated lazily. | -| | See :doc:`real_and_lazy_data` | -+-----------------+-------------------------------------------------------+ -| Weights caching | See `regridder performance`_. | -+-----------------+-------------------------------------------------------+ -| Notes | Additional details. | -+-----------------+-------------------------------------------------------+ ++-----------------+-----------------------------------------------------------+ +| **API** | Link to API documentation. | ++-----------------+-----------------------------------------------------------+ +| **Method** | The type of algorithm used to calculate the result. | +| | See section on `comparing methods`_. | ++-----------------+-----------------------------------------------------------+ +| **Source Grid** | The type of **coordinates** required on the ``src`` cube. | ++-----------------+-----------------------------------------------------------+ +| **Target Grid** | The type of **coordinates** required on the ``tgt`` cube. | ++-----------------+-----------------------------------------------------------+ +| **Coordinate | The type of **coordinate system** required on the | +| System** | ``src``/``tgt`` cube coordinates. | ++-----------------+-----------------------------------------------------------+ +| **Lazy | If the result is calculated lazily. See | +| Regridding** | :doc:`real and lazy data `.| ++-----------------+-----------------------------------------------------------+ +| **Weights | See `regridder performance`_. | +| Caching** | | ++-----------------+-----------------------------------------------------------+ +| **Notes** | Additional details. | ++-----------------+-----------------------------------------------------------+ AreaWeighted ------------ -+-----------------+----------------------------------------------------+ -| API | :class:`~iris.analysis.AreaWeighted` | -+-----------------+----------------------------------------------------+ -| Method | Conservative | -+-----------------+----------------------------------------------------+ -| Source grid | Pair of 1D lat/lon coordinates, must have bounds. | -+-----------------+----------------------------------------------------+ -| Target grid | Pair of 1D lat/lon coordinates, must have bounds. | -+-----------------+----------------------------------------------------+ -| Coord system | Must be equal on source and target, may be None. | -+-----------------+----------------------------------------------------+ -| Lazy regridding | True | -+-----------------+----------------------------------------------------+ -| Weights caching | False | -+-----------------+----------------------------------------------------+ -| Notes | Supports masked data with ``mdtol`` argument. | -| | See `area conservation`_. | -+-----------------+----------------------------------------------------+ ++-----------------+--------------------------------------------------------+ +| **API** | :class:`~iris.analysis.AreaWeighted` | ++-----------------+--------------------------------------------------------+ +| **Method** | Conservative | ++-----------------+--------------------------------------------------------+ +| **Source Grid** | Pair of 1D lat/lon coordinates, must have bounds. | ++-----------------+--------------------------------------------------------+ +| **Target Grid** | Pair of 1D lat/lon coordinates, must have bounds. | ++-----------------+--------------------------------------------------------+ +| **Coordinate | Must be equal on ``src`` and ``tgt``, may be ``None``. | +| System** | | ++-----------------+--------------------------------------------------------+ +| **Lazy | ``True`` | +| Regridding** | | ++-----------------+--------------------------------------------------------+ +| **Weights | ``False`` | +| Caching** | | ++-----------------+--------------------------------------------------------+ +| **Notes** | Supports masked data with ``mdtol`` argument. | +| | See `area conservation`_. | ++-----------------+--------------------------------------------------------+ Linear ------ -+-----------------+----------------------------------------------------+ -| API | :class:`~iris.analysis.Linear` | -+-----------------+----------------------------------------------------+ -| Method | Linear | -+-----------------+----------------------------------------------------+ -| Source grid | Pair of 1D lat/lon coordinates. | -+-----------------+----------------------------------------------------+ -| Target grid | Pair of 1D lat/lon coordinates. | -+-----------------+----------------------------------------------------+ -| Coord system | May be present on both src and tgt or both be None.| -| | May be different. | -+-----------------+----------------------------------------------------+ -| Lazy regridding | True | -+-----------------+----------------------------------------------------+ -| Weights caching | False | -+-----------------+----------------------------------------------------+ -| Notes | Supports extrapolation outside source data bounds. | -+-----------------+----------------------------------------------------+ ++-----------------+----------------------------------------------------------------+ +| **API** | :class:`~iris.analysis.Linear` | ++-----------------+----------------------------------------------------------------+ +| **Method** | Linear | ++-----------------+----------------------------------------------------------------+ +| **Source Grid** | Pair of 1D lat/lon coordinates. | ++-----------------+----------------------------------------------------------------+ +| **Target Grid** | Pair of 1D lat/lon coordinates. | ++-----------------+----------------------------------------------------------------+ +| **Coordinate | May be present on both ``src`` and ``tgt`` or both be ``None``.| +| System** | May be different. | ++-----------------+----------------------------------------------------------------+ +| **Lazy | ``True`` | +| Regridding** | | ++-----------------+----------------------------------------------------------------+ +| **Weights | ``False`` | +| Caching** | | ++-----------------+----------------------------------------------------------------+ +| **Notes** | Supports extrapolation outside source data bounds. | ++-----------------+----------------------------------------------------------------+ Nearest ------- -+-----------------+----------------------------------------------------+ -| API | :class:`~iris.analysis.Nearest` | -+-----------------+----------------------------------------------------+ -| Method | Nearest (destination to source) | -+-----------------+----------------------------------------------------+ -| Source grid | Pair of 1D lat/lon coordinates. | -+-----------------+----------------------------------------------------+ -| Target grid | Pair of 1D lat/lon coordinates. | -+-----------------+----------------------------------------------------+ -| Coord system | May be present on both src and tgt or both be None.| -| | May be different. | -+-----------------+----------------------------------------------------+ -| Lazy regridding | True | -+-----------------+----------------------------------------------------+ -| Weights caching | False | -+-----------------+----------------------------------------------------+ ++-----------------+----------------------------------------------------------------+ +| **API** | :class:`~iris.analysis.Nearest` | ++-----------------+----------------------------------------------------------------+ +| **Method** | Nearest (destination to source) | ++-----------------+----------------------------------------------------------------+ +| **Source Grid** | Pair of 1D lat/lon coordinates. | ++-----------------+----------------------------------------------------------------+ +| **Target Grid** | Pair of 1D lat/lon coordinates. | ++-----------------+----------------------------------------------------------------+ +| **Coordinate | May be present on both ``src`` and ``tgt`` or both be ``None``.| +| System** | May be different. | ++-----------------+----------------------------------------------------------------+ +| **Lazy | ``True`` | +| Regridding** | | ++-----------------+----------------------------------------------------------------+ +| **Weights | ``False`` | +| Caching** | | ++-----------------+----------------------------------------------------------------+ UnstructuredNearest ------------------- +-----------------+----------------------------------------------------+ -| API | :class:`~iris.analysis.UnstructuredNearest` | +| **API** | :class:`~iris.analysis.UnstructuredNearest` | +-----------------+----------------------------------------------------+ -| Method | Nearest (destination to source) | +| **Method** | Nearest (destination to source) | +-----------------+----------------------------------------------------+ -| Source grid | Pair of lat/lon coordinates with any dimensionality| -| | (e.g. 1D or 2D). Must be associated to the same | +| **Source Grid** | Pair of lat/lon coordinates with any dimensionality| +| | (e.g., 1D or 2D). Must be associated to the same | | | axes on the source cube. | +-----------------+----------------------------------------------------+ -| Target grid | Pair of 1D lat/lon coordinates. | +| **Target Grid** | Pair of 1D lat/lon coordinates. | +-----------------+----------------------------------------------------+ -| Coord system | Must be equal on source and target, may be None. | +| **Coordinate | Must be equal on ``src`` and ``tgt``, may be | +| System** | ``None``. | +-----------------+----------------------------------------------------+ -| Lazy regridding | False | +| **Lazy | ``False`` | +| Regridding** | | +-----------------+----------------------------------------------------+ -| Weights caching | False | +| **Weights | ``False`` | +| Caching** | | +-----------------+----------------------------------------------------+ PointInCell ----------- +-----------------+----------------------------------------------------+ -| API | :class:`~iris.analysis.PointInCell` | +| **API** | :class:`~iris.analysis.PointInCell` | +-----------------+----------------------------------------------------+ -| Method | Point in cell | +| **Method** | Point in cell | +-----------------+----------------------------------------------------+ -| Source grid | Pair of lat/lon coordinates with any dimensionality| -| | (e.g. 1D or 2D). Must be associated to the same | +| **Source Grid** | Pair of lat/lon coordinates with any dimensionality| +| | (e.g., 1D or 2D). Must be associated to the same | | | axes on the source cube. | +-----------------+----------------------------------------------------+ -| Target grid | Pair of 1D lat/lon coordinates, must have bounds. | +| **Target Grid** | Pair of 1D lat/lon coordinates, must have bounds. | +-----------------+----------------------------------------------------+ -| Coord system | Must be equal on source and target, may be None. | +| **Coordinate | Must be equal on ``srs`` and ``tgt``, may be | +| System** | ``None``. | +-----------------+----------------------------------------------------+ -| Lazy regridding | False | +| **Lazy | ``False`` | +| Regridding** | | +-----------------+----------------------------------------------------+ -| Weights caching | True | +| **Weights | ``True`` | +| Caching** | | +-----------------+----------------------------------------------------+ External Regridders @@ -156,28 +172,31 @@ ESMFAreaWeighted ---------------- +-----------------+-------------------------------------------------------------------------+ -| API | :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFAreaWeighted` | +| **API** | :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFAreaWeighted` | +-----------------+-------------------------------------------------------------------------+ -| Method | Conservative | +| **Method** | Conservative | +-----------------+-------------------------------------------------------------------------+ -| Source grid | May be either: | +| **Source Grid** | May be either: | | | | | | - A pair of 1D x/y coordinates on different axes. Must have bounds. | | | - A pair of 2D x/y coordinates on the same axes. Must have bounds. | -| | - An unstructured mesh located on faces. | +| | - An unstructured mesh located on cell faces. | +-----------------+-------------------------------------------------------------------------+ -| Target grid | Any of the above. may be a different type to src grid. | +| **Target Grid** | Any of the above. May be a different type to ``src`` grid. | +-----------------+-------------------------------------------------------------------------+ -| Coord system | Source and target grid may have any coord system or None. | +| **Coordinate | ``src`` and ``tgt`` grid may have any coordinate system or ``None``. | +| System** | | +-----------------+-------------------------------------------------------------------------+ -| Lazy regridding | True | +| **Lazy | ``True`` | +| Regridding** | | +-----------------+-------------------------------------------------------------------------+ -| Weights caching | True | +| **Weights | ``True`` | +| Caching** | | +-----------------+-------------------------------------------------------------------------+ -| Notes | Supports masked data with ``mdtol`` argument (see `area conservation`_).| +| **Notes** | Supports masked data with ``mdtol`` argument (see `area conservation`_).| | | Differs numerically to :class:`~iris.analysis.AreaWeighted` due to | | | representing edges as great circle arcs rather than lines of | -| | latitude/longitude. This causes less difference at higher resulotions. | +| | latitude/longitude. This causes less difference at higher resolutions. | | | This can be mitigated somewhat by using the | | | ``src_resolution`` / ``tgt_resolution`` arguments. | +-----------------+-------------------------------------------------------------------------+ @@ -186,46 +205,52 @@ ESMFBilinear ------------ +-----------------+---------------------------------------------------------------------+ -| API | :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFBilinear` | +| **API** | :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFBilinear` | +-----------------+---------------------------------------------------------------------+ -| Method | Linear | +| **Method** | Linear | +-----------------+---------------------------------------------------------------------+ -| Source grid | May be either: | +| **Source Grid** | May be either: | | | | | | - A pair of 1D x/y coordinates on different axes. | | | - A pair of 2D x/y coordinates on the same axes. | -| | - An unstructured mesh located on faces. | +| | - An unstructured mesh located on cell faces. | +-----------------+---------------------------------------------------------------------+ -| Target grid | Any of the above. may be a different type to src grid. | +| **Target Grid** | Any of the above. May be a different type to ``src`` grid. | +-----------------+---------------------------------------------------------------------+ -| Coord system | Source and target grid may have any coord system or None. | +| **Coordinate | ``src`` and ``tgt`` grid may have any coordinate system or ``None``.| +| System** | | +-----------------+---------------------------------------------------------------------+ -| Lazy regridding | True | +| **Lazy | ``True`` | +| Regridding** | | +-----------------+---------------------------------------------------------------------+ -| Weights caching | True | +| **Weights | ``True`` | +| Caching** | | +-----------------+---------------------------------------------------------------------+ ESMFNearest ----------- +-----------------+---------------------------------------------------------------------+ -| API | :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFNearest` | +| **API** | :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFNearest` | +-----------------+---------------------------------------------------------------------+ -| Method | Nearest (destination to source) | +| **Method** | Nearest (destination to source) | +-----------------+---------------------------------------------------------------------+ -| Source grid | May be either: | +| **Source Grid** | May be either: | | | | | | - A pair of 1D x/y coordinates on different axes. | | | - A pair of 2D x/y coordinates on the same axes. | -| | - An unstructured mesh located on faces. | +| | - An unstructured mesh located on cell faces | +-----------------+---------------------------------------------------------------------+ -| Target grid | Any of the above. may be a different type to src grid. | +| **Target Grid** | Any of the above. May be a different type to ``src`` grid. | +-----------------+---------------------------------------------------------------------+ -| Coord system | Source and target grid may have any coord system or None. | +| **Coordinate | ``src`` and ``tgt`` grid may have any coordinate system or ``None``.| +| System** | | +-----------------+---------------------------------------------------------------------+ -| Lazy regridding | True | +| **Lazy | ``True`` | +| Regridding** | | +-----------------+---------------------------------------------------------------------+ -| Weights caching | True | +| **Weights | ``True`` | +| Caching** | | +-----------------+---------------------------------------------------------------------+ .. _comparing methods: @@ -250,7 +275,7 @@ what it means to be *conservative* can be found in the section on Linear ------ -Good for approximating data represented at precise points in space and in +Good for approximating data represented at *precise points* in space and in cases where it is desirable for the resulting data to be smooth. For more detail, see the section on `regridder smoothness`_. @@ -259,7 +284,7 @@ Nearest Tends to be the fastest regridding method. Ensures each resulting data value represents a data value in the source. Good in cases where averaging is -inappropriate, e.g. for discontinuous data. +inappropriate, e.g., for discontinuous data. Point in cell ------------- @@ -289,17 +314,19 @@ Area weighted regridding schemes such as :class:`~iris.analysis.AreaWeighted` an :class:`~iris-esmf-regrid:esmf_regrid.schemes.ESMFAreaWeighted` use *conservative* regridding schemes. The property which these regridders *conserve* is the global area weighted average of the data (or equivalently, -the area weighted sum). More precisely, this means that: - When regridding from a source cube to a target cube defined over the same area - (e.g. the entire globe), assuming there are no masked data points, the area - weighted average (weighted by the area covered by each data point) of the source - cube ought to be equal (within minor tolerances) to the area weighted average of - the result. +the area weighted sum). More precisely, this means that:: + + When regridding from a source cube to a target cube defined + over the same area (e.g., the entire globe), assuming there + are no masked data points, the area weighted average + (weighted by the area covered by each data point) of the + source cube ought to be equal (within minor tolerances) + to the area weighted average of the result. This property will be particularly important to consider if you are intending to calculate global properties such as average temperature or total rainfall over a given area. It may be less important if you are only interested in local behaviour, -e.g. temperature at particular locations. +e.g., temperature at particular locations. When there are masked points in your data, the same global conservative properties no longer strictly hold. This is because the area which the unmasked points in the @@ -309,7 +336,7 @@ around the source mask which will be masked in the result and therefore unaccoun for in the area weighted average calculation. Conversely, with the keyword argument ``mdtol=1`` there will be an unmasked area in the result that is masked in the source. This may be particularly important if you are intending to calculate properties -which depend area e.g. calculating the total global rainfall based on data in units +which depend area e.g., calculating the total global rainfall based on data in units of ``kg m-2`` as an area weighted sum. With ``mdtol=0`` this will consistently underestimate this total and with ``mdtol=1`` will consistently overestimate. This can be somewhat mitigated with a choice of ``mdtol=0.5``, but you should still be aware of @@ -318,7 +345,9 @@ context dependent and there wil likely be occasions where a choice of ``mdtol=0` ``mdtol=1`` is more suitable. The important thing is to *know your data, know what* *you're doing with your data and know how your regridder fits in this process*. -#TODO: add worked example +.. todo:: + + add worked example .. _regridder smoothness: @@ -352,7 +381,9 @@ a given source point would have the same value and there would be a steep differ target points near the cell boundary. For linear regridding however, the resulting data will vary smoothly. -#TODO: add worked example +.. todo:: + + add worked example Consistency ----------- @@ -361,9 +392,11 @@ be manageable when contained within context of a particular workflow, you should not to compare data which has been regrid with different regridding methods as the artefacts of that regridding method may dominate the underlying differences. -#TODO: add worked example +.. todo:: -It should also be noted that some implementations of the *same method* (e.g. + add worked example + +It should also be noted that some implementations of the *same method* (e.g., :class:`~iris.analysis.Nearest` and :class:`~iris.analysis.UnstructuredNearest`) may differ slightly and so may yield slightly different results when applied to equivalent data. However this difference will be significantly less than the difference between @@ -384,4 +417,6 @@ Generally, the *prepare* step is the more expensive of the two. It is better to repeating this step unnecessarily. This can be done by *reusing* a regridder, as described in the :ref:`user guide `. -#TODO: add benchmarks - note the iris and iris-esmf-regrid version +.. todo:: + + add benchmarks - note the iris and iris-esmf-regrid version From 4ad782f891645fb65e4e03c9c547483d78d81528 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Fri, 16 Feb 2024 15:24:38 +0000 Subject: [PATCH 2/3] set todo_emit_warnings = False --- docs/src/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/conf.py b/docs/src/conf.py index ee168a1806..28eb8a6e4c 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -194,7 +194,7 @@ def _dotv(version): # sphinx.ext.todo configuration ----------------------------------------------- # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html todo_include_todos = False -todo_emit_warnings = True +todo_emit_warnings = False # api generation configuration autodoc_member_order = "alphabetical" From 7620737a19fa028e23a30fde7a8f9a318e07599f Mon Sep 17 00:00:00 2001 From: Bill Little Date: Fri, 16 Feb 2024 15:31:50 +0000 Subject: [PATCH 3/3] add linkcheck broken url --- docs/src/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/conf.py b/docs/src/conf.py index 28eb8a6e4c..f5a95bf902 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -398,6 +398,7 @@ def _dotv(version): "https://biggus.readthedocs.io/", "https://stickler-ci.com/", "https://twitter.com/scitools_iris", + "https://stackoverflow.com/questions/tagged/python-iris", ] # list of sources to exclude from the build.