API Reference

This contains a reference document to the PyCSEP API.

Loading catalogs and forecasts

load_stochastic_event_sets(filename[, type, ...])	General function to load stochastic event sets
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
load_gridded_forecast(fname[, loader])	Loads grid based forecast from hard-disk.
load_catalog_forecast(fname[, ...])	General function to handle loading catalog forecasts.

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, ...])	Plot catalog according to plate-carree projection

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 mag_bins
CSEPCatalog.spatial_magnitude_counts([...])	Return counts of events in space-magnitude region.

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 gridded forecast according to plate-carree projection

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
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.

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.

Testing regions:

california_relm_region([dh_scale, ...])	Returns class representing California testing region.
italy_csep_region([dh_scale, magnitudes, ...])	Returns class representing Italian testing 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
california_relm_region([dh_scale, ...])	Returns class representing California testing region.

Plotting

General plotting:

plot_histogram(simulated, observation[, ...])	Plots histogram of single statistic for stochastic event sets and observations.
plot_ecdf(x, ecdf[, axes, xv, show, plot_args])	Plots empirical cumulative distribution function.
plot_basemap(basemap, extent[, ax, figsize, ...])	Wrapper function for multiple cartopy base plots, including access to standard raster webservices
plot_spatial_dataset(gridded, region[, ax, ...])	Plot spatial dataset such as data from a gridded forecast
add_labels_for_publication(figure[, style, ...])	Adds publication labels too the outside of a figure.

Plotting from catalogs:

plot_magnitude_versus_time(catalog[, ...])	Plots magnitude versus linear time for an earthquake data.
plot_catalog(catalog[, ax, show, extent, ...])	Plot catalog in a region

Plotting stochastic event sets and evaluations:

plot_cumulative_events_versus_time(...[, ...])	Same as below but performs the statistics on numpy arrays without using pandas data frames.
plot_magnitude_histogram(catalogs, comcat[, ...])	Generates a magnitude histogram from a catalog-based forecast
plot_number_test(evaluation_result[, axes, ...])	Takes result from evaluation and generates a specific histogram plot to show the results of the statistical evaluation for the n-test.
plot_magnitude_test(evaluation_result[, ...])	Takes result from evaluation and generates a specific histogram plot to show the results of the statistical evaluation for the M-test.
plot_distribution_test(evaluation_result[, ...])	Takes result from evaluation and generates a specific histogram plot to show the results of the statistical evaluation for the M-test.
plot_likelihood_test(evaluation_result[, ...])	Takes result from evaluation and generates a specific histogram plot to show the results of the statistical evaluation for the L-test.
plot_spatial_test(evaluation_result[, axes, ...])	Plot spatial test result from catalog based forecast
plot_calibration_test(evaluation_result[, ...])

Plotting gridded forecasts and evaluations:

plot_spatial_dataset(gridded, region[, ax, ...])	Plot spatial dataset such as data from a gridded forecast
plot_comparison_test(results_t[, results_w, ...])	Plots list of T-Test (and W-Test) Results
plot_poisson_consistency_test(eval_results)	Plots results from CSEP1 tests following the CSEP1 convention.

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. This search function is a wrapper around the ComCat Web API described here: https://earthquake.usgs.gov/fdsnws/event/1/ Some of the search parameters described there are NOT implemented here, usually because they do not apply to GeoJSON search results, which we are getting here and parsing into Python data structures. This function returns a list of SummaryEvent objects, described elsewhere in this package. Usage: TODO: Show usage information. :param starttime: Python datetime - Limit to events on or after the specified start time. :type starttime: datetime :param endtime: Python datetime - Limit to events on or before the specified end time. :type endtime: datetime :param updatedafter: Python datetime - Limit to events updated after the specified time. :type updatedafter: datetime :param minlatitude: Limit to events with a latitude larger than the specified minimum. :type minlatitude: float :param maxlatitude: Limit to events with a latitude smaller than the specified maximum. :type maxlatitude: float :param minlongitude: Limit to events with a longitude larger than the specified minimum. :type minlongitude: float :param maxlongitude: Limit to events with a longitude smaller than the specified maximum. :type maxlongitude: float :param latitude: Specify the latitude to be used for a radius search. :type latitude: float :param longitude: Specify the longitude to be used for a radius search. :type longitude: float :param maxradiuskm: Limit to events within the specified maximum number of kilometers from the geographic point defined by the latitude and longitude parameters. :type maxradiuskm: float :param maxradius: Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters. :type maxradius: float :param catalog: Limit to events from a specified catalog. :type catalog: str :param contributor: Limit to events contributed by a specified contributor. :type contributor: str :param limit: Limit the results to the specified number of events. NOTE, this will be throttled by this Python API to the supported Web API limit of 20,000. :type limit: int :param maxdepth: Limit to events with depth less than the specified maximum. :type maxdepth: float :param maxmagnitude: Limit to events with a magnitude smaller than the specified maximum. :type maxmagnitude: float :param mindepth: Limit to events with depth more than the specified minimum. :type mindepth: float :param minmagnitude: Limit to events with a magnitude larger than the specified minimum. :type minmagnitude: float :param offset: Return results starting at the event count specified, starting at 1. :type offset: int :param orderby: Order the results. The allowed values are: - time order by origin descending time - time-asc order by origin ascending time - magnitude order by descending magnitude - magnitude-asc order by ascending magnitude :type orderby: str :param alertlevel: Limit to events with a specific PAGER alert level. The allowed values are: - green Limit to events with PAGER alert level "green". - yellow Limit to events with PAGER alert level "yellow". - orange Limit to events with PAGER alert level "orange". - red Limit to events with PAGER alert level "red". :type alertlevel: str :param eventtype: Limit to events of a specific type. NOTE: "earthquake" will filter non-earthquake events. :type eventtype: str :param maxcdi: Maximum value for Maximum Community Determined Intensity reported by DYFI. :type maxcdi: float :param maxgap: Limit to events with no more than this azimuthal gap. :type maxgap: float :param maxmmi: Maximum value for Maximum Modified Mercalli Intensity reported by ShakeMap. :type maxmmi: float :param maxsig: Limit to events with no more than this significance. :type maxsig: float :param mincdi: Minimum value for Maximum Community Determined Intensity reported by DYFI. :type mincdi: float :param minfelt: Limit to events with this many DYFI responses. :type minfelt: int :param mingap: Limit to events with no less than this azimuthal gap. :type mingap: float :param minsig: Limit to events with no less than this significance. :type minsig: float :param producttype: Limit to events that have this type of product associated. Example producttypes: - moment-tensor - focal-mechanism - shakemap - losspager - dyfi :type producttype: str :param productcode: Return the event that is associated with the productcode. The event will be returned even if the productcode is not the preferred code for the event. Example productcodes: - nn00458749 - at00ndf1fr :type productcode: str :param reviewstatus: Limit to events with a specific review status. The different review statuses are: - automatic Limit to events with review status "automatic". - reviewed Limit to events with review status "reviewed". :type reviewstatus: str :param host: Replace default ComCat host (earthquake.usgs.gov) with a custom host. :type host: str :param enable_limit: Enable 20,000 event search limit. Will turn off searching in segments, which is meant to safely avoid that limit. Use only when you are certain your search will be small. :type enable_limit: bool.

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.