Web-service Disagg Calc for IML: Unclear what the "Disaggregation Targets" output should be communicating to users
When we perform a hazard disaggregation at a particular return period (say, 2475 years), it makes sense to provide information on the difference between the target return period that the user has provided, and the return period that the actual disaggregation corresponds to. That's because disaggregation calcs fundamentally occur at a given IM level, not a return period. Most of the time the IML for the desired return period is interpolated from an initial hazard curve, and that there will be a slight mismatch between the interpolated value and the return period of the actual IML.
On the other hand, if we're skipping the specified return period and only care about disaggregating at a target IML, say, PGA=2.3 g, then as a user I wouldn't expect to see a "target return period" at all - or at least I'd expect that the target and recovered return periods are the same. Instead, when I do a web service call for the disagg IML:
url = 'https://earthquake.usgs.gov/ws/nshmp/conus-2018/dynamic/disagg/-122.3/47.61/200?PGA=2.3&out=DISAGG_DATA'
The summary
response in data
looks like:
{'name': 'Disaggregation targets',
'display': True,
'data': [{'name': 'Return period', 'value': 898804.63, 'units': 'yrs'},
{'name': 'Exceedance rate', 'value': 1.1125888e-06, 'units': 'yr⁻¹'},
{'name': 'PGA ground motion', 'value': 2.3, 'units': 'g'}]},
{'name': 'Recovered targets',
'display': True,
'data': [{'name': 'Return period', 'value': 1882632.7, 'units': 'yrs'},
{'name': 'Exceedance rate', 'value': 5.3117105e-07, 'units': 'yr⁻¹'}]}
Initially, I wasn't sure what the correct exceedance rate value actually was - this is important to know if a user is doing a risk analysis that involves constructing the hazard space from multiple disaggs, rather than a single hazard curve calculation. To check, I ended up running a hazard calc web-service call:
url = 'https://earthquake.usgs.gov/ws/nshmp/conus-2018/dynamic/hazard/-122.3/47.61/200?truncate=false&maxdir=false&imt=PGA'
response:
{'component': 'Total',
'values': {'xs': [
... ,
1.02,
1.53,
2.3,
3.44,
5.17],
'ys': [
... ,
0.00010766422,
1.6666815e-05,
1.1125888e-06,
3.7650503e-08,
2.6863475e-09]}}
So it looks like, based on the hazard calc value at PGA=2.3 g, the AFE of 1.11e-06 corresponds to the value in "Disaggregation Targets" above. My question is then, what does the "Recovered targets" refer to? Is there some way to make it clear in the IML disagg output which IML-AFE pair the data actually refers to?