Welcome to statseis’s documentation!

Statseis API Reference

Utility funcitons

statseis.utils.add_distance_to_position_haversine(lon, lat, distance_km_horizontal, distance_km_vertical)

Returns the a point shifted in km by the value of its arguments using the haversine method

statseis.utils.add_distance_to_position_pyproj(lon, lat, distance_km_horizontal, distance_km_vertical)

Returns the a point shifted in km by the value of its arguments using the Pyproj module

statseis.utils.calculate_distance_pyproj_vectorized(lon1, lat1, lon2_array, lat2_array, ellipsoid='WGS84')

Returns the distance (km) from a point to an array of points using the Pyproj module

statseis.utils.convert_extent_to_epsg3857(extent)

statseis.utils.datetime_to_decimal_days(DATETIMES)

Durn datetime objects to decimal days

statseis.utils.datetime_to_decimal_year(timestamps)

Turn datetime objects to decimal years

statseis.utils.estimate_axis_labels(array, n_labels=5)

Failed attempt to automaticallly generate better axis labels than matplotlib

statseis.utils.find_event_in_catalog(ID, catalog)

statseis.utils.find_nearest(array, value, index=False)

Returns the nearest value in an array to its argument.

statseis.utils.get_CDF(data)

statseis.utils.get_bins(numbers, nearest=10)

Returns optimal bins for plotting a histogram.

statseis.utils.get_catalogue_extent(catalogue, buffer=None)

Returns the min/max of the Lon/Lat of an earthquake catalogue

statseis.utils.haversine(lon1, lat1, lon2, lat2)

Calculate the great circle distance in kilometers between two points on the earth (specified in decimal degrees)

statseis.utils.haversine_vectorised(lon1, lat1, lon2, lat2)

Returns the distance (km) from a point to an array of points using the haversine method

statseis.utils.magnitude_to_moment(magnitude)

Covert moment magnitude to seismic moment

statseis.utils.min_max_median_mean(numbers)

Returns the min, max, median, and mean of a list of numbers

statseis.utils.no_nans_or_infs(res_file, metric=None)

statseis.utils.read_in_convert_datetime(path)

Read in a CSV of source parameters with datetimes (not strings).

statseis.utils.reformat_catalogue(df)

standardise column names, must feed in dataframe with columns: [‘ID’, ‘MAGNITUDE’, ‘DATETIME’, ‘DEPTH’, ‘LON’, ‘LAT’]

statseis.utils.restrict_catalogue_geographically(df, region)

Returns catalogue within LON/LAT region of interest

statseis.utils.select_within_box(LON, LAT, df, r)

statseis.utils.string_to_datetime(list_of_datetimes, format='%Y-%m-%d %H:%M:%S')

Turn datetimes from string into datetime objects

statseis.utils.string_to_datetime_df(dataframe, format='%Y-%m-%d %H:%M:%S.%f')

Find DATETIME column in df and change to datetime objects

statseis.utils.string_to_datetime_return(dataframe, format='%Y-%m-%d %H:%M:%S')

Find DATETIME column in df and change to datetime objects Returns dataframe so function can be mapped

Routines for performing the Lilliefors test for exponentiality.

The Lilliefors test is performed as a function of lower magnitude cutoff. The provided p-value is eventually used to estimate a Mc-Lilliefors, which complies with the exponential Gutenberg–Richter relation to obtain a meaningful b-value.

The accompanied Jupyter notebook demonstrates the use of the class below.

Associated publication:

Herrmann, M. and W. Marzocchi (2020). “Inconsistencies and Lurking Pitfalls in the

Magnitude–Frequency Distribution of High-Resolution Earthquake Catalogs”. Seismological Research Letters 92(2A). doi: 10.1785/0220200337

copyright:

2020 Marcus Herrmann, Università degli Studi di Napoli ‘Federico II’

license:

European Union Public Licence (EUPL-1.2-or-later) (https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12)

class statseis.mc_lilliefors.McLilliefors(mags, signif_lev=0.1, log_level=20)

Bases: object

Class to perform the Lilliefors test for exponentiality (as function of Mc).

Note: this class is related and compatible to the FMD class in https://gitlab.seismo.ethz.ch/microEQ/TM/blob/master/TM/analysis.py#L910 , which also supports b-value estimation.

calc_testdistr_mcutoff(n_repeats=100, Mstart=None, log=True)

Get test distribution (e.g., p-value) as function of magnitude cutoff.

Parameters:

• n_repeats (int, optional) – Number of random initializations of noise added to mangitudes (which make the discrete magnitudes continuous), by default 100.

• Mstart (float, optional) – Overwrite minimum magnitude from where to start, by default starts at smallest magnitude present in the set.

• log (bool, optional) – Whether to log or not to log, by default True.

estimate_Mc_expon_test(mbin=None)

Get the magnitude of completeness using Lilliefors test of exponentiality.

This means: the Mc is determined as the lowest magnitude where the p-value is above

the significance level, i.e. where the exponential assumption is not rejected.

Here we will generally use the average p-value among several realizations of the random noise. For robustness, this average p-value must exceed the significance level for at least 0.05 magnitude units, in which case the first exceedance, i.e., the smallest magnitude bin, yields the eventual Mc-Lilliefors.

Parameters:

mbin (float, optional) – Overwrite the “binning”. Defaults to the magnitude binning.

Returns:

The estimated magnitude of completeness

Return type:

float

get_test_distribution(mags=None, Mc=None, n_repeats=100)

Perform a test several times and return its distribution.

Every repetition is performed with a newly sampled random noise that is added to the magnitudes.

lilliefors_test(mags=None, log=True)

Perform a Lilliefors hypothesis test for exponentiality.

Parameters:

• mags (1-D array_like, optional) – The magnitude set. Defaults to the magnitude set of this FMD object.

• log (bool, optional) – Whether to output the test results to stdout, by default True. Only useful to switch off for batch-processing tests.

Returns:

p-value of the hypothesis test.

Return type:

float

plot_testdist_expon_mcutoff(color='#000000', name=None, legendgroup=None, asfig=True)

Plot test distribution (e.g., p-value) as function of magnitude cutoff.

Plots the mean, min/max, and +/- std curves.

Parameters:

• color (str, optional) – The color to use, by default ‘#000000’ (black).

• name (str, optional) – The name in the legend entry, by default None.

• legendgroup (bool, int, or string, optional) – Whether to group all curves into one group, by default None. And if yes, in which (needs to be specified as an integer, i.e. the group id).

• asfig (bool, optional) – Whether to return a plotly Figure instance (True), or only a dict (False). Defaults to True.

Returns:

plotly Figure instance or a dictionary to be converted into a plotly Figure.

Return type:

plotly.graph_objs._figure.Figure or dict

update_mags(mags)

Update the magnitude vector.

Also recalculates n_ev property.

Indices and tables

• Index

• Module Index

• Search Page