4.6. Relative Score Method — Modified Cloud Analysis

imselection.compute_rsm_mca(cloud_dict_im1, cloud_dict_im2)[source]

Relative Sufficiency Measure between two IMs using Modified Cloud Analysis.

Implements Equation 5 of Ebrahimian & Jalayer (2021).

A positive RSM value means IM₂ is more sufficient than IM₁ for characterising structural demand.

API contract: cloud_dict_im1 and cloud_dict_im2 must have been computed from the same N ground-motion records, in the same order, with the same censored_limit and lower_limit parameters. Under these conditions the EDP-based collapse flag and lower-EDP filter are identical for both IMs, so raw_data['im_nc'] arrays are positionally aligned.

Parameters:

  • cloud_dict_im1 (dict) – MCA result for IM₁ (reference IM).

  • cloud_dict_im2 (dict) – MCA result for IM₂ (candidate IM).

Returns:

  • dict with keys

  • * 'rsm' — scalar RSM in bits (positive → IM₂ better)

  • * 'rsm_per_record' — ndarray of per-record log₂ ratios, shape (N,)

  • * 'n_records' — number of non-collapse records used

  • * 'method' — 'MCA'

  • * 'params_im1' — regression parameters used for IM₁

  • * 'params_im2' — regression parameters used for IM₂

Theoretical Background

The Relative Score Method (RSM) quantifies the information gain from using one intensity measure over another using a relative sufficiency metric expressed in bits (Ebrahimian & Jalayer, 2021).

Kullback–Leibler divergence

The sufficiency of IM₂ relative to IM₁ is measured by the Kullback–Leibler (KL) divergence between the demand distributions conditioned on each IM. For two lognormal distributions \(D|IM_1 \sim \ln\mathcal{N}(\mu_1, \sigma_1^2)\) and \(D|IM_2 \sim \ln\mathcal{N}(\mu_2, \sigma_2^2)\), the KL divergence is:

\[D_{KL}(f_1 \| f_2) = \ln\frac{\sigma_2}{\sigma_1} + \frac{\sigma_1^2 + (\mu_1 - \mu_2)^2}{2\sigma_2^2} - \frac{1}{2}\]

Relative Sufficiency Measure

The RSM of IM₂ relative to IM₁, averaged over the record set, is:

\[\text{RSM}(\text{IM}_2 \mid \text{IM}_1) = \frac{1}{N} \sum_{j=1}^{N} \ln\frac{f_{D|\text{IM}_1}(\text{EDP}_j)} {f_{D|\text{IM}_2}(\text{EDP}_j)}\]

expressed in nats (divided by \(\ln 2\) to convert to bits). A positive RSM means IM₂ is the more sufficient IM.

For MCA, the conditional demand distributions are derived from the cloud regression residuals evaluated at each record’s demand and IM level.

Example

from openquake.vmtk.imselection import imselection

ims = imselection()
# Compare cloud_dict2 (IM2) against cloud_dict1 (IM1)
result = ims.compute_rsm_mca(cloud_dict1, cloud_dict2)
print(f"RSM(IM2 vs IM1) = {result['rsm']:.4f} bits")