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', 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’.

  • cloud_method ({'bootstrap', 'classical'}, optional) –

    When fragility_method='lognormal', selects the uncertainty quantification approach.

    • 'bootstrap': non-parametric bootstrapping (default).

    • 'classical': Bayesian MCMC (Metropolis-Hastings) on the full 5-parameter model chi = [ln a, b, beta, alpha0, alpha1] following Jalayer et al. (2017). The Robust Fragility is computed as the posterior expected value of the fragility model (Eq. 10), and confidence bands are derived from the posterior variance (Eq. 11).

  • 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 – A nested dictionary. Keys present for all fragility methods: 'cloud inputs', 'fragility', 'regression'. Additional keys for fragility_method='lognormal': 'raw_data'; and either 'bootstraps' (cloud_method='bootstrap') or 'mcmc' (cloud_method='classical').

'fragility' always contains: fragility_method, cloud_method, intensities, poes, medians, sigma_record2record, sigma_build2build, sigma_ds, betas_total. When cloud_method='classical', also includes poes_robust_plus, poes_robust_minus, and confidence_k.

Return type:

dict

Notes

The ‘lognormal’ method implements a dual-regression approach: 1. Linear Regression: Performed in log-log space on

non-collapse data (log(EDP) = log(a) + b * log(IM)).

  1. Logistic Regression: Used to predict P(C|IM).

  2. Total Fragility: P(DS|IM) = P(DS|NC,IM)*P(NC|IM) + P(C|IM).

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

  1. 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

  2. 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.

  3. 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.

  4. 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