Vulnerability Models#

In order to perform probabilistic or scenario risk calculations, it is necessary to define a Vulnerability Function for each building typology present in the Exposure Model. In this section, the schema for the Vulnerability Model is described in detail. A graphical representation of a Vulnerability Model (mean loss ratio for a set of intensity measure levels) is illustrated in the figure below.

../../_images/vulnerability-zero-cov.png — Graphical representation of a vulnerability model#

Note that although the uncertainty for each loss ratio is not represented in the figure below:, it can be considered in the input file, by means of a coefficient of variation per loss ratio and a probabilistic distribution, which can currently be set to lognormal (LN), Beta (BT); or by specifying a discrete probability mass (PM) [1] distribution of the loss ratio at a set of intensity levels. An example of a Vulnerability Function that models the uncertainty in the loss ratio at different intensity levels using a lognormal distribution is illustrated in the next figure.

../../_images/vulnerability-nonzero-cov.png — Graphical representation of a vulnerability function that models the uncertainty in the loss ratio using a lognormal distribution. The mean loss ratios and coefficients of variation are illustrated for a set of intensity levels.#

In general, defining vulnerability functions requires the user to specify the distribution of the loss ratio for a set of intensity levels. The loss ratio distributions can be defined using either a discrete or a continuous format, and the Vulnerability Model file can include a mix of both types of vulnerability functions. It is also possible to define a Vulnerability Function using a set of deterministic loss ratios corresponding to a set of intensity levels (i.e., ignoring the uncertainty in the conditional loss ratios).

An example Vulnerability Model comprising three vulnerability functions is shown in the listing below. This Vulnerability Model contains one function that uses the lognormal distribution to represent the uncertainty in the loss ratio at different intensity levels, one function that uses the Beta distribution, and one function that is defined using a discrete probability mass distribution.:

<?xml version="1.0" encoding="UTF-8"?>
<nrml xmlns="http://openquake.org/xmlns/nrml/0.5">

<vulnerabilityModel id="vulnerability_example"
                    assetCategory="buildings"
                    lossCategory="structural">

  <description>vulnerability model</description>

  <vulnerabilityFunction id="W1_Res_LowCode" dist="LN">
   <imls imt="PGA">0.005 0.15 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0</imls>
   <meanLRs>0.01 0.04 0.10 0.20 0.33 0.50 0.67 0.80 0.90 0.96 0.99</meanLRs>
   <covLRs>0.03 0.12 0.24 0.32 0.38 0.40 0.38 0.32 0.24 0.12 0.03</covLRs>
  </vulnerabilityFunction>


  <vulnerabilityFunction id="S1_Res_HighCode" dist="BT">
   <imls imt="SA(0.3)">0.05 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0</imls>
   <meanLRs>0.01 0.03 0.07 0.15 0.24 0.37 0.50 0.60 0.67 0.72 0.75</meanLRs>
   <covLRs>0.03 0.12 0.24 0.32 0.38 0.40 0.38 0.32 0.24 0.12 0.03</covLRs>
  </vulnerabilityFunction>


  <vulnerabilityFunction id="ATC13_URM_Res" dist="PM">
   <imls imt="MMI">6 7 8 9 10 11 12</imls>
   <probabilities lr="0.000">0.95 0.49 0.30 0.14 0.03 0.01 0.00</probabilities>
   <probabilities lr="0.005">0.03 0.38 0.40 0.30 0.10 0.03 0.01</probabilities>
   <probabilities lr="0.050">0.02 0.08 0.16 0.24 0.30 0.10 0.01</probabilities>
   <probabilities lr="0.200">0.00 0.02 0.08 0.16 0.26 0.30 0.03</probabilities>
   <probabilities lr="0.450">0.00 0.02 0.03 0.10 0.18 0.30 0.18</probabilities>
   <probabilities lr="0.800">0.00 0.01 0.02 0.04 0.10 0.18 0.39</probabilities>
   <probabilities lr="1.000">0.00 0.01 0.01 0.02 0.03 0.08 0.38</probabilities>
  </vulnerabilityFunction>

</vulnerabilityModel>

</nrml>

The initial portion of the schema contains general information that describes some general aspects of the Vulnerability Model. The information in this metadata section is common to all of the functions in the Vulnerability Model and needs to be included at the beginning of every Vulnerability Model file. The parameters are illustrated in the snippet shown and described below:

<vulnerabilityModel id="vulnerability_example"
                    assetCategory="buildings"
                    lossCategory="structural">

  <description>vulnerability model</description>

id: a unique string (ASCII) used to identify the Vulnerability Model. This string can contain letters (a–z; A–Z), numbers (0–9), dashes (-), and underscores (_), with a maximum of 100 characters.
assetCategory: an optional string (ASCII) used to specify the type of assets for which vulnerabilityfunctions will be defined in this file (e.g: buildings, lifelines).
lossCategory: mandatory; valid strings for this attribute are “structural”, “nonstructural”, “contents”, “business_interruption”, and “occupants”.
description: mandatory; a brief string with further information about the Vulnerability Model, for example, which building typologies are covered or the source of the functions in the Vulnerability Model.

The following snippet from the above Vulnerability Model example file defines a Vulnerability Function modelling the uncertainty in the conditional loss ratios using a (continuous) lognormal distribution:

<vulnerabilityFunction id="W1_Res_LowCode" dist="LN">
 <imls imt="PGA">0.005 0.15 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 2.0</imls>
 <meanLRs>0.01 0.04 0.10 0.20 0.33 0.50 0.67 0.80 0.90 0.96 0.99</meanLRs>
 <covLRs>0.03 0.12 0.24 0.32 0.38 0.40 0.38 0.32 0.24 0.12 0.03</covLRs>
</vulnerabilityFunction>

The following attributes are needed to define a Vulnerability Function which uses a continuous distribution to model the uncertainty in the conditional loss ratios:

id: a unique string (ASCII) used to identify the taxonomy for which the function is being defined. This string is used to relate the Vulnerability Function with the relevant asset in the Exposure Model. This string can contain letters (a–z; A–Z), numbers (0–9), dashes (-), and underscores (_), with a maximum of 100 characters.
dist: mandatory; for vulnerabilityfunctions which use a continuous distribution to model the uncertainty in the conditional loss ratios, this attribute should be set to either “LN” if using the lognormal distribution, or to “BT” if using the Beta distribution.
imls: mandatory; this attribute specifies the list of intensity levels for which the parameters of the conditional loss ratio distributions will be defined. In addition, it is also necessary to define the intensity measure type (imt).
meanLR``s: mandatory; this field is used to define the mean loss ratios for this *Vulnerability Function* for each of the intensity levels defined by the attribute ``imls. The number of mean loss ratios defined by the meanLRs attribute must be equal to the number of intensity levels defined by the attribute imls.
covLRs: mandatory; this field is used to define the coefficient of variation for the conditional distribution of the loss ratios for this Vulnerability Function for each of the intensity levels defined by the attribute imls. The number of coefficients of variation of loss ratios defined by the covLRs attribute must be equal to the number of intensity levels defined by the attribute imls. The uncertainty in the conditional loss ratios can be ignored by setting all of the covLRs for a given Vulnerability Function to zero.

The next snippet from the Vulnerability Model example file of the Vulnerability Function listing above defines a Vulnerability Function which models the uncertainty in the conditional loss ratios using a (discrete) probability mass distribution:

<vulnerabilityFunction id="ATC13_URM_Res" dist="PM">
 <imls imt="MMI">6 7 8 9 10 11 12</imls>
 <probabilities lr="0.000">0.95 0.49 0.30 0.14 0.03 0.01 0.00</probabilities>
 <probabilities lr="0.005">0.03 0.38 0.40 0.30 0.10 0.03 0.01</probabilities>
 <probabilities lr="0.050">0.02 0.08 0.16 0.24 0.30 0.10 0.01</probabilities>
 <probabilities lr="0.200">0.00 0.02 0.08 0.16 0.26 0.30 0.03</probabilities>
 <probabilities lr="0.450">0.00 0.02 0.03 0.10 0.18 0.30 0.18</probabilities>
 <probabilities lr="0.800">0.00 0.01 0.02 0.04 0.10 0.18 0.39</probabilities>
 <probabilities lr="1.000">0.00 0.01 0.01 0.02 0.03 0.08 0.38</probabilities>
</vulnerabilityFunction>

The following attributes are needed to define a Vulnerability Function which uses a discrete probability mass distribution to model the uncertainty in the conditional loss ratios:

id: a unique string (ASCII) used to identify the taxonomy for which the function is being defined. This string is used to relate the Vulnerability Function with the relevant asset in the Exposure Model. This string can contain letters (a–z; A–Z), numbers (0–9), dashes (-), and underscores (_), with a maximum of 100 characters.
dist: mandatory; for vulnerability functions which use a discrete probability mass distribution to model the uncertainty in the conditional loss ratios, this attribute should be set to “PM”.
imls: mandatory; this attribute specifies the list of intensity levels for which the parameters of the conditional loss ratio distributions will be defined. In addition, it is also necessary to define the intensity measure type (imt).
probabilities: mandatory; this field is used to define the probability of observing a particular loss ratio (specified for each row of probabilities using the attribute lr), conditional on the set of intensity levels specified using the attribute imls. for this Vulnerability Function. Thus, the number of probabilities defined by each probabilities attribute must be equal to the number of intensity levels defined by the attribute imls. On the other hand, there is no limit to the number of loss ratios for which probabilities can be defined. In the example shown here, notice that the set of probabilities conditional on any particular intensity level, say, \(MMI = 8\) , sum up to one.

Note that the schema for representing vulnerability models has changed between Natural hazards’ Risk Markup Language v0.4 (used prior to OpenQuake engine v1.7) and Natural hazards’ Risk Markup Language v0.5 (introduced in OpenQuake engine v1.7).

A deprecation warning is printed every time you attempt to use a Vulnerability Model in the old Natural hazards’ Risk Markup Language v0.4 format in an OpenQuake engine v1.7 (or later) risk calculation. To get rid of the warning you must upgrade the old vulnerability models files to Natural hazards’ Risk Markup Language v0.5. You can use the command upgrade_nrml with oq to do this as follows:

user@ubuntu:~$ oq upgrade_nrml <directory-name>

The above command will upgrade all of your old Vulnerability Model files to Natural hazards’ Risk Markup Language v0.5. The original files will be kept, but with a .bak extension appended. Notice that you will need to set the lossCategory attribute to its correct value manually. This is easy to do, since if you try to run a computation you will get a clear error message telling the expected value for the lossCategory for each file.

Several methodologies to derive vulnerability functions are currently being evaluated by GEM Foundation and have been included as part of the Risk Modeller’s Toolkit, the code for which can be found on a public repository at GitHub at: gemsciencetools/rmtk.

A web-based tool to build an Vulnerability Model in the Natural hazards’ Risk Markup Language schema are also under development, and can be found at the OpenQuake platform at the following address: https://platform.openquake.org/ipt/.