Merge pull request #442 from GEMScienceTools/update_mgmpe

adding M9 basin adjustment capabilities to comparison module

docsrc/contents/smt.rst

@@ -96,7 +96,7 @@ We can specify the inputs to perform a residual analysis with as follows:
         
 3. We can also specify the GMPEs and intensity measures within a ``.toml`` file. The ``.toml`` file method is required for the use of GMPEs with user-specifiable input parameters.
 
-   The additional input parameters which are specifiable for certain GMPEs are available within their corresponding GSIM files (found in ``oq-engine.openquake.hazardlib.gsim``). or for ModifiableGMPE features in ``oq-engine.openquake.hazardlib.gsim.mgmpe.modifiable_gmpe``).
+   The additional input parameters which are specifiable for certain GMPEs are available within their corresponding GMPE ``.py`` files (found in ``oq-engine.openquake.hazardlib.gsim``). or for ModifiableGMPE features in ``oq-engine.openquake.hazardlib.gsim.mgmpe.modifiable_gmpe``).
 
    The ``.toml`` file for specifying GMPEs and intensity measures to consider within a residual analysis should be specified as follows:
 
@@ -138,16 +138,6 @@ We can specify the inputs to perform a residual analysis with as follows:
                          # a single residuals toml the results of the last variant of the GMPE
                          # will overwrite the others (and only the results of the last variant 
                          # in the toml will be plotted too). This bug will be fixed.
-       
-       # Note that a bug exists for GMPEs which use the add_alias feature, meaning that the user
-       # must specify parameters that should be inherently used by specifiying the gsim class (to
-       # be fixed). Some examples of how to circumvent this bug are provided below
-       
-       [models.AbrahamsonEtAl2014] # Use instead of specifying AbrahamsonEtAl2014RegJPN
-       region = "JPN"
-       
-       [models.NGAEastUSGSGMPE]  # Use instead of specifying NGAEastUSGSSeed1CCSP or 1CCSP gsim classes
-       gmpe_table = 'nga_east_1CCSP.hdf5'
             
        [imts]
        imt_list = ['PGA', 'SA(0.1)', 'SA(0.2)', 'SA(0.5)', 'SA(1.0)']    
@@ -438,7 +428,9 @@ Comparing GMPEs
 
 2. The tools within the Comparison module include Sammon's Maps, hierarchical clustering plots and matrix plots of Euclidean distance for the median (and 16th and 84th percentiles) of predicted ground-motion per GMPE per intensity measure. Plotting capabilities for response spectra and attenuation curves (trellis plots) are also provided in this module.
 
-   The inputs for these comparitive tools must be specified within a single ``.toml`` file as specified below. GMPE parameters can be specified as within the example ``.toml`` file provided above for us in residual analysis. In the ``.toml`` file we have specified the source parameters for earthquakes characteristic of Albania (compressional thrust faulting with magnitudes of interest w.r.t. seismic hazard in the range of Mw 5 to Mw 7), and we have specified some GMPEs which were found to perform well in the residual analysis against Albania ground-motion data. To plot a GMPE logic tree we must assign model weights using ``lt_weight_gmc1`` or '``lt_weight_gmc2`` in each GMPE depending on which GMC logic tree we wish to include the GMPE within (up to 4 GMC logic trees can currently be plotted within one analysis). To plot only the final logic tree and not the individual GMPEs comprising it, we use ``lt_weight_gmc1_plot_lt_only`` instead (depending on which GMC we wish to not plot the individual GMPEs for - see the .toml file below for an example of these potential configurations).
+   The inputs for these comparitive tools must be specified within a single ``.toml`` file as specified below. GMPE parameters can be specified as within the example ``.toml`` file provided above for us in residual analysis. In the ``.toml`` file we have specified the source parameters for earthquakes characteristic of Albania (compressional thrust faulting with magnitudes of interest w.r.t. seismic hazard in the range of Mw 5 to Mw 7), and we have specified some GMPEs which were found to perform well in the residual analysis against Albania ground-motion data. To plot a GMPE logic tree we must assign model weights using ``lt_weight_gmc1`` or '``lt_weight_gmc2`` in each GMPE depending on which GMC logic tree we wish to include the GMPE within (up to 4 GMC logic trees can currently be plotted within one analysis). To plot only the final logic tree and not the individual GMPEs comprising it, we use ``lt_weight_gmc1_plot_lt_only`` instead (depending on which GMC we wish to not plot the individual GMPEs for - see the ``.toml`` file below for an example of these potential configurations).
+
+   NOTE: To specify a GMM argument which is a bool (i.e. ``True`` or ``False``), the user must specify the bool as all lowercase within the ``.toml`` file (i.e. ``true`` or ``false``). An example is provided immediately below for the ``CampbellBozorgnia2014`` GMPE.
 
     .. code-block:: ini
     
@@ -494,39 +486,39 @@ Comparing GMPEs
         
         # Plot logic tree and individual GMPEs within first GMC logic tree config (gmc1)
         [models.BooreEtAl2020]
-            lt_weight_gmc1 = 0.30
+        lt_weight_gmc1 = 0.30
             
         [models.LanzanoEtAl2019_RJB_OMO]
-            lt_weight_gmc1 = 0.40
+        lt_weight_gmc1 = 0.40
         
         # Default ESHM20 logic tree branches considered in gmc1
         [models.1-KothaEtAl2020ESHM20]
-            lt_weight_gmc1 = 0.000862
-            sigma_mu_epsilon = 2.85697 
-            c3_epsilon = 1.72    
+        lt_weight_gmc1 = 0.000862
+        sigma_mu_epsilon = 2.85697 
+        c3_epsilon = 1.72    
         [models.2-KothaEtAl2020ESHM20]   
-            lt_weight_gmc1 = 0.067767
-            sigma_mu_epsilon = 1.35563
-            c3_epsilon = 0
+        lt_weight_gmc1 = 0.067767
+        sigma_mu_epsilon = 1.35563
+        c3_epsilon = 0
         [models.3-KothaEtAl2020ESHM20]   
-            lt_weight_gmc1 = 0.162742
-            sigma_mu_epsilon = 0
-            c3_epsilon = 0        
+        lt_weight_gmc1 = 0.162742
+        sigma_mu_epsilon = 0
+        c3_epsilon = 0        
         [models.4-KothaEtAl2020ESHM20]
-            lt_weight_gmc1 = 0.067767
-            sigma_mu_epsilon = -1.35563
-            c3_epsilon = 0 
+        lt_weight_gmc1 = 0.067767
+        sigma_mu_epsilon = -1.35563
+        c3_epsilon = 0 
         [models.5-KothaEtAl2020ESHM20]
-            lt_weight_gmc1 = 0.000862
-            sigma_mu_epsilon = -2.85697 
-            c3_epsilon = -1.72    
+        lt_weight_gmc1 = 0.000862
+        sigma_mu_epsilon = -2.85697 
+        c3_epsilon = -1.72    
             
         # Plot logic tree only for a second GMC logic tree config (gmc2)
         [models.CauzziEtAl2014]
-            lt_weight_gmc2_plot_lt_only = 0.50
+        lt_weight_gmc2_plot_lt_only = 0.50
             
         [models.AkkarEtAlRjb2014]
-            lt_weight_gmc2_plot_lt_only = 0.50
+        lt_weight_gmc2_plot_lt_only = 0.50
             
         # Also specify a GMM to compute ratios of the attenuation against (GMM/baseline)
         [ratios_baseline_gmm.BooreEtAl2020]
@@ -586,7 +578,7 @@ Comparing GMPEs
        > # Plot ratios of median attenuation curves for each GMM/median attenuation curves for baseline GMM
        > comp.plot_ratios(filename, output_directory) 
 
-    Ratio plots for input parameters specified in toml file (note that here the baseline GMM is BooreEtAl2014):
+    Ratio plots for input parameters specified in toml file (note that here the baseline GMM is ``BooreEtAl2014``):
         .. image:: /contents/smt_images/RatioPlots.png      
 
 7. Sammon's Maps
@@ -699,7 +691,15 @@ Comparing GMPEs
         [models.12-ModifiableGMPE]
         gmpe = 'BooreEtAl2014'
         site_term = 'NRCan15SiteTermLinear' # Use NRCan15 linear site term
-    
+
+        [models.13-ModifiableGMPE]
+        gmpe = 'AtkinsonMacias2009'
+        basin_term = 'CB14BasinTerm' # Apply CB14 basin adjustment
+
+        [models.14-ModifiableGMPE]
+        gmpe = 'KuehnEtAl2020SInter'
+        basin_term = 'M9BasinTerm' # Apply M9 basin adjustment
+            
 References
 ==========
 

openquake/smt/comparison/compare_gmpes.py

@@ -132,10 +132,6 @@ def get_gmpes(config_file):
         value = get_model(key, config['models'])
         gmpe_list.append(value.strip())
 
-    # Check number of GMPEs matches number of GMPE labels
-    if len(gmpe_list) != len(gmpe_labels):
-        raise ValueError("Number of labels must match number of GMPEs.")
-
     # Get the baseline GMPE used to compute ratios of GMPEs with if required
     if 'ratios_baseline_gmm' in config_file.keys():
         if len(config_file['ratios_baseline_gmm']) > 1:
@@ -311,6 +307,9 @@ def plot_cluster(filename, output_directory):
     """ 
     config = Configurations(filename)
 
+    if len(config.gmpes_list) != len(config.gmpe_labels):
+        raise ValueError("Number of labels must match number of GMPEs.")
+
     if len(config.gmpes_list) < 2:
         raise ValueError("Cannot perform clustering for a single GMPE.")   
 
@@ -344,6 +343,9 @@ def plot_sammons(filename, output_directory):
         plotting methods.
     """ 
     config = Configurations(filename)
+
+    if len(config.gmpes_list) != len(config.gmpe_labels):
+        raise ValueError("Number of labels must match number of GMPEs.")
 
     if len(config.gmpes_list) < 2:
         raise ValueError("Cannot perform Sammons Mapping for a single GMPE.")
@@ -380,6 +382,9 @@ def plot_euclidean(filename, output_directory):
     """ 
     config = Configurations(filename)
 
+    if len(config.gmpes_list) != len(config.gmpe_labels):
+        raise ValueError("Number of labels must match number of GMPEs.")
+
     if len(config.gmpes_list) < 2:
         raise ValueError(
             "Cannot perform Euclidean dist matrix plotting for a single GMPE.")

openquake/smt/comparison/utils_compare_gmpes.py

@@ -689,7 +689,7 @@ def get_colors(custom_color_flag, custom_color_list):
     colors = ['r', 'g', 'b', 'y', 'lime', 'dodgerblue', 'gold', '0.8', 'm', 'k',
               'mediumseagreen', 'tab:orange', 'tab:purple', 'tab:brown', '0.5']
 
-    if custom_color_flag == 'True':
+    if custom_color_flag is True:
         colors = custom_color_list
 
     return colors

openquake/smt/comparison/utils_gmpes.py

@@ -305,7 +305,8 @@ def mgmpe_check(gmpe):
     """
     Check if the GMPE should be modified using ModifiableGMPE. This function in
     effect parses the toml parameters for a GMPE into the equivalent parameters
-    required for ModifiableGMPE
+    required for ModifiableGMPE. If a ModifiableGMPE is not required, a valid
+    GSIM object with all specified kwargs is returned instead
     :param gmpe:
         gmpe: GMPE to be modified if required
     """
@@ -318,7 +319,8 @@ def mgmpe_check(gmpe):
         for idx, par in enumerate(params):
             if idx > 1:
                 par = str(par)
-                if 'sigma_model' in par or 'site_term' in par:
+                if ('sigma_model' in par or 'site_term' in par or
+                    'basin_term' in par):
                     idx_params.append(idx)
                 if 'fix_total_sigma' in par:
                     idx_params.append(idx)
@@ -421,6 +423,14 @@ def mgmpe_check(gmpe):
         # NRCan15SiteTerm (linear)
         if 'NRCan15SiteTermLinear' in gmpe:
             kwargs['nrcan15_site_term'] = {'kind': 'linear'}
+
+        # CB14 basin term
+        if 'CB14BasinTerm' in gmpe:
+            kwargs['cb14_basin_term'] = {}
+
+        # M9 basin adjustment
+        if 'M9BasinTerm' in gmpe:
+            kwargs['m9_basin_term'] = {}
 
         gmm = mgmpe.ModifiableGMPE(**kwargs)
 
@@ -435,9 +445,12 @@ def mgmpe_check(gmpe):
                 idx_to_drop.append(idx_p)
         params = params.drop(idx_to_drop)
         gmpe_clean = params.iloc[0].strip()
-        for idx_p, par in enumerate(params):
-            if idx_p > 0:
-                gmpe_clean = gmpe_clean + '\n' + par
+        if len(params) > 1:
+            for idx_p, par in enumerate(params):
+                if idx_p > 0:
+                    gmpe_clean = gmpe_clean + '\n' + par
+        else: # Ensures GSIM aliases work
+            gmpe_clean = gmpe_clean.replace('[','').replace(']','')
         gmm = valid.gsim(gmpe_clean)
-        
+
     return gmm

openquake/smt/demos/demo_comparison_analysis_inputs.toml

@@ -39,7 +39,7 @@ non_trellis_or_spectra_depths = [[5, 20], [6, 20], [7, 20]] # [[mag, depth], [ma
 
 # Specify label for gmpes
 [gmpe_labels]
-gmpes_label = ['B20', 'L19', 'K1', 'K2', 'K3', 'K4', 'K5', 'CA15', 'AK14']
+gmpes_label = ['B20', 'L19', 'K1', 'K2', 'K3', 'K4', 'K5', 'CB14', 'AK14']
 
 # Specify gmpes
 
@@ -77,15 +77,16 @@ sigma_mu_epsilon = -2.85697
 c3_epsilon = -1.72    
 
 # Plot logic tree only for the second GMC logic tree config (gmc2)
-[models.CauzziEtAl2014]
+[models.CampbellBozorgnia2014]
 lt_weight_gmc2_plot_lt_only = 0.50
-
+estimate_ztor=true
+
 [models.AkkarEtAlRjb2014]
 lt_weight_gmc2_plot_lt_only = 0.50
 
 # Also specify a GMM to compute ratios of the attenuation against (GMM/baseline)
 [ratios_baseline_gmm.BooreEtAl2020]
 
 [custom_colors]
-custom_colors_flag = 'False' # Set to "True" for custom colours in plots)
+custom_colors_flag = false # Set to true for custom colours in plots)
 custom_colors_list = ['lime', 'dodgerblue', 'gold', '0.8']

openquake/smt/tests/comparison/data/compare_gmpe_inputs.toml

@@ -57,5 +57,5 @@ lt_weight_gmc2_plot_lt_only = 0.5
 
 
 [custom_colors]
-custom_colors_flag = 'False' #By default set to "False" (set to "True" for custom colours)
+custom_colors_flag = false # Set to true for custom colours
 custom_colors_list = ['lime','dodgerblue','gold','0.8']

openquake/smt/tests/comparison/data/mgmpe_inputs.toml

@@ -36,7 +36,7 @@ non_trellis_or_spectra_depths = [[5,20],[6,25],[7,30]] # [[mag,depth],[mag,depth
 
 # Specify label for gmpes
 [gmpe_labels]
-gmpes_label = ['NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA']
+gmpes_label = ['NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA', 'NA']
 
 [models.0-ModifiableGMPE]
 gmpe = 'YenierAtkinson2015BSSA'
@@ -89,7 +89,15 @@ add_delta_sigma_to_total_sigma = 0.5 # Add a delta to the total GMPE sigma
 [models.12-ModifiableGMPE]
 gmpe = 'CampbellBozorgnia2014'
 set_total_sigma_as_tau_plus_delta = 0.5 # Set total sigma to square root of (tau**2 + delta**2)
-
+
+[models.13-ModifiableGMPE]
+gmpe = 'AtkinsonMacias2009'
+basin_term = 'CB14BasinTerm' # Apply CB14 basin adjustment
+
+[models.14-ModifiableGMPE]
+gmpe = 'KuehnEtAl2020SInter'
+basin_term = 'M9BasinTerm' # Apply M9 basin adjustment
+
 [models.NGAEastGMPE]
 gmpe_table = 'NGAEast_FRANKEL_J15.hdf5' # use a gmpe table
 
@@ -103,5 +111,5 @@ sigma_model = 'al_atik_2015_sigma' # use Al Atik (2015) sigma model
 with_betw_ratio = 1.5
 
 [custom_colors]
-custom_colors_flag = 'False' # By default set to "False" (set to "True" for custom colours)
+custom_colors_flag = false # Set to true for custom colours
 custom_colors_list = ['lime','dodgerblue','gold','0.8']