API Documentation

Commands

The main entrypoint functions from the Command Line Interface are:

`floatcsep`	Entry point for the floatCSEP command-line interface (CLI).
`run`	Core routine of the floatCSEP workflow.
`stage`	This function is a preliminary step that stages the models before the experiment is run.
`plot`	Generates plots for an already executed experiment.
`reproduce`	Reproduces the results of a previously run experiment.

Experiment

The Experiment class is the main handler of floatCSEP, which orchestrates the Model and Evaluation instances onto an experimental workflow. The class and its main methods are:

`Experiment`	Main class that handles an Experiment's context.
`Experiment.set_models`	Parse the models' configuration file/dict.
`Experiment.set_tests`	Parse the tests' configuration file/dict.
`Experiment.stage_models`	Stages all the experiment's models.
`Experiment.set_tasks`	Lazy definition of the experiment core tasks by wrapping instances, methods and arguments.
`Experiment.run`	Run the task tree.
`Experiment.read_results`	Reads an Evaluation result for a given time window and returns a list of the results for all tested models.
`Experiment.make_repr`	Creates a reproducibility configuration file, re-directing the forecasts/catalog paths, in order to reproduce the existing results and compare them with previous runs.

Model

The Model class is the handler of forecasts creation, storage and reading. The abstract and concrete classes, and their main methods are:

`Model`	The Model class represents a forecast generating system.
`Model.get_source`	Retrieves the model from a web repository
`Model.factory`	Factory method.
`TimeIndependentModel`	A Model whose forecast is invariant in time.
`TimeIndependentModel.get_forecast`	Wrapper that just returns a forecast when requested.
`TimeDependentModel.stage`	Retrieve model artifacts and Set up its interface with the experiment.
`TimeDependentModel.prepare_args`	When the model is a source code, the args file is a plain text file with the required input arguments.
`TimeDependentModel.create_forecast`	Creates a forecast from the model source and a given time window.
`TimeDependentModel.get_forecast`	Wrapper that returns a forecast, by accessing the model's forecast repository.

Evaluations

The Evaluation class is a wrapper for pycsep functions, encapsulating the multiple function, arguments, forecast and catalogs of the entire experiment. The class and main methods are:

`Evaluation`	Class representing a Scoring Test, which wraps the evaluation function, its arguments, parameters and hyperparameters.
`Evaluation.prepare_args`	Prepares the positional argument for the Evaluation function.
`Evaluation.compute`	Runs the test, structuring the arguments according to the test-typology/function-signature

Accessors

These are functions that access a model source from a web repository.

`from_zenodo`
`from_git`
`download_file`
`check_hash`

Helper Functions

These are the helper functions of floatCSEP

`parse_csep_func`	Search in pyCSEP and floatCSEP a function or method whose name matches the provided string.
`timewindow2str`	Converts a time window (list/tuple of datetimes) to a string that represents it.
`str2timewindow`	Converts a string representation of a time window into a list of datetimes representing the time window edges.
`parse_timedelta_string`	Parses a float or string representing the testing time window length.
`read_time_cfg`	Builds the temporal configuration of an experiment.
`read_region_cfg`	Builds the region configuration of an experiment.
`time_windows_ti`	Creates the testing intervals for a time-independent experiment.
`time_windows_td`	Creates the testing intervals for a time-dependent experiment.

Some additional plotting functions to pyCSEP are:

`plot_sequential_likelihood`	Plot of likelihood against time.
`magnitude_vs_time`	Scatter plot of the catalog magnitudes and origin times.
`sequential_likelihood`	Performs the likelihood test on Gridded Forecast using an Observed Catalog.
`sequential_information_gain`	Evaluates the Information Gain for multiple time-windows.
`vector_poisson_t_w_test`	Computes Student's t-test for the information gain per earthquake over.

Readers

A small wrapper for pyCSEP readers

`CatalogParser`	Parsers for `csep.core.catalogs.CSEPCatalog`.
`CatalogParser.ascii`	Load a pyCSEP catalog in the ASCII catalog format.
`CatalogParser.json`	Load a pyCSEP catalog from JSON.
`CatalogSerializer`	Serializers for `csep.core.catalogs.CSEPCatalog`.
`CatalogSerializer.ascii`	Serialize a catalog to the pyCSEP ASCII format.
`CatalogSerializer.json`	Serialize a catalog to JSON using the pyCSEP encoder.
`GriddedForecastParsers`	Parsers for grid-based earthquake forecasts.
`GriddedForecastParsers.dat`	Load a CSEP-style ASCII .dat gridded forecast.
`GriddedForecastParsers.xml`	Load a CSEP XML gridded forecast.
`GriddedForecastParsers.quadtree`	Load a quadtree forecast from CSV.
`GriddedForecastParsers.csv`	Load a gridded forecast from CSV.
`GriddedForecastParsers.hdf5`	Load a gridded forecast from an HDF5 container.
`CatalogForecastParsers`	Parsers for catalog-based forecasts stored on disk.
`CatalogForecastParsers.csv`	Load a catalog-based forecast from a CSV file.
`CatalogForecastParsers.load_hermes_catalog`	Loads hermes synthetic catalogs in csep-ascii format.
`HDF5Serializer.grid2hdf5`	Store a cartesian gridded forecast into an HDF5 file.
`check_format`	Basic format checks for supported forecast files.
`serialize`	Small CLI for testing gridded forecast parsers.

Environments

The computational environment managers for floatcsep.

`CondaManager`	Manages a conda (or mamba) environment, providing methods to create, check and manipulate conda environments specifically.
`CondaManager.create_environment`	Creates a conda environment using either an environment.yml file or the specified Python version in setup.py/setup.cfg or project/toml.
`CondaManager.env_exists`	Checks if the conda environment exists by querying the list of existing conda environments.
`CondaManager.install_dependencies`	Installs the necessary dependencies for the environment based on the specified configuration or requirements.
`CondaManager.run_command`	Runs a specified command within the conda environment.
`VenvManager`	Manages a virtual environment created using Python's venv module.
`CondaManager.create_environment`	Creates a conda environment using either an environment.yml file or the specified Python version in setup.py/setup.cfg or project/toml.
`CondaManager.env_exists`	Checks if the conda environment exists by querying the list of existing conda environments.
`CondaManager.install_dependencies`	Installs the necessary dependencies for the environment based on the specified configuration or requirements.
`CondaManager.run_command`	Runs a specified command within the conda environment.

Registries

The registries hold references to the access points (e.g., filepaths) of the experiment components (e.g., forecasts, catalogs, results, etc.), and allows to be aware of their status.

`ModelFileRegistry`	The class is responsible to handle the keys (in this case filepaths) to access model objects such as forecasts, input catalogs or argument/parameter files.
`ModelFileRegistry.fmt`	Returns: The extension or format of the forecast
`ModelFileRegistry.get_input_catalog_key`	Gets the filepath of the input catalog for a given sequence of keys (usually a timewindow string).
`ModelFileRegistry.get_forecast_key`	Gets the filepath of a forecast for a given sequence of keys (usually a timewindow string).
`ModelFileRegistry.get_args_key`	Gets the filepath of an arguments file for a given sequence of keys (usually a timewindow string).
`ModelFileRegistry.get_input_dir`	Returns the directory that contains the per-window input files (args/catalog).
`ModelFileRegistry.get_forecast_dir`	Returns the directory that contains the forecasts.
`ModelFileRegistry.get_args_template_path`	Path to the model’s canonical args template: <model.path>/input/<args_file>.
`ModelFileRegistry.forecast_exists`	Checks if forecasts exist for a sequence of time_windows
`ModelFileRegistry.build_tree`	Creates the run directory, and reads the file structure inside.
`ExperimentFileRegistry`	The class has the responsibility of managing the keys (based on models, timewindow and evaluation name strings) to the structure of the experiment inputs (catalogs, models etc) and results from the competing evaluations.
`ExperimentFileRegistry.add_model_registry`	Adds a model's ForecastRegistry to the ExperimentFileRegistry.
`ExperimentFileRegistry.get_model_registry`	Retrieves a model's ForecastRegistry from the ExperimentFileRegistry.
`ExperimentFileRegistry.get_result_key`	Gets the file path of an evaluation result.
`ExperimentFileRegistry.get_test_catalog_key`	Gets the file path of a testing catalog.
`ExperimentFileRegistry.get_figure_key`	Gets the file path of a result figure.
`ExperimentFileRegistry.result_exist`	Checks if a given test results exist
`ExperimentFileRegistry.build_tree`	Creates the run directory and reads the file structure inside.

Repositories

The repositories here are designed to store and access the experiment artifacts (results, catalogs, forecasts), abstracting the experiment logic from the pyCSEP io functionality.

`CatalogRepository`	The class handles the main and sub-catalogs from the experiment.
`CatalogRepository.set_main_catalog`	Sets the catalog to be used for the experiment.
`CatalogRepository.catalog`	Returns a CSEP catalog loaded from the given query function or a stored file if it exists.
`CatalogRepository.get_test_cat`	Filters the complete experiment catalog to a test sub-catalog bounded by the test time-window.
`CatalogRepository.set_test_cats`	Filters the complete experiment catalog to a test sub-catalog bounded by the test time-window.
`CatalogRepository.set_input_cats`	Filters the complete experiment catalog to input sub-catalog filtered to the beginning of the test time-window.
`CatalogRepository.filter_catalog`	Wrapper for pyCSEP catalog filters, to constrain a catalog to a given time and magnitude range, as well to a spatial region.
`GriddedForecastRepository`	The class is responsible to access (or store in memory) the gridded-based forecasts of a model.
`GriddedForecastRepository.load_forecast`	Returns a forecast object or a sequence of them for a set of time window strings.
`CatalogForecastRepository`	The class is responsible to access (or store in memory) the catalog-based forecasts of a model.
`CatalogForecastRepository.load_forecast`	Returns a forecast object or a sequence of them for a set of time window strings.
`ResultsRepository`	The class is responsible to access, read and write the results of a given evaluation
`ResultsRepository.load_results`	Reads an Evaluation result for a given time window and returns a list of the results for all tested models.
`ResultsRepository.write_result`	Writes the evaluation results using their method .to_dict() as json file.

Engine

The engine routines are designed for the execution of an experiment.

`Task`	Represents a unit of work to be executed later as part of a task graph.
`Task.run`	Executes the task by calling the method on the object instance with the stored arguments.
`Task.sign_match`	Checks whether the task matches a given function signature.
`TaskGraph`	Context manager of floatcsep workload distribution.
`TaskGraph.ntasks`	Returns the number of tasks currently in the graph.
`TaskGraph.add`	Adds a new task to the task graph.
`TaskGraph.add_dependency`	Adds a dependency to a task already within the graph.
`TaskGraph.run`	Executes in sequential all tasks in the task graph according to the order set in Experiment.set_tasks().

GitHub | CSEP Website | pyCSEP | Download PDF