Model Classes

class floatcsep.model.Model(name, zenodo_id=None, giturl=None, repo_hash=None, authors=None, doi=None, **kwargs)[source]

Bases: ABC

The Model class represents a forecast generating system. It can represent a source code, a collection or a single forecast, etc. A Model can be instantiated from either the filesystem or host repositories.

Parameters:

  • name (str) – Name of the model

  • model_path (str) – Relative path of the model (file or code) to the work directory

  • zenodo_id (int) – Zenodo ID or record of the Model

  • giturl (str) – Link to a git repository

  • repo_hash (str) – Specific commit/branch/tag hash.

  • authors (list[str]) – Authors’ names metadata

  • doi (str) – Digital Object Identifier metadata:

as_dict(excluded=('name', 'repository', 'workdir', 'environment'))[source]
Returns:

Dictionary with relevant attributes. Model can be re-instantiated from this dict

abstractmethod create_forecast(tstring, **kwargs)[source]

Creates a forecast based on the model’s logic.

Parameters:

tstring (str)

Return type:

None

classmethod factory(model_cfg)[source]

Factory method. Instantiate first on any explicit option provided in the model configuration.

Parameters:

model_cfg (dict)

Return type:

Model

classmethod from_dict(record, **kwargs)[source]

Returns a Model instance from a dictionary containing the required attributes. Can be used to quickly instantiate from a .yml file.

Parameters:

record (dict) –

Contains the keywords from the __init__ method.

Note

Must have either an explicit key name, or it must have exactly one key with the model’s name, whose values are the remaining __init__ keywords.

Returns:

A Model instance

abstractmethod get_forecast(tstring, region=None)[source]

Retrieves the forecast based on a time window.

Parameters:

tstring (str)

abstractmethod get_source()[source]

Retrieves the model from a web repository

abstractmethod stage(time_windows=None)[source]

Prepares the stage for a model run.

Return type:

None

class floatcsep.model.TimeIndependentModel(name, model_path, forecast_unit=1, store_db=False, **kwargs)[source]

Bases: Model

A Model whose forecast is invariant in time. A TimeIndependentModel is commonly represented by a single forecast as static data.

Parameters:

  • name (str) – The name of the model.

  • model_path (str) – The path to the model data.

  • forecast_unit (float) – The unit of time for the forecast.

  • store_db (bool) – flag to indicate whether to store the model in a database.

create_forecast(tstring, **kwargs)[source]

Creates a forecast from the model source and a given time window.

Note

Dummy function for this class, although eventually could also be a source code (e.g., a Smoothed-Seismicity-Model built from the input-catalog).

Parameters:

tstring (str)

Return type:

None

get_forecast(tstring=None, region=None)[source]

Wrapper that just returns a forecast when requested.

Parameters:

tstring (str | list)

Return type:

GriddedForecast | List[GriddedForecast]

get_source()[source]

Fetch a single-file forecast into the model directory

Return type:

None

stage(time_windows=None, **kwargs)[source]

Acquire the forecast data if it is not in the file system. Sets the paths internally (or database pointers) to the forecast data.

Parameters:

time_windows (list) – time_windows that the forecast data represents.

Return type:

None

class floatcsep.model.TimeDependentModel(name, model_path, func=None, func_kwargs=None, args_file='args.txt', input_cat='catalog.csv', fmt='csv', **kwargs)[source]

Bases: Model

Model that creates varying forecasts depending on a time window. Requires either a collection of Forecasts or a function/source code that returns a Forecast.

Parameters:

  • name (str) – The name of the model

  • model_path (str) – The path to either the source code, or the folder containing static forecasts.

  • func (str | Callable) – A function/command that runs the model.

  • func_kwargs (dict) – The keyword arguments to run the model. They are usually (over)written into the file {model_path}/input/{args_file}

  • args_file (str) – Name of the arguments file that will be used to create forecasts

  • input_cat (str) – Name of the file that will be used as input catalog to create forecasts

  • **kwargs – Additional keyword parameters, such as a prefix (str) for the resulting forecast file paths, args_file (str) as the path for the model arguments file or input_cat that indicates where the input catalog will be placed for the model.

  • fmt (str)

create_forecast(tstring, **kwargs)[source]

Creates a forecast from the model source and a given time window.

Note

The argument tstring is formatted according to how the Experiment handles time_windows, specified in the functions timewindow2str() and str2timewindow()

Parameters:

  • tstring (str) – String representing the start and end of the forecast, formatted as ‘YY1-MM1-DD1_YY2-MM2-DD2’.

  • **kwargs

Return type:

None

get_forecast(tstring=None, region=None)[source]

Wrapper that returns a forecast, by accessing the model’s forecast repository.

Note

The argument tstring is formatted according to how the Experiment handles time_windows, specified in the functions timewindow2str() and str2timewindow()

Parameters:

  • tstring (str | list) – String representing the start and end of the forecast, formatted as ‘YY1-MM1-DD1_YY2-MM2-DD2’.

  • region – String representing the region for which to return a forecast. If None, will return a forecast for all regions.

Return type:

GriddedForecast | CatalogForecast | List[GriddedForecast] | List[CatalogForecast]

get_source(zenodo_id=None, giturl=None, **kwargs)[source]

Search, download or clone the model source in the filesystem from git or zenodo, respectively.

Parameters:

  • zenodo_id (int) – Zenodo identifier of the repository. Usually as https://zenodo.org/record/{zenodo_id}

  • giturl (str) – git remote repository URL from which to clone the source

  • **kwargs – see from_zenodo() and from_git()

Return type:

None

prepare_args(start, end, **kwargs)[source]

When the model is a source code, the args file is a plain text file with the required input arguments. At minimum, it consists of the start and end of the forecast timewindow, but it can also contain other arguments (e.g., minimum magnitude, number of simulations, cutoff learning magnitude, etc.)

Parameters:

  • start (datetime) – start date of the forecast timewindow

  • end (datetime) – end date of the forecast timewindow

  • **kwargs – represents additional model arguments (name/value pair)

Return type:

None

prepare_extra_input(start, end, **kwargs)[source]
When the model is a source code, and the run is in parallel, additional data located in

the model’s input folder is copied onto the mounted folder (in /tmp or /results)

Parameters:

  • start (datetime) – start date of the forecast timewindow

  • end (datetime) – end date of the forecast timewindow

  • **kwargs – represents additional model arguments (name/value pair)

Return type:

None

stage(time_windows=None, run_mode='sequential', stage_dir='results', run_id='run')[source]

Retrieve model artifacts and Set up its interface with the experiment.

  1. Get the model from filesystem, Zenodo or Git. Prepares the directory

  2. If source code, creates the computational environment (conda, venv or Docker)

  3. Prepares the registry tree: filepaths/keys corresponding to existing forecasts and those to be generated, as well as input catalog and arguments file.

Return type:

None