docs: Added query_gns, query_gcmt to docs index. Fixed catalog filtering tutorial links and expanded with m_vs_t plot. Added reference links to multiple tutorials. Changed sphinx confx to not display full function signature in API docs. Added comparative tests/plots to gridded_forecast_+tutorial

refac: shifted some function args ordering
ft: Comparative plots now handle being passed only one forecast.

Author: pabloitu

csep/core/catalogs.py

@@ -23,7 +23,7 @@
 from csep.utils.log import LoggingMixin
 from csep.utils.readers import csep_ascii
 from csep.utils.file import get_file_extension
-from csep.utils.plots import plot_catalog
+from csep.utils.plots import plot_catalog, plot_magnitude_versus_time
 
 
 class AbstractBaseCatalog(LoggingMixin):
@@ -829,15 +829,16 @@ def b_positive(self):
         """ Implements the b-positive indicator from Nicholas van der Elst """
         pass
 
-    def plot(self, ax=None, show=False, extent=None, set_global=False, plot_args=None,
-             **kwargs):
-        """ Plot catalog according to plate-carree projection
+    def plot(self, ax=None, show=False, extent=None, set_global=False, **kwargs):
+        """ Plot catalog according to plate-carree projection. See
+        https://docs.cseptesting.org/reference/generated/csep.utils.plots.plot_catalog.html for
+        a description of keyword arguments.
 
         Args:
             ax (`matplotlib.pyplot.axes`): Previous axes onto which catalog can be drawn
             show (bool): if true, show the figure. this call is blocking.
             extent (list): Force an extent [lon_min, lon_max, lat_min, lat_max]
-            plot_args (optional/dict): dictionary containing plotting arguments for making figures
+            set_global (bool): Whether to plot using a global projection
 
         Returns:
             axes: matplotlib.Axes.axes
@@ -856,14 +857,30 @@ def plot(self, ax=None, show=False, extent=None, set_global=False, plot_args=Non
         except AttributeError:
             pass
 
-        plot_args = plot_args or {}
+        plot_args = kwargs.get('plot_args', {})
         plot_args_default.update(plot_args)
 
         # this call requires internet connection and basemap
         ax = plot_catalog(self, ax=ax, show=show, extent=extent,
                           set_global=set_global, **plot_args_default, **kwargs)
         return ax
 
+    def plot_magnitude_versus_time(self, ax=None, show=False, **kwargs):
+        """ Plot the magnitude-time series of a catalog. See
+        https://docs.cseptesting.org/reference/generated/csep.utils.plots.plot_magnitude_versus_time.html for
+        a description of keyword arguments.
+
+        Args:
+            ax (`matplotlib.pyplot.axes`): Previous axes onto which catalog can be drawn
+            show (bool): if true, show the figure. this call is blocking.
+
+        Returns:
+            axes: matplotlib.Axes.axes
+        """
+
+        ax = plot_magnitude_versus_time(self, ax=ax, show=show, **kwargs)
+
+        return ax
 
 class CSEPCatalog(AbstractBaseCatalog):
     """

csep/utils/plots.py

@@ -828,9 +828,7 @@ def plot_gridded_dataset(
     gridded: numpy.ndarray,
     region: "CartesianGrid2D",
     basemap: Optional[str] = None,
-    ax: Optional[pyplot.Axes] = None,
     projection: Optional[Union[ccrs.Projection, str]] = None,
-    show: bool = False,
     extent: Optional[List[float]] = None,
     set_global: bool = False,
     plot_region: bool = True,
@@ -840,6 +838,8 @@ def plot_gridded_dataset(
     clabel: Optional[str] = None,
     alpha: Optional[float] = None,
     alpha_exp: float = 0,
+    ax: Optional[pyplot.Axes] = None,
+    show: bool = False,
     **kwargs,
 ) -> matplotlib.axes.Axes:
     """
@@ -856,11 +856,9 @@ def plot_gridded_dataset(
             (whose indices correspond to each spatial cell) to a 2D-square array.
         region (CartesianGrid2D): Region in which gridded values are contained.
         basemap (str): Passed to :func:`~csep.utils.plots.plot_basemap` along with `kwargs`.
-        ax (matplotlib.axes.Axes): Previously defined ax object. Defaults to `None`.
         projection (cartopy.crs.Projection or str): Projection to be used in the underlying
             basemap. It can be a cartopy projection instance, or `approx` for a quick
             approximation of Mercator. Defaults to :class:`~cartopy.crs.PlateCarree` if `None`.
-        show (bool): If `True`, displays the plot. Defaults to `False`.
         extent (list of float): ``[lon_min, lon_max, lat_min, lat_max]``. Defaults to `None`.
         set_global (bool): Display the complete globe as basemap. Defaults to `False`.
         plot_region (bool): If `True`, plot the dataset region border. Defaults to `True`.
@@ -871,6 +869,8 @@ def plot_gridded_dataset(
         alpha (float): Transparency level. Defaults to `None`.
         alpha_exp (float): Exponent for the alpha function (recommended between `0.4` and `1`).
             Defaults to `0`.
+        ax (matplotlib.axes.Axes): Previously defined ax object. Defaults to `None`.
+        show (bool): If `True`, displays the plot. Defaults to `False`.
         **kwargs: Additional keyword arguments to customize the plot:
 
             - **colorbar_labelsize** (`int`): Font size for the colorbar label.
@@ -953,11 +953,11 @@ def plot_test_distribution(
     evaluation_result: "EvaluationResult",
     bins: Union[str, int, List[Any]] = "fd",
     percentile: Optional[int] = 95,
-    ax: Optional[matplotlib.axes.Axes] = None,
     auto_annotate: Union[bool, dict] = True,
     sim_label: str = "Simulated",
     obs_label: str = "Observation",
     legend: bool = True,
+    ax: Optional[matplotlib.axes.Axes] = None,
     show: bool = False,
     **kwargs,
 ) -> matplotlib.axes.Axes:
@@ -1096,8 +1096,8 @@ def plot_test_distribution(
 def plot_calibration_test(
     evaluation_result: "EvaluationResult",
     percentile: float = 95,
-    ax: Optional[matplotlib.axes.Axes] = None,
     label: Optional[str] = None,
+    ax: Optional[matplotlib.axes.Axes] = None,
     show: bool = False,
     **kwargs,
 ) -> matplotlib.axes.Axes:
@@ -1261,6 +1261,13 @@ def _plot_comparison_test(
     plot_args = {**DEFAULT_PLOT_ARGS, **kwargs.get("plot_args", {}), **kwargs}
     fig, ax = pyplot.subplots(figsize=plot_args["figsize"]) if ax is None else (ax.figure, ax)
 
+    # Handle case when there is only a single pair of t_results and w_results
+    if not isinstance(results_t, list):
+        results_t = [results_t]
+
+    if results_w is not None and not isinstance(results_w, list):
+        results_w = [results_w]
+
     # Iterate through T-test results, or jointly through t- and w- test results
     Results = zip(results_t, results_w) if results_w else zip(results_t)
     for index, result in enumerate(Results):
@@ -1337,11 +1344,15 @@ def _plot_comparison_test(
 
     if plot_args["legend"]:
         # Add custom legend to explain results
+
         legend_elements = [
             Line2D([0], [0], color="red", lw=2,
                    label=f"T-test rejected ($\\alpha = {results_t[0].quantile[-1]}$)"),
             Line2D([0], [0], color="green", lw=2, label="T-test non-rejected"),
-            Line2D([0], [0], color="gray", lw=2, label="T-test indistinguishable"),
+            Line2D([0], [0], color="gray", lw=2, label="T-test indistinguishable")
+        ]
+        if results_w is not None:
+            legend_elements.extend([
             Line2D(
                 [0],
                 [0],
@@ -1361,8 +1372,8 @@ def _plot_comparison_test(
                 markersize=6,
                 markerfacecolor="white",
                 label="W-test indistinguishable",
-            ),
-        ]
+            )])
+
         ax.legend(handles=legend_elements, loc="best", fontsize=plot_args["legend_fontsize"])
 
     if plot_args["tight_layout"]:
@@ -1379,9 +1390,9 @@ def _plot_consistency_test(
     normalize: bool = False,
     one_sided_lower: bool = False,
     percentile: float = 95,
-    ax: Optional[pyplot.Axes] = None,
     plot_mean: bool = False,
     color: str = "black",
+    ax: Optional[pyplot.Axes] = None,
     show: bool = False,
     **kwargs,
 ) -> matplotlib.axes.Axes:
@@ -1523,8 +1534,8 @@ def _plot_concentration_ROC_diagram(
     catalog: "CSEPCatalog",
     linear: bool = True,
     plot_uniform: bool = True,
-    show: bool = True,
     ax: Optional[pyplot.Axes] = None,
+    show: bool = True,
     **kwargs,
 ) -> matplotlib.axes.Axes:
     """
@@ -1649,8 +1660,8 @@ def _plot_ROC_diagram(
     catalog: "CSEPCatalog",
     linear: bool = True,
     plot_uniform: bool = True,
-    show: bool = True,
     ax: Optional[pyplot.Axes] = None,
+    show: bool = True,
     **kwargs,
 ) -> matplotlib.pyplot.Axes:
     """
@@ -1786,8 +1797,8 @@ def _plot_Molchan_diagram(
     catalog: "CSEPCatalog",
     linear: bool = True,
     plot_uniform: bool = True,
-    show: bool = True,
     ax: Optional[pyplot.Axes] = None,
+    show: bool = True,
     **kwargs,
 ) -> matplotlib.axes.Axes:
 

docs/concepts/regions.rst

@@ -4,6 +4,7 @@
 Regions
 #######
 
+.. automodule:: csep.core.regions
 .. automodule:: csep.utils.basic_types
 
 PyCSEP includes commonly used CSEP testing regions and classes that facilitate working with gridded data sets. This
@@ -15,7 +16,6 @@ module is early in development and will be a focus of future development.
 
 .. :currentmodule:: csep
 
-.. automodule:: csep.core.regions
 
 Practically speaking, earthquake forecasts, especially time-dependent forecasts, treat time differently than space and
 magnitude. If we consider a family of monthly forecasts for the state of California for earthquakes with **M** 3.95+,
@@ -98,7 +98,8 @@ mapping defined in (2). The :meth:`get_index_of<csep.core.regions.CartesianGrid2
 of longitudes and latitudes and returns the index of the polygon they are associated with. For instance, this index can
 now be used to access a data value stored in another data structure.
 
-.. ***************
+.. _testing-regions:
+
 Testing Regions
 ########################
 
@@ -110,8 +111,17 @@ these regions.
 
     california_relm_region
     italy_csep_region
+    nz_csep_region
     global_region
 
+Also, the CSEP collection regions (i.e., extended regions where data were collected to create forecasts in testing regions) can be obtained as:
+
+.. autosummary::
+
+    california_relm_collection_region
+    italy_csep_collection_region
+    nz_csep_collection_region
+
 .. ****************
 Region Utilities
 ########################

docs/conf.py

@@ -176,6 +176,7 @@
     # Insert links to documentation of objects in the examples
     "reference_url": {"csep": None},
 }
+autodoc_typehints = "description"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/getting_started/theory.rst

@@ -551,6 +551,8 @@ likelihood falls in the tail of the simulated likelihood distribution.
 Again this is shown by a coloured symbol which highlights whether the
 forecast model passes or fails the test.
 
+.. _forecast-comparison-tests:
+
 Forecast comparison tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/reference/api_reference.rst

@@ -17,6 +17,8 @@ Loading catalogs and forecasts
    load_catalog
    query_comcat
    query_bsi
+   query_gns
+   query_gcmt
    load_gridded_forecast
    load_catalog_forecast
 
@@ -249,7 +251,7 @@ Plotting catalog-based evaluations:
 .. autosummary::
    :toctree: generated
 
-   plot_distribution_test
+   plot_test_distribution
    plot_calibration_test
 
 Plotting grid-based evaluations:

examples/tutorials/catalog_filtering.py

@@ -24,15 +24,19 @@
 import csep
 from csep.core import regions
 from csep.utils import time_utils, comcat
-# sphinx_gallery_thumbnail_path = '_static/CSEP2_Logo_CMYK.png'
 
 ####################################################################################################################################
 # Load catalog
 # ------------
 #
-# PyCSEP provides access to the ComCat web API using :func:`csep.query_comcat` and to the Bollettino Sismico Italiano
-# API using :func:`csep.query_bsi`. These functions require a :class:`datetime.datetime` to specify the start and end
-# dates.
+# PyCSEP provides access to multiple catalog webservices, using the following functions:
+#
+#   * `ANSS Comprehensive Earthquake Catalog (ComCat) <https://earthquake.usgs.gov/data/comcat/>`_: :func:`csep.query_comcat`
+#   * `INGV Bolletino Sismico Italiano (BSI) <https://terremoti.ingv.it/en/bsi>`_: :func:`csep.query_bsi`
+#   * `GNS New Zealand GeoNet <https://www.geonet.org.nz/>`_: :func:`csep.query_gns`
+#   * `Global CMT <https://www.globalcmt.org/>`_ (through the `ISC <https://www.isc.ac.uk/>`_ API): :func:`csep.query_gcmt`
+#
+# These functions require a :class:`datetime.datetime` to specify the start and end dates of the query.
 
 start_time = csep.utils.time_utils.strptime_to_utc_datetime('2019-01-01 00:00:00.0')
 end_time = csep.utils.time_utils.utc_now_datetime()
@@ -91,18 +95,33 @@
 catalog = catalog.filter_spatial(aftershock_region).apply_mct(event.magnitude, m71_epoch)
 print(catalog)
 
+####################################################################################################################################
+# Additional CSEP regions (e.g., California, Italy, New Zealand) can be accessed through the :mod:`csep.core.regions` module. See :ref:`testing-regions` for more information.
+
 
 ####################################################################################################################################
 # Plot catalog
 # -------------
 #
-# To visualize the catalog, use :meth:`csep.core.catalogs.AbstractBaseCatalog.plot` to plot it spatially
+# To visualize the catalog spatially, simply use the method :meth:`~csep.core.catalogs.CSEPCatalog.plot`
 catalog.plot(show=True)
 
 
+####################################################################################################################################
+# To plot the magnitude time series, use :meth:`~csep.core.catalogs.CSEPCatalog.plot_magnitude_vs_time`
+catalog.plot_magnitude_versus_time(show=True)
+
 ####################################################################################################################################
 # Write catalog
 # -------------
 #
-# Use :meth:`csep.core.catalogs.AbstractBaseCatalog.write_ascii` to write the catalog into the comma separated value format.
+# Use the method :meth:`~csep.core.catalogs.CSEPCatalog.write_ascii` to write the catalog into the comma separated value format.
 catalog.write_ascii('2019-11-11-comcat.csv')
+
+
+####################################################################################################################################
+# Load catalog
+# ------------
+#
+# Also, the function :func:`csep.load_catalog` can be used to read catalogs un multiple formats (See :ref:`catalogs-reference`)
+catalog = csep.load_catalog('2019-11-11-comcat.csv')