Ground-Motion Correlation Models#
Ground-motion models predict a median logarithmic intensity and its aleatory variability. Ground-motion correlation models describe the dependence between the residuals sampled around that median. This dependence matters when ground motions are generated at multiple sites, for multiple intensity measure types (IMTs), or when observations are used to condition a simulated field.
Residual components#
For event \(e\), site \(s\) and IMT \(i\), the logarithmic ground motion can be written as
where \(\mu\) is the median predicted by the ground-motion model, \(\eta\) is a standardized between-event residual and \(\epsilon\) is a standardized within-event residual. The corresponding standard deviations are \(\tau\) and \(\phi\); the total standard deviation is commonly written as
The residual components have different dependence structures and must not be interchanged:
A within-event model describes residual variation between sites during the same earthquake. It may also describe dependence between IMTs.
A between-event model describes dependence between the event terms of different IMTs. An event term is shared by all sites affected by that event.
A total-residual model describes dependence between the sum of the two residual components. It is commonly used in conditional-spectrum methods.
If between-event and within-event correlations are known separately, the same-site total-residual correlation is
A published total-residual model does not, by itself, identify the separate between-event and within-event correlations.
Dimensions of correlation#
The OpenQuake hazard library distinguishes three geometric capabilities.
Spatial correlation#
A spatial model gives the correlation of one IMT between two sites, usually as a function of their separation \(h\):
When a spatial-only model is used for multiple IMTs, it correlates the sites independently for each IMT. It does not supply the off-diagonal cross-IMT blocks.
Cross-IMT correlation#
A cross-IMT model gives the correlation between two IMTs at the same site:
The residual component for which the model was calibrated remains essential. For example, a total-residual cross-IMT model must not be substituted for a between-event model merely because both return an IMT-by-IMT matrix.
Joint spatial and cross-IMT correlation#
A direct joint model gives the dependence between any two site-and-IMT pairs:
For \(M\) IMTs and \(N\) sites, OpenQuake orders the joint vector by IMT, so the correlation matrix has shape \(MN \times MN\). Direct joint models can also return rectangular blocks between target and observation locations. Those blocks are required for station conditioning.
Separate spatial and cross-IMT models are sometimes combined using a separable approximation,
This is a modelling assumption, not a general identity. A direct joint model is preferable when one has been calibrated for the application.
Covariance and sampling#
For within-event residuals, a correlation coefficient becomes a covariance through the site- and IMT-dependent standard deviations:
The equivalent expression for between-event residuals uses \(\tau\), while total-residual covariance uses \(\sigma\). The OpenQuake correlation-model interfaces operate primarily on standardized correlations; calculators apply the corresponding standard deviations when constructing covariance or residual ground motions.
The default sampler forms a dense correlation matrix and uses a Cholesky factorization. Its memory requirement grows quadratically and its factorization cost grows cubically with \(MN\). Consequently, a calculation that is tractable for one IMT or a small site collection can become infeasible for a large multi-IMT field. Structured methods and alternative factorizations are needed for substantially larger calculations.
Configuration examples are provided in the User Guide for scenario hazard, event-based PSHA, ShakeMap workflows, and advanced calculations. The implemented model classes and interfaces are listed in the hazardlib API reference.
Conditioning on observations#
Conditioning requires more than marginal posterior standard deviations. If \(T\) denotes target values and \(O\) observations, the posterior within-event covariance contains the full joint blocks \(\Sigma_{TT}\), \(\Sigma_{TO}\) and \(\Sigma_{OO}\):
This is why direct joint models expose rectangular correlation blocks. See Conditioning Ground Shaking for the complete conditioning workflow.
The current compatibility path uses Jayaram and Baker (2009) when no within-event model is configured and Goda and Atkinson (2009) when no between-event model is configured. If the selected within-event model is spatial-only, the off-diagonal IMT blocks are completed with a fixed Baker and Jayaram (2008) separable approximation. That model describes total-residual correlation, so its use for the within-event blocks is a legacy approximation. A direct joint within-event model bypasses this construction. Loth and Baker (2013) is the first such model distributed with hazardlib. It was calibrated jointly across sites and 5%-damped spectral-acceleration periods from 0.01 to 10 seconds. PGA is supported using SA(0.01) as a correlation proxy, following the operational ShakeMap convention. This changes only the correlation coefficients; PGA medians and standard deviations still come from the GSIM. The model rejects simultaneous PGA and SA(0.01), which would otherwise create duplicate residual fields, and does not support PGV or other IMTs.
The implementation uses the coefficient tables corrected by the 2020 erratum and follows the authors’ 2022 Matlab refinements. These preserve the diagonal ridge during interpolation and use a revised, higher-precision nugget matrix to retain positive definiteness.
Conditional spectra require an explicitly configured total-residual model; omitting it does not request an independent calculation.
ShakeMap limitation#
The legacy ShakeMap XML workflow supplies median ground motions and marginal total standard deviations. For reproducibility, OpenQuake currently retains a workflow that applies configured spatial and total-residual cross-IMT models to those quantities. Applying a total-residual correlation model in this way does not reconstruct the station-conditioned posterior covariance and should not be interpreted as exact ShakeMap-consistent sampling.
Issue #11706 tracks a future workflow based on richer ShakeMap products. That workflow will need to distinguish covariance information exported by ShakeMap from any approximate cross-IMT reconstruction used during posterior sampling.
References#
Baker, J. W., and Cornell, C. A. (2006). Correlation of response spectral values for multicomponent ground motions. Bulletin of the Seismological Society of America, 96(1), 215-227. https://doi.org/10.1785/0120050060
Baker, J. W., and Jayaram, N. (2008). Correlation of spectral acceleration values from NGA ground motion models. Earthquake Spectra, 24(1), 299-317. https://doi.org/10.1193/1.2857544
Bradley, B. A. (2012). Empirical correlations between peak ground velocity and spectrum-based intensity measures. Earthquake Spectra, 28(1), 17-35. https://doi.org/10.1193/1.3675582
Goda, K., and Atkinson, G. M. (2009). Probabilistic characterization of spatially correlated response spectra for earthquakes in Japan. Bulletin of the Seismological Society of America, 99(5), 3003-3020. https://doi.org/10.1785/0120090007
Heresi Venegas, P. C., and Miranda Mijares, E. (2019). Uncertainty in intraevent spatial correlation of elastic pseudo-acceleration spectral ordinates. Bulletin of Earthquake Engineering, 17(3), 1099-1115. https://doi.org/10.1007/s10518-018-0506-6
Jayaram, N., and Baker, J. W. (2009). Correlation model for spatially distributed ground-motion intensities. Earthquake Engineering & Structural Dynamics, 38(15), 1687-1708. https://doi.org/10.1002/eqe.922
Loth, C., and Baker, J. W. (2013). A spatial cross-correlation model of spectral accelerations at multiple periods. Earthquake Engineering & Structural Dynamics, 42(3), 397-417. https://doi.org/10.1002/eqe.2212
Loth, C., and Baker, J. W. (2020). Erratum: A spatial cross-correlation model for ground motion spectral accelerations at multiple periods. Earthquake Engineering & Structural Dynamics, 49(3), 315-316. https://doi.org/10.1002/eqe.3233