Postprocessing Module

The postprocessor module provides a class postprocessor that allows users to compute fragility functions, perform cloud and multiple stripe analyses, and calculate vulnerability functions and average annual losses. The module supports various fragility fitting methods, including lognormal, probit, logit, and ordinal models. It also includes functionality to handle uncertainty and variability in the analysis.

Classes

class postprocessor

A class for post-processing results of nonlinear time-history analysis, including fragility and vulnerability analysis.

Methods:

calculate_lognormal_fragility(theta, sigma_record2record, sigma_build2build=0.30, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3))

Computes the probability of exceeding a damage state using a lognormal cumulative distribution function (CDF).

Parameters:

  • theta (float) – The median seismic intensity corresponding to a damage threshold.

  • sigma_record2record (float) – The logarithmic standard deviation representing record-to-record variability.

  • sigma_build2build (float, optional) – The logarithmic standard deviation representing building-to-building variability. Default is 0.30.

  • intensities (array-like, optional) – The intensity measure levels (IMLs) at which the exceedance probabilities are computed. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

Returns:

An array of exceedance probabilities corresponding to each intensity measure level.

Return type:

numpy.ndarray

calculate_rotated_fragility(theta, percentile, sigma_record2record, sigma_build2build=0.30, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3))

Calculates a rotated fragility function based on a lognormal CDF, adjusting the median intensity to align with a specified target percentile.

Parameters:

  • theta (float) – The median seismic intensity corresponding to the damage threshold.

  • percentile (float) – The target percentile for fragility function rotation (e.g., 0.2 for the 20th percentile).

  • sigma_record2record (float) – The uncertainty associated with record-to-record variability.

  • sigma_build2build (float, optional) – The uncertainty associated with modeling variability. Default is 0.30.

  • intensities (array-like, optional) – The intensity measure levels (IMLs) at which the exceedance probabilities are computed. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

Returns:

The new median intensity, total standard deviation, and probabilities of exceedance.

Return type:

tuple(float, float, array-like)

calculate_glm_fragility(imls, edps, damage_thresholds, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3), fragility_method='logit')

Computes non-parametric fragility functions using Generalized Linear Models (GLM) with either a Logit or Probit link function.

Parameters:

  • imls (array-like) – Intensity Measure Levels (IMLs) corresponding to each observation.

  • edps (array-like) – Engineering Demand Parameters (EDPs) representing structural response values.

  • damage_thresholds (array-like) – List of thresholds defining different damage states.

  • intensities (array-like, optional) – Intensity measure values at which probabilities of exceedance (PoEs) are evaluated. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

  • fragility_method (str, optional) – Specifies the GLM model to be used for fragility function fitting. Options: ‘logit’ (default) or ‘probit’.

Returns:

A 2D array where each column represents the probability of exceeding a specific damage state at each intensity level.

Return type:

numpy.ndarray

calculate_ordinal_fragility(imls, edps, damage_thresholds, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3))

Fits an ordinal (cumulative) probit model to estimate fragility curves for different damage states.

Parameters:

  • imls (array-like) – Intensity measure levels corresponding to the observed EDPs.

  • edps (array-like) – Engineering Demand Parameters (EDPs) representing structural responses.

  • damage_thresholds (array-like) – Damage state thresholds for classifying exceedance levels.

  • intensities (array-like, optional) – Intensity measure levels for which fragility curves are evaluated. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

Returns:

A 2D array of exceedance probabilities (CDF values) for each intensity level.

Return type:

numpy.ndarray

do_cloud_analysis(imls, edps, damage_thresholds, lower_limit, censored_limit, sigma_build2build=0.3, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3), fragility_rotation=False, rotation_percentile=0.1, fragility_method='lognormal')

Perform a censored cloud analysis to assess fragility functions for a set of engineering demand parameters (EDPs) and intensity measure levels (IMLs).

Parameters:

  • imls (list or array) – A list or array of intensity measure levels (IMLs).

  • edps (list or array) – A list or array of engineering demand parameters (EDPs).

  • damage_thresholds (list) – A list of damage thresholds associated with different levels of damage.

  • lower_limit (float) – The minimum value of EDP below which cloud records are excluded.

  • censored_limit (float) – The maximum value of EDP above which cloud records are excluded.

  • sigma_build2build (float, optional) – The building-to-building variability or modeling uncertainty. Default is 0.3.

  • intensities (array, optional) – An array of intensity measure levels used to sample and evaluate the fragility functions. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

  • fragility_rotation (bool, optional) – A boolean flag to indicate whether or not the fragility function should be rotated about a target percentile. Default is False.

  • rotation_percentile (float, optional) – The target percentile (between 0 and 1) around which the fragility function will be rotated. Default is 0.1.

  • fragility_method (str, optional) – The method used to fit the fragility function. Options: ‘probit’, ‘logit’, ‘ordinal’, or ‘lognormal’ (default).

Returns:

A dictionary containing the outputs of the cloud analysis, including fragility functions and regression coefficients.

Return type:

dict

do_multiple_stripe_analysis(imls, edps, damage_thresholds, sigma_build2build=0.3, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3), fragility_rotation=False, rotation_percentile=0.10)

Perform maximum likelihood estimation (MLE) for fragility curve fitting following a multiple stripe analysis.

Parameters:

  • imls (list or array) – A list or array of intensity measure levels (IMLs).

  • edps (list or array) – A list or array of engineering demand parameters (EDPs).

  • damage_thresholds (list) – A list of EDP-based damage thresholds.

  • sigma_build2build (float, optional) – The building-to-building variability or modeling uncertainty. Default is 0.3.

  • intensities (array, optional) – An array of intensity measure levels over which the fragility function will be sampled. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

  • fragility_rotation (bool, optional) – A boolean flag to indicate whether or not to rotate the fragility curve about a given percentile. Default is False.

  • rotation_percentile (float, optional) – The target percentile (between 0 and 1) around which the fragility function will be rotated. Default is 0.10.

Returns:

A dictionary containing the results of the multiple stripe analysis, including medians, dispersions, and probabilities of exceedance.

Return type:

dict

calculate_sigma_loss(loss)

Calculate the uncertainty in the loss estimates based on the method proposed in Silva (2019).

Parameters:

loss (list or array) – A list or array of expected loss ratios.

Returns:

The uncertainty (sigma) associated with the mean loss ratio, and the parameters of a beta distribution (a and b).

Return type:

tuple(list or array, list or array, list or array)

get_vulnerability_function(poes, consequence_model, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3), uncertainty=True)

Calculate the vulnerability function given the probabilities of exceedance and a consequence model.

Parameters:

  • poes (array) – An array of probabilities of exceedance associated with the damage states considered.

  • consequence_model (list) – A list of damage-to-loss ratios corresponding to each damage state.

  • intensities (array, optional) – An array of intensity measure levels. Default is a geometric sequence from 0.05 to 10.0 with 50 points.

  • uncertainty (bool, optional) – A flag to indicate whether to calculate the coefficient of variation associated with Loss|IM. Default is True.

Returns:

A DataFrame containing the intensity measure levels (IML), expected loss ratios, and optionally, the coefficient of variation (COV) for each IML.

Return type:

pandas.DataFrame

calculate_average_annual_damage_probability(fragility_array, hazard_array, return_period=1, max_return_period=5000)

Calculate the Average Annual Damage State Probability (AADP) based on fragility and hazard curves.

Parameters:

  • fragility_array (2D array) – A 2D array where the first column contains intensity measure levels, and the second column contains the corresponding probabilities of exceedance.

  • hazard_array (2D array) – A 2D array where the first column contains intensity measure levels, and the second column contains the annual rates of exceedance.

  • return_period (float, optional) – The return period used to scale the hazard rate. Default is 1.

  • max_return_period (float, optional) – The maximum return period threshold used to filter out very low hazard rates. Default is 5000.

Returns:

The average annual damage state probability.

Return type:

float

calculate_average_annual_loss(vulnerability_array, hazard_array, return_period=1, max_return_period=5000)

Calculate the Average Annual Loss (AAL) based on vulnerability and hazard curves.

Parameters:

  • vulnerability_array (2D array) – A 2D array where the first column contains intensity measure levels, and the second column contains the corresponding loss ratios.

  • hazard_array (2D array) – A 2D array where the first column contains intensity measure levels, and the second column contains the annual rates of exceedance.

  • return_period (float, optional) – The return period used to scale the hazard rate. Default is 1.

  • max_return_period (float, optional) – The maximum return period threshold used to filter out very low hazard rates. Default is 5000.

Returns:

The average annual loss.

Return type:

float

References

  1. Porter, K. (2017). “When Addressing Epistemic Uncertainty in a Lognormal Fragility Function, How Should One Adjust the Median?”, Proceedings of the 16th World Conference on Earthquake Engineering (16WCEE), Santiago, Chile.

  2. Charvet, I., Ioannou, I., Rossetto, T., Suppasri, A., and Imamura, F. (2014). “Empirical fragility assessment of buildings affected by the 2011 Great East Japan tsunami using improved statistical models”, Natural Hazards, 73, 951–973, 2014.

  3. Lahcene, E., Ioannou, I., Suppasri, A., Pakoksung, K., Paulik, R., Syamsidik, S., Bouchette, F., and Imamura, F. (2021). “Characteristics of building fragility curves for seismic and non-seismic tsunamis: case studies of the 2018 Sunda Strait, 2018 Sulawesi–Palu, and 2004 Indian Ocean tsunamis”, Natural Hazards Earth System Sciences, 21, 2313–2344, https://doi.org/10.5194/nhess-21-2313-2021.

  4. Lallemant, D., Kiremidjian, A., and Burton, H. (2015). “Statistical procedures for developing earthquake damage fragility curves”, Earthquake Engineering and Structural Dynamics, 44, 1373–1389. doi: 10.1002/eqe.2522.

  5. Jalayer, F., Ebrahamian, H., Trevlopoulos, K., and Bradley, B. (2023). “Empirical tsunami fragility modelling for hierarchical damage levels”, Natural Hazards and Earth System Sciences, 23(2), 909–931. https://doi.org/10.5194/nhess-23-909-2023

  6. Baker, J.W. (2015). “Efficient Analytical Fragility Function Fitting Using Dynamic Structural Analysis”, Earthquake Spectra. 2015;31(1):579-599. doi:10.1193/021113EQS025M

  7. Singhal A., Kiremidjian AS. Method for probabilistic evaluation of seismic structural damage. Journal of Structural Engineering 1996; 122: 1459–1467. DOI:10.1061/(ASCE)0733-9445(1996)122:12(1459)

  8. Bird J.F., Bommer J.J., Bray J.D., Sancio R., Spence R.J.S., (2004). “Comparing loss estimation with observed damage in a zone of ground failure: a study of the 1999 Kocaeli Earthquake in Turkey”, Bulletin of Earthquake Engineering 2004; 2: 329–360. DOI: 10.1007/s10518-004-3804-0

  9. Nguyen, M., and Lallemant, D. (2022). “Order Matters: The Benefits of Ordinal Fragility Curves for Damage and Loss Estimation”. Risk Analysis, 42: 1136-1148. https://doi.org/10.1111/risa.13815

  10. Silva, V. (2019). “Uncertainty and correlation in seismic vulnerability functions of building classes.” Earthquake Spectra. DOI: 10.1193/013018eqs031m.