<commit_before>\emph{All} risk calculators in the \glsdesc{acr:oqe} require an
\gls{exposuremodel} that needs to be provided in the \gls{acr:nrml} schema,
the use of which is illustrated through several examples in this section. The
information included in an \gls{exposuremodel} comprises a metadata section
listing general information about the exposure, followed by a cost conversions
section that describes how the different areas, costs, and occupancies for the
assets will be specified, followed by data regarding each individual
\gls{asset} in the portfolio.

A simple \gls{exposuremodel} comprising a single \gls{asset} is shown in
Listing~\ref{lst:input_exposure_minimal}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}
  \caption{Example exposure model comprising a single asset (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_minimal.xml}{Download example})}
  \label{lst:input_exposure_minimal}
\end{listing}

Let us take a look at each of the sections in the above example file in turn.
The first part of the file contains the metadata section:

\inputminted[firstline=5,firstnumber=5,lastline=8,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}

The information in the metadata section is common to all of the \glspl{asset}
in the portfolio and needs to be incorporated at the beginning of every
\gls{exposuremodel} file. There are a number of parameters that compose the
metadata section, which is intended to provide general information regarding
the \glspl{asset} within the \gls{exposuremodel}. These parameters are
described below:

\begin{itemize}

  \item \Verb+id+: mandatory; a unique string used to identify the
    \gls{exposuremodel}. This string can contain letters~(a--z; A--Z), 
    numbers~(0--9), dashes~(--), and underscores~(\_), with a maximum of 
    100~characters.

  \item \Verb+category+: an optional string used to define the type of
    \glspl{asset} being stored (e.g: buildings, lifelines).

  \item \Verb+taxonomySource+: an optional attribute used to define the
    \gls{taxonomy} being used to classify the \glspl{asset}.

  \item \Verb+description+: mandatory; a brief string (ASCII) with further
    information about the \gls{exposuremodel}.

\end{itemize}


Next, let us look at the part of the file describing the area and cost
conversions:

\inputminted[firstline=10,firstnumber=10,lastline=15,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}

Notice that the \Verb+costType+ element defines a \Verb+name+, a \Verb+type+, 
and a \Verb+unit+ attribute.

The \gls{acr:nrml} schema for the \gls{exposuremodel} allows the definition of
a structural cost, a nonstructural components cost, a contents cost, and a
business interruption or downtime cost for each \gls{asset} in the portfolio.
Thus, the valid values for the \Verb+name+ attribute of the \Verb+costType+
element are the following:

\begin{itemize}

  \item \Verb+structural+: used to specify the structural replacement cost
    of assets

  \item \Verb+nonstructural+: used to specify the replacement cost for the
    nonstructural components of assets

  \item \Verb+contents+: used to specify the contents replacement cost

  \item \Verb+business_interruption+: used to specify the cost that will be 
    incurred per unit time that a damaged asset remains closed following an 
    earthquake

\end{itemize}

The \gls{exposuremodel} shown in the example above defines only the structural
values for the \glspl{asset}. However, multiple cost types can be defined for
each \gls{asset} in the same \gls{exposuremodel}.

The \Verb+unit+ attribute of the \Verb+costType+ element is used for
specifying the currency unit for the corresponding cost type. Note that the
\glsdesc{acr:oqe} itself is agnostic to the currency units; the \Verb+unit+ is
thus a descriptive attribute which is used by the \glsdesc{acr:oqe} to annotate the
results of a risk assessment. This attribute can be set to any valid Unicode
string.

The \Verb+type+ attribute of the \Verb+costType+ element specifies whether the
costs will be provided as an aggregated value for an asset, or per building or
unit comprising an \gls{asset}, or per unit area of an \gls{asset}. The valid
values for the \Verb+type+ attribute of the \Verb+costType+ element are the
following:

\begin{itemize}

  \item \Verb+aggregated+: indicates that the replacement costs will be 
    provided as an aggregated value for each \gls{asset}

  \item \Verb+per_asset+: indicates that the replacement costs will be 
    provided per structural unit comprising each \gls{asset}

  \item \Verb+per_area+: indicates that the replacement costs will be 
    provided per unit area for each \gls{asset}

\end{itemize}

If the costs are to be specified \Verb+per_area+ for any of the
\Verb+costTypes+, the \Verb+area+ element will also need to be defined in the
conversions section. The \Verb+area+ element defines a \Verb+type+, and a
\Verb+unit+ attribute.

The \Verb+unit+ attribute of the \Verb+area+ element is used for specifying
the units for the area of an \gls{asset}. The \glsdesc{acr:oqe} itself is
agnostic to the area units; the \Verb+unit+ is thus a descriptive attribute
which is used by the \glsdesc{acr:oqe} to annotate the results of a risk
assessment. This attribute can be set to any valid ASCII string.

The \Verb+type+ attribute of the \Verb+area+ element specifies whether the
area will be provided as an aggregated value for an \gls{asset}, or per
building or unit comprising an \gls{asset}. The valid values for the
\Verb+type+ attribute of the \Verb+area+ element are the following:

\begin{itemize}

  \item \Verb+aggregated+: indicates that the area will be provided as an 
    aggregated value for each \gls{asset}

  \item \Verb+per_asset+: indicates that the area will be provided per 
    building or unit comprising each \gls{asset}

\end{itemize}


The way the information about the characteristics of the \glspl{asset} in an
\gls{exposuremodel} are stored can vary strongly depending on how and why the
data was compiled. As an example, if national census information is used to
estimated the distribution of \glspl{asset} in a given region, it is likely
that the number of buildings within a given geographical area will be used to
define the dataset, and will be used for estimating the number of collapsed
buildings for a scenario earthquake. On the other hand, if simplified
methodologies based on proxy data such as population distribution are used to
develop the \gls{exposuremodel}, then it is likely that the built up area or
economic cost of each building typology will be directly derived, and will be
used for the estimation of economic losses.


Finally, let us look at the part of the file describing the set of
\glspl{asset} in the portfolio to be used in seismic damage or risk
calculations:

\inputminted[firstline=17,firstnumber=17,lastline=27,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}

Each \gls{asset} definition involves specifiying a set of mandatory and
optional attributes concerning the \gls{asset}. The following set of
attributes can be assigned to each \gls{asset} based on the current schema for
the \gls{exposuremodel}:

\begin{itemize}

  \item \Verb+id+: mandatory; a unique string used to identify the 
    given \gls{asset}, which is used by the \glsdesc{acr:oqe} to relate each
    \gls{asset} with its associated results. This string can contain 
    letters~(a--z; A--Z), numbers~(0--9), dashes~(-), and underscores~(\_), 
    with a maximum of 100~characters.

  \item \Verb+taxonomy+: mandatory; this string specifies the building typology
    of the given \gls{asset}. The taxonomy strings can be user-defined, or
    based on an existing classification scheme such as the GEM Taxonomy, PAGER,
    or EMS-98.

  \item \Verb+number+: the number of individual structural units comprising a
    given \gls{asset}. This attribute is mandatory for damage calculations. For
    risk calculations, this attribute must be defined if either the area or any
    of the costs are provided per structural unit comprising each \gls{asset}.

  \item \Verb+area+: area of the \gls{asset}, at a given location. As 
    mentioned earlier, the area is a mandatory attribute only if any one of the 
    costs for the \gls{asset} is specified per unit area.

  \item \Verb+location+: mandatory; specifies the longitude 
    (between -180$^{\circ}$ to 180$^{\circ}$) and latitude 
    (between -90$^{\circ}$ to 90 $^{\circ}$) of the given \gls{asset}, both
    specified in decimal degrees\footnote{Within the \glsdesc{acr:oqe}, 
    longitude and latitude coordinates are internally rounded to a precision
    of 5 digits after the decimal point.}.

  \item \Verb+costs+: specifies a set of costs for the given \gls{asset}. 
    The replacement value for different cost types must be provided on 
    separate lines within the \Verb+costs+ element. As shown in the example 
    above, each cost entry must define the \Verb+type+ and the \Verb+value+. 
    Currently supported valid options for the cost \Verb+type+ are: 
    \Verb+structural+,  \Verb+nonstructural+, \Verb+contents+, and 
    \Verb+business_interruption+.

  \item \Verb+occupancies+: mandatory only for probabilistic or scenario 
    risk calculations that specify an \Verb+occupants_vulnerability_file+.
    Each entry within this element specifies the number of
    occupants for the asset for a particular period of the day. As shown in 
    the example above, each occupancy entry must define the \Verb+period+ and 
    the \Verb+occupants+. Currently supported valid options for the 
    \Verb+period+ are: \Verb+day+, \Verb+transit+, and \Verb+night+. Currently,
    the number of \Verb+occupants+ for an asset can only be provided as an 
    aggregated value for the asset.

\end{itemize}

For the purposes of performing a retrofitting benefit/cost analysis, it is
also necessary to define the retrofitting cost (\Verb+retrofitted+). The
combination between the possible options in which these three attributes can
be defined leads to four ways of storing the information about the
\glspl{asset}. For each of these cases a brief explanation and example is
provided in this section.


\paragraph{Example 1}

This example illustrates an \gls{exposuremodel} in which the aggregated cost
(structural, nonstructural, contents and business interruption) of the
\glspl{asset} of each taxonomy for a set of locations is directly provided.
Thus, in order to indicate how the various costs will be defined, the
following information needs to be stored in the \gls{exposuremodel} file, as
shown in Listing~\ref{lst:input_exposure_cagg_metadata}.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=18,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cagg.xml}
  \caption{Example exposure model using aggregate costs: metadata definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_cagg.xml}{Download example})}
  \label{lst:input_exposure_cagg_metadata}
\end{listing}

In this case, the cost \Verb+type+ of each component as been defined as
\Verb+aggregated+. Once the way in which each cost is going to be defined has
been established, the values for each asset can be stored according to the
format shown in Listing~\ref{lst:input_exposure_cagg_assets}.

\begin{listing}[htbp]
  \inputminted[firstline=19,firstnumber=19,lastline=29,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cagg.xml}
  \caption{Example exposure model using aggregate costs: assets definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_cagg.xml}{Download example})}
  \label{lst:input_exposure_cagg_assets}
\end{listing}

Each \gls{asset} is uniquely identified by its \Verb+id+. Then, a pair of
coordinates (latitude and longitude) for a \Verb+location+ where the asset is
assumed to exist is defined. Each \gls{asset} must be classified according to
a \Verb+taxonomy+, so that the \glsdesc{acr:oqe} is capable of employing the
appropriate \gls{vulnerabilityfunction} or \gls{fragilityfunction} in the risk
calculations. Finally, the cost values of each \Verb+type+ are stored within
the \Verb+costs+ attribute. In this example, the aggregated value for all
structural units (within a given \gls{asset}) at each location is provided
directly, so there is no need to define other attributes such as \Verb+number+
or \Verb+area+. This mode of representing an \gls{exposuremodel} is probably
the simplest one.


\paragraph{Example 2}

In the snippet shown in Listing~\ref{lst:input_exposure_cunit_metadata}, an
\gls{exposuremodel} containing the number of structural units and the
associated costs per unit of each \gls{asset} is presented.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=18,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cunit.xml}
  \caption{Example exposure model using costs per unit: metadata definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_cunit.xml}{Download example})}
  \label{lst:input_exposure_cunit_metadata}
\end{listing}

For this case, the cost \Verb+type+ has been set to \Verb+per_asset+. Then,
the information from each \gls{asset} can be stored following the format shown
in Listing~\ref{lst:input_exposure_cunit_assets}.

\begin{listing}[htbp]
  \inputminted[firstline=19,firstnumber=19,lastline=29,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cunit.xml}
  \caption{Example exposure model using costs per unit: assets definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_cunit.xml}{Download example})}
  \label{lst:input_exposure_cunit_assets}
\end{listing}

In this example, the various costs for each \gls{asset} is not provided
directly, as in the previous example. In order to carry out the risk
calculations in which the economic cost of each \gls{asset} is provided, the
\glsdesc{acr:oqe} multiplies, for each \gls{asset}, the number of units
(buildings) by the ``per asset'' replacement cost. Note that in this case,
there is no need to specify the attribute \Verb+area+.


\paragraph{Example 3}

The example shown in Listing~\ref{lst:input_exposure_carea_aagg_metadata}
comprises an \gls{exposuremodel} containing the built up area of each
\gls{asset}, and the associated costs are provided per unit area.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=20,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aagg.xml}
  \caption{Example exposure model using costs per unit area and aggregated areas: metadata definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_carea_aagg.xml}{Download example})}
  \label{lst:input_exposure_carea_aagg_metadata}
\end{listing}

In order to compile an \gls{exposuremodel} with this structure, the cost
\Verb+type+ should be set to \Verb+per_area+. In addition, it is also
necessary to specify if the \Verb+area+ that is being store represents the
aggregated area of number of units within an asset, or the average area of a
single unit. In this particular case, the \Verb+area+ that is being stored is
the aggregated built up area per asset, and thus this attribute was set to
\Verb+aggregated+. Listing~\ref{lst:input_exposure_carea_aagg_assets}
illustrates the definition of the \glspl{asset} for this example.

\begin{listing}[htbp]
  \inputminted[firstline=21,firstnumber=21,lastline=31,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aagg.xml}
  \caption{Example exposure model using costs per unit area and aggregated areas: assets definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_carea_aagg.xml}{Download example})}
  \label{lst:input_exposure_carea_aagg_assets}
\end{listing}

Once again, the \glsdesc{acr:oqe} needs to carry out some calculations in
order to compute the different costs per \gls{asset}. In this case, this value
is computed by multiplying the aggregated built up \Verb+area+ of each
\gls{asset} by the associated cost per unit area. Notice that in this case,
there is no need to specify the attribute \Verb+number+.


\paragraph{Example 4}

This example demonstrates an \gls{exposuremodel} that defines the number of
structural units for each \gls{asset}, the average built up area per
structural unit and the associated costs per unit area.
Listing~\ref{lst:input_exposure_carea_aunit_metadata} shows the metadata
definition for an \gls{exposuremodel} built in this manner.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=20,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aunit.xml}
  \caption{Example exposure model using costs per unit area and areas per unit: metadata definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_carea_aunit.xml}{Download example})}
  \label{lst:input_exposure_carea_aunit_metadata}
\end{listing}

Similarly to what was described in the previous example, the various costs
\Verb+type+ also need to be established as \Verb+per_area+, but the
\Verb+type+ of area is now defined as \Verb+per_asset+.
Listing~\ref{lst:input_exposure_carea_aunit_assets} illustrates the definition
of the assets for this example.

\begin{listing}[htbp]
  \inputminted[firstline=21,firstnumber=21,lastline=31,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aunit.xml}
  \caption{Example exposure model using costs per unit area and areas per unit: assets definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_carea_aunit.xml}{Download example})}
  \label{lst:input_exposure_carea_aunit_assets}
\end{listing}

In this example, the \glsdesc{acr:oqe} will make use of all the parameters to
estimate the various costs of each \gls{asset}, by multiplying the number of
structural units by its average built up area, and then by the respective cost
per unit area.


\paragraph{Example 5}

In this example, additional information will be included, which is required
for other risk analysis besides loss estimation, such as the calculation of
insured losses or benefit/cost analysis. For the calculation of insured
losses, it is necessary to establish how the insurance \glspl{limit} and
\glspl{deductible} are going to be defined.
Listing~\ref{lst:input_exposure_ins_rel_metadata} illustrates the metadata
section of an \gls{exposuremodel} where the insurance \glspl{limit} and
\glspl{deductible} for structural components will be defined relative to the
structural replacement cost.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=21,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_ins_rel.xml}
  \caption{Example exposure model using relative insurance limits and deductibles: metadata definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_ins_rel.xml}{Download example})}
  \label{lst:input_exposure_ins_rel_metadata}
\end{listing}

In this example, both the insurance \gls{limit} and the \gls{deductible} are
defined as a fraction of the replacement cost, by setting the attribute
\Verb+isAbsolute+ to \Verb+false+. Then, for each type of cost, the
\gls{limit} and \gls{deductible} value can be stored for each asset, as
illustrated in the snippet shown in
Listing~\ref{lst:input_exposure_ins_rel_assets}.

\begin{listing}[htbp]
  \inputminted[firstline=22,firstnumber=22,lastline=32,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_ins_rel.xml}
  \caption{Example exposure model using relative insurance limits and deductibles: assets definition (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_ins_rel.xml}{Download example})}
  \label{lst:input_exposure_ins_rel_assets}
\end{listing}

On the other hand, a user could define one or both of these parameters as
absolute values, by setting the aforementioned attribute to \Verb+true+. This
is shown in the example shown in Listing~\ref{lst:input_exposure_ins_abs}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_ins_abs.xml}
  \caption{Example exposure model using absolute insurance limits and deductibles (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_ins_abs.xml}{Download example})}
  \label{lst:input_exposure_ins_abs}
\end{listing}

Moreover, in order to perform a benefit/cost assessment, it is also necessary
to indicate the retrofitting cost. This parameter is handled in the same
manner as the structural cost, and it should be stored according to the format
shown in Listing~\ref{lst:input_exposure_retrofit}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_retrofit.xml}
  \caption{Example exposure model specifying retrofit costs (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_retrofit.xml}{Download example})}
  \label{lst:input_exposure_retrofit}
\end{listing}

Despite the fact that for the demonstration of how the insurance parameters
and retrofitting cost can be stored the per building type of cost structure
described in Example~1 was used, it is important to mention that any of the
other cost storing approaches can also be employed (Examples 2--4).


\paragraph{Example 6}

The \glsdesc{acr:oqe} is also capable of estimating human losses, based on the
number of occupants in an \gls{asset}, at a certain time of the day. The example
\gls{exposuremodel} shown in Listing~\ref{lst:input_exposure_occupants} illustrates
how this parameter is defined for each \gls{asset}. In addition, this example also
serves the purpose of presenting an \gls{exposuremodel} in which three cost
types have been defined using three different options.

As previously mentioned, in this example only three costs are being stored,
and each one follows a different approach. The \Verb+structural+ cost is being
defined as the aggregate replacement cost for all of the buildings comprising
the asset (Example~1), the \Verb+nonstructural+ value is defined as the
replacement cost per unit area where the area is defined per building
comprising the \gls{asset} (Example~4), and the \Verb+contents+ and
\Verb+business_interruption+ values are provided per building comprising the
\gls{asset} (Example~2). The number of occupants at different times of the day are
also provided as aggregated values for all of the buildings comprising the
\gls{asset}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_occupants.xml}
  \caption{Example exposure model specifying the aggregate number of occupants per asset (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_occupants.xml}{Download example})}
  \label{lst:input_exposure_occupants}
\end{listing}


\paragraph{Example 7}

Starting from \glsdesc{acr:oqe27}, the user may also provide a set of \glspl{tag} 
for each \gls{asset} in the \gls{exposuremodel}. The primary intended use case for the 
\glspl{tag} is to enable aggregation or accumulation of risk results (casualties /
damages / losses) for each \gls{tag}. The \glspl{tag} could be used to specify
location attributes, occupancy types, or insurance policy codes for the 
different \glspl{asset} in the \gls{exposuremodel}.

The example
\gls{exposuremodel} shown in Listing~\ref{lst:input_exposure_tags} illustrates
how one or more \glspl{tag} can be defined for each \gls{asset}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_tags.xml}
  \caption{Example exposure model specifying six location based tags for each asset (\href{https://raw.githubusercontent.com/GEMScienceTools/oq-engine-docs/master/oqum/risk/verbatim/input_exposure_tags.xml}{Download example})}
  \label{lst:input_exposure_tags}
\end{listing}


A web-based tool to build an \gls{exposuremodel} in the \gls{acr:nrml} schema
are also under development, and can be found at the OpenQuake platform at the
following address: \href{https://platform.openquake.org/ipt/}{https://platform.openquake.org/ipt/}.<commit_msg>Manual: Describe the asset tags in the exposure section [skip CI]<commit_after>\emph{All} risk calculators in the \glsdesc{acr:oqe} require an
\gls{exposuremodel} that needs to be provided in the \gls{acr:nrml} schema,
the use of which is illustrated through several examples in this section. The
information included in an \gls{exposuremodel} comprises a metadata section
listing general information about the exposure, followed by a cost conversions
section that describes how the different areas, costs, and occupancies for the
assets will be specified, followed by data regarding each individual
\gls{asset} in the portfolio.

A simple \gls{exposuremodel} comprising a single \gls{asset} is shown in
Listing~\ref{lst:input_exposure_minimal}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}
  \caption{Example exposure model comprising a single asset (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_minimal.xml}{Download example})}
  \label{lst:input_exposure_minimal}
\end{listing}

Let us take a look at each of the sections in the above example file in turn.
The first part of the file contains the metadata section:

\inputminted[firstline=5,firstnumber=5,lastline=8,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}

The information in the metadata section is common to all of the \glspl{asset}
in the portfolio and needs to be incorporated at the beginning of every
\gls{exposuremodel} file. There are a number of parameters that compose the
metadata section, which is intended to provide general information regarding
the \glspl{asset} within the \gls{exposuremodel}. These parameters are
described below:

\begin{itemize}

  \item \Verb+id+: mandatory; a unique string used to identify the
    \gls{exposuremodel}. This string can contain letters~(a--z; A--Z), 
    numbers~(0--9), dashes~(--), and underscores~(\_), with a maximum of 
    100~characters.

  \item \Verb+category+: an optional string used to define the type of
    \glspl{asset} being stored (e.g: buildings, lifelines).

  \item \Verb+taxonomySource+: an optional attribute used to define the
    \gls{taxonomy} being used to classify the \glspl{asset}.

  \item \Verb+description+: mandatory; a brief string (ASCII) with further
    information about the \gls{exposuremodel}.

\end{itemize}


Next, let us look at the part of the file describing the area and cost
conversions:

\inputminted[firstline=10,firstnumber=10,lastline=15,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}

Notice that the \Verb+costType+ element defines a \Verb+name+, a \Verb+type+, 
and a \Verb+unit+ attribute.

The \gls{acr:nrml} schema for the \gls{exposuremodel} allows the definition of
a structural cost, a nonstructural components cost, a contents cost, and a
business interruption or downtime cost for each \gls{asset} in the portfolio.
Thus, the valid values for the \Verb+name+ attribute of the \Verb+costType+
element are the following:

\begin{itemize}

  \item \Verb+structural+: used to specify the structural replacement cost
    of assets

  \item \Verb+nonstructural+: used to specify the replacement cost for the
    nonstructural components of assets

  \item \Verb+contents+: used to specify the contents replacement cost

  \item \Verb+business_interruption+: used to specify the cost that will be 
    incurred per unit time that a damaged asset remains closed following an 
    earthquake

\end{itemize}

The \gls{exposuremodel} shown in the example above defines only the structural
values for the \glspl{asset}. However, multiple cost types can be defined for
each \gls{asset} in the same \gls{exposuremodel}.

The \Verb+unit+ attribute of the \Verb+costType+ element is used for
specifying the currency unit for the corresponding cost type. Note that the
\glsdesc{acr:oqe} itself is agnostic to the currency units; the \Verb+unit+ is
thus a descriptive attribute which is used by the \glsdesc{acr:oqe} to annotate the
results of a risk assessment. This attribute can be set to any valid Unicode
string.

The \Verb+type+ attribute of the \Verb+costType+ element specifies whether the
costs will be provided as an aggregated value for an asset, or per building or
unit comprising an \gls{asset}, or per unit area of an \gls{asset}. The valid
values for the \Verb+type+ attribute of the \Verb+costType+ element are the
following:

\begin{itemize}

  \item \Verb+aggregated+: indicates that the replacement costs will be 
    provided as an aggregated value for each \gls{asset}

  \item \Verb+per_asset+: indicates that the replacement costs will be 
    provided per structural unit comprising each \gls{asset}

  \item \Verb+per_area+: indicates that the replacement costs will be 
    provided per unit area for each \gls{asset}

\end{itemize}

If the costs are to be specified \Verb+per_area+ for any of the
\Verb+costTypes+, the \Verb+area+ element will also need to be defined in the
conversions section. The \Verb+area+ element defines a \Verb+type+, and a
\Verb+unit+ attribute.

The \Verb+unit+ attribute of the \Verb+area+ element is used for specifying
the units for the area of an \gls{asset}. The \glsdesc{acr:oqe} itself is
agnostic to the area units; the \Verb+unit+ is thus a descriptive attribute
which is used by the \glsdesc{acr:oqe} to annotate the results of a risk
assessment. This attribute can be set to any valid ASCII string.

The \Verb+type+ attribute of the \Verb+area+ element specifies whether the
area will be provided as an aggregated value for an \gls{asset}, or per
building or unit comprising an \gls{asset}. The valid values for the
\Verb+type+ attribute of the \Verb+area+ element are the following:

\begin{itemize}

  \item \Verb+aggregated+: indicates that the area will be provided as an 
    aggregated value for each \gls{asset}

  \item \Verb+per_asset+: indicates that the area will be provided per 
    building or unit comprising each \gls{asset}

\end{itemize}


The way the information about the characteristics of the \glspl{asset} in an
\gls{exposuremodel} are stored can vary strongly depending on how and why the
data was compiled. As an example, if national census information is used to
estimated the distribution of \glspl{asset} in a given region, it is likely
that the number of buildings within a given geographical area will be used to
define the dataset, and will be used for estimating the number of collapsed
buildings for a scenario earthquake. On the other hand, if simplified
methodologies based on proxy data such as population distribution are used to
develop the \gls{exposuremodel}, then it is likely that the built up area or
economic cost of each building typology will be directly derived, and will be
used for the estimation of economic losses.


Finally, let us look at the part of the file describing the set of
\glspl{asset} in the portfolio to be used in seismic damage or risk
calculations:

\inputminted[firstline=17,firstnumber=17,lastline=27,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_minimal.xml}

Each \gls{asset} definition involves specifiying a set of mandatory and
optional attributes concerning the \gls{asset}. The following set of
attributes can be assigned to each \gls{asset} based on the current schema for
the \gls{exposuremodel}:

\begin{itemize}

  \item \Verb+id+: mandatory; a unique string used to identify the 
    given \gls{asset}, which is used by the \glsdesc{acr:oqe} to relate each
    \gls{asset} with its associated results. This string can contain 
    letters~(a--z; A--Z), numbers~(0--9), dashes~(-), and underscores~(\_), 
    with a maximum of 100~characters.

  \item \Verb+taxonomy+: mandatory; this string specifies the building typology
    of the given \gls{asset}. The taxonomy strings can be user-defined, or
    based on an existing classification scheme such as the GEM Taxonomy, PAGER,
    or EMS-98.

  \item \Verb+number+: the number of individual structural units comprising a
    given \gls{asset}. This attribute is mandatory for damage calculations. For
    risk calculations, this attribute must be defined if either the area or any
    of the costs are provided per structural unit comprising each \gls{asset}.

  \item \Verb+area+: area of the \gls{asset}, at a given location. As 
    mentioned earlier, the area is a mandatory attribute only if any one of the 
    costs for the \gls{asset} is specified per unit area.

  \item \Verb+location+: mandatory; specifies the longitude 
    (between -180$^{\circ}$ to 180$^{\circ}$) and latitude 
    (between -90$^{\circ}$ to 90 $^{\circ}$) of the given \gls{asset}, both
    specified in decimal degrees\footnote{Within the \glsdesc{acr:oqe}, 
    longitude and latitude coordinates are internally rounded to a precision
    of 5 digits after the decimal point.}.

  \item \Verb+costs+: specifies a set of costs for the given \gls{asset}. 
    The replacement value for different cost types must be provided on 
    separate lines within the \Verb+costs+ element. As shown in the example 
    above, each cost entry must define the \Verb+type+ and the \Verb+value+. 
    Currently supported valid options for the cost \Verb+type+ are: 
    \Verb+structural+,  \Verb+nonstructural+, \Verb+contents+, and 
    \Verb+business_interruption+.

  \item \Verb+occupancies+: mandatory only for probabilistic or scenario 
    risk calculations that specify an \Verb+occupants_vulnerability_file+.
    Each entry within this element specifies the number of
    occupants for the asset for a particular period of the day. As shown in 
    the example above, each occupancy entry must define the \Verb+period+ and 
    the \Verb+occupants+. Currently supported valid options for the 
    \Verb+period+ are: \Verb+day+, \Verb+transit+, and \Verb+night+. Currently,
    the number of \Verb+occupants+ for an asset can only be provided as an 
    aggregated value for the asset.

\end{itemize}

For the purposes of performing a retrofitting benefit/cost analysis, it is
also necessary to define the retrofitting cost (\Verb+retrofitted+). The
combination between the possible options in which these three attributes can
be defined leads to four ways of storing the information about the
\glspl{asset}. For each of these cases a brief explanation and example is
provided in this section.


\paragraph{Example 1}

This example illustrates an \gls{exposuremodel} in which the aggregated cost
(structural, nonstructural, contents and business interruption) of the
\glspl{asset} of each taxonomy for a set of locations is directly provided.
Thus, in order to indicate how the various costs will be defined, the
following information needs to be stored in the \gls{exposuremodel} file, as
shown in Listing~\ref{lst:input_exposure_cagg_metadata}.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=18,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cagg.xml}
  \caption{Example exposure model using aggregate costs: metadata definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_cagg.xml}{Download example})}
  \label{lst:input_exposure_cagg_metadata}
\end{listing}

In this case, the cost \Verb+type+ of each component as been defined as
\Verb+aggregated+. Once the way in which each cost is going to be defined has
been established, the values for each asset can be stored according to the
format shown in Listing~\ref{lst:input_exposure_cagg_assets}.

\begin{listing}[htbp]
  \inputminted[firstline=19,firstnumber=19,lastline=29,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cagg.xml}
  \caption{Example exposure model using aggregate costs: assets definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_cagg.xml}{Download example})}
  \label{lst:input_exposure_cagg_assets}
\end{listing}

Each \gls{asset} is uniquely identified by its \Verb+id+. Then, a pair of
coordinates (latitude and longitude) for a \Verb+location+ where the asset is
assumed to exist is defined. Each \gls{asset} must be classified according to
a \Verb+taxonomy+, so that the \glsdesc{acr:oqe} is capable of employing the
appropriate \gls{vulnerabilityfunction} or \gls{fragilityfunction} in the risk
calculations. Finally, the cost values of each \Verb+type+ are stored within
the \Verb+costs+ attribute. In this example, the aggregated value for all
structural units (within a given \gls{asset}) at each location is provided
directly, so there is no need to define other attributes such as \Verb+number+
or \Verb+area+. This mode of representing an \gls{exposuremodel} is probably
the simplest one.


\paragraph{Example 2}

In the snippet shown in Listing~\ref{lst:input_exposure_cunit_metadata}, an
\gls{exposuremodel} containing the number of structural units and the
associated costs per unit of each \gls{asset} is presented.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=18,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cunit.xml}
  \caption{Example exposure model using costs per unit: metadata definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_cunit.xml}{Download example})}
  \label{lst:input_exposure_cunit_metadata}
\end{listing}

For this case, the cost \Verb+type+ has been set to \Verb+per_asset+. Then,
the information from each \gls{asset} can be stored following the format shown
in Listing~\ref{lst:input_exposure_cunit_assets}.

\begin{listing}[htbp]
  \inputminted[firstline=19,firstnumber=19,lastline=29,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_cunit.xml}
  \caption{Example exposure model using costs per unit: assets definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_cunit.xml}{Download example})}
  \label{lst:input_exposure_cunit_assets}
\end{listing}

In this example, the various costs for each \gls{asset} is not provided
directly, as in the previous example. In order to carry out the risk
calculations in which the economic cost of each \gls{asset} is provided, the
\glsdesc{acr:oqe} multiplies, for each \gls{asset}, the number of units
(buildings) by the ``per asset'' replacement cost. Note that in this case,
there is no need to specify the attribute \Verb+area+.


\paragraph{Example 3}

The example shown in Listing~\ref{lst:input_exposure_carea_aagg_metadata}
comprises an \gls{exposuremodel} containing the built up area of each
\gls{asset}, and the associated costs are provided per unit area.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=20,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aagg.xml}
  \caption{Example exposure model using costs per unit area and aggregated areas: metadata definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_carea_aagg.xml}{Download example})}
  \label{lst:input_exposure_carea_aagg_metadata}
\end{listing}

In order to compile an \gls{exposuremodel} with this structure, the cost
\Verb+type+ should be set to \Verb+per_area+. In addition, it is also
necessary to specify if the \Verb+area+ that is being store represents the
aggregated area of number of units within an asset, or the average area of a
single unit. In this particular case, the \Verb+area+ that is being stored is
the aggregated built up area per asset, and thus this attribute was set to
\Verb+aggregated+. Listing~\ref{lst:input_exposure_carea_aagg_assets}
illustrates the definition of the \glspl{asset} for this example.

\begin{listing}[htbp]
  \inputminted[firstline=21,firstnumber=21,lastline=31,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aagg.xml}
  \caption{Example exposure model using costs per unit area and aggregated areas: assets definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_carea_aagg.xml}{Download example})}
  \label{lst:input_exposure_carea_aagg_assets}
\end{listing}

Once again, the \glsdesc{acr:oqe} needs to carry out some calculations in
order to compute the different costs per \gls{asset}. In this case, this value
is computed by multiplying the aggregated built up \Verb+area+ of each
\gls{asset} by the associated cost per unit area. Notice that in this case,
there is no need to specify the attribute \Verb+number+.


\paragraph{Example 4}

This example demonstrates an \gls{exposuremodel} that defines the number of
structural units for each \gls{asset}, the average built up area per
structural unit and the associated costs per unit area.
Listing~\ref{lst:input_exposure_carea_aunit_metadata} shows the metadata
definition for an \gls{exposuremodel} built in this manner.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=20,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aunit.xml}
  \caption{Example exposure model using costs per unit area and areas per unit: metadata definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_carea_aunit.xml}{Download example})}
  \label{lst:input_exposure_carea_aunit_metadata}
\end{listing}

Similarly to what was described in the previous example, the various costs
\Verb+type+ also need to be established as \Verb+per_area+, but the
\Verb+type+ of area is now defined as \Verb+per_asset+.
Listing~\ref{lst:input_exposure_carea_aunit_assets} illustrates the definition
of the assets for this example.

\begin{listing}[htbp]
  \inputminted[firstline=21,firstnumber=21,lastline=31,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_carea_aunit.xml}
  \caption{Example exposure model using costs per unit area and areas per unit: assets definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_carea_aunit.xml}{Download example})}
  \label{lst:input_exposure_carea_aunit_assets}
\end{listing}

In this example, the \glsdesc{acr:oqe} will make use of all the parameters to
estimate the various costs of each \gls{asset}, by multiplying the number of
structural units by its average built up area, and then by the respective cost
per unit area.


\paragraph{Example 5}

In this example, additional information will be included, which is required
for other risk analysis besides loss estimation, such as the calculation of
insured losses or benefit/cost analysis. For the calculation of insured
losses, it is necessary to establish how the insurance \glspl{limit} and
\glspl{deductible} are going to be defined.
Listing~\ref{lst:input_exposure_ins_rel_metadata} illustrates the metadata
section of an \gls{exposuremodel} where the insurance \glspl{limit} and
\glspl{deductible} for structural components will be defined relative to the
structural replacement cost.

\begin{listing}[htbp]
  \inputminted[firstline=8,firstnumber=8,lastline=21,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_ins_rel.xml}
  \caption{Example exposure model using relative insurance limits and deductibles: metadata definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_ins_rel.xml}{Download example})}
  \label{lst:input_exposure_ins_rel_metadata}
\end{listing}

In this example, both the insurance \gls{limit} and the \gls{deductible} are
defined as a fraction of the replacement cost, by setting the attribute
\Verb+isAbsolute+ to \Verb+false+. Then, for each type of cost, the
\gls{limit} and \gls{deductible} value can be stored for each asset, as
illustrated in the snippet shown in
Listing~\ref{lst:input_exposure_ins_rel_assets}.

\begin{listing}[htbp]
  \inputminted[firstline=22,firstnumber=22,lastline=32,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_ins_rel.xml}
  \caption{Example exposure model using relative insurance limits and deductibles: assets definition (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_ins_rel.xml}{Download example})}
  \label{lst:input_exposure_ins_rel_assets}
\end{listing}

On the other hand, a user could define one or both of these parameters as
absolute values, by setting the aforementioned attribute to \Verb+true+. This
is shown in the example shown in Listing~\ref{lst:input_exposure_ins_abs}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_ins_abs.xml}
  \caption{Example exposure model using absolute insurance limits and deductibles (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_ins_abs.xml}{Download example})}
  \label{lst:input_exposure_ins_abs}
\end{listing}

Moreover, in order to perform a benefit/cost assessment, it is also necessary
to indicate the retrofitting cost. This parameter is handled in the same
manner as the structural cost, and it should be stored according to the format
shown in Listing~\ref{lst:input_exposure_retrofit}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_retrofit.xml}
  \caption{Example exposure model specifying retrofit costs (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_retrofit.xml}{Download example})}
  \label{lst:input_exposure_retrofit}
\end{listing}

Despite the fact that for the demonstration of how the insurance parameters
and retrofitting cost can be stored the per building type of cost structure
described in Example~1 was used, it is important to mention that any of the
other cost storing approaches can also be employed (Examples 2--4).


\paragraph{Example 6}

The \glsdesc{acr:oqe} is also capable of estimating human losses, based on the
number of occupants in an \gls{asset}, at a certain time of the day. The example
\gls{exposuremodel} shown in Listing~\ref{lst:input_exposure_occupants} illustrates
how this parameter is defined for each \gls{asset}. In addition, this example also
serves the purpose of presenting an \gls{exposuremodel} in which three cost
types have been defined using three different options.

As previously mentioned, in this example only three costs are being stored,
and each one follows a different approach. The \Verb+structural+ cost is being
defined as the aggregate replacement cost for all of the buildings comprising
the asset (Example~1), the \Verb+nonstructural+ value is defined as the
replacement cost per unit area where the area is defined per building
comprising the \gls{asset} (Example~4), and the \Verb+contents+ and
\Verb+business_interruption+ values are provided per building comprising the
\gls{asset} (Example~2). The number of occupants at different times of the day are
also provided as aggregated values for all of the buildings comprising the
\gls{asset}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_occupants.xml}
  \caption{Example exposure model specifying the aggregate number of occupants per asset (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_occupants.xml}{Download example})}
  \label{lst:input_exposure_occupants}
\end{listing}


\paragraph{Example 7}

Starting from \glsdesc{acr:oqe27}, the user may also provide a set of \glspl{tag} 
for each \gls{asset} in the \gls{exposuremodel}. The primary intended use case for the 
\glspl{tag} is to enable aggregation or accumulation of risk results (casualties /
damages / losses) for each \gls{tag}. The \glspl{tag} could be used to specify
location attributes, occupancy types, or insurance policy codes for the 
different \glspl{asset} in the \gls{exposuremodel}.

The example
\gls{exposuremodel} shown in Listing~\ref{lst:input_exposure_tags} illustrates
how one or more \glspl{tag} can be defined for each \gls{asset}.

\begin{listing}[htbp]
  \inputminted[firstline=1,firstnumber=1,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_tags.xml}
  \caption{Example exposure model specifying six location based tags for each asset (\href{https://raw.githubusercontent.com/gem/oq-engine/master/doc/manual/oqum/risk/verbatim/input_exposure_tags.xml}{Download example})}
  \label{lst:input_exposure_tags}
\end{listing}

The list of tag names that will be used in the \gls{exposuremodel} must be provided
in the metadata section of the exposure file, as shown in the following snippet
from the full file:

\inputminted[firstline=17,firstnumber=17,lastline=17,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_tags.xml}

The \gls{tag} values for the different \glspl{tag} can then be specified for
each \gls{asset} as shown in the following snippet from the same file:

\inputminted[firstline=28,firstnumber=28,lastline=29,fontsize=\footnotesize,frame=single,linenos,bgcolor=lightgray]{xml}{oqum/risk/verbatim/input_exposure_tags.xml}

Note that it is not mandatory that every \gls{tag} name specified in the metadata
section must be provided with a \gls{tag} value for each \gls{asset}. 

A web-based tool to build an \gls{exposuremodel} in the \gls{acr:nrml} schema
starting from a csv file or a spreadsheet can be found at the OpenQuake platform at the
following address: \href{https://platform.openquake.org/ipt/}{https://platform.openquake.org/ipt/}.
{'fraction_non_alphanumeric': 0.08564018826241475, 'fraction_numerical': 0.004572087215445202, 'mean_word_length': 5.390375644488092, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 34, 'lorem ipsum': 0, 'www.': 0, 'xml': 106}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 30, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2748553', 'n_tokens_mistral': 16358, 'n_tokens_neox': 15152, 'n_words': 5586}