============
Risk Metrics
============

Introduction
------------

Risk metrics quantify the expected losses and consequences from seismic hazards over time. 
This section provides interactive tools to compute and visualize key risk indicators for 
cities across 12 global regions.

The following risk metrics are computed:

* **Structural AALR**: Expected annual structural damage as a fraction of replacement cost
* **Non-Structural AALR**: Expected annual non-structural damage
* **Contents AALR**: Expected annual contents damage
* **Building AALR**: Combined structural and non-structural losses
* **Total AALR**: Combined structural, non-structural, and contents losses
* **Fatalities AALR**: Expected annual fatality rate per building
* **Average Annual Collapse Probability (AACP)**: Annual probability of structural collapse

All AALR metrics use the **efficient intensity measure** for each building class — the IMT that
minimises average dispersion across damage states, reducing uncertainty in the estimates.

Methodology
-----------

Risk Calculation
~~~~~~~~~~~~~~~~

The Average Annual Loss (AAL) is computed by integrating the product of the vulnerability 
function and the hazard curve:

.. math::

   AAL = \int_0^{\infty} V(IM) \cdot \left| \frac{d\lambda(IM)}{dIM} \right| \, dIM

where:

* :math:`V(IM)` is the mean loss ratio from the vulnerability function at intensity :math:`IM`
* :math:`\lambda(IM)` is the annual rate of exceedance from the hazard curve
* The derivative represents the annual rate of occurrence at each intensity level

Numerical Integration
~~~~~~~~~~~~~~~~~~~~~

The integral is approximated using the trapezoidal rule:

.. math::

   AAL \approx \sum_{i=1}^{n} \frac{V(IM_i) + V(IM_{i-1})}{2} \cdot |\lambda(IM_{i-1}) - \lambda(IM_i)|

For collapse probability, the calculation integrates the collapse fragility function with 
the hazard curve:

.. math::

   AACP = \int_0^{\infty} P(C|IM) \cdot \left| \frac{d\lambda(IM)}{dIM} \right| \, dIM


Interactive Viewer
------------------

Use the interactive viewer below to explore precompiled risk metrics for a specific building class
within a selected region. The bar charts show values across cities.

.. raw:: html

   <div class="viewer-container" id="risk-viewer">
       <div class="viewer-controls">
           <div class="control-row">
               <div class="control-group">
                   <label for="risk-model-select">Model:</label>
                   <select id="risk-model-select" class="viewer-select model-select" onchange="switchModel(this.value).then(() => { initRiskViewer(); })">
                       <option value="GEM">GEM</option>
                   </select>
               </div>
           </div>
       </div>
       <div class="viewer-controls">
           <div class="control-row" style="display: flex; gap: 15px; flex-wrap: wrap; align-items: end;">
               <div class="control-group">
                   <label for="risk-region-select">Region:</label>
                   <select id="risk-region-select" class="viewer-select">
                       <option value="">-- Select Region --</option>
                   </select>
               </div>
               <div class="control-group">
                   <label for="risk-building-select">Building Class:</label>
                   <select id="risk-building-select" class="viewer-select">
                       <option value="">-- Select Building Class --</option>
                   </select>
               </div>
               <div class="control-group">
                   <label for="risk-occupancy-select">Occupancy:</label>
                   <select id="risk-occupancy-select" class="viewer-select">
                       <option value="">-- Select Occupancy --</option>
                   </select>
               </div>
               <div class="control-group">
                   <label for="risk-imt-select">Intensity Measure:</label>
                   <select id="risk-imt-select" class="viewer-select">
                       <option value="">-- Select IMT --</option>
                   </select>
               </div>
               <div class="control-group">
                   <button id="risk-calculate-btn" class="viewer-btn btn-primary">Load Risk Metrics</button>
               </div>
           </div>
       </div>
       
       <div class="risk-results" style="margin-top: 20px;">
           <div class="viewer-plot" id="risk-structural-plot" style="height: 350px;"></div>
           <div class="viewer-plot" id="risk-nonstructural-plot" style="height: 350px;"></div>
           <div class="viewer-plot" id="risk-contents-plot" style="height: 350px;"></div>
           <div class="viewer-plot" id="risk-building-plot" style="height: 350px;"></div>
           <div class="viewer-plot" id="risk-total-plot" style="height: 350px;"></div>
           <div class="viewer-plot" id="risk-fatalities-plot" style="height: 350px;"></div>
           <div class="viewer-plot" id="risk-collapse-plot" style="height: 350px;"></div>
       </div>
   </div>

   <script>
       document.addEventListener('DOMContentLoaded', function() {
           if (typeof initRiskViewer === 'function') {
               initRiskViewer();
           }
       });
   </script>


Data Requirements
-----------------

The risk calculations require:

1. **Hazard Curves**: Annual exceedance probabilities for each intensity measure level, 
   stored in ``in/hazard/hazard_curves_{mosaic}_{IMT}.csv``

2. **Vulnerability Functions**: Mean loss ratios and coefficients of variation as a function 
   of intensity measure

3. **City Database**: Geographic and regional information for cities, including hazard 
   mosaic assignments


Regional Coverage
-----------------

Risk metrics are available for the following 12 regions:

.. list-table:: Regional Coverage
   :header-rows: 1
   :widths: 30 70

   * - Region
     - Description
   * - North America
     - United States, Canada, Mexico
   * - Europe
     - EU member states and surrounding countries
   * - Oceania
     - Australia, New Zealand, Pacific Islands
   * - South America
     - All South American countries
   * - Caribbean & Central America
     - Caribbean islands and Central American countries
   * - Middle East
     - Gulf states and Levant region
   * - Africa
     - All African countries
   * - Southeast Asia
     - ASEAN member states
   * - East Asia
     - China, Japan, Korea, Taiwan
   * - South Asia
     - India, Pakistan, Bangladesh, Nepal, Sri Lanka
   * - Central Asia
     - Former Soviet Central Asian republics, Afghanistan
   * - North Asia
     - Russia and northern territories