docs: added references to plotting API. added references in each docstring to where the function is used in the tutorials. Added and fixed multiple docs references. Added changelogs in docstrings with versionchanged/versionadded directives to outline major changes. Added optional label to multiple args in docstrings

ft: re-added xlabel_rotation for comparison_plots
fix: typos in docstrings
build-sphinx: rewrite "make clean" directive, to effectively delete generated sphinx-gallery and sphinx-autodocs material.

Author: pabloitu

csep/__init__.py

@@ -333,7 +333,7 @@ def query_gns(start_time, end_time,  min_magnitude=2.950,
         verbose (bool): print catalog summary statistics
 
     Returns:
-        :class:`csep.core.catalogs.CSEPCatalog
+        :class:`csep.core.catalogs.CSEPCatalog`
     """
 
     # Timezone should be in UTC

csep/utils/plots.py

@@ -17,7 +17,8 @@ livehtml:
 
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf auto_examples/
+	rm -rf tutorials/*
+	rm -rf reference/generated
 
 .PHONY: help Makefile
 

docs/Makefile

@@ -91,7 +91,7 @@ statistics from these catalogs and compare them against one another.
 
 We provide four statistics that probe fundamental aspects of the earthquake forecasts. Please see
 :ref:`Savran et al., 2020<savran-2020>` for a complete description of the individual tests. For the implementation
-details please follow the links below and see the :ref:`example<catalog-forecast-evaluation>` for catalog-based
+details please follow the links below and see the :ref:`Example <tutorial-catalog-forecast-evaluation>` for catalog-based
 forecast evaluation for an end-to-end walk through.
 
 .. automodule:: csep.core.catalog_evaluations

docs/concepts/evaluations.rst

@@ -129,7 +129,7 @@ Working with catalog-based forecasts
 
 .. autosummary:: csep.core.forecasts.CatalogForecast
 
-Please see visit :ref:`this<catalog-forecast-evaluation>` example for an end-to-end tutorial on how to evaluate a catalog-based
+Please see visit :ref:`this Example <tutorial-catalog-forecast-evaluation>` for an end-to-end tutorial on how to evaluate a catalog-based
 earthquake forecast. An example of a catalog-based forecast stored in the default pyCSEP format can be found
 `here <https://github.com/SCECcode/pycsep/blob/dev/csep/artifacts/ExampleForecasts/CatalogForecasts/ucerf3-landers_1992-06-28T11-57-34-14.csv>`__.
 

docs/concepts/forecasts.rst

@@ -6,8 +6,6 @@ Regions
 
 .. automodule:: csep.core.regions
    :no-index:
-.. automodule:: csep.utils.basic_types
-   :no-index:
 
 PyCSEP includes commonly used CSEP testing regions and classes that facilitate working with gridded data sets. This
 module is early in development and will be a focus of future development.

docs/concepts/regions.rst

@@ -104,6 +104,8 @@ examples use the Helmstetter et al (2007) smoothed seismicity forecast
     Found 24 events in the ComCat catalog.
 
 
+.. _theory-consistency-tests:
+
 Consistency tests
 ~~~~~~~~~~~~~~~~~
 
@@ -655,6 +657,8 @@ case, the model with aftershocks performs statistically worse than the
 benchmark model. We note that this comparison is used for demonstation
 purposes only.
 
+.. _theory-catalog-forecasts:
+
 Catalog-based forecast tests
 ----------------------------
 

docs/getting_started/theory.rst

@@ -234,28 +234,30 @@ Region utilities:
 .. currentmodule:: csep.utils.plots
 .. automodule:: csep.utils.plots
 
+.. _api-plot-functions:
+
 Plotting
 --------
 
-General plotting:
+PyCSEP offers multiple plot functionalities to visually explore forecasts, catalogs and results.
+
+Exploratory plotting:
 
 .. autosummary::
    :toctree: generated
 
    plot_magnitude_versus_time
    plot_cumulative_events_versus_time
    plot_magnitude_histogram
-   plot_basemap
-   plot_catalog
-   plot_gridded_dataset
 
-Plotting catalog-based evaluations:
+Spatial plotting:
 
 .. autosummary::
    :toctree: generated
 
-   plot_test_distribution
-   plot_calibration_test
+   plot_basemap
+   plot_catalog
+   plot_gridded_dataset
 
 Plotting grid-based evaluations:
 
@@ -265,6 +267,14 @@ Plotting grid-based evaluations:
    plot_comparison_test
    plot_consistency_test
 
+Plotting catalog-based evaluations:
+
+.. autosummary::
+   :toctree: generated
+
+   plot_test_distribution
+   plot_calibration_test
+
 Plotting alarm-based evaluations:
 
 .. autosummary::

docs/reference/api_reference.rst

@@ -100,6 +100,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _tutorial-catalog-filtering-plot:
+#
 # Plot catalog
 # -------------
 #

examples/tutorials/catalog_filtering.py

@@ -102,6 +102,9 @@
 comcat_catalog.plot(show=True)
 
 ####################################################################################################################################
+#
+# .. _catalog-forecast-evaluation-exploratory:
+#
 # Exploratory visualizations
 # --------------------------
 #
@@ -126,6 +129,9 @@
 number_test_result = catalog_evaluations.number_test(forecast, comcat_catalog)
 
 ####################################################################################################################################
+#
+# .. _catalog-forecast-evaluation-plot:
+#
 # Plot number test result
 # -----------------------
 #

examples/tutorials/catalog_forecast_evaluation.py

@@ -93,6 +93,9 @@
 csep.write_json(spatial_test_result, 'example_spatial_test.json')
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-plot:
+#
 # Plot spatial test results
 # -------------------------
 #
@@ -105,6 +108,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-plot-comparison:
+#
 # Performing a comparative test
 # -----------------------------
 #
@@ -126,6 +132,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-concentration-roc:
+#
 # Plot ROC Curves
 # ---------------
 #
@@ -149,6 +158,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _grid-forecast-evaluation-roc-and-molchan:
+#
 # Plot ROC and Molchan curves using the alarm-based approach
 # ----------------------------------------------------------
 

examples/tutorials/gridded_forecast_evaluation.py

@@ -15,11 +15,17 @@
     5. Creating composite plots
     6. Plot multiple Evaluation Results
 
+
+Please refer to the :ref:`Plotting API Reference <api-plot-functions>` for a description of all
+PyCSEP plotting functionality.
 """
 
 ################################################################################################################
-# Example 1: Spatial dataset plot arguments
-# -----------------------------------------
+#
+# .. _tutorial-plot-customizations-ex1:
+#
+# Example 1: Customizing Gridded Dataset Plot
+# -------------------------------------------
 
 ####################################################################################################################################
 # **Load required libraries**
@@ -49,10 +55,10 @@
 # * Assign a title
 # * Set labels to the geographic axes
 # * Draw country borders
-# * Set a linewidth of 0.5 to country border
-# * Assign ``'rainbow'`` as the colormap. Possible values from ``matplotlib.cm`` library
+# * Set a linewidth of 1.5 to country border
+# * Assign ``'rainbow'`` as the colormap. Possible values from :mod:`matplotlib.cm` library
 # * Defines 0.8 for an exponential transparency function (default is 0 for constant alpha, whereas 1 for linear).
-# * An object cartopy.crs.Projection() is passed as Projection to the map
+# * An object :class:`cartopy.crs.Projection` (in this case :class:`cartopy.crs.Mercator`) is passed to the map
 #
 # The complete description of plot arguments can be found in :func:`csep.utils.plots.plot_gridded_dataset`
 #
@@ -70,6 +76,9 @@
                    show=True)
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex2:
+#
 # Example 2: Plot a global forecast and a selected magnitude bin range
 # --------------------------------------------------------------------
 #
@@ -105,7 +114,7 @@
 ####################################################################################################################################
 # **Plotting the dataset**
 #
-# To plot a global forecast, we must assign the option ``set_global=True``, which is required by :ref:`cartopy` to handle
+# To plot a global forecast, we must assign the option ``set_global=True``, which is required by :mod:`cartopy` to handle
 # internally the extent of the plot. We can further customize the plot using the required arguments from :func:`~csep.utils.plots.plot_gridded_dataset`
 #
 
@@ -131,6 +140,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex3:
+#
 # Example 3: Plot a catalog with a custom basemap
 # -----------------------------------------------
 
@@ -152,7 +164,7 @@
 # * Set minimum and maximum marker size of 7 and 500, respectively.
 # * Set the marker color red
 # * Set a 0.3 transparency
-# * mag_scale is used to exponentially scale the size with respect to magnitude. Recommended 1-8
+# * `power` is used to exponentially scale the size with respect to magnitude. Recommended 1-8
 # * Set legend True and location in 3 (lower-left corner)
 # * Set a list of magnitude ticks to display in the legend
 #
@@ -165,7 +177,7 @@
              'max_size': 500,
              'markercolor': 'red',
              'alpha': 0.3,
-             'mag_scale': 8,
+             'power': 4,
              'legend': True,
              'legend_loc': 3,
              'coastline': False,
@@ -178,8 +190,15 @@
 
 ax = catalog.plot(show=True, **plot_args)
 
+####################################################################################################################################
+# Alternatively, it can be plotted using the :func:`csep.utils.plots.plot_catalog` function
+
+plots.plot_catalog(catalog=catalog, show=True, **plot_args)
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex4:
+#
 # Example 4: Plot composition
 # -----------------------------------------------
 #
@@ -205,6 +224,7 @@
 # Plot the basemap alone by using :func:`csep.utils.plots.plot_basemap`. Do not set ``show=True`` and store the returned ``ax`` object to
 # start the composite plot
 
+# Start the base plot
 ax = plots.plot_basemap(figsize=(8, 8),
                         projection=cartopy.crs.AlbersEqualArea(central_longitude=-120.),
                         extent=forecast.region.get_bbox(),
@@ -217,9 +237,12 @@
 ax = forecast.plot(colormap='PuBu_r', alpha_exp=0.5, ax=ax)
 
 # Use show=True to finalize the composite.
-catalog.plot(markercolor='darkred', ax=ax, show=True)
+plots.plot_catalog(catalog=catalog, markercolor='darkred', ax=ax, show=True)
 
 ####################################################################################################################################
+#
+# .. _tutorial-plot-customizations-ex5:
+#
 # Example 5: Plot multiple evaluation results
 # -------------------------------------------
 

examples/tutorials/plot_customizations.py

@@ -1,6 +1,6 @@
 """
 
-.. tutorial-handling-grid-forecast:
+.. _tutorial-handling-grid-forecast:
 
 Handling Grid-based Forecasts
 =============================
@@ -42,6 +42,9 @@
                                       name='helmstetter_mainshock')
 
 ####################################################################################################################################
+#
+# .. _tutorial-handling-grid-forecast-plot:
+#
 # Plot forecast
 # -------------
 #

examples/tutorials/plot_gridded_forecast.py

@@ -186,6 +186,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _quadtree_gridded-forecast-evaluation-plot:
+#
 # Plot spatial test results
 # -------------------------
 #

examples/tutorials/quadtree_gridded_forecast_evaluation.py

@@ -68,6 +68,9 @@
 
 
 ####################################################################################################################################
+#
+# .. _tutorial-working-catalog-forecasts-plot:
+#
 # Plot expected event counts
 # --------------------------
 #