To be a valid perturbation script, a file must use the python .py extension, be placed in the srf_generation/source_parameter_generation/uncertainties/versions directory of the Pre-Processing repository and have a function called generate_source_params.

Perturbation function

The function generate_source_params should have the following signature:

def generate_source_params(
    source_data: Union[GCMT_Source, NHM_Source],
    additional_source_parameters: Dict[str, Any],
    vel_mod_1d: pd.DataFrame,
    vs30_data: pd.DataFrame = None,
    **kwargs
) -> Dict[str, Any]:

Parameters:

source_data:

Is named tuple of the type GCMT_Source or NHM_Source, containing all the relevant information from the source input file for that event/fault.

GCMT_Source has the following attributes, accessible by way of dot notation:

  • pid (str): The name of the event
  • lat, lon, depth, mag, strike, dip, rake (float): As expected

NHM_Source has the following attributes, accessible by way of dot notation:

  • name (str): The name of the fault
  • tect_type (str): The tectonic type of the fault, usually one of SHALLOW_CRUSTAL, VOLCANIC, SUBDUCTION_INTERFACE
  • fault_type (str): The type of fault, usually one of NORMAL_FAULT, OTHER_CRUSTAL_FAULTING
  • length_mean (float): The length of the
  • length_sigma, # float
  • dip_mean (float): The mean dip of the fault
  • dip_sigma (float): The sigma value of the fault dip
  • dip_dir (float): The direction the fault dips in
  • rake (float): The fault rake
  • dbot_mean (float): The mean bottom depth of the fault
  • dbot_sigma (float): The sigma value of the fault bottom depth
  • dtop_mean (float): The mean fault top depth
  • dtop_min (float): The minimum fault top depth
  • dtop_max (float): The maximum fault top depth
  • slip_rate_mean (float): The mean fault slip rate
  • slip_rate_sigma (float): The sigma value of the fault slip rate
  • coupling_coefficient (float):
  • coupling_coefficient_sigma (float)
  • magnitude_mean (float): The mean magnitude of the fault. We usually calculate the magnitude from the Leonard or Skarlatoudis magnitude area scaling relation instead
  • recurrance_interval_mean (float): The mean number of years between ruptures
  • coordinates (List of float pairs): The lon-lat points of the top edge of each subfault, where each point shares a subfault with each of the two adjacent points.

additional_source_params:

Any parameters specified by way of the --source_params or --common_source_params arguments will be available from this dictionary using the name passed as the key. e.g. additional_source_params["sdrop"]

vel_mod_1d:

This contains the 1d velocity model used for srf generation as a pandas DataFrame, where each row is a layer, and the columns are depth (The depth of that layer), vp, vs, rho, qp, qs.

The columns are available by using the column names as keys (vel_mod1d["vs"]), while the rows are available using the iloc method of the dataframe (vel_mod_1d.iloc(5))

depthvpvsrhoqpqs

If the dataframe is iterated over using vel_mod_1d.itertuples(), the properties are available as shown below:

for line in vel_mod_1d.itertuples():
    d   = line.depth
    vp  = line.vp
    vs  = line.vs
    rho = line.rho
    qp  = line.qp
    qs  = line.qs

vs30_data:

If provided this will be a DataFrame with station vs30 medians and sigmas. If sigmas are not given as an argument they will not be available here. The keys of the dataframe are the station names, so the .loc method of the dataframe is available if selecting a particular station is required, otherwise access the same as the vel_mod_1d DataFrame.

Store the realised vs30 in a new dataframe in the 'vs30' column

mean, sigma = vs30_data.loc['CCCC']
for station in vs30_data.itertuples():
    mean   = station.median
    sigma  = station.sigma

**kwargs:

This argument is provided only to preserve compatibility with possible future function signatures.

If the function signature changes and this parameter is not available then the version file will not be compatible and crash when attempting to perturbate the realisation.

Should not normally be used in a function, as any parameters needed should be specified.

Return value

The return value of the function should be a dictionary with strings as keys.

The available keys are as follows with the expected contents listed, any additional keys will be ignored.

  • params: A dictionary containing key-value pairs, the keys should all be strings and the values should all be simple python variable (Not objects like a DataFrame). All elements in this should be in one of the lists in the common script. All the values in this dictionary will be saved to the realisation csv file.
  • vel_mod_1d: A DataFrame containing a perturbated velocity model, if this is the same as the input velocity model, then it is not saved.
    • This can be constructed by taking a copy of the input dataframe using vel_mod_1d.copy(deep=True) and modifying the values contained.  The original dataframe should not be modified
  • vs30: A DataFrame containing perturbated vs30 values for each station. These must be stored in the "vs30" column to be saved correctly. This can be the original dataframe with a "vs30" column added, as only the "vs30" column will be saved

  • asperities (Optional): A dictionary with two keys: "background" and "asperities". The value for background should be a numeric value to be used as the value in non-asperity regions of the slip. The value for asperities should be a list of Asperity objects from the first to be applied to the last to be applied, with later ones over writing any overlap with earlier ones.


Example return dict:

realisation = {
    "params": params_dict,
    "vel_mod_1d": perturbated_veloicty_model_dataframe,
    "vs30": vs30_data["median"],
    "asperities": {"background": 1.0, "asperities": [BottomAsperity, TopAsperity]},
}

Rest of the file

The rest of the file can be used as the user wishes, such as defining additional probability distributions.

Fault objects are available, the correct fault type can be obtained by calling

  • No labels