Implements ConditionalGMPE class and applies it with model of Macedo et al. (2019)

[g-weatherill]

The pull request implements a new form of GMPE, which is a conditional ground motion model. This describes a family of ground motion models in which the predicted parameter is dependent not only on source, distance and site properties, but also on a different ground motion measure (e.g. PGA, SA(T)). This is applied here to the GMM of Macedo et al. (2019), but several other examples can be found in the literature (e.g. Abrahamson et al., 2016; Liu et al. 2022; Campbell et al., 2023; among others). Most conditional GMMs are for intensity measures such as duration, Arias Intensity or Cumulative Absolute Velocity, which include as predictors the more common peak motion or response spectral parameters such as PGA or SA(T).

A general template for a conditional GMPE is provided via the ConditionalGMPE class, which extends the standard GMPE class in two ways: 1) it requires specification of the intensity measures upon which the predicted parameter is conditioned (including the spectral period) and 2) it adds a function get_conditioning_ground_motions, which retrieves the ground motion values themselves.

The implementation is designed to address two use cases:

1. The case in which the ground motion values (GMVs) that form the inputs to the ConditionalGMPE are known explicitly or calculated independently of OpenQuake. This is the "Shakemap" case and applies when the GMM is used directly from the library (rather than as part of an OpenQuake calculation). Here the known GMVs and their uncertainties can be input into the GMM by adding these as labelled vectors inside the ctx recarray alonside the source, path and distance properties, e.g. PGA_MEAN, PGA_TOTAL_STDDEV, SA(1.0)_MEAN, SA(1.0)_TOTAL_STDDEV etc.

2. The case in which the ground motion values (GMVs) are not specified a priori and must instead be determined from a ground motion model. This case would allow the conditional GMM to be used in a probabilistic seismic hazard and risk calculation, for which no GMVs are known a priori. The extact manner in which the uncertainty in the conditioning ground motion is propagated through to the predicted ground motion may vary from model to model and is therefore left to be addressed in the implementation of the GMM in question. The Macedo et al. (2019) GMM here illustrates clearly how this should be done, however.

If the GMPE is not specified nor are the predictor GMVs provided in the ctx then an error will be raised.

Tests are developed for both the ConditionalGMM class and the MacedoEtAl2019SInter/SSlab classes. For the Macedo et al. (2019) model we have not yet been able to obtain an independent implementation of the model from the authors to generate the test tables. We did, however, verify the output ground motions against the figures provided in the original publication to a satisfactory level of agreement. Wetherefore apply the NotVerified warning. The Macedo et al. (2019) model is also regionalised, so this is included as a configurable parameter and as a set of aliases.

Finally, the conditional GMM is demonstrated in a classical PSHA test case via the Macedo et al. (2019) GMM to produce curves for Arias intensity conditioned on PGA and SA(1.0 s).

Including here @emthompson-usgs and @cbworden for feedback regarding the Shakemap use case.

[emthompson-usgs]

Thanks @g-weatherill and sorry for not posting earlier. This will be very important for the ShakeMap team, and we plan to use this as a template to contribute more conditional models to OQ in the coming months.

[emthompson-usgs]

Hi @g-weatherill and @mmpagani,

I'm trying to work out how to call this class with the preferred method as indicated in @micheles's response to an issue we had in which the advice is to use the ContextMaker class along with it's get_mean_stds method. I'll note that it is relatively easy to get this to work by calling the ConditionalGMPE class directly, so this quesiton is about how to make the ConditionalGMPE class work with the ContextMaker.

If I simply substitute in the MacedoEtAl2019SInter model into @micheles's example:

import numpy as np
from openquake.hazardlib import valid
from openquake.hazardlib.contexts import simple_cmaker

gsim = valid.gsim('''[MacedoEtAl2019SInter]''')
n = 10
mags = np.linspace(5, 7, n)
cmaker = simple_cmaker([gsim], ['PGA'], mags=['%.2f' % mag for mag in mags])
ctx = cmaker.new_ctx(n)
ctx["mag"] = mags
ctx["vs30"] = np.linspace(200, 300, n)
ctx["rrup"] = np.linspace(1, 100, n)

mean, sigma, tau, phi = cmaker.get_mean_stds([ctx])

I get a sensible error since I haven't specified a conditioning data or model:

ValueError: Conditioning ground motions must be specified in ctx or a GMPE must be provided

If I try to add the condition data to the ctx:

ctx["SA(1.0)_MEAN"] = np.logspace(-1., 0.0, n)

I get an error:

ValueError: no field of name SA(1.0)_MEAN

I can get around this by directly creating the ctx with np.recarray.

Additionally, the ConditionalGMPE class takes a gmpe argument that can be used if conditioning data are not provided. It seems like this should be provided through the valid.gsim method. My first guess at how this would work is like this:

gsim = valid.gsim('''[MacedoEtAl2019SInter]
gmpe=[AbrahamsonEtAl2015SInter]''')

But that results in an error:

AttributeError: 'str' object has no attribute 'items'

Any guidance on how to resolve these issues would be great. Thanks.

[kslytherin]

Why do you list AbrahamsonEtAl2019 in the comments but in the in fact you use AbrahamsonEtAl2015? Is this a typo?

[g-weatherill]

Yes, this is a typo. Thanks for spotting it.

[emthompson-usgs]

@g-weatherill @micheles, we have another conditional GMM that we would like to contribute but it inherits from the ConditionalGMPE that is created in this pull request. I haven't run into this issue before. Should our feature branch off of the g-weatherill:ConditionalGMM branch instead of master? Sorry, I'm not sure what the best practice is in this situation.

[g-weatherill]

@emthompson-usgs Thanks for looking into this. A couple of comments:

1. I can get around this by directly creating the ctx with np.recarray.

Yes, the ctx has to be created as a recarray. The function looks for the required fields within the dtype.names of the recarray.

2. Any guidance on how to resolve these issues would be great. Thanks.

The following seems to work for me using valid.gsim:

gmm = valid.gsim('[MacedoEtAl2019SInter]\ngmpe.AbrahamsonEtAl2015SInter={}')

I'm not totally fluent in the TOML syntax, but it should be possible to pass arguments to the GMM being specified in the gmpe argument too. Probably @micheles can clarify that.

3. Regarding contributing another GMPE that inherits from this branch ... I think the general git best practice would be to create another branch off of the g-weatherill:ConditionalGMM branch. That being said, however, I would suggest to proceed with caution in this case, as it is not clear whether this feature is being considered as a candidate feature for the oq-engine (and after 7 months of inactivity, one would begin to assume it is not!). There are already incompatibilities in this branch with the current master after this Removed **kwargs from the GMPE signatures #9595. So if you plan to use it in your own fork then you could just use the current branch as it is and add your GMPE locally, then wait to see whether this becomes a feature of the oq-engine (in which case you can just open a new PR with the additional model) or not (in which case you may as well just work with this feature and the additional model locally).

[micheles]

We are being slow in replying here because Marco has been travelling around the world in the last two weeks, please have patience.

[emthompson-usgs]

@g-weatherill Thanks for the pointers. We now have a branch with the Macedo et al. 2021 model and it is getting close to being ready and fully tested. I am hopeful that this feature will be merged (and the incompatibility with master can be resolved) and we can then add the 2021 model shortly after. In the meantime, we can think about possible contingency plans.