docs: added postprocess documentation. fixed link to experimental con…

…cepts.

ft: added simple method get_test to experiment class for users to quickly access an evaluation by its name

docs/guide/postprocess_config.rst

@@ -3,4 +3,363 @@
 Post-Process Options
 ====================
 
-TBI
+The ``postprocess`` inset can be used within an experiment configuration file to configure the **plotting** and **reporting** functions to be performed after the experiment calculations have been completed. The plotting functions provide a graphic representation of the catalogs, forecasts and evaluation results, whereas the reporting functions assemble these into a human-readable report.
+
+**Example postprocess configuration**:
+
+.. code-block:: yaml
+   :caption: config.yml
+   :emphasize-lines: 8-
+
+    name: experiment
+    time_config: ...
+    region_config: ...
+    catalog: ...
+    model_config: ...
+    test_config: ...
+
+    postprocess:
+      plot_forecasts:
+        colormap: magma
+        basemap: ESRI_terrain
+        catalog: True
+
+      plot_catalog:
+        basemap: google-satellite
+        mag_ticks: [5, 6, 7, 8]
+        markersize: 7
+
+
+.. important::
+
+    By default, **floatCSEP** plots the testing catalogs, forecasts and results, summarizing them into a **Markdown** report. The postprocess configuration aids to customize these options, or to extend them by using custom python scripts.
+
+Plot Forecasts
+--------------
+
+The ``plot_forecast`` command wraps the functionality of the **pyCSEP** function :func:`~csep.utils.plots.plot_spatial_dataset`, which is used to plot the forecasts spatial rates.
+Most of the arguments of ``plot_forecast`` mimics those of :func:`~csep.utils.plots.plot_spatial_dataset` with some additions and are summarized here:
+
+.. dropdown::  Forecast plotting arguments
+   :animate: fade-in-slide-down
+   :icon: list-unordered
+
+   .. list-table::
+      :widths: 20 80
+      :header-rows: 1
+
+      * - **Arguments**
+        - **Description**
+      * - ``all_time_windows``
+        - Whether all testing time windows are plotted (true or false). By default, only the last time window is plotted.
+      * - ``figsize``
+        - List with the figure proportions. Default is `[6.4, 4.8]`
+      * - ``title``
+        - Title for the plot. Default is None
+      * - ``title_size``
+        - Size of the title text. Default is 10
+      * - ``projection``
+        - Projection for the map. Default ``cartopy.crs.PlateCarree`` Example:
+
+          .. code-block:: yaml
+
+            plot_forecasts:
+                projection: Mercator
+
+          or if the projection contains keyword arguments:
+
+          .. code-block:: yaml
+
+            plot_forecasts:
+                projection:
+                    Mercator:
+                        central_longitude: 50
+
+      * - ``grid``
+        - Whether to show grid lines. Default is True
+      * - ``grid_labels``
+        - Whether to show grid labels. Default is True
+      * - ``grid_fontsize``
+        - Font size for grid labels. Default is 10.0
+      * - ``basemap``
+        - Basemap option. Possible values are: ``stock_img``, ``google-satellite``,  ``ESRI_terrain``, ``ESRI_imagery``, ``ESRI_relief``, ``ESRI_topo``, ``ESRI_terrain``, or a webservice URL. Default is None
+      * - ``coastline``
+        - Flag to plot coastline. Default is True
+      * - ``borders``
+        - Flag to plot country borders. Default is False
+      * - ``region_border``
+        - Flag to plot the forecast region border. Default is True
+      * - ``tile_scaling``
+        - Zoom level (1-12) for basemap tiles or ``auto`` for automatic scaling
+      * - ``linewidth``
+        - Line width of borders and coastlines. Default is 1.5
+      * - ``linecolor``
+        - Color of borders and coastlines. Default is ``black``
+      * - ``cmap``
+        - Color map for the plot. Default is ``viridis``
+      * - ``clim``
+        - Range of the colorbar, in ``log10`` values. Example: ``[-5, 0]``
+      * - ``clabel``
+        - Label for the colorbar. Default is None
+      * - ``clabel_fontsize``
+        - Font size for the colorbar label. Default is None
+      * - ``cticks_fontsize``
+        - Font size for the colorbar ticks. Default is None
+      * - ``alpha``
+        - Transparency level. Default is 1
+      * - ``alpha_exp``
+        - Exponent for the alpha function, recommended between 0.4 and 1. Default is 0
+      * - ``catalog``
+        - Plots the testing catalog on top of the forecast, corresponding to the forecast time window.
+
+          .. code-block:: yaml
+
+            plot_forecasts:
+                catalog: True
+
+          and if the catalog needs to be customized:
+
+          .. code-block:: yaml
+
+            plot_forecasts:
+                catalog:
+                  legend_loc: 1
+                  legend_fontsize: 14
+                  markercolor: blue
+
+          See :ref:`plot_catalogs` for customization options.
+
+
+.. important::
+
+    By default, only the forecast corresponding to the last time window is plotted. To plot all time windows, use ``all_time_windows: True``
+
+
+.. _plot_catalogs:
+
+Plot Catalogs
+-------------
+
+Test catalogs are automatically plotted when **floatCSEP** calculations are finished. Similar to plotting the forecasts, the ``plot_catalog`` command wraps the functionality of the **pyCSEP** function :func:`~csep.utils.plots.plot_catalog`.
+
+
+
+.. dropdown::  Catalog Plotting Arguments
+   :animate: fade-in-slide-down
+   :icon: list-unordered
+
+   .. list-table::
+      :widths: 20 80
+      :header-rows: 1
+
+      * - **Arguments**
+        - **Description**
+      * - ``all_time_windows``
+        - If along the main testing catalogs, all sub-testing catalogs from all the time windows are plotted (true or false). Default is False.
+      * - ``figsize``
+        - List or tuple with the figure proportions. Default is [6.4, 4.8].
+      * - ``title``
+        - Title for the plot. Default is the catalog name.
+      * - ``title_size``
+        - Size of the title text. Default is 10.
+      * - ``filename``
+        - File name to save the figure. Default is None.
+      * - ``projection``
+        - Projection for the map. Default ``cartopy.crs.PlateCarree`` Example:
+
+          .. code-block:: yaml
+
+            plot_forecasts:
+                projection: Mercator
+
+          or if the projection contains keyword arguments:
+
+          .. code-block:: yaml
+
+            plot_forecasts:
+                projection:
+                    Mercator:
+                        central_longitude: 50
+
+      * - ``basemap``
+        - Basemap option. Possible values are: ``stock_img``, ``google-satellite``,  ``ESRI_terrain``, ``ESRI_imagery``, ``ESRI_relief``, ``ESRI_topo``, ``ESRI_terrain``, or a webservice URL. Default is None
+      * - ``coastline``
+        - Flag to plot coastline. Default is True.
+      * - ``grid``
+        - Whether to display grid lines. Default is True.
+      * - ``grid_labels``
+        - Whether to display grid labels. Default is True.
+      * - ``grid_fontsize``
+        - Font size for grid labels. Default is 10.0.
+      * - ``marker``
+        - Marker type for plotting earthquakes.
+      * - ``markersize``
+        - Constant size for all earthquakes.
+      * - ``markercolor``
+        - Color for all earthquakes. Default is ``blue``.
+      * - ``borders``
+        - Flag to plot country borders. Default is False.
+      * - ``region_border``
+        - Flag to plot the catalog region border. Default is True.
+      * - ``alpha``
+        - Transparency level for the earthquake scatter. Default is 1.
+      * - ``mag_scale``
+        - Scaling factor for the scatter plot based on earthquake magnitudes.
+      * - ``legend``
+        - Flag to display the legend box. Default is True.
+      * - ``legend_loc``
+        - Position of the legend (integer or string). Default is 'best'.
+      * - ``mag_ticks``
+        - List of magnitude ticks to display in the legend.
+      * - ``labelspacing``
+        - Separation between legend ticks. Default is 0.5.
+      * - ``tile_scaling``
+        - Zoom level (1-12) for basemap tiles, or ``auto`` for automatic scaling based on extent.
+      * - ``linewidth``
+        - Line width of borders and coastlines. Default is 1.5.
+      * - ``linecolor``
+        - Color of borders and coastlines. Default is ``black``.
+
+
+.. important::
+
+    By default, only the main test catalog (containing all events within the experiment frame) is plotted. To also plot the test catalogs from each time window separately, use ``all_time_windows: True``
+
+
+Custom Plotting
+---------------
+
+Additional plotting functionality can be injected to an experiment by using a custom **python** script, which is specified within the ``postprocess`` configuration:
+
+**Example:**
+
+.. code-block:: yaml
+
+    postprocess:
+      plot_custom: plot_script.py:main
+
+where the script path and a function within should be written as:
+
+.. code-block:: yaml
+
+    plot_custom: {python_script_path}:{function_name}
+
+This option provides a `hook` for python code to be run after the experiment calculation, giving it read access to attributes from the :class:`~floatcsep.experiment.Experiment` class. The `hook` requirements are that the script to be located within the same directory as the configuration file, whereas the function must receive a :class:`floatcsep.experiment.Experiment` as unique argument:
+
+.. code-block:: python
+   :caption: Example custom plot script
+
+    from floatcsep import Experiment
+
+    def main_function(experiment: Experiment):
+
+        timewindows = experiment.timewindows
+        model = experiment.get_model("pymock")
+
+        rates = []
+        times = []
+
+        for timewindow in timewindows:
+            forecast = model.get_forecast(time_window)
+            rates.append(forecast.event_counts)
+            times = timewindow[0]
+
+        fig, ax = plt.subplots(1, 1)
+        ax.plot(times, rates)
+        pyplot.savefig("results/pymock_rates.png")
+
+
+In this way, the plot function can use all the :class:`~floatcsep.experiment.Experiment` attributes/methods to access catalogs, forecasts and test results. Please check the Tutorial :ref:`case_g` for an advanced use.
+
+Here are some basic functionalities from **floatCSEP** to access catalogs, forecasts and results using **python** code:
+
+
+.. dropdown::  Experiment method/attributes.
+   :animate: fade-in-slide-down
+   :icon: list-unordered
+
+   .. list-table::
+      :widths: 20 80
+      :header-rows: 1
+
+      * - **Method/Attribute**
+        - **Description**
+      * - :attr:`~floatcsep.experiment.Experiment.timewindows`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.start_date`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.end_date`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.region`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.mag_min`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.mag_max`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.mag_bin`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.magnitudes`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.depth_min`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.depth_max`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.mag_min`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.run_dir`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.models`
+        -
+      * - :meth:`~floatcsep.experiment.Experiment.get_model`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.tests`
+        -
+      * - :meth:`~floatcsep.experiment.Experiment.get_test`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.results_repo`
+        -
+      * - :attr:`~floatcsep.experiment.Experiment.catalog_repo`
+        -
+
+.. dropdown::  Models and forecasts
+   :animate: fade-in-slide-down
+   :icon: list-unordered
+
+      .. list-table::
+         :widths: 20 80
+         :header-rows: 1
+
+         * - **Method/Attribute**
+           - **Description**
+         * - :attr:`~floatcsep.model.Model.get_forecast`
+           -
+
+.. dropdown::  Catalogs
+   :animate: fade-in-slide-down
+   :icon: list-unordered
+
+   .. list-table::
+      :widths: 20 80
+      :header-rows: 1
+
+      * - **Method/Attribute**
+        - **Description**
+      * - :attr:`~floatcsep.infrastructure.repositories.CatalogRepository.catalog`
+        -
+      * - :meth:`~floatcsep.infrastructure.repositories.CatalogRepository.get_test_cat`
+        -
+
+.. dropdown::  Results
+   :animate: fade-in-slide-down
+   :icon: list-unordered
+
+   .. list-table::
+      :widths: 20 80
+      :header-rows: 1
+
+      * - **Method/Attribute**
+        - **Description**
+      * - :meth:`~floatcsep.experiment.Experiment.read_results`
+        -
+      * - :meth:`~floatcsep.infrastructure.repositories.ResultsRepository.load_results`
+        -

docs/index.rst

@@ -38,6 +38,7 @@ floatCSEP: Floating Experiments
    :height: 48px
 
 .. |experiment| image:: https://img.icons8.com/pulsar-color/48/science-application.png
+   :target: intro/concepts.html
    :height: 48px
 
 .. |api| image:: https://img.icons8.com/nolan/64/code--v2.png

floatcsep/experiment.py

@@ -296,6 +296,12 @@ def get_model(self, name: str) -> Model:
             if model.name == name:
                 return model
 
+    def get_test(self, name: str) -> Model:
+        """Returns an Evaluation by its name string."""
+        for test in self.tests:
+            if test.name == name:
+                return test
+
     def stage_models(self) -> None:
         """
         Stages all the experiment's models. See :meth:`floatcsep.model.Model.stage`