Model Building Toolkit (mbt) module

The Model Building Toolkit module contains code for building a PSHA earthquake occurrence model. The main goals of this tools are to:

1. Streamline the process of building a PSHA earthquake occurrence model

2. Ensure that the process adopted to build the model is reproducible and extendable.

Here you can find information on the available functions including their inputs and outputs. The tools in the mbt cover many important aspects of model construction. Some other functions are instead included in the wkf For an example of how they might be used in a workflow, see the SSC workflow module.

Available mbt and wkf functions

The mbt functions exist as part of the original version of the mbtk, when it was smaller and relied solely on a sequence of jupyter notebooks. Many functions that were here have been improved and/or moved to other locations. The wkf functions add further tools for building hazard models in the SSC workflow.

Catalogue tools

Module openquake.wkf.catalogue contains tools for working with catalogue files in the hmtk format

openquake.wkf.catalogue.create_subcatalogues(fname_polygons: str, fname_cat: str, folder_out: str, source_ids: str = [])

Given a catalogue and a gis-file with polygons (e.g. shapefile or .geojson), this code creates for each polygon a subcatalogue with the earthquakes with epicenters in the polygon.

Parameters:

• fname_polygons – The name of the gis file containing the polygons.

• fname_cat – The name of the file with the catalogue (hmtk formatted)

• folder_out – The name of the output folder where to create the output .csv files containing the subcatalogues

• source_ids – [optional] The list of source ids to be considered. If omitted all the polygons will be considered.

openquake.wkf.catalogue.extract(fname_in: str, **kwargs) → DataFrame

Creates a copy of a .csv catalogue containing only the events responding to the selection criteria. Accepted parameters:

• Minimum hypocentral depth: min_depth

• Maximum hypocentral depth: min_depth

• Minimum magnitude: min_mag

• Maximum magnitude: max_mag

Parameters:

• fname_in – Name of the input .csv file with the catalogue

• fname_out – Name of the output .csv file with the catalogue

Returns:

A dataframe with the filtered catalogue

openquake.wkf.catalogue.from_df(df, end_year=None) → Type[Catalogue]

Converts a dataframe into a openquake.hmtk.seismicity.catalogue.Catalogue instance

Parameters:

df – The dataframe with the catalogue

Returns:

The catalogue instance

openquake.wkf.catalogue.get_dataframe(fname: str) → DataFrame

Creates a dataframe with the information included in a .ndk formatted file. For a description of the .ndk format see: https://www.globalcmt.org/

Parameters:

fname – Name of the .ndk file

Returns:

A dataframe with the information in the .ndk file

openquake.wkf.catalogue.to_df(cat: Type[Catalogue]) → DataFrame

Converts an openquake.hmtk.seismicity.catalogue.Catalogue instance into a dataframe

Parameters:

cat – The catalogue instance

Returns:

The dataframe with the catalogue

Tectonic regionalisation tools

These are used in conjunction with the subduction tools for classifying events in subduction regions.

class openquake.mbt.tools.tr.set_subduction_earthquakes.SetSubductionEarthquakes(label, treg_filename, distance_folder, edges_folder, distance_buffer_below, distance_buffer_above, lower_depth, catalogue_filename, log_fname=None, upper_depth=None, low_year=-10000, upp_year=+10000, low_mag=-5., upp_mag=15.)

Classifies earthquakes generated by a subduction earthquake source (either interface or inslab).

Parameters:

• label (str) – Flag used to classify the earthquakes

• treg_filename (str) – Name of the .hdf5 containing the tectonic regionalisation

• distance_folder (str) – Folder where to store the epicenter-surface files

• edges_folder (str) – Folder containing the edges specifying the geometry of the surface

• distance_buffer_below (float) – Distance [km] below the fault surface used to select earthquakes

• distance_buffer_above (float) – Distance [km] above the fault surface used to select earthquakes

• catalogue_filename (str) – Name of the file containing the earthquakes to be classified

• log_fname (str) – Name of the .log file

• low_year – Lowest year selected

• upp_year – Largest year selected

• low_mag – Lowest magnitude selected

• upp_mag – Largest magnitude selected

classify(compute_distances, remove_from, surftype='ComplexFault')

Parameters:

• compute_distances (bool) – A boolean indicating if distances between earthquakes and the subduction surface should be computed. If False the distances stored in self.distance_folder will be used.

• remove_from (list) – A list of labels identifying TR from where the earthquakes assigned to this TR must be removed

MFD functions

openquake.wkf.compute_gr_params._weichert_plot(cent_mag, n_obs, binw, t_per, ex_rates_scaled, lcl, ucl, mmax, aval_wei, bval_wei, src_id=None, plt_show=False, ref_mag=None, ref_mag_rate=None, ref_mag_rate_sig=None, bval_sigma=None)

Plot the Weichert parameter fit against the catalogue

Parameters:

• cent_mag – centre magnitudes of plotting bins

• n_obs – number of observations in plotting bins

• binw – binwidth

• t_per – time length for observation windows (used for incremental)

• ex_rates_scaled – scaled exceedance rates (output from get_weichert_confidence_intervals)

• lcl – lower confidence interval (output from get_weichert_confidence_intervals)

• ucl – upper confidence interval (output from get_weichert_confidence_intervals)

• mmax – maximum magnitude

• aval_wei – Weichert a-value

• bval_wei – Weichert b-value

• src_id – source id (used for plot title)

• plt_show – flag to show plot

• ref_mag – reference magnitude

• ref_mag_rate – rate at reference magnitude

• ref_mag_rate_sigma – uncertainty in rate at reference magnitude

• bval_sigma – uncertainty in b-value

openquake.wkf.compute_gr_params.compute_a_value(fname_input_pattern: str, bval: float, fname_config: str, folder_out: str, use: str = '', folder_out_figs: str = None, plt_show=False, src_id_pattern: str = None)

This function assignes an a-value to each source with a file selected by the provided fname_input_pattern.

Parameters:

• fname_input_pattern – The name of a file or of a pattern

• bval – The b-value of the GR distribution

• fname_config – Configuration file

• folder_out – Path to the output folder

openquake.wkf.compute_gr_params.compute_a_value_from_density(fname_input_pattern: str, fname_config: str, fname_polygon: str, use: str = '', folder_out_figs: str = None, plt_show=False)

This function computes the a_gr value for polygons given a rate of occurrence per unit of area. This rate is specified in the fname_config file.

openquake.wkf.compute_gr_params.get_agr(mag, bgr, rate)

Parameters:

• mag – The magnitude to which the parameter rate refers to. If the rates are binned this should be the lower limit of the bin containing mag

• bgr – The b-value of the Gutenberg-Richer relatioship

• rate – The rate of occurrence of earthquakes larger than mag

Returns:

The a-value of the GR relationship

openquake.wkf.compute_gr_params.get_exrs(df: DataFrame, bgr: str)

Computes annual exceedence rates using eq. 10 in Weichert (1980; BSSA).

Parameters:

• df – An instance of pandas.DataFrame with the following columns: - mag: magnitude - nobs: number of observations - deltaT: duration [yr]

• bgr – The b-value of the Gutenberg-Richer relatioship

Returns:

Annual exceedance rate for all the magnitude values in the dataframe.

openquake.wkf.compute_gr_params.get_weichert_confidence_intervals(mag, occ, tcompl, bgr)

Computes 16th-84th confidence intervals according to Weichert (1980)

Parameters:

• mag – A vector with the magnitude value of each magnitude bin

• occ – The number of occurrences in each magnitude bin

• tcompl – Duration [in years] of the completeness interval for each magnitude bin

• bgr – The GR b-value

Returns:

A tuple with: the upper and lower confidence interval, a vector with the occurrence rates and the occurrence rates scaled

openquake.wkf.compute_gr_params.subcatalogues_analysis(fname_input_pattern, fname_config, skip=[], outdir='', **kwargs)

Analyze the catalogues included in a folder.

openquake.wkf.compute_gr_params.weichert_analysis(fname_input_pattern, fname_config, folder_out=None, folder_out_figs=None, skip=[], binw=0.1, plt_show=False)

Computes GR parameters for a set of catalogues stored in a .csv file

Parameters:

• fname_input_pattern – It can be either a string (definining a pattern) or a list of .csv files. The file names must have the source ID at the end. The delimiter of the source ID on the left is _

• fname_config – The name of the .toml configuration file

• folder_out – The folder where to store the files with the counting of occurrences

• folder_out_figs – The folder where to store the figures

• skip – A list with the IDs of the sources to skip

• plt_show – Boolean. When true show the plots on screen.

openquake.wkf.plot.completeness.completeness_plot(fname_input_pattern, fname_config, outdir, skip=[], yealim='', **kwargs)

Plot the density of events in time using mbt.tools.model_building.plot_mtd.

Parameters:

• fname_input – name of input file for catalogue

• fname_config – configuration file, should contain a completeness_table for each zone to be plotted or a default completeness_table to be used

• outdir – Output folder for figures

• skip – optional list of source IDs to skip

• yealim – optional upper and lower year limits

openquake.wkf.mfd.check_mfds(fname_input_pattern: str, fname_config: str = None, *, src_id: str = None)

Given a set of .xml files and a configuration file with GR params, this code compares the total MFD of the sources against the original one in the configuration file. The ID of the source if not provided is taken from the name of the files (i.e., last label preceded by _)

Parameters:

• fname_input_pattern – pattern to match for xml files

• fname_config – configuration file with GR params to compare

openquake.wkf.plot_incremental_mfd.plot_GR_inc_fixedparams_completeness_imp(cat, mbin, a, b, comptab, plt_show=True, plt_title='')

Given an earthquake catalogue, estimates of the a and b-value and a completeness table, plot the observed and expected number of events in each bin. Expected number includes Poisson lower (5%, orange) and upper (95%, blue) bounds

Parameters:

• cat – catalogue (geo)dataframe with hmtk column names

• mbin – binwidth for plots

• a – Gutenberg-Richter a-value estimated for this catalogue (given the completeness)

• b – Gutenberg-Richter b-value estimated for this catalogue (given the completeness)

• comptab – numpy array describing completeness upon which GR estimates are based e.g. comptab = [[1975, 5.5], [1960, 5.0], [1900, 7.0]]

• plt_show – boolean specifying if plot should be displayed. Defaults to True if unspecified

• plt_title – title for plot

openquake.wkf.plot_incremental_mfd.plot_incremental_mfds(fname_input_pattern, fname_config, folder_out_figs=None, skip=[], binw=0.1, plt_show=False)

Given a catalogue and a config, plots the incremental number of observed earthquakes within completeness windows and the expected counts determined from completeness and fmd parametrs.

Parameters:

• fname_input_pattern – It can be either a string (definining a pattern) or a list of .csv files. The file names must have the source ID at the end. The delimiter of the source ID on the left is _

• fname_config – The name of the .toml configuration file

• folder_out_figs – The folder where to store the figures

• skip – A list with the IDs of the sources to skip

• plt_show – Boolean. When true show the plots on screen.

Declustering

Primarily, the declustering is handled in the hmtk module of the OpenQuake engine, but this function in the mbtk is most commonly used by the hazard team (for now).

openquake.mbt.tools.model_building.dclustering.decluster(catalogue_hmtk_fname, declustering_meth, declustering_params, output_path, labels=None, tr_fname=None, subcatalogues=False, fmat='csv', olab='', save_af=False, out_fname_ext='', fix_defaults=False)

Parameters:

• catalogue_hmtk_fname (str) – Full path to the file containing the initial catalogue

• declustering_meth (str) – A string indicating the type of declustering

• declustering_params (dict) – Parameters required by the declustering algorithm

• output_path (str) – Folder where the output catalogue/s will be created

• labels (list) – It can be a string or a list of strings

• tr_fname (str) – An .hdf5 file containing the TR classification of the catalogue

• subcatalogues (bool) – When true creates subcatalogues per tectonic region

• fmat (str) – Can be either ‘csv’ or ‘pkl’

• olab (str) – Optional label for output catalogues

• save_af (boolean) – Save aftershocks and foreshocks

• out_fname_ext (str) – String to be added to the putput filename

• fix_defaults (str) – Fix defaults values when missing

Distributed seismicity tools

openquake.wkf.distributed_seismicity.explode(srcs, check_moment_rates=True)

Takes sources with hypocentral depth distribution and divides them into one source for each depth

openquake.wkf.distributed_seismicity.from_list_ps_to_multipoint(srcs: list, src_id: str)

Converts a list of point sources into a multi-point source

Parameters:

• srcs – A list of point sources

• src_id – The ID of the multipoint source created

openquake.wkf.distributed_seismicity.get_bounding_box(sfc)

Get the bounding box of a simple fault source

Parameters:

src – See :method:`get_data`

Returns:

A list with four floats i.e. the coordinates of the lower left and upper right corners of the bounding box.

openquake.wkf.distributed_seismicity.get_data(sfc, coo_pnt_src, pnt_srcs, dist_type='rjb', buffer=1.0)

Computes point sources within the bounding box and the corresponding rjb distances.

Parameters:

• sfc – An instance of openquake.hazardlib.geo.surface.BaseSurface

• coo_pnt_src – An array with the coordinates of the point sources

• pnt_srcs – A list of openquake.hazardlib.source.PointSource

• dist_type – A string specifying the metric used to measure the distance between the fault plane and the point sources

• buffer – A float [km] indicating the threshold distance within which point sources are considered within the buffer surrounding the fault.

openquake.wkf.distributed_seismicity.get_stacked_mfd(srcs: list, within_idx: list, binw: float)

This returns a stacked MFD for the sources in the srcs provided as input.

Parameters:

• srcs – A list of sources

• within_idx – A list with the indexes of the sources in srcs whose mfd must be used in the stacking

• binw – A float indicating the bin width of the

openquake.wkf.distributed_seismicity.remove_buffer_around_faults(fname: str, path_point_sources: str, out_path: str, dst: float | ndarray, threshold_mag: float | ndarray = 6.5, use: str = '', rupture_mesh_spacing=5.0, complex_fault_mesh_spacing=5.0, area_source_discretization=5.0, PLOTTING=False)

Remove the seismicity above magnitude thresholds for all the point sources within corresponding buffer distances around faults.

Parameters:

• fname – The name of the file with the fault sources in .xml format

• path_point_sources – The pattern to select the .xml files of the point sources e.g. ./../m01_asc/oq/zones/src_*.xml

• out_path – The path where to write the output .xml file

• dst – Either a single float specifying a constant buffer distance in km, or an array of distances corresponding to threshold_mag values

• threshold_mag – Either a single float specifying a constant magnitude threshold, or an array of magnitude thresholds corresponding to dst values

Returns:

A .xml file with the adjusted point sources

class openquake.mbt.tools.adaptive_smoothing.AdaptiveSmoothing(locations, grid=False, use_3d=False, bvalue=None, use_maxdist=False, weight=None)

Applies Helmstetter (2007) adaptive smoothing kernel to the data

information_gain(counts, T=1, read_counts_from_file=False, fname_counts=None)

Calculates the information gain per event given a smoothing model and a list of model counts Counting results should match the cells of the smoothed rates.

Parameters:

• counts – counts in grid cells matching the smoothed cells stored in self.out

• T – optional time scaling for testing rates over a fixed time period

• read_counts_from_file – if True, read count data from a csv instead of using directly supplied counts

• fname_counts – if read_counts_from_file is True, read counts from specified file.

plot_smoothing(log_density=False, plot_cat=False)

Plot adaptive smoothing outputs given a csv file of smoothing values (lon, lat, nocc). Compatible with output of adaptive or fixed kernel smoothing approaches

Parameters:

smooth_out – Location of output file containing the adaptive smoothing results

poiss_loglik(rate_lambda, obs, T=1)

Calculate the poisson likelihood, given the observed number of events and the forecast rate.

Parameters:

• rate_lambda – expected number of events

• obs – observed number of events

• T – Scaling of forecast to observations. For example, a forecast built with 100 years of data tested over a ten year testing period should have T = 0.1, or a 1 year forecast tested over 5 years would have T = 5

Returns:

likelihood value

run_adaptive_smooth(catalogue, config)

Runs an analysis of adaptive smoothed seismicity of Helmstetter et al (2007).

Parameters:

• catalogue – Instance of the openquake.hmtk.seismicity.catalogue.Catalogue class catalogue.data dictionary containing the following - ‘year’ - numpy.ndarray vector of years ‘longitude’ - numpy.ndarray vector of longitudes ‘latitude’ - numpy.ndarray vector of latitudes ‘depth’ - numpy.ndarray vector of depths (can use CsvParser to adapt any csv file to Catalogue for this step)

• config (dict) –

  Configuration settings of the algorithm: * ‘kernel’ - Kernel choice for adaptive smoothing. Options are “Gaussian”

  or “PowerLaw” (string)

  • ’n_v’ - number of nearest neighbour to use for smoothing distance (int)

  • ’d_i_min’ - minimum smoothing distance d_i, should be chosen based on location uncertainty. Default of 0.5 in Helmstetter et al. (float)

  Optional (required only when use_maxdist = True) * ‘maxdist’ - in km, the maximum distance at which to consider other events * ‘h3res’ - the h3 resolution for the smoothing calculations

Returns:

Smoothed seismicity data as np.ndarray, of the form [Longitude, Latitude, Smoothed_value] if maxdist == True, the smoothed values will be normalised to the number of events in the catalogue. This makes the output directly comparable with the Gaussian smoothing options in the mbtk

Fault modeling tools

The fault modelling tools are used to create fault sources from fault data (trace, slip rate, dip, etc.) in json format and a dictionary of parameters that define modelling assumptions and how ruptures will be generated from the fault source. The functions use the following defaults:

defaults = {'name': 'unnamed',
            'b_value': 1.,
            'bin_width': 0.1,
            'm_min': 4.0,
            'm_max': None,
            'm_char': None,
            'm_cli': 6.0,
            'm_upper': 10.,
            'slip_class': 'mle',
            'aseismic_coefficient': 0.,
            'upper_seismogenic_depth': 0.,
            'lower_seismogenic_depth': 35.,
            'rupture_mesh_spacing': 2.,
            'rupture_aspect_ratio': 2.,
            'minimum_fault_length': 5.,
            'tectonic_region_type': 'Active Shallow Crust',
            'temporal_occurrence_model': hz.tom.PoissonTOM(1.0),
            'magnitude_scaling_relation': 'Leonard2014_Interplate',
            'width_scaling_relation': 'Leonard2014_Interplate',
            'subsurface_length': False,
            'rigidity': 32e9,
            'mfd_type': 'DoubleTruncatedGR'
         }

openquake.mbt.tools.fault_modeler.fault_source_modeler.build_fault_model(*, cfg_file=None, geojson_file=None, xml_output=None, black_list=None, select_list=None, project_name=None, width_method='seismo_depth', oqt_source=False, param_map=None, defaults=None, **kwargs)

Main interface to create the fault source model from an active fault database in geojson format. Priority for the optional parameters is set to:

1. single arguments

2. dictionary

3. .ini file

openquake.mbt.tools.fault_modeler.fault_source_modeler.read_config_file(cfg_file)

Import various processing options from the (.ini) configuration file

openquake.mbt.tools.fault_modeler.fault_modeling_utils.angle_difference(trend_1, trend_2, return_abs=True)

Calculates the difference between two trends or azimuths (trend_1 and trend_2), in degrees.

Parameters:

• trend_1 (float) – Number in degrees of first trend/azimuth.

• trend_2 (float) – Number in degrees of second trend/azimuth.

• return_abs (bool) – Flag for returning the absolute value of the angular difference. if return_abs is False, the returned angle is from trend_2 to trend_1 in the coordinate convention adopted (clockwise for azimuth, counter-clockwise for unit circle angles).

openquake.mbt.tools.fault_modeler.fault_modeling_utils.calc_double_truncated_GR_mfd_from_fault_params(fault_dict, area_method='simple', width_method='seismo_depth', width_scaling_relation='Leonard2014_Interplate', slip_class=None, magnitude_scaling_relation=None, m_max=None, m_min=None, m_cli=None, b_value=None, slip_rate=None, bin_width=None, fault_area=None, defaults=defaults, param_map=param_map, rigidity=None, aseismic_coefficient=None)

Creates a double-truncated Gutenberg-Richter magnitude-frequency distribution from fault parameters.

Fault parameters (not methods or scaling relations) passed here will override those in the fault_dict.

Currently, only an EvenlyDiscretizedMFD (double-truncated Gutenberg-Richter with a constant bin size) is implemented.

Parameters:

• aseismic_coefficient (float)

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• area_method (str) – Method used to calculate the surface area of a fault. Possible values are simple and from_surface. The ‘simple’ method calculates the fault area as the fault length times the width (down-dip distance). The from_surface method calculates the fault area through the discretization methods used in the SimpleFaultSurface.

• width_method (str) – Method used to calculate the width (down-dip distance) of a fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated given the scaling_rel. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• slip_class (str) – Magnitude of the slip rate (and associated parameters) to be used in the calculations. Possible values are mle (most-likely estimate), min and max.

• mag_scaling_rel (str) – Magnitude-scaling relation used to calculate the maximum magnitude from the fault parameters.

• m_max (float) – Maximum magnitude in the fault’s magnitude-frequency distribution.

• m_min (float) – Minimum magnitude in the fault’s magnitude-frequency distribution.

• m_cli (float) – In a ‘DoubleTruncatedGR’ we calculate the a-value given b-value, and two magnitude extremes: m_min and m_max. m_cli is the value of magni- tude above which we effectively compute the rates. Note that m_cli >= m_min.

• b_value (float) – Gutenberg-Richter b-value for magnitude-frequency distribution. A b-value passed here will override project and fault defaults.

• slip_rate (float) – Slip rate to be used in calculating the magnitude-frequency distributiuon. A slip_rate passed here will override project and fault defaults.

• aseismic_coefficient – Fraction of slip rate that is released aseismically and doesn’t contribute to moment accumulation or seismic release on the fault. Ranges between 0 and 1.

• bin_width (float) – Width of the bins for the magnitude-frequency distribution.

• fault_area (float) – Surface area of the fault used to calculate the momen release rate on the fault. A slip_rate value passed here will override the value calculated from the fault’s geometry.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Magnitude-scaling relation class.

Return type:

EvenlyDiscretizedMFD

openquake.mbt.tools.fault_modeler.fault_modeling_utils.calc_fault_width_from_length(fault_dict, width_scaling_relation='Leonard2014_Interplate', defaults=defaults, param_map=param_map, **kwargs)

Calculates the width (down-dip distance) of a fault from its length given a scaling relation. Currently, only leonard_2010 is defined.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• kwargs – Additional arguments to pass to the scaling relation function

Returns:

Fault width

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.calc_fault_width_from_usd_lsd_dip(fault_dict, defaults=defaults, param_map=param_map)

Calculates the width (down-dip distance) of the fault from the fault’s dip and seismogenic boundaries.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Fault width

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.calc_mfd_from_fault_params(fault_dict, mfd_type=None, area_method='simple', width_method='seismo_depth', width_scaling_relation='Leonard2014_Interplate', slip_class=None, magnitude_scaling_relation=None, m_min=None, m_max=None, m_cli=None, m_char=None, b_value=None, slip_rate=None, bin_width=None, fault_area=None, defaults=defaults, param_map=param_map, rigidity=None, aseismic_coefficient=None)

Creates a magnitude-frequency distribution from fault parameters and MFD type.

Fault parameters (not methods or scaling relations) passed here will override those in the fault_dict.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• mfd_type – Type (functional form) of magnitude-frequency distribution. Currently, options are ‘DoubleTruncatedGR’ and ‘YoungsCoppersmith1985’; the latter is a hybrid GR-Characteristic model.

• area_method (str) – Method used to calculate the surface area of a fault. Possible values are simple and from_surface. The ‘simple’ method calculates the fault area as the fault length times the width (down-dip distance). The from_surface method calculates the fault area through the discretization methods used in the SimpleFaultSurface.

• width_method (str) – Method used to calculate the width (down-dip distance) of a fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated given the scaling_rel. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• slip_class (str) – Magnitude of the slip rate (and associated parameters) to be used in the calculations. Possible values are mle (most-likely estimate), min and max.

• mag_scaling_rel (str) – Magnitude-scaling relation used to calculate the maximum magnitude from the fault parameters.

• m_max (float) – Maximum magnitude in the fault’s magnitude-frequency distribution. This is used for the ‘DoubleTruncatedGR’ mfd.

• m_min (float) – Minimum magnitude in the fault’s magnitude-frequency distribution.

• m_cli (float) – In a ‘DoubleTruncatedGR’ we calculate the a-value given b-value, and two magnitude extremes: m_min and m_max. m_cli is the value of magni- tude above which we effectively compute the rates. Note that m_cli >= m_min.

• m_char (float) – Characteristic magnitude in the fault’s magnitude-frequency distribution. This is used for the ‘YoungsCoppersmith1985’ mfd.

• b_value (float) – Gutenberg-Richter b-value for magnitude-frequency distribution. A b-value passed here will override project and fault defaults.

• slip_rate (float) – Slip rate to be used in calculating the magnitude-frequency distributiuon. A slip_rate passed here will override project and fault defaults.

• aseismic_coefficient (float) – Fraction of slip rate that is released aseismically and doesn’t contribute to moment accumulation or seismic release on the fault. Ranges between 0 and 1.

• bin_width (float) – Width of the bins for the magnitude-frequency distribution.

• fault_area (float) – Surface area of the fault used to calculate the momen release rate on the fault. A slip_rate value passed here will override the value calculated from the fault’s geometry.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

The MFD and seismic slip rate

Return type:

tuple

openquake.mbt.tools.fault_modeler.fault_modeling_utils.calc_youngs_coppersmith_mfd_from_fault_params(fault_dict, area_method='simple', width_method='seismo_depth', width_scaling_relation='Leonard2014_Interplate', slip_class=None, magnitude_scaling_relation=None, m_char=None, m_cli=None, m_min=None, b_value=None, slip_rate=None, bin_width=None, fault_area=None, rigidity=None, defaults=defaults, param_map=param_map, aseismic_coefficient=None)

Creates a Youngs-Coppersmith (hybrid characteristic and GR) magnitude-frequency distribution from fault parameters.

Fault parameters (not methods or scaling relations) passed here will override those in the fault_dict.

Parameters:

• aseismic_coefficient (float)

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• area_method (str) – Method used to calculate the surface area of a fault. Possible values are simple and from_surface. The ‘simple’ method calculates the fault area as the fault length times the width (down-dip distance). The from_surface method calculates the fault area through the discretization methods used in the SimpleFaultSurface.

• width_method (str) – Method used to calculate the width (down-dip distance) of a fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated given the scaling_rel. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• slip_class (str) – Magnitude of the slip rate (and associated parameters) to be used in the calculations. Possible values are mle (most-likely estimate), min and max.

• mag_scaling_rel (str) – Magnitude-scaling relation used to calculate the maximum magnitude from the fault parameters.

• m_char (float) – Characteristic magnitude in the fault’s magnitude-frequency distribution.

• m_cli (float) – In a ‘Youngs-Coppersmith’ we calculate the MFD using two magnitude extremes: m_cli and m_char. m_cli is the value of magnitude above which we effectively compute the rates.

• b_value (float) – Gutenberg-Richter b-value for magnitude-frequency distribution. A b-value passed here will override project and fault defaults.

• slip_rate (float) – Slip rate to be used in calculating the magnitude-frequency distributiuon. A slip_rate passed here will override project and fault defaults.

• aseismic_coefficient – Fraction of slip rate that is released aseismically and doesn’t contribute to moment accumulation or seismic release on the fault. Ranges between 0 and 1.

• bin_width (float) – Width of the bins for the magnitude-frequency distribution.

• fault_area (float) – Surface area of the fault used to calculate the momen release rate on the fault. A slip_rate value passed here will override the value calculated from the fault’s geometry.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Magnitude-scaling relation class.

Return type:

YoungsCoppersmithMFD

openquake.mbt.tools.fault_modeler.fault_modeling_utils.construct_sfs_dict(fault_dict, mfd_type=None, area_method='simple', width_method='seismo_depth', width_scaling_relation=None, slip_class=None, magnitude_scaling_relation=None, subsurface_length=None, m_min=None, m_max=None, m_cli=None, m_char=None, b_value=None, slip_rate=None, rigidity=None, aseismic_coefficient=None, bin_width=None, fault_area=None, defaults=defaults, param_map=param_map)

Makes a dictionary containing all of the parameters needed to create a SimpleFaultSource. Fault parameters (not methods or scaling relations) passed here will override those in the fault_dict.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• mfd_type – Type (functional form) of magnitude-frequency distribution. Currently, options are ‘DoubleTruncatedGR’ and ‘YoungsCoppersmith1985’; the latter is a hybrid GR-Characteristic model.

• area_method (str) – Method used to calculate the surface area of a fault. Possible values are simple and from_surface. The ‘simple’ method calculates the fault area as the fault length times the width (down-dip distance). The from_surface method calculates the fault area through the discretization methods used in the SimpleFaultSurface.

• width_method (str) – Method used to calculate the width (down-dip distance) of a fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated given the scaling_rel. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• slip_class (str) – Magnitude of the slip rate (and associated parameters) to be used in the calculations. Possible values are mle (most-likely estimate), min and max.

• mag_scaling_rel (str) – Magnitude-scaling relation used to calculate the maximum magnitude from the fault parameters.

• m_max (float) – Maximum magnitude in the fault’s magnitude-frequency distribution. This is used for the ‘DoubleTruncatedGR’ mfd.

• m_char (float) – Characteristic magnitude in the fault’s magnitude-frequency distribution. This is used for the ‘YoungsCoppersmith1985’ mfd.

• m_min (float) – Minimum magnitude in the fault’s magnitude-frequency distribution.

• m_cli (float) – In a ‘DoubleTruncatedGR’ we calculate the a-value given b-value, and two magnitude extremes: m_min and m_max. m_cli is the value of magni- tude above which we effectively compute the rates. Note that m_cli >= m_min.

• b_value (float) – Gutenberg-Richter b-value for magnitude-frequency distribution. A b-value passed here will override project and fault defaults.

• slip_rate (float) – Slip rate to be used in calculating the magnitude-frequency distributiuon. A slip_rate passed here will override project and fault defaults.

• aseismic_coefficient (float) – Fraction of slip rate that is released aseismically and doesn’t contribute to moment accumulation or seismic release on the fault. Ranges between 0 and 1.

• bin_width (float) – Width of the bins for the magnitude-frequency distribution.

• fault_area (float) – Surface area of the fault used to calculate the momen release rate on the fault. A slip_rate value passed here will override the value calculated from the fault’s geometry.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

A dictionary with all of the parameters to create a SimpleFaultSource

Return type:

dict

openquake.mbt.tools.fault_modeler.fault_modeling_utils.fetch_param_val(fault_dict, param, defaults=defaults, param_map=param_map)

Finds the value for a fault (or project) parameter by searching first through the fault_dict, then through the defaults.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• param (str) – The name of the parameter to fetch, i.e. the keyword.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_dip(fault_dict, requested_val='mle', defaults=defaults, param_map=param_map)

Returns a value of dip from the dip tuple for each structure. If no dip tuple is present, a default value is returned based on the fault kinematics.

Parameters:

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_fault_area(fault_dict, area_method='simple', width_method='seismo_depth', width_scaling_relation='Leonard2014_Interplate', defaults=defaults, param_map=param_map)

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• area_method (str) – Method used to calculate the surface area of a fault. Possible values are simple and from_surface. The ‘simple’ method calculates the fault area as the fault length times the width (down-dip distance). The from_surface method calculates the fault area through the discretization methods used in the SimpleFaultSurface.

• width_method (str) – Method used to calculate the width (down-dip distance) of a fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated given the scaling_rel. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_fault_length(fault_dict, defaults=defaults, param_map=param_map)

Returns the length of a fault.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Length of fault

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_fault_width(fault_dict, width_method='length_scaling', width_scaling_relation='Leonard2014_Interplate', defaults=defaults, param_map=param_map)

Returns the width (i.e., the down-dip distance) of a fault. Two methods exist: One based on the fault length and a scaling relation, and one based on the upper and lower seismogenic depths.

Parameters:

• fault_dict (dict) – desc

• width_method (str) – Method used to calculate the width of the fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• fault_dict – Dictionary containing the fault attributes and geometry

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Fault width

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_m_max(fault_dict, magnitude_scaling_relation=None, area_method='simple', width_method='seismo_depth', width_scaling_relation='Leonard2014_Interplate', defaults=defaults, param_map=param_map)

Calculates (or fetches) the maximum magnitude for a fault, given a fault attribute, the fault geometry and a scaling relation, or a project default.

The priority order is:

1- Fault attribute. 2- Default value if not none 3- Fault geometry and scaling relation, if lower than m_upper

otherwise use m_upper

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• mag_scaling_rel (openquake.hazardlib.scalrel.BaseMSR) – Magnitude-scaling relation, as implemented in the openquake.hazardlib.scalerel class. If no value is passed here, then the project default magnitude-scaling relation is used.

• area_method (str) – Method used to calculate the surface area of a fault. Possible values are simple and from_surface. The ‘simple’ method calculates the fault area as the fault length times the width (down-dip distance). The from_surface method calculates the fault area through the discretization methods used in the SimpleFaultSurface.

• width_method (str) – Method used to calculate the width (down-dip distance) of a fault. ‘length_scaling’ implements a scaling relation between the fault length (derived from the trace) and the fault width, which is calculated given the scaling_rel. ‘seismo_depth’ calculates the width based on the fault’s dip and the given values for upper and lower seismogenic depth.

• width_scaling_rel (str) – The scaling relation between length and width. Currently, only the scaling relation of Leonard (2010) BSSA is implemented, as ‘leonard_2010’.

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Maximum earthquake magnitude.

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_net_slip_rate(fault_dict, slip_class='mle', param_map=param_map, defaults=defaults)

Either fetches or calculates the net slip rate on a fault given what slip rate component measurements are present and the fault’s geometry and kinematics.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• slip_class (str) – Magnitude of the slip rate (and associated parameters) to be used in the calculations. Possible values are mle (most-likely estimate), min and max.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Net slip rate on fault.

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_rake(fault_dict, requested_val='mle', defaults=defaults, param_map=param_map)

Parameters:

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

openquake.mbt.tools.fault_modeler.fault_modeling_utils.get_scaling_rel(scaling_rel_name)

Return an initialized scaling relation object from the name string

openquake.mbt.tools.fault_modeler.fault_modeling_utils.leonard_width_from_length(fault_dict, const_1=1.75, const_2=1.5, beta=2. / 3., max_width_1=150., max_width_2=17., defaults=defaults, param_map=param_map)

Calculates the down-dip width of the faults following equation 5 of Leonard 2010 BSSA, with the addition of an additional maximum for dip-slip faults.

The width is calculated as:

C * length^beta

where C is defined independently for two separate classes of faults based on the type of fault/

Primarily dip-slip faults fall under WIDTH_CLASS 1, while primarily strike-slip faults fall under WIDTH_CLASS 2.

C is called const_1 and const_2.

Additionally, maximum widths are given here for both fault classes. The maximum width for the strike-slip class is from Leonard 2010, while for the dip slip class one is hereby imposed.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• const_1 (float) – Coefficient for L-W scaling for dip-slip faults.

• const_2 (float) – Coefficient for L-W scaling for strike-slip faults.

• beta (float) – Exponent for length-width scaling. Given as 2/3 by Leonard, 2010.

• max_width_1 (float) – Maximum width for dip-slip faults. Not given by Leonard but a reasonable maximum value given here to prevent runaway ruptures.

• max_width_2 (float) – Maximum width for strike-slip ruptures. Given as 17 by Leonard (2010).

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Maximum width for a fault.

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.line_from_trace_coords(trace_coords)

Creates a Line class from the coordinate pairs of a fault’s trace.

Parameters:

trace_coords – Sequence of coordinate pairs (list, but tuple or numpy.arrays would work, with format [[x0, y0], [x1, y1], …]

Type:

list

Returns:

Line with fault coordinates.

Return type:

openquake.hazardlib.geo.line.Line

openquake.mbt.tools.fault_modeler.fault_modeling_utils.make_fault_source(sfs_dict, oqt_source=False)

Takes a dictionary with the parameters for SimpleFaultSource creation, and creates a SimpleFaultSource.

Parameters:

• sfs_dict (dict) – Dictionary with parameters/attributes for the fault source. May be created with construct_sfs_dict.

• oqt_source (Boolean) – Flag to return a SimpleFaultSource and OQtSource output

Returns:

SimpleFaultSource or OqtSource

openquake.mbt.tools.fault_modeler.fault_modeling_utils.net_slip_from_strike_slip_fault_geom(fault_dict, slip_class='mle', _abs=True, param_map=param_map, defaults=defaults)

Calculates the net slip rate on a fault given a strike slip rate and the fault’s geometry and rake.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• slip_class (str) – Magnitude of the slip rate (and associated parameters) to be used in the calculations. Possible values are mle (most-likely estimate), min and max.

• _abs (bool) – Flag to return the signed or unsigned (absolute value) of the slip rate.

Returns:

Net slip rate.

Return type:

float

openquake.mbt.tools.fault_modeler.fault_modeling_utils.trace_from_coords(fault_dict, defaults=defaults, param_map=param_map, check_coord_order=True)

Gets the fault trace from a fault_dict, makes a Line class, and (optionally, by default) checks the coordinate ordering and dip for the right-hand-rule convention and reverses the coordinates if need be.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

• check_coord_order (bool) – Flag to check the coordinate ordering for right-hand-rule compliance, and reverse the ordering if need be.

Returns:

Line with fault coordinates.

Return type:

openquake.hazardlib.geo.line.Line

openquake.mbt.tools.fault_modeler.fault_modeling_utils.write_geom(fault_dict, requested_val='mle', width_method='seismo_depth', width_scaling_relation='Leonard2014_Interplate', defaults=defaults, param_map=param_map)

Parameters:

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

openquake.mbt.tools.fault_modeler.fault_modeling_utils.write_metadata(fault_dict, defaults=defaults, param_map=param_map)

Gets the fault’s metadata (‘tectonic_region_type’, ‘name’, ‘source_id’) from the fault_dict and writes it in a new dictionary.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Dictionary with metadata.

Return type:

dict

openquake.mbt.tools.fault_modeler.fault_modeling_utils.write_rupture_params(fault_dict, magnitude_scaling_relation=None, defaults=defaults, param_map=param_map)

Gets the fault’s rupture parameters (‘rupture_mesh_spacing’, ‘magnitude_scaling_relation’, ‘rupture_aspect_ratio’, ‘temporal_occurrence_model’) from the fault_dict and writes them in a new dictionary.

Parameters:

• fault_dict (dict) – Dictionary containing the fault attributes and geometry

• defaults (dict) – Dictionary of project defaults.

• param_map (dict) – Dictionary of the mapping from a fault’s attribute names to the variables used in this library.

Returns:

Dictionary with rupture parameters.

Return type:

dict

Other useful functions

These are mostly used within the model-building workflow

openquake.wkf.compute_mmax_from_catalogues.compute_mmax(fname_input_pattern: str, fname_config: str, label: str)

This function assignes an mmax value to each source with a catalogue file as selected by the provided fname_input_pattern.

openquake.wkf.seismicity.hypocentral_depth.hypocentral_depth_analysis(fname: str, depth_min: float, depth_max: float, depth_binw: float, figure_name_out: str = '', show: bool = False, depth_bins=[], remove_fixed=[], label='', figure_format='png') → Tuple[ndarray, ndarray]

Parameters:

• fname – The name of the file containing the catalogue

• depth_min – The minimum depth [km]

• depth_max – The maximum depth [km]

• depth_binw – The width of the bins used [km]. Alternatively it’s possible to use the bins by setting the bins variable.

• figure_name_out – The name of the figure to be created

• show – When true the show figures on screen

• depth_bins – The bins used to build the statistics. Overrides the depth_min, depth_max, depth_binw combination.

• remove_fixed – list of fixed depth values to be removed from the analysis

• label – A label used in the title of the figure

• figure_format – Format of the figure

openquake.wkf.seismicity.nodal_plane.process_gcmt_datafames(fname_folder: str, folder_out: str, save_csv: bool = False)

Process GCMt dataframes describing the nodal planes of events and produce figures of the classification of the focal mechanisms according to Kaverina et al. (1996)

Parameters:

• fnames – A list containing the names of the files to be processed or a pattern These should be csv files containing information from GCMT (plunge_b, plunge_p, plunge_t, dip1, dip2, strike1, strike2)

• folder_out – The name of the output folder

• save_csv – If true, save a copy of the input data with an appended fm column representing the classification

openquake.mbi.wkf.focal_mech_loc_plots.focal_mech_loc_plots(fname, figsize=(15, 10), width=0.5, size=0.1)

Produce a figure consisting of:

1. nodal planes plotted in space (lat/Lon) with Kaverina classification colours

2. scatterplot of event Kaverina classificatons and magnitudes

3. scatterplot of event strike vs rake, coloured by Kaverina classification

Please note that the ‘width’ parameter might need to be adjusted for different models

openquake.wkf.seismicity.smoothing.create_smoothing_per_zone(fname_points: str, fname_polygons: str, folder_out: str = '/tmp', skip: str = [], use: str = [])

Creates subsets of points, one for each of the polygons included in the fname_polygons shapefile. The attibute table must have an ‘id’ attribute.

Parameters:

• fname_points – Name of the file with the output of the smoothing

• fname_polygons – The shapefile with the polygons

• folder_out – The name of the folder where to write the output

Returns:

A number of .csv files in folder_out

openquake.mbi.wkf.create_nrml_sources.write_as_multipoint_sources(df, model, src_id, subzones, model_subz, mmin, bwid, rms, tom, folder_out)

Write a set of point sources to NRML as a multi-point

Parameters:

• df – A dataframe where each row is a point source

• model – A dictionary with the model representation

• src_id – A string with the ID of the source

• subzones – Must be false since we do not support this feature

• model_subz – ditto

• mmin – A float defining the minimum magnitude of the newly created source

• bwid – A float defining the width of the magnitude bins for the MFD of the newly created source

• rms – A float specifying the rupture mesh spacing

• tom – An instance of openquake.hazardlib.tom.BaseTOM subclasses

• folder_out – The output folder