Utilities Module

This module includes commonly used utilities throughout the floatCSEP packages.

Helper Functions

This section documents the helpers module.

floatcsep.utils.helpers.magnitude_vs_time(catalog)[source]

Simple magnitude vs. time plot (TBI in pyCSEP)

Parameters:

catalog – Catalog to be plotted

Returns:

Ax object

floatcsep.utils.helpers.parse_csep_func(func)[source]

Search in pyCSEP and floatCSEP a function or method whose name matches the provided string.

Parameters:

func (str, obj) – representing the name of the pycsep/floatcsep function or method

Returns:

The callable function/method object. If it was already callable, returns the same input

floatcsep.utils.helpers.parse_nested_dicts(nested_dict)[source]

Parses nested dictionaries to return appropriate parsing on each element

Parameters:

nested_dict (dict)

Return type:

dict

floatcsep.utils.helpers.parse_timedelta_string(window, exp_class='ti')[source]

Parses a float or string representing the testing time window length.

Note

Time-independent experiments defaults to year as time unit whereas time-dependent to days

Parameters:

  • window (str, int) – length of the time window

  • exp_class (str) – experiment class

Returns:

Formatted str representing the length and unit (year, month, week, day) of the time window

floatcsep.utils.helpers.plot_matrix_comparative_test(evaluation_results, p=0.05, order=True, plot_args={})[source]

Produces matrix plot for comparative tests for all models (TBI in pyCSEP)

Parameters:

  • evaluation_results (list of result objects) – paired t-test results

  • p (float) – significance level

  • order (bool) – columns/rows ordered by ranking

Returns:

handle for figure

Return type:

ax (matplotlib.Axes)

floatcsep.utils.helpers.plot_sequential_likelihood(evaluation_results, plot_args=None)[source]

Plot of likelihood against time.

Parameters:

  • evaluation_results (list) – An evaluation result containing the likelihoods

  • plot_args (dict) – A configuration dictionary for the plotting.

Returns:

Ax object

floatcsep.utils.helpers.read_region_cfg(region_config, **kwargs)[source]

Builds the region configuration of an experiment.

Parameters:

  • region_config (dict) – Dictionary containing the explicit region attributes of the experiment (see _attrs local variable)

  • **kwargs – Only the keywords contained in the local variable _attrs are captured. This ensures to capture the keywords passed to an Experiment object

Returns:

A dictionary containing the region attributes of the experiment

floatcsep.utils.helpers.read_time_cfg(time_config, **kwargs)[source]

Builds the temporal configuration of an experiment.

Parameters:

  • time_config (dict) – Dictionary containing the explicit temporal attributes of the experiment (see _attrs local variable)

  • **kwargs – Only the keywords contained in the local variable _attrs are captured. This ensures to capture the keywords passed to an Experiment object

Returns:

A dictionary containing the experiment time attributes and the time windows to be evaluated

floatcsep.utils.helpers.sequential_information_gain(gridded_forecasts, benchmark_forecasts, observed_catalogs, seed=None, random_numbers=None)[source]

Evaluates the Information Gain for multiple time-windows.

Parameters:

  • gridded_forecasts (Sequence[GriddedForecast]) – list csep.core.forecasts.GriddedForecast

  • benchmark_forecasts (Sequence[GriddedForecast]) – list csep.core.forecasts.GriddedForecast

  • observed_catalogs (Sequence[CSEPCatalog]) – list csep.core.catalogs.Catalog

  • seed (int) – used fore reproducibility, and testing

  • random_numbers (numpy.ndarray) – random numbers used to override the random number generation injection point for testing.

Returns:

csep.core.evaluations.EvaluationResult

Return type:

evaluation_result

floatcsep.utils.helpers.sequential_likelihood(gridded_forecasts, observed_catalogs, seed=None, random_numbers=None)[source]

Performs the likelihood test on Gridded Forecast using an Observed Catalog.

Note: The forecast and the observations should be scaled to the same time period before calling this function. This increases transparency as no assumptions are being made about the length of the forecasts. This is particularly important for gridded forecasts that supply their forecasts as rates.

Parameters:

  • gridded_forecasts (Sequence[GriddedForecast]) – list csep.core.forecasts.GriddedForecast

  • observed_catalogs (Sequence[CSEPCatalog]) – list csep.core.catalogs.Catalog

  • seed (int) – used fore reproducibility, and testing

  • random_numbers (numpy.ndarray) – random numbers used to override the random number generation injection point for testing.

Returns:

csep.core.evaluations.EvaluationResult

Return type:

evaluation_result

floatcsep.utils.helpers.str2timewindow(tw_string)[source]

Converts a string representation of a time window into a list of datetimes representing the time window edges.

Parameters:

tw_string (str | Sequence[str]) – A string representing the time window (‘{datetime}_{datetime}’)

Returns:

A list (of list) containing the pair of datetimes objects

Return type:

Sequence[datetime] | Sequence[Sequence[datetime]]

floatcsep.utils.helpers.time_windows_td(start_date=None, end_date=None, timeintervals=None, timehorizon=None, timeoffset=None, **_)[source]

Creates the testing intervals for a time-dependent experiment.

Note

The following are combinations are possible:

  • (start_date, end_date, timeintervals)

  • (start_date, end_date, timehorizon)

  • (start_date, timeintervals, timehorizon)

  • (start_date, end_date, timehorizon, timeoffset)

  • (start_date, timeinvervals, timehorizon, timeoffset)

Parameters:

  • start_date (datetime.datetime) – Start of the experiment

  • end_date (datetime.datetime) – End of the experiment

  • timeintervals (int) – number of intervals to discretize the time span

  • timehorizon (str) – time length of each time window

  • timeoffset (str) – Offset between consecutive forecast. if None or timeoffset=timehorizon, windows are non-overlapping

Returns:

List of tuples containing the lower and upper boundaries of each testing window, as datetime.datetime.

floatcsep.utils.helpers.time_windows_ti(start_date=None, end_date=None, intervals=None, horizon=None, growth='incremental', **_)[source]

Creates the testing intervals for a time-independent experiment.

Note

The following argument combinations are possible:

  • (start_date, end_date)

  • (start_date, end_date, timeintervals)

  • (start_date, end_date, timehorizon)

  • (start_date, timeintervals, timehorizon)

Parameters:

  • start_date (datetime.datetime) – Start of the experiment

  • end_date (datetime.datetime) – End of the experiment

  • intervals (int) – number of intervals to discretize the time span

  • horizon (str) – time length of each interval

  • growth (str) – incremental or cumulative time windows

Returns:

List of tuples containing the lower and upper boundaries of each testing window, as datetime.datetime.

floatcsep.utils.helpers.timewindow2str(datetimes)[source]

Converts a time window (list/tuple of datetimes) to a string that represents it. Can be a single timewindow or a list of time windows.

Parameters:

datetimes (Sequence) – A sequence (of sequences) of datetimes, representing a list of time_windows

Returns:

A sequence of strings for each time window

Return type:

str | list[str]

floatcsep.utils.helpers.vector_poisson_t_w_test(forecast, benchmark_forecasts, catalog)[source]

Computes Student’s t-test for the information gain per earthquake over.

a list of forecasts and w-test for normality

Uses all ref_forecasts to perform pair-wise t-tests against the forecast provided to the function.

Parameters:

  • forecast (csep.GriddedForecast) – forecast to evaluate

  • benchmark_forecasts (list of csep.GriddedForecast) – list of forecasts to evaluate

  • catalog (csep.AbstractBaseCatalog) – evaluation catalog filtered consistent with forecast

  • **kwargs – additional default arguments

Returns:

iterable of evaluation results

Return type:

results (list of csep.EvaluationResult)

Accessors

This section documents the accessors module.

floatcsep.utils.accessors.check_hash(filename, checksum)[source]

Checks if existing file hash matches checksum from url.

floatcsep.utils.accessors.download_file(url, filename)[source]

Downloads files (from zenodo).

Parameters:

  • url (str) – the url where the file is located

  • filename (str) – the filename required.

Return type:

None

floatcsep.utils.accessors.from_git(url, path, branch=None, depth=1, force=False, **kwargs)[source]

Clones a shallow repository from a git url.

Parameters:

  • url (str) – url of the repository

  • path (str) – path/folder where to clone the repo

  • branch (str) – repository’s branch to clone (default: main)

  • depth (int) – depth history of commits

  • force (bool) – If True, deletes existing path before cloning

  • **kwargs – keyword args passed to Repo.clone_from

Returns:

the pygit repository

floatcsep.utils.accessors.from_zenodo(record_id, folder, force=False)[source]

Download data from a Zenodo repository.

Downloads if file does not exist, checksum has changed in local respect to url or force

Parameters:

  • record_id – corresponding to the Zenodo repository

  • folder – where the repository files will be downloaded

  • force – force download even if file exists and checksum passes

Returns:

Readers

This section documents the readers module.