Post-Process Options

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:

config.yml

 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

floatCSEP can quickly plot the spatial rates of used and/or created forecasts. The plot_forecast command wraps the functionality of the pyCSEP function plot_spatial_dataset(), used to plot mean rates (in log10) of both GriddedForecast and CatalogForecast. Most arguments of plot_forecast mimics those of plot_spatial_dataset() with some extra additions. These are summarized here:

Forecast plotting arguments

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: plot_forecasts: projection: Mercator or if the projection contains keyword arguments: 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. plot_forecasts: catalog: True and if the catalog needs to be customized: plot_forecasts: catalog: legend_loc: 1 legend_fontsize: 14 markercolor: blue See Plot Catalogs for customization options.

Important

By default, only the forecast corresponding to the last time window of a model is plotted. To plot all time windows, use all_time_windows: True

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 plot_catalog().

Catalog Plotting Arguments

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: plot_forecasts: projection: Mercator or if the projection contains keyword arguments: 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:

postprocess:
  plot_custom: plot_script.py:main

where the script path and a function within should be written as:

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 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 floatcsep.experiment.Experiment as unique argument:

Example custom plot script:

from floatcsep import Experiment

def main_function(experiment: Experiment):

    timewindows = experiment.timewindows
    model = experiment.get_model("pymock")

    rates = []
    start_times = []

    for timewindow in timewindows:
        forecast = model.get_forecast(timewindow)
        rates.append(forecast.event_counts)
        start_times = timewindow[0]

    fig, ax = plt.subplots(1, 1)
    ax.plot(start_times, rates)
    pyplot.savefig("results/pymock_rates.png")

In this way, the plot function can use all the Experiment attributes/methods to access catalogs, forecasts and test results. Please check the Postprocess API and the Tutorial G - Testing a Time-Dependent Model for an advanced use.

Custom Reporting

In addition to plotting, floatCSEP allows users to generate custom reports in Markdown format. The MarkdownReport class is designed to support the automatic creation of these reports, allowing users to assemble figures, text, and other results in a well-structured manner.

The custom report functionality can be invoked by specifying the following in the postprocess configuration:

Example:

config.yml

 postprocess:
   report: report_script.py:generate_report

This configuration specifies a custom python script with the following format:

report: {python_script_path}:{function_name}

The script must be located within the same directory as the configuration file and the function must receive an instance of floatcsep.experiment.Experiment instance as its only argument.

Example Custom Report Script::

from floatcsep.utils.reporting import MarkdownReport

def generate_report(experiment):
    # Create a MarkdownReport object
    report = MarkdownReport(out_name="custom_report.md")

    # Add an introduction based on the experiment details
    intro = {
        'simulation_name': experiment.name,
        'forecast_name': 'ETAS',
        'origin_time': experiment.start_date,
        'evaluation_time': experiment.end_date,
        'catalog_source': 'Observed Catalog',
        'num_simulations': 10000
    }
    report.add_introduction(intro)

    # Add some text
    report.add_text(['This report contains results from the ETAS model experiment.', 'Additional details below.'])


    # Add a figure (for example, forecast rates over time)
    report.add_figure(
        title="Forecast Rates",
        relative_filepaths=["results/2020-01-01_2020_01_02/forecasts/etas/forecast_rates.png"],
        ncols=1,
        caption="Forecasted seismicity rates over time."
    )

    # Save the report
    report.save(save_dir="results")

The MarkdownReport class provides various methods for assembling a report, allowing the user to format the content, insert figures, add tables, and generate text dynamically based on the results of an experiment.

For more advanced usage of report generation, please review the default floatCSEP report in the module floatcsep.postprocess.reporting.generate_report, an implementation example in the tutorial H - A Time-Dependent Experiment and the Postprocess API for an advance use.

Postprocess API

Here are some basic functionalities from floatCSEP to access catalogs, forecasts and results using python code:

Experiment and Catalogs

Method/Attribute	Description
`Experiment.timewindows`	A list of timewindows, where each is a pair of `datetime.datetime` objects representing the window boundaries.
`Experiment.start_date`	The starting `datetime.datetime` of the experiment.
`Experiment.end_date`	The end `datetime.datetime` of the experiment.
`Experiment.region`	A `csep.core.regions.CartesianGrid2D` object representing the spatial extent of the experiment.
`Experiment.mag_min`	The minimum magnitude of the experiment.
`Experiment.mag_max`	The maximum magnitude of the experiment.
`Experiment.mag_bin`	The magnitude bin size.
`Experiment.magnitudes`	A list of the magnitude bins of the experiment.
`Experiment.depth_min`	The minimum depth of the experiment.
`Experiment.depth_max`	The maximum depth of the experiment.
`Experiment.run_dir`	Returns the running directory of the experiment, where all evaluation results and figures are stored. Default is `results/` unless specified different in the `config.yml`.
`Experiment.models`	Returns a list containing all the experiment’s `Model` objects.
`Experiment.get_model(str)`	Returns a `Model` from its given name.
`Experiment.tests`	Returns a list containing all the experiment’s `Evaluation` objects.
`Experiment.get_test(str)`	Returns a `Evaluation` from its given name
`Experiment.catalog_repo`	A `CatalogRepository` which can access the experiments catalogs.
`Experiment.catalog_repo.catalog`	The main catalog of the experiment, of `csep.core.catalogs.CSEPCatalog` class.
`Experiment.catalog_repo.get_test_cat(timewindow)`	Returns the testing catalog for a given `timewindow` formatted as string. Use `floatcsep.utils.helpers.timewindow2str()` in case the window is a list of two `datetime.datetime` objects.

Models and forecasts

The experiment models can be accessed by using Experiment.models or Experiment.get_model(str).

Method/Attribute	Description
`Model.name`	Name of the model
`Model.get_forecast(timewindow)`	Returns the forecast for a given `timewindow` (formatted as string. Use `floatcsep.utils.helpers.timewindow2str()` in case the window is a list of two `datetime.datetime` objects). Example: model = experiment.get_model('etas') timewindow = experiment.timewindows[0] timewindow_str = timewindow2str(timewindow) model.get_forecast(timewindow_str)
`Model.registry.path`	Directory of the model file or source code.
`Model.registry.database`	Database path where forecasts are stored.
`TimeIndependentModel.forecast_unit`	The forecast unit for a time independent model.
`TimeDependentModel.func`	The function command to execute a time dependent source code.
`TimeDependentModel.func_kwargs()`	The keyword arguments of the model, passed to the arguments file.
`TimeDependentModel.registry.args_file`	The path of the arguments file. Default is `args.txt`.
`TimeDependentModel.registry.input_cat`	The path of the input catalog for the model execution.

Results

The experiment evaluations can be accessed by using Experiment.tests or Experiment.get_test(str).

Method/Attribute

Description

Evaluation.read_results(timewindow, models)

Returns the evaluation results for a given time window and models. Example usage:

test = experiment.get_test('n_test')  # get a test by its name
model = experiment.get_model('etas')  # get a model by its name
timewindow = experiment.timewindows[0]  # first time window
result = test.read_results(timewindow, model)

or from all models:

test = experiment.get_test('s_test')  # get a test by its name
timewindow = experiment.timewindows[-1]  # last time window
result = test.read_results(timewindow, experiment.models)

MarkdownReport Methods

Method	Description
`MarkdownReport.add_introduction()`	Adds an introductory section to the report. This typically contains metadata such as the simulation name, forecast model, evaluation time, and other summary information.
`MarkdownReport.add_text()`	Adds text to the report. Each entry corresponds to a paragraph, and the text argument should be provided as a list of strings.
`MarkdownReport.add_figure()`	Inserts one or more figures into the report. You can specify the title, filepaths to the figures, and an optional caption. Figures are arranged in rows and columns as specified by the `ncols` argument.
`MarkdownReport.add_table()`	Creates a table in the report. The table data should be provided as a list of rows, where each row is a list of cell contents.
`MarkdownReport.add_list()`	Adds a bulleted list of items to the report.
`MarkdownReport.add_heading()`	Inserts a heading into the report. The `level` argument controls the heading level (1 for top-level, 2 for subheading, etc.).
`MarkdownReport.table_of_contents()`	Generates a table of contents based on the headings and sections included in the report so far. It will be automatically placed at the beginning of the report if an introduction is included.
`MarkdownReport.save()`	Saves the Markdown report to a specified directory.

GitHub | CSEP Website | pyCSEP | Download PDF