Vulnerability Functions
=======================

.. automethod:: openquake.vmtk.postprocessor.postprocessor.calculate_vulnerability_function

.. admonition:: 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 :math:`k` damage states and associated mean loss ratios
   :math:`\mu_i` (the expected loss given damage state :math:`i`), the mean loss ratio
   conditioned on IM is:

   .. math::

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

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

   .. math::

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

   with :math:`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 :math:`[0, 1]` and can represent skewed, bounded loss ratios.
   The Beta distribution is parametrised by its mean :math:`\mu` and coefficient of
   variation :math:`\text{CoV}`:

   .. math::

      \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):

   .. math::

      \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 :math:`\sigma_i` is the standard deviation of the loss given damage state
   :math:`i`. The resulting :math:`\text{CoV}` together with the mean
   :math:`E[L \mid \text{IM}]` fully parametrises the Beta vulnerability model
   (Silva, 2019).