7.6. Modified Cloud Analysis Postprocessing

postprocessor.process_mca_results(imls, edps, damage_thresholds, lower_limit, censored_limit, sigma_build2build=0.3, sigma_ds=0.3, intensities=np.geomspace(0.05, 10, 50), n_bootstrap=200, random_seed=None, fragility_rotation=False, rotation_percentile=0.10, fragility_method='lognormal', dispersion_type='constant', cloud_method='bootstrap', n_mcmc=5000, n_mcmc_burnin=1000, confidence_k=2)[source]

Perform a Modified Cloud Analysis (MCA) to derive seismic fragility functions. This method extends classical cloud analysis by incorporating logistic regression to account for structural collapse cases. It supports lognormal, ordinal, and GLM-based fragility fitting.

When fragility_method='lognormal', two cloud_method options are available:

'bootstrap' (default): uses non-parametric bootstrapping to estimate the mean fragility and parameter uncertainty.
'classical': implements the Bayesian Robust Fragility procedure of Jalayer et al. (2017), sampling the 5-parameter vector chi = [ln a, b, beta, alpha0, alpha1] from its posterior distribution via MCMC (Metropolis-Hastings), and computing the Robust Fragility as the posterior expected value of the fragility model together with confidence bands.

Parameters:

imls (array_like) – Intensity Measure Levels (e.g., Sa, AvgSA) from the cloud.
edps (array_like) – Engineering Demand Parameters (e.g., maximum interstory drift) from the cloud.
damage_thresholds (list of float) – The demand-based thresholds defining the onset of different damage states.
lower_limit (float) – The EDP value below which data is ignored for regression (demand is considered negligible for damage).
censored_limit (float) – The “Collapse” threshold. EDP values above this are treated as collapse instances in the logistic regression.
sigma_build2build (float, optional) – Additional modeling uncertainty (building-to-building variability). Default is 0.3.
sigma_ds (float, optional) – The logarithmic standard deviation representing uncertainty in damage-state thresholds. Default value is 0.30.
intensities (np.array, optional) – The seismic intensity range over which to evaluate the fragility functions. Default is a geometric space from 0.05 to 10.
n_bootstrap (int, optional) – Number of bootstrap samples to draw for statistical stability (used only when cloud_method='bootstrap'). Default is 200.
random_seed (int, optional) – Seed for reproducibility of the bootstrap sampling or MCMC. Default is None.
fragility_rotation (bool, optional) – Whether to rotate the fragility curve around a specific percentile to adjust for target reliability. Default is False.
rotation_percentile (float, optional) – The target percentile for fragility function rotation. Default is 0.10.
fragility_method ({'lognormal', 'ordinal', 'probit', 'logit'}, optional) – The methodology used to fit the fragility functions. Default is 'lognormal'.
dispersion_type ({'constant', 'variable'}, optional) – Dispersion model for the ordinal CLM (fragility_method='ordinal' only). 'constant' (default) enforces a shared slope across all damage states (fully-ordered special case). 'variable' fits independent binary probit models per damage state and applies isotonic regression to enforce the hierarchical ordering of medians.
cloud_method ({'bootstrap', 'classical'}, optional) – When fragility_method='lognormal', selects the uncertainty quantification approach. 'bootstrap' uses non-parametric bootstrapping (default). 'classical' uses Bayesian MCMC (Metropolis-Hastings) on the full 5-parameter model chi = [ln a, b, beta, alpha0, alpha1] following Jalayer et al. (2017), computing the Robust Fragility as the posterior expected value and deriving confidence bands from the posterior variance.
n_mcmc (int, optional) – Total number of MCMC samples (including burn-in) used when cloud_method='classical'. Default is 5000.
n_mcmc_burnin (int, optional) – Number of initial MCMC samples discarded as burn-in. Default is 1000.
confidence_k (float, optional) – Half-width of the robust confidence band in units of the posterior standard deviation. Default is 2.

Returns:

cloud_dict – Nested result dictionary. Always contains keys 'cloud inputs', 'fragility', 'regression'. When fragility_method='lognormal', also contains 'raw_data' plus either 'bootstraps' or 'mcmc' depending on cloud_method.

Return type:

dict

Notes

The 'classical' cloud method follows the 5-parameter fragility model from Jalayer et al. (2017), Eq. 7:

P(DCR>1|Sa,chi) = Phi(ln(eta)/beta) * P(NC|Sa) + P(C|Sa)

where chi = [ln a, b, beta, alpha0, alpha1]. The posterior joint distribution f(chi|D) is sampled via MCMC using the likelihood from Eq. A1.2 (Jalayer et al. 2017). The Robust Fragility (Eq. 10) is the posterior mean of the fragility model over the sampled chi vectors, and the confidence bands (Eq. 11) are derived from the posterior variance.

References

Jalayer, F., Ebrahimian, H., Miano, A., Manfredi, G., and Sezen, H. (2017). Analytical fragility assessment using unscaled ground motion records. Earthquake Engng Struct. Dyn., 46, 2639-2663. https://doi.org/10.1002/eqe.2922
Jalayer, F., Elefante, L., De Risi, R., and Manfredi, G. (2014). Cloud Analysis revisited: Efficient fragility calculation and uncertainty propagation using simple linear regression. Proceedings of the 10th NCEE, Anchorage, AK.
Jalayer, F., De Risi, R., and Manfredi, G. (2015). Bayesian Cloud Analysis: efficient structural fragility assessment using linear regression. Bulletin of Earthquake Engineering, 13(4), 1183-1203.
Miano, A., Jalayer, F., and Prota, A. (2019). Considering structural modelling uncertainties using Bayesian cloud analysis. COMPDYN 2019.

Theoretical Background

The Modified Cloud Analysis (MCA) extends the classical cloud analysis approach (Jalayer et al., 2015) by explicitly accounting for structural collapse through a dual-regression procedure.

Step 1 — Log-log regression (non-collapse records)

For records that do not cause collapse (EDP < censored_limit), the engineering demand parameter is related to the intensity measure through a linear model in log-log space:

\[\ln(\text{EDP}) = \ln(a) + b \cdot \ln(\text{IM}) + \varepsilon, \quad \varepsilon \sim \mathcal{N}(0,\, \beta_{\text{r2r}}^2)\]

where \(a\) and \(b\) are regression coefficients and \(\beta_{\text{r2r}}\) is the record-to-record dispersion. The median EDP given IM is:

\[\widehat{\text{EDP}} \mid \text{IM} = a \cdot \text{IM}^{\,b}\]

Step 2 — Logistic regression (collapse probability)

Records exceeding censored_limit are classified as collapse. The probability of collapse conditioned on IM is estimated via logistic regression:

\[P(C \mid \text{IM}) = \frac{1}{1 + \exp\!\bigl[-(\alpha_0 + \alpha_1\,\ln \text{IM})\bigr]}\]

Step 3 — Lognormal conditional fragility

For each damage state \(i\) with threshold \(\delta_i\), the conditional (non-collapse) fragility is modelled as a lognormal CDF:

\[P(\text{DS} \geq ds_i \mid \text{NC}, \text{IM}) = \Phi\!\left(\frac{\ln(\text{IM}/\theta_i)}{\beta_{\text{total}}}\right)\]

where \(\theta_i\) is the median IM capacity and the total dispersion combines three sources of uncertainty:

\[\beta_{\text{total}} = \sqrt{\beta_{\text{r2r}}^2 + \beta_{\text{b2b}}^2 + \beta_{\text{DS}}^2}\]

with \(\beta_{\text{r2r}}\) the record-to-record variability, \(\beta_{\text{b2b}}\) the building-to-building variability, and \(\beta_{\text{DS}}\) the uncertainty in the damage-state threshold.

Step 4 — Total fragility

The total probability of exceeding each damage state is obtained by combining the non-collapse fragility with the collapse probability via the total probability theorem:

\[P(\text{DS} \geq ds_i \mid \text{IM}) = P(\text{DS} \geq ds_i \mid \text{NC}, \text{IM}) \cdot P(\text{NC} \mid \text{IM}) + P(C \mid \text{IM})\]

where \(P(\text{NC} \mid \text{IM}) = 1 - P(C \mid \text{IM})\).

Bootstrap vs. Classical (Bayesian MCMC) Estimation

The cloud_method parameter controls how the 5-parameter model \(\boldsymbol{\chi} = [\ln a,\, b,\, \beta_{\text{r2r}},\, \alpha_0,\, \alpha_1]\) is estimated.

Bootstrap (cloud_method='bootstrap', default): Ordinary Least Squares regression is repeated n_bootstrap times on resampled datasets. The fragility curves and their uncertainty band are derived from the percentile spread of bootstrap realisations.

Classical / Bayesian MCMC (cloud_method='classical'): The joint posterior of \(\boldsymbol{\chi}\) is sampled with a Metropolis–Hastings MCMC chain (Jalayer et al., 2017). The robust fragility (Eq. 10 in the reference) averages the lognormal CDF over the posterior, and the \(\pm k \cdot \sigma\) confidence band (Eq. 11) bounds the predictive spread. The n_mcmc, n_mcmc_burnin, and confidence_k parameters control the chain length and band width.

Reference: Jalayer F, Ebrahimian H, Miano A, Manfredi G, Sezen H. (2017). “Analytical fragility assessment using unscaled ground motion records.” Earthquake Engineering and Structural Dynamics, 46: 2639–2663. https://doi.org/10.1002/eqe.2922

Example

import numpy as np
from openquake.vmtk.postprocessor import postprocessor

pp = postprocessor()
# imls, edps: 1-D arrays of IM levels and EDP responses from NTHA
cloud_dict = pp.process_mca_results(
    imls=imls,
    edps=edps,
    damage_thresholds=[0.005, 0.015, 0.040],
    lower_limit=0.001,
    censored_limit=0.10,
)
print(cloud_dict['fragility']['medians'])

# Ordinal CLM — constant dispersion (fully-ordered special case)
cloud_ord_const = pp.process_mca_results(
    imls=imls,
    edps=edps,
    damage_thresholds=[0.005, 0.015, 0.040],
    lower_limit=0.001,
    censored_limit=0.10,
    fragility_method='ordinal',
    dispersion_type='constant',   # default
)

# Ordinal CLM — variable dispersion (general hierarchical case)
cloud_ord_var = pp.process_mca_results(
    imls=imls,
    edps=edps,
    damage_thresholds=[0.005, 0.015, 0.040],
    lower_limit=0.001,
    censored_limit=0.10,
    fragility_method='ordinal',
    dispersion_type='variable',   # per-DS dispersions
)