Merge pull request #219 from jukent/taylor-robust

Documentation improvement for TaylorDiagram class and set_titles_and_labels

.gitignore

@@ -11,3 +11,6 @@ docs/_build/
 dist/
 .eggs/
 *egg-info
+
+# IDEs
+settings.json

docs/examples/taylor.ipynb

@@ -57,7 +57,7 @@
     "\n",
     "# Draw diagonal dashed lines from origin to correlation values\n",
     "# Also enforces proper X-Y ratio\n",
-    "taylor.add_xgrid(np.array([0.6, 0.9]))\n",
+    "taylor.add_corr_grid(np.array([0.6, 0.9]))\n",
     "\n",
     "# Add models to Taylor diagram\n",
     "taylor.add_model_set(a_sdev,\n",

docs/release-notes.rst

@@ -5,6 +5,19 @@
 Release Notes
 =============
 
+v2024.04.1 (April 1, 2024)
+------------------------------
+This release ...
+
+Documentation
+^^^^^^^^^^^^^
+* Document known issue with `suptitle` argument of  ``set_titles_and_labels`` and Cartopy plots by `Julia Kent`_ in (:pr:`219`)
+
+Deprecations
+^^^^^^^^^^
+* Pending deprecation warnings added for ``TaylorDiagram`` methods ``add_xgrid`` and ``add_ygrid`` which are changing to the new ``add_corr_grid`` and ``add_std_grid`` by `Julia Kent`_ in (:pr:`219`)
+
+
 v2024.02.1 (February 28, 2024)
 ------------------------------
 This release changes to implicit namespace packaging and addresses a bug in the Taylor diagram functionality when disabling ``annotate_on``.

src/geocat/viz/taylor.py

@@ -1,5 +1,5 @@
 """Taylor Diagrams."""
-
+import warnings
 import typing
 
 import numpy as np
@@ -44,6 +44,11 @@ class TaylorDiagram(object):
     stdLevel : list
         Optional list of tick locations for stddev axis
 
+    Notes
+    -----
+    Rendering of Taylor Diagrams looks best with a figure that is at least 10x10 inches. If you  make your figure size too small,
+    legends, lagels, and other text items might overlap in undesired ways.
+
     References
     ----------
     - https://validate-climate-model-validation.readthedocs.io/en/latest/_modules/validate/taylor.html
@@ -377,13 +382,13 @@ def add_model_set(self,
 
         return modelTexts, modelset
 
-    def add_xgrid(self,
-                  arr: typing.Union[xr.DataArray, np.ndarray, list, float],
-                  color: str = 'lightgray',
-                  linestyle=(0, (9, 5)),
-                  linewidth: float = 0.5,
-                  **kwargs):
-        """Add gridlines to the X axis (correlation) specified by array *arr*
+    def add_corr_grid(self,
+                      arr: typing.Union[xr.DataArray, np.ndarray, list, float],
+                      color: str = 'lightgray',
+                      linestyle=(0, (9, 5)),
+                      linewidth: float = 0.5,
+                      **kwargs):
+        """Add gridlines to the correlation axis specified by array *arr*
 
         Parameters
         ----------
@@ -411,7 +416,7 @@ def add_xgrid(self,
         --------
         All usage examples are within the GeoCAT-Examples Gallery. To see more usage cases, search the function on the `website <https://geocat-examples.readthedocs.io/en/latest/index.html>`_.
 
-        - `NCL_taylor_2.py <https://geocat-examples.readthedocs.io/en/latest/gallery/TaylorDiagrams/NCL_taylor_2.html?highlight=add_xgrid>`_
+        - `NCL_taylor_2.py <https://geocat-examples.readthedocs.io/en/latest/gallery/TaylorDiagrams/NCL_taylor_2.html?highlight=add_corr_grid>`_
         """
 
         for value in arr:
@@ -423,14 +428,34 @@ def add_xgrid(self,
                            linewidth=linewidth,
                            **kwargs)
 
-    def add_ygrid(self,
+    def add_xgrid(self,
                   arr: typing.Union[xr.DataArray, np.ndarray, list, float],
                   color: str = 'lightgray',
                   linestyle=(0, (9, 5)),
-                  linewidth: int = 1,
+                  linewidth: float = 0.5,
                   **kwargs):
-        """Add gridlines (radii) to the Y axis (standard deviation) specified
-        by array *arr*
+        """Add gridlines to the correlation axis specified by array *arr*.
+
+        This method will be deprecated in favor of
+        `TaylorDiagram.add_corr_grid()`
+        """
+
+        warnings.warn(
+            '`TaylorDiagram.add_xgrid` will be deprecated in the future. Please use `TaylorDiagram.add_corr_grid` instead.',
+            PendingDeprecationWarning)
+
+        return self.add_corr_grid(arr, color, linestyle, linewidth, **kwargs)
+
+    def add_std_grid(self,
+                     arr: typing.Union[xr.DataArray, np.ndarray, list, float],
+                     color: str = 'lightgray',
+                     linestyle=(0, (9, 5)),
+                     linewidth: int = 1,
+                     **kwargs):
+        """Add radial gridlines to the standard deviation axis specified by
+        array.
+
+        *arr*
 
         Parameters
         ----------
@@ -458,7 +483,7 @@ def add_ygrid(self,
         --------
         All usage examples are within the GeoCAT-Examples Gallery. To see more usage cases, search the function on the `website <https://geocat-examples.readthedocs.io/en/latest/index.html>`_.
 
-         - `NCL_taylor_2.py <https://geocat-examples.readthedocs.io/en/latest/gallery/TaylorDiagrams/NCL_taylor_2.html?highlight=add_ygrid>`_
+         - `NCL_taylor_2.py <https://geocat-examples.readthedocs.io/en/latest/gallery/TaylorDiagrams/NCL_taylor_2.html?highlight=add_std_grid>`_
         """
 
         t_array = np.linspace(0, np.pi / 2)
@@ -471,6 +496,25 @@ def add_ygrid(self,
                                    linewidth=linewidth,
                                    **kwargs)
 
+    def add_ygrid(self,
+                  arr: typing.Union[xr.DataArray, np.ndarray, list, float],
+                  color: str = 'lightgray',
+                  linestyle=(0, (9, 5)),
+                  linewidth: int = 1,
+                  **kwargs):
+        """Add gridlines to the standard deviation axis specified by array.
+
+        *arr*.
+
+        This method will be deprecated in favor of `TaylorDiagram.add_std_grid()`
+        """
+
+        warnings.warn(
+            '`TaylorDiagram.add_ygrid` will be deprecated in the future. Please use `TaylorDiagram.add_std_grid` instead.',
+            PendingDeprecationWarning)
+
+        return self.add_std_grid(arr, color, linestyle, linewidth, **kwargs)
+
     def add_grid(self, *args, **kwargs):
         """Add a grid.
 

src/geocat/viz/util.py

@@ -556,6 +556,8 @@ def set_titles_and_labels(ax: typing.Union[matplotlib.axes.Axes,
     >>> |                   Axes                    |
     >>> |                                           |
 
+    Be aware that the `suptitle` functionality does not always render well for Cartopy plots. If your main title appears too far above your plot, the recommended fix is to decrease the y-dimension of your figure size.
+
     Examples
     --------
     All usage examples are within the GeoCAT-Examples Gallery. To see more usage cases, search the function on the
@@ -571,7 +573,10 @@ def set_titles_and_labels(ax: typing.Union[matplotlib.axes.Axes,
     if maintitle is not None:
         if subtitle is not None:
             fig = ax.get_figure()
-            fig.suptitle(maintitle, fontsize=maintitlefontsize, y=1.04)
+            fig.suptitle(maintitle,
+                         fontsize=maintitlefontsize,
+                         y=1.04,
+                         ha='center')
         elif lefttitle is not None or righttitle is not None:
             ax.set_title(maintitle, fontsize=maintitlefontsize + 2, y=1.12)
         else: