API Reference

This contains a reference document to the PyCSEP API.

Loading catalogs, forecasts and results

load_catalog(filename[, type, format, ...])	General function to load single catalog
query_comcat(start_time, end_time[, ...])	Access Comcat catalog through web service
query_bsi(start_time, end_time[, ...])	Access BSI catalog through web service
query_gns(start_time, end_time[, ...])	Access GNS Science catalog through web service
query_gcmt(start_time, end_time[, ...])
load_gridded_forecast(fname[, loader])	Loads grid based forecast from hard-disk.
load_catalog_forecast(fname[, ...])	General function to handle loading catalog forecasts.
load_stochastic_event_sets(filename[, type, ...])	General function to load stochastic event sets
load_evaluation_result(fname)	Load evaluation result stored as json file

Catalogs

Catalog operations are defined using AbstractBaseCatalog class.

AbstractBaseCatalog([filename, data, ...])	Abstract catalog base class for PyCSEP catalogs.
CSEPCatalog(**kwargs)	Standard catalog class for PyCSEP catalog operations.
UCERF3Catalog(**kwargs)	Catalog written from UCERF3-ETAS binary format

Catalog operations

Input and output operations for catalogs:

CSEPCatalog.to_dict()	Serializes class to json dictionary.
CSEPCatalog.from_dict(adict, **kwargs)	Creates a class from the dictionary representation of the class state.
CSEPCatalog.to_dataframe([with_datetime])	Returns pandas Dataframe describing the catalog.
CSEPCatalog.from_dataframe(df, **kwargs)	Creates catalog from dataframe.
CSEPCatalog.write_json(filename)	Writes catalog to json file
CSEPCatalog.load_json(filename, **kwargs)	Loads catalog from JSON file
CSEPCatalog.load_catalog(filename[, loader])	Loads catalog stored in CSEP1 ascii format
CSEPCatalog.write_ascii(filename[, ...])	Write catalog in csep2 ascii format.
CSEPCatalog.load_ascii_catalogs(filename, ...)	Loads multiple catalogs in csep-ascii format.
CSEPCatalog.get_csep_format()	Returns CSEP format for a catalog
CSEPCatalog.plot([ax, show, extent, set_global])	Plots the catalog epicenters.

Accessing event information:

CSEPCatalog.event_count	Number of events in catalog
CSEPCatalog.get_magnitudes()	Returns magnitudes of all events in catalog
CSEPCatalog.get_longitudes()	Returns longitudes of all events in catalog
CSEPCatalog.get_latitudes()	Returns latitudes of all events in catalog
CSEPCatalog.get_depths()	Returns depths of all events in catalog
CSEPCatalog.get_epoch_times()	Returns the datetime of the event as the UTC epoch time (aka unix timestamp)
CSEPCatalog.get_datetimes()	Returns datetime object from timestamp representation in catalog
CSEPCatalog.get_cumulative_number_of_events()	Returns the cumulative number of events in the catalog.

Filtering and binning:

CSEPCatalog.filter([statements, in_place])	Filters the catalog based on statements.
CSEPCatalog.filter_spatial([region, ...])	Removes events outside of the region.
CSEPCatalog.apply_mct(m_main, event_epoch[, mc])	Applies time-dependent magnitude of completeness following a mainshock.
CSEPCatalog.spatial_counts()	Returns counts of events within discrete spatial region
CSEPCatalog.magnitude_counts([mag_bins, ...])	Computes the count of events within magnitude bins
CSEPCatalog.spatial_magnitude_counts([...])	Return counts of events in space-magnitude bins.

Other utilities:

CSEPCatalog.update_catalog_stats()	Compute summary statistics of events in catalog
CSEPCatalog.length_in_seconds()	Returns catalog length in seconds assuming that the catalog is sorted by time.
CSEPCatalog.get_bvalue([mag_bins, return_error])	Estimates the b-value of a catalog from Marzocchi and Sandri (2003).

Forecasts

PyCSEP provides classes to interact with catalog and grid based Forecasts

GriddedForecast([start_time, end_time])	Class to represent grid-based forecasts
CatalogForecast([filename, catalogs, name, ...])	Catalog based forecast defined as a family of stochastic event sets.

Gridded forecast methods:

GriddedForecast.data	Contains the spatio-magnitude forecast as 2d numpy.ndarray.
GriddedForecast.event_count	Returns a sum of the forecast data
GriddedForecast.sum()	Sums over all of the forecast data
GriddedForecast.magnitudes
GriddedForecast.min_magnitude	Returns the lowest magnitude bin edge
GriddedForecast.magnitude_counts()	Returns counts of events in magnitude bins
GriddedForecast.spatial_counts([cartesian])	Integrates over magnitudes to return the spatial version of the forecast.
GriddedForecast.get_latitudes()	Returns the latitude of the lower left node of the spatial grid
GriddedForecast.get_longitudes()	Returns the lognitude of the lower left node of the spatial grid
GriddedForecast.get_magnitudes()	Returns the left edge of the magnitude bins.
GriddedForecast.get_index_of(lons, lats)	Returns the index of lons, lats in spatial region
GriddedForecast.get_magnitude_index(mags[, tol])	Returns the indices into the magnitude bins of selected magnitudes
GriddedForecast.load_ascii(ascii_fname[, ...])	Reads Forecast file from CSEP1 ascii format.
GriddedForecast.from_custom(func[, func_args])	Creates MarkedGriddedDataSet class from custom parsing function.
GriddedForecast.get_rates(lons, lats, mags)	Returns the rate associated with a longitude, latitude, and magnitude.
GriddedForecast.target_event_rates(...[, scale])	Generates data set of target event rates given a target data.
GriddedForecast.scale_to_test_date(test_datetime)	Scales forecast data by the fraction of the date.
GriddedForecast.plot([ax, show, log, ...])	Plot the spatial rate of the forecast

Catalog forecast methods:

CatalogForecast.magnitudes	Returns left bin-edges of magnitude bins
CatalogForecast.min_magnitude	Returns smallest magnitude bin edge of forecast
CatalogForecast.spatial_counts([cartesian])	Returns the expected spatial counts from forecast
CatalogForecast.magnitude_counts()	Returns expected magnitude counts from forecast
CatalogForecast.get_expected_rates([verbose])	Compute the expected rates in space-magnitude bins
CatalogForecast.get_dataframe()	Return a single dataframe with all of the events from all of the catalogs.
CatalogForecast.write_ascii(fname[, header, ...])	Writes data forecast to ASCII format
CatalogForecast.load_ascii(fname, **kwargs)	Loads ASCII format for data forecast.

Evaluations

PyCSEP provides implementations of evaluations for both catalog-based forecasts and grid-based forecasts.

Catalog-based forecast evaluations:

number_test(forecast, observed_catalog[, ...])	Performs the number test on a catalog-based forecast.
spatial_test(forecast, observed_catalog[, ...])	Performs spatial test for catalog-based forecasts.
magnitude_test(forecast, observed_catalog[, ...])	Performs magnitude test for catalog-based forecasts
resampled_magnitude_test(forecast, ...[, ...])	Performs the resampled magnitude test for catalog-based forecasts (Serafini et al., 2024), which corrects the bias from the original M-test implementation to the total N of events.
MLL_magnitude_test(forecast, observed_catalog)	Implements the modified Multinomial log-likelihood ratio (MLL) magnitude test (Serafini et al., 2024).
pseudolikelihood_test(forecast, observed_catalog)	Performs the spatial pseudolikelihood test for catalog forecasts.
calibration_test(evaluation_results[, delta_1])	Perform the calibration test by computing a Kilmogorov-Smirnov test of the observed quantiles against a uniform distribution.

Grid-based forecast evaluations:

number_test(gridded_forecast, observed_catalog)	Computes "N-Test" on a gridded forecast.
magnitude_test(gridded_forecast, ...[, ...])	Performs the Magnitude Test on a Gridded Forecast using an observed catalog.
spatial_test(gridded_forecast, observed_catalog)	Performs the Spatial Test on the Forecast using the Observed Catalogs.
likelihood_test(gridded_forecast, ...[, ...])	Performs the likelihood test on Gridded Forecast using an Observed Catalog.
conditional_likelihood_test(...[, ...])	Performs the conditional likelihood test on Gridded Forecast using an Observed Catalog.
paired_t_test(forecast, benchmark_forecast, ...)	Computes the t-test for gridded earthquake forecasts.
w_test(gridded_forecast1, gridded_forecast2, ...)	Calculate the Single Sample Wilcoxon signed-rank test between two gridded forecasts.

Evaluation result base class

EvaluationResult([test_distribution, name, ...])

Regions

PyCSEP includes commonly used CSEP testing regions and classes that facilitate working with gridded data sets. This module is early in development and help is welcome here!

Region class(es):

CartesianGrid2D(polygons, dh[, name, mask, ...])	Represents a 2D cartesian gridded region.
CartesianGrid2D.from_origins(origins[, dh, ...])	Creates instance of class from 2d numpy.array of lon/lat origins.
CartesianGrid2D.from_dict(adict)	Creates a region object from a dictionary
CartesianGrid2D.to_dict()
CartesianGrid2D.get_cartesian(data)	Returns 2d ndrray representation of the data set, corresponding to the bounding box.
CartesianGrid2D.get_cell_area()	Compute the area of each polygon in sq.
CartesianGrid2D.get_index_of(lons, lats)	Returns the index of lons, lats in self.polygons
QuadtreeGrid2D(polygons, quadkeys, bounds[, ...])	Respresents a 2D quadtree gridded region.
QuadtreeGrid2D.from_catalog(catalog, threshold)	Creates instance of class from 2d numpy.array of lon/lat of Catalog.
QuadtreeGrid2D.from_single_resolution(zoom)	Creates instance of class at single-resolution using provided zoom-level.
QuadtreeGrid2D.from_quadkeys(quadk[, ...])	Creates instance of class from available quadtree grid.
QuadtreeGrid2D.get_cartesian(data)	Returns 2d ndrray representation of the data set, corresponding to the bounding box.

Testing regions:

california_relm_region([dh_scale, ...])	Returns class representing California testing region.
california_relm_collection_region([...])	Return collection region for California RELM testing region
italy_csep_region([dh_scale, magnitudes, ...])	Returns class representing Italian testing region.
italy_csep_collection_region([dh_scale, ...])	Return collection region for Italy CSEP collection region
nz_csep_region([dh_scale, magnitudes, name, ...])	Return collection region for the New Zealand CSEP testing region
nz_csep_collection_region([dh_scale, ...])	Return collection region for the New Zealand CSEP collection region
global_region([dh, name, magnitudes])	Creates a global region used for evaluating gridded forecasts on the global scale.

Region utilities:

magnitude_bins(start_magnitude, ...)	Returns array holding magnitude bin edges.
create_space_magnitude_region(region, magnitudes)	Simple wrapper to create space-magnitude region
parse_csep_template(xml_filename)	Reads CSEP XML template file and returns the lat/lon values for the forecast.
increase_grid_resolution(points, dh, factor)	Takes a set of origin points and returns a new set with higher grid resolution.
masked_region(region, polygon)	Build a new region based off the coordinates in the polygon.
generate_aftershock_region(mainshock_mw, ...)	Creates a spatial region around a given epicenter

Plotting

PyCSEP offers multiple plot functionalities to visually explore forecasts, catalogs and results.

Exploratory plotting:

plot_magnitude_versus_time(catalog[, color, ...])	Scatter plot of the catalog magnitudes and origin times.
plot_cumulative_events_versus_time(...[, ...])	Plots the cumulative number of forecasted events from a CatalogForecast versus the observed events over time.
plot_magnitude_histogram(forecast[, ...])	Generates a semi-log magnitude histogram comparing a catalog-based forecast with observed data.

Spatial plotting:

plot_basemap([basemap, extent, coastline, ...])	Wrapper function for multiple Cartopy base plots, including access to standard raster web services and reading of filesystem geoTIFF.
plot_catalog(catalog[, basemap, projection, ...])	Spatial plot of catalog epicenters.
plot_gridded_dataset(gridded, region[, ...])	Plot spatial gridded dataset such as data from a gridded forecast.

Plotting grid-based evaluations:

plot_comparison_test(results_t[, results_w, ...])	Plots a list of T-Test (and optional W-Test) results on a single axis.
plot_consistency_test(eval_results[, ...])	Plots the results from one or multiple consistency tests.

Plotting catalog-based evaluations:

plot_test_distribution(evaluation_result[, ...])	Plots the histogram of a test statistic distribution calculated from stochastic event sets along with the observed statistic.
plot_calibration_test(evaluation_result[, ...])	Plots a calibration test (Quantile-Quantile plot) with confidence intervals.

Plotting alarm-based evaluations:

plot_ROC_diagram(forecast, catalog[, ...])	Plots the ROC (Receiver Operating Characteristic) curve for a given forecast and observed catalog.
plot_concentration_ROC_diagram(forecast, catalog)	Plots the Concentration ROC Diagram for a given forecast and observed catalog.
plot_Molchan_diagram(forecast, catalog[, ...])	Plot the Molchan Diagram based on forecast and test catalogs using the contingency table.

Time Utilities

epoch_time_to_utc_datetime(epoch_time_milli)	Accepts an epoch_time in milliseconds the UTC timezone and returns a python datetime object.
datetime_to_utc_epoch(dt)	Converts python datetime.datetime into epoch_time in milliseconds.
millis_to_days(millis)	Converts time in millis to days
days_to_millis(days)	Converts days to millis
strptime_to_utc_epoch(time_string[, format])	Returns epoch time from formatted time string
timedelta_from_years(time_in_years)	Returns python datetime.timedelta object based on the astronomical year in seconds.
strptime_to_utc_datetime(time_string[, format])	Converts time_string with format into time-zone aware datetime object in the UTC timezone.
utc_now_datetime()	Returns current datetime
utc_now_epoch()	Returns current epoch time
create_utc_datetime(datetime)	Creates TZAware UTC datetime object from unaware object.
decimal_year(test_date)	Convert given test date to the decimal year representation.

Comcat Access

We integrated the code developed by Mike Hearne and others at the USGS to reduce the dependencies of this package. We plan to move this to an external and optional dependency in the future.

search([starttime, endtime, updatedafter, ...])	Search the ComCat database for events matching input criteria.
get_event_by_id(eventid[, catalog, ...])	Search the ComCat database for an event matching the input event id.

Calculation Utilities

nearest_index(array, value)	Returns the index from array that is less than the value specified.
find_nearest(array, value)	Returns the value from array that is less than the value specified.
func_inverse(x, y, val[, kind])	Returns the value of a function based on interpolation.
discretize(data, bin_edges[, right_continuous])	returns array with len(bin_edges) consisting of the discretized values from each bin.
bin1d_vec(p, bins[, tol, right_continuous])	Efficient implementation of binning routine on 1D Cartesian Grid.

Statistics Utilities

sup_dist(cdf1, cdf2)	given two cumulative distribution functions, compute the supremum of the set of absolute distances.
sup_dist_na(data1, data2)	computes the ks statistic for two ecdfs that are not necessarily aligned on the same values.
cumulative_square_diff(cdf1, cdf2)	given two cumulative distribution functions, compute the cumulative sq.
binned_ecdf(x, vals)	returns the statement P(X ≤ x) for val in vals.
ecdf(x)	Compute the ecdf of vector x.
greater_equal_ecdf(x, val[, cdf])	Given val return P(x ≥ val).
less_equal_ecdf(x, val[, cdf])	Given val return P(x ≤ val).
min_or_none(x)	Given an array x, returns the min value.
max_or_none(x)	Given an array x, returns the max value.
get_quantiles(sim_counts, obs_count)	Computes delta1 and delta2 quantile scores from empirical distribution and observation
poisson_log_likelihood(observation, forecast)	Wrapper around scipy to compute the Poisson log-likelihood
poisson_joint_log_likelihood_ndarray(...)	Efficient calculation of joint log-likelihood of grid-based forecast.
poisson_inverse_cdf(random_matrix, lam)	Wrapper around scipy inverse poisson cdf function

Basic types

AdaptiveHistogram([dh, anchor])

Allows us to work with data that need to be discretized and aggregated even though the the global min/max values are not known before hand.