Experiment Handler

class floatcsep.experiment.Experiment(name=None, doi=None, authors=None, journal=None, manuscript_doi=None, catalog_doi=None, last_run=None, floatcsep_version=None, pycsep_version=None, exp_time=None, LICENSE=None, time_config=None, region_config=None, catalog=None, models=None, tests=None, postprocess=None, default_test_kwargs=None, run_dir='results', run_mode='sequential', stage_dir='results', report_hook=None, **kwargs)[source]

Bases: object

Main class that handles an Experiment’s context. Contains all the specifications, instructions and methods to carry out an experiment.

Parameters:

  • name (str) – Experiment name

  • time_config (dict) –

    Contains all the temporal specifications. It can contain the following keys:

    • start_date (datetime.datetime): Experiment start date

    • end_date (datetime.datetime): Experiment end date

    • exp_class (str): ti (Time-Independent) or td (Time-Dependent)

    • intervals (int): Number of testing intervals/windows

    • horizon (str, float): Time length of the forecasts (e.g. 1, 10, 1 year, 2 days). ti defaults to years, td to days.

    • growth (str): incremental or cumulative

    • offset (float): recurrence of forecast creation.

    For further details, see time_windows_ti() and time_windows_td()

  • region_config (dict) –

    Contains all the spatial and magnitude specifications. It must contain the following keys:

    • region (str, csep.core.regions.CartesianGrid2D): The geographical region, which can be specified as: (i) the name of a csep/floatcsep default region function (e.g. california_relm_region()) (ii) the name of a user function or (iii) the path to a lat/lon file

    • mag_min (float): Minimum magnitude of the experiment

    • mag_max (float): Maximum magnitude of the experiment

    • mag_bin (float): Magnitud bin size

    • magnitudes (list, numpy.ndarray): Explicit magnitude bins

    • depth_min (float): Minimum depth. Defaults to -2

    • depth_max (float): Maximum depth. Defaults to 6000

  • model_config (str) – Path to the models’ configuration file

  • test_config (str) – Path to the evaluations’ configuration file

  • run_mode (str) – ‘sequential’ or ‘parallel’

  • default_test_kwargs (dict) – Default values for the testing (seed, number of simulations, etc.)

  • postprocess (dict) – Contains the instruction for postprocessing (e.g. plot forecasts, catalogs)

  • **kwargs – see Note

  • doi (str)

  • authors (str)

  • journal (str)

  • manuscript_doi (str)

  • catalog_doi (str)

  • last_run (str)

  • floatcsep_version (str)

  • pycsep_version (str)

  • exp_time (str)

  • LICENSE (str)

  • catalog (str)

  • models (str)

  • tests (str)

  • run_dir (str)

  • stage_dir (...)

  • report_hook (dict)

Note

Instead of using time_config and region_config, an Experiment can be instantiated using these dicts as keywords. (e.g. Experiment( **time_config, **region_config), Experiment(start_date=start_date, intervals=1, region='csep-italy', ...)

as_dict(extra=(), extended=False)[source]

Converts an Experiment instance into a dictionary.

Parameters:

  • extra (Sequence) – additional instance attribute to include in the dictionary.

  • extended – Include explicit parameters

Returns:

A dictionary with serialized instance’s attributes, which are floatCSEP readable

Return type:

dict

classmethod from_yml(config_yml, repr_dir=None, **kwargs)[source]

Initializes an experiment from a .yml file. It must contain the.

attributes described in the Experiment, read_time_config() and read_region_config() descriptions

Parameters:

  • config_yml (str) – The path to the .yml file

  • repr_dir (str) – folder where to reproduce results

Returns:

An Experiment class instance

get_model(name)[source]

Returns a Model by its name string.

Parameters:

name (str)

Return type:

Model

get_test(name)[source]

Returns an Evaluation by its name string.

Parameters:

name (str)

Return type:

Evaluation

make_repr()[source]

Creates a reproducibility configuration file, re-directing the forecasts/catalog paths, in order to reproduce the existing results and compare them with previous runs.

Return type:

None

read_results(test, window)[source]

Reads an Evaluation result for a given time window and returns a list of the results for all tested models.

Parameters:
Return type:

List

run()[source]

Run the task tree.

Return type:

None

set_models(model_config, order=None)[source]

Parse the models’ configuration file/dict. Instantiates all the models as floatcsep.model.Model and store them into Experiment.models.

Parameters:

  • model_config (dict, list, str) – configuration file or dictionary containing the model initialization attributes, as defined in Model()

  • order (list) – desired order of models

Return type:

List

set_tasks()[source]

Lazy definition of the experiment core tasks by wrapping instances, methods and arguments. Creates a graph with task nodes, while assigning task-parents to each node, depending on each Evaluation signature. The tasks can then be run in sequential as a list or asynchronous using the graph’s node dependencies. For instance:

  • A forecast can only be made if catalog was filtered to its window

  • A consistency test can be run if the forecast exists in a window

  • A comparison test requires the forecast and ref forecast

  • A sequential test requires the forecasts exist for all windows

  • A batch test requires all forecast exist for a given window.

Return type:

None

set_tests(test_config)[source]

Parse the tests’ configuration file/dict. Instantiate them as floatcsep.evaluation.Evaluation and store them into Experiment.tests.

Parameters:

test_config (dict, list, str) – configuration file or dictionary containing the evaluation initialization attributes, as defined in Evaluation()

Return type:

list

set_tree()[source]
stage_models()[source]

Stages all the experiment’s models. See floatcsep.model.Model.stage()

Return type:

None

to_yml(filename, **kwargs)[source]

Serializes the Experiment instance into a .yml file.

Note

This instance can then be reinstantiated using from_yml()

Parameters:

  • filename (str) – Name of the file onto which dump the instance

  • **kwargs – Pass to as_dict()

Return type:

None

Returns: