Merge pull request pik-copan#217 from pik-copan/203-map_plots

review map plotting

README.rst

@@ -93,11 +93,7 @@ Required at runtime:
     (for ``Data`` and ``NetCDFDictionary``)
 
 Optional *(used only in certain classes and methods)*:
-  - `PyNGL <http://www.pyngl.ucar.edu/Download/>`_
-    (for ``NetCDFDictionary``)
   - `Matplotlib <http://matplotlib.org/>`_
-  - `Matplotlib Basemap Toolkit <http://matplotlib.org/basemap/>`_
-    (for drawing maps)
   - `Cartopy <https://scitools.org.uk/cartopy/docs/latest/index.html>`_
     (for some plotting features)
   - `mpi4py <https://github.com/mpi4py/mpi4py>`_

docs/source/api/climate/map_plots.rst

@@ -1,8 +1,8 @@
 
-climate.map_plots
+climate.map_plot
 =================
 
-.. automodule:: pyunicorn.climate.map_plots
+.. automodule:: pyunicorn.climate.map_plot
     :synopsis: spatially embedded complex networks, multivariate data,
                time series surrogates
     :members:

src/pyunicorn/__init__.py

@@ -16,7 +16,6 @@
 pyunicorn
 =========
 
-
 Subpackages
 -----------
 core
@@ -27,12 +26,6 @@
     Functional networks
 timeseries
     Time series surrogates
-
-To Do
------
-   - A lot - See current product backlog.
-   - Clean up MapPlots class -> Alex!?
-
 """
 
 from .version import __version__

src/pyunicorn/climate/__init__.py

@@ -22,15 +22,6 @@
 ~~~~~~~~~~~~~~~~~~~~
 [Donges2009c]_, [Donges2009a]_, [Donges2009b]_, [Donges2011a]_, [Zou2011]_,
 [Tominski2011]_, [Heitzig2012]_
-
-To do
-~~~~~
-  - A lot - See current product backlog.
-
-Known Bugs
-~~~~~~~~~~
-  - ...
-
 """
 
 from ..core import GeoNetwork, GeoGrid, Network
@@ -41,8 +32,7 @@
 from .coupled_tsonis import CoupledTsonisClimateNetwork
 from .havlin import HavlinClimateNetwork
 from .hilbert import HilbertClimateNetwork
-from .map_plots import MapPlots
-from .cartopy_plots import CartopyPlots
+from .map_plot import MapPlot
 from .mutual_info import MutualInfoClimateNetwork
 from .partial_correlation import PartialCorrelationClimateNetwork
 from .rainfall import RainfallClimateNetwork

src/pyunicorn/climate/map_plot.py

@@ -0,0 +1,119 @@
+# This file is part of pyunicorn.
+# Copyright (C) 2008--2023 Jonathan F. Donges and pyunicorn authors
+# URL: <http://www.pik-potsdam.de/members/donges/software>
+# License: BSD (3-clause)
+#
+# Please acknowledge and cite the use of this software and its authors
+# when results are used in publications or published elsewhere.
+#
+# You can use the following reference:
+# J.F. Donges, J. Heitzig, B. Beronov, M. Wiedermann, J. Runge, Q.-Y. Feng,
+# L. Tupikina, V. Stolbova, R.V. Donner, N. Marwan, H.A. Dijkstra,
+# and J. Kurths, "Unified functional network and nonlinear time series analysis
+# for complex systems science: The pyunicorn package"
+
+"""
+Provides classes for analyzing spatially embedded complex networks, handling
+multivariate data and generating time series surrogates.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+try:
+    import cartopy.crs as ccrs
+    import cartopy.feature as cf
+except ImportError:
+    print("climate: Package cartopy could not be loaded. Some functionality "
+          "in class MapPlot might not be available!")
+
+from ..core import Grid
+
+#
+#  Define class MapPlot
+#
+
+
+# pylint: disable=too-few-public-methods
+class MapPlot:
+    """
+    Encapsulates map plotting functions via Cartopy and Matplotlib.
+    """
+
+    def __init__(self, grid: Grid, title: str):
+        """
+        :arg grid: The `Grid` object describing the map data to be plotted.
+        :arg str title: The title describing the map data.
+        """
+        self.grid: Grid = grid
+        self.title: str = title
+
+        #
+        #  Adjust Cartopy settings, fine tuning can be done externally
+        #
+
+        # Specify Coordinate Refference System for Map Projection
+        # pylint: disable-next=abstract-class-instantiated
+        self.projection = ccrs.PlateCarree()
+
+        # Specify CRS (where data should be plotted)
+        # pylint: disable-next=abstract-class-instantiated
+        self.crs = ccrs.PlateCarree()
+
+        # get spatial dims
+        self.lon = self.grid.convert_lon_coordinates(self.grid.lon_sequence())
+        self.lat = self.grid.lat_sequence()
+        self.gridsize_lon = len(self.lon)
+        self.gridsize_lat = len(self.lat)
+        self.lon_min = self.grid.boundaries()["lon_min"]
+        self.lon_max = self.grid.boundaries()["lon_max"]
+        self.lat_min = self.grid.boundaries()["lat_min"]
+        self.lat_max = self.grid.boundaries()["lat_max"]
+
+        # extent of data will also give extent of world map
+        self.data_extent = [self.lon_min, self.lon_max,
+                            self.lat_min, self.lat_max]
+
+    def plot(self, data: np.ndarray, label: str):
+        """
+        Plot dataset onto ``self.grid``. A simple setup to get a quick view of
+        your data.
+
+        The plot can be customized by calling additional Matplotlib or Cartopy
+        methods afterwards. It can then be saved via ``plt.savefig()``.
+
+        :arg ndarray data: The dataset to be plotted on the Grid.
+        :arg str label: A name for the dataset to print as label.
+        """
+
+        #  Generate figure
+        plt.figure()
+
+        # create GeoAxes object
+        gax = plt.axes(projection=self.projection)
+
+        # create some standards of plotting that can be adjusted
+        # before calling ``generate_cartopy_plot()``
+        # adjust size and plot coastlines and borders
+        gax.set_extent(self.data_extent, crs=self.crs)
+        # ax.set_global()
+        gax.add_feature(cf.COASTLINE.with_scale("50m"), lw=0.5)
+        gax.add_feature(cf.BORDERS.with_scale("50m"), lw=0.2)
+
+        # Draw gridlines in degrees over map
+        gl = gax.gridlines(
+            crs=self.crs, draw_labels=True,
+            linewidth=.6, color='gray',
+            alpha=0.5, linestyle='-.'
+        )
+        gl.xlabel_style = {"size": 7}
+        gl.ylabel_style = {"size": 7}
+
+        # plot data upon map
+        plt.tricontourf(self.lon, self.lat, data,
+                        extent=self.data_extent, transform=self.crs)
+        cbar = plt.colorbar(shrink=0.5)
+        cbar.set_label(label, rotation=270)
+
+        # add title
+        plt.title(self.title)