7.9. Vulnerability Functions

postprocessor.calculate_vulnerability_function(poes, consequence_model, cov_consequence=None, uncertainty=True, method=None, intensities=np.round(np.geomspace(0.05, 10.0, 50), 3))[source]

Compute a vulnerability function (mean loss ratio and associated uncertainty) by convolving fragility functions with a consequence (damage-to-loss) model.

The expected loss ratio is computed as the convolution of mutually exclusive damage-state probabilities with damage-to-loss ratios. Uncertainty in the loss ratio conditional on intensity measure level (Loss | IM) can be computed either explicitly using the law of total variance or via an empirical Silva-type envelope.

Parameters:

  • poes (ndarray, shape (n_IM, n_DS)) – Probabilities of exceedance of each damage state conditional on the intensity measure level (P[DS >= k | IM]). Damage states must be ordered from least to most severe.

  • consequence_model (array-like, length n_DS) – Mean damage-to-loss ratios associated with each damage state. Values must lie in the interval [0, 1].

  • cov_consequence (array-like, length n_DS, optional) – Coefficient of variation of the damage-to-loss ratio for each damage state. Required when method="explicit". Each entry represents the conditional uncertainty of loss given the damage state.

  • uncertainty (bool, optional) – Flag indicating whether to compute uncertainty (coefficient of variation) of the loss ratio conditional on IM. If False, the COV column is still returned and filled with zeros. Default is True.

  • method ({"explicit", "silva"}, optional) –

    Method used to compute uncertainty when uncertainty=True.

    • ”explicit” (default): Computes uncertainty using the law of total variance, accounting for both damage-state mixing and uncertainty within each damage state. Requires cov_consequence.

    • ”silva”: Computes uncertainty using a Silva-type empirical envelope based only on the mean loss ratio.

    If uncertainty=True and method=None, the method defaults to “explicit”.

  • intensities (ndarray, optional) – Intensity measure levels corresponding to the rows of poes. Default is a geometric sequence between 0.05 and 10.0.

Returns:

df – DataFrame with the following columns:

  • IML : Intensity measure level

  • Loss : Expected loss ratio at the given IML

  • COV : Coefficient of variation of the loss ratio at the given IML

The COV column is always returned. If uncertainty=False, it contains zeros.

Return type:

pandas.DataFrame

Raises:

Exception – If the dimensions of poes, consequence_model, or cov_consequence are inconsistent, or if method="explicit" is selected without providing cov_consequence.

Notes

For the explicit uncertainty method, the variance of the loss ratio is computed using the law of total variance:

Var(LR | IM) = sum_k p_k [ sigma_k^2 + (mu_k - mu)^2 ]

where:

  • p_k is the probability of being in damage state k given IM,

  • mu_k is the mean loss ratio for damage state k,

  • sigma_k^2 is the variance of the loss ratio within damage state k,

  • mu is the mean loss ratio at the given IM.

This formulation is consistent with performance-based earthquake engineering (PBEE) frameworks and produces physically meaningful, IM-dependent uncertainty.

Theoretical Background

A vulnerability function expresses the expected loss ratio (repair cost normalised by replacement cost) as a function of the intensity measure (Silva, 2019).

Expected loss ratio

Given fragility curves for \(k\) damage states and associated mean loss ratios \(\mu_i\) (the expected loss given damage state \(i\)), the mean loss ratio conditioned on IM is:

\[E[L \mid \text{IM}] = \sum_{i=1}^{k} \mu_i \cdot P(D = i \mid \text{IM})\]

where \(P(D = i \mid \text{IM})\) is the probability of being in damage state \(i\), derived from the fragility curves:

\[P(D = i \mid \text{IM}) = P(D \geq i \mid \text{IM}) - P(D \geq i+1 \mid \text{IM})\]

with \(P(D \geq k+1 \mid \text{IM}) = 0\) by convention.

Uncertainty and the Beta distribution

The full loss-ratio distribution at each IM level is modelled as a Beta distribution, which is defined on \([0, 1]\) and can represent skewed, bounded loss ratios. The Beta distribution is parametrised by its mean \(\mu\) and coefficient of variation \(\text{CoV}\):

\[\alpha = \mu \left(\frac{\mu(1-\mu)}{\text{CoV}^2} - 1\right), \qquad \beta = (1-\mu)\left(\frac{\mu(1-\mu)}{\text{CoV}^2} - 1\right)\]

The variance of the loss ratio at each IM level is propagated using the law of total variance, combining damage-state uncertainty (from the fragility curves) with consequence uncertainty (from the consequence functions):

\[\text{Var}[L \mid \text{IM}] = \sum_{i=1}^{k} \Bigl[ \sigma_i^2 + \mu_i^2 \Bigr] P(D = i \mid \text{IM}) - E[L \mid \text{IM}]^2\]

where \(\sigma_i\) is the standard deviation of the loss given damage state \(i\). The resulting \(\text{CoV}\) together with the mean \(E[L \mid \text{IM}]\) fully parametrises the Beta vulnerability model (Silva, 2019).