Postprocess Module

This module includes utilities for handling plots and reporting.

Plot Handler

This section documents the plot_handler module.

floatcsep.postprocess.plot_handler.parse_plot_config(plot_config)[source]

Parses the configuration of a given plot directive, usually gotten from the experiment config.yml as:

postprocess:
    {plot_config}
Parameters:

plot_config (dict | str | bool) – The plotting directive, which can be a dictionary, a boolean, or a string. If it is a dictionary, then it is directly returned. If it is a boolean, then the default plotting configuration is used. If it is a string, then it is expected to be of the form {script_path}.py:{func_name}.

floatcsep.postprocess.plot_handler.parse_projection(proj_config)[source]

Retrieve projection configuration. e.g., as defined in the config file:

projection:
    Mercator:
        central_longitude: 0.0
Parameters:

proj_config (dict | str | bool)

floatcsep.postprocess.plot_handler.plot_catalogs(experiment)[source]

Plots and saves the testing catalogs.

It can be set specified in the experiment config.yml as:

postprocess:
    plot_catalog: True

or by specifying arguments as:

postprocess:
    plot_catalog:
        projection: Mercator
        basemap: google-satellite
        markersize: 2

The default is plot_catalog: True

Parameters:

experiment (Experiment) – The experiment instance, whose catalogs were already accessed and filtered.

Return type:

None

floatcsep.postprocess.plot_handler.plot_custom(experiment)[source]

Hook for user-based plotting functions. It corresponds to a function within a python file, specified in the experiment config.yml as:

postprocess:
    plot_custom: {module}.py:{function}
Parameters:

experiment (Experiment) – The experiment instance, whose models were already run and their forecast are located in the filesystem/database

floatcsep.postprocess.plot_handler.plot_forecasts(experiment)[source]

Plots and saves all the generated forecasts.

It can be set specified in the experiment config.yml as:

postprocess:
    plot_forecasts: True

or by specifying arguments as:

postprocess:
    plot_forecasts:
        projection: Mercator
        basemap: google-satellite
        cmap: magma

The default is plot_forecasts: True

Parameters:

experiment (Experiment) – The experiment instance, whose models were already run and their forecast are located in the filesystem/database

Return type:

None

floatcsep.postprocess.plot_handler.plot_results(experiment, dpi=300, show=False)[source]

Plots all evaluation results, according to the plotting functions given in the tests configuration file.

Parameters:

  • experiment (Experiment) – The experiment instance, whose results were already calculated.

  • dpi (int) – The resolution of the plots.

  • show (bool) – Whether to show the plots.

Return type:

None

Reporting

This section documents the reporting module.

class floatcsep.postprocess.reporting.MarkdownReport(root_dir)[source]

Bases: object

Helper class to build a Markdown report.

Parameters:

root_dir (str | Path)

add_figure(title, fig_path, level=2, ncols=1, text='', caption='', width=None)[source]

Add one or more figures to the report.

‘width’ is a fraction of the text width (0 < width <= 1). If None, a default is chosen automatically based on aspect ratio and ncols.

Parameters:
Return type:

None

add_heading(title, level=1, text='', add_toc=True)[source]

Add a heading with optional text and TOC entry.

Parameters:
Return type:

None

add_introduction(meta)[source]

Add an experiment metadata block from a dictionary.

Expects a mapping like:

{“Start date”: “…”, “End date”: “…”, …}

Parameters:

meta (dict)

Return type:

str

add_list(items)[source]

Add a bulleted list.

Return type:

None

add_table(data, use_header=True)[source]

Generate an HTML table from a 2D array-like structure.

Parameters:

use_header (bool)

Return type:

None

add_text(text)[source]

Add a paragraph from a list of lines.

Return type:

None

add_title(title, subtitle='')[source]

Add the main report title.

Layout:
  • Left: experiment name (subtitle) as main H1,

    title as a slightly smaller line below.

  • Right: floatCSEP logo, a bit larger.

Parameters:

subtitle (str)

Return type:

None

save(out_path)[source]

Write the Markdown report to disk.

Parameters:

out_path (str | Path)

Return type:

None

table_of_contents()[source]

Generate a Table of Contents from top-level headings (H2).

Return type:

None

to_markdown()[source]

Return the whole report as a single Markdown string.

Return type:

str

floatcsep.postprocess.reporting.custom_report(report_function, experiment)[source]

Run a user-provided report function from a script.

Parameters:
Return type:

None

floatcsep.postprocess.reporting.generate_report(experiment, timewindow=-1)[source]

Create the main experiment report (Markdown + PDF).

Parameters:
Return type:

None

floatcsep.postprocess.reporting.get_image_aspect(img_path)[source]

Return width/height aspect ratio for an image, or None on failure.

Parameters:

img_path (str | Path)

Return type:

float | None

floatcsep.postprocess.reporting.log = <Logger floatLogger (WARNING)>[source]

Use the MarkdownReport class to create output for the experiment.

Report includes:

  • plots of catalogs

  • plots of forecasts

  • evaluation results

  • metadata from the run

floatcsep.postprocess.reporting.markdown_to_pdf(markdown_source, pdf_path, base_url=None)[source]

Render Markdown (string or file) to PDF.

Parameters:

  • markdown_source (str | Path) – Markdown string or path to a .md file.

  • pdf_path (str | Path) – Output PDF path.

  • base_url (str | Path | None) – Base directory for resolving relative image paths, CSS, etc.

Return type:

Path

floatcsep.postprocess.reporting.reproducibility_report(exp_comparison)[source]

Create the reproducibility report in Markdown.

Parameters:

exp_comparison (ExperimentComparison)

Return type:

None

floatcsep.postprocess.reporting.width_fraction_from_aspect(aspect, ncols=1)[source]

Decide how much of the text width a figure should occupy, based on its aspect ratio (width / height) and the number of columns.

Returns a fraction in (0, 1], e.g. 0.6 = 60% of text width.

Parameters:
Return type:

float