Experiment Handler

class floatcsep.experiment.Experiment(name=None, time_config=None, region_config=None, catalog=None, models=None, tests=None, postprocess=None, default_test_kwargs=None, rundir='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 timewindows_ti() and timewindows_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

  • 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

  • catalog (str)

  • models (str)

  • tests (str)

  • rundir (str)

  • 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:

Model

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_input_cat(tstring, model)[source]

Filters the complete experiment catalog to an input sub-catalog filtered to the beginning of the test time-window.

Parameters:

  • tstring (str) – Time window string

  • model (Model) – Model to give the input catalog

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 sequentially 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_test_cat(tstring)[source]

Filters the complete experiment catalog to a test sub-catalog bounded by the test time-window. Writes it to filepath defined in Experiment.registry

Parameters:

tstring (str) – Time window string

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

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: