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

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.

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