================
Fragility Models
================

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

Fragility functions describe the probability that a structure will reach or exceed a given damage 
state as a function of an intensity measure (IM). In this framework, fragility functions are 
assumed to follow a **lognormal distribution**, which is commonly adopted in seismic risk 
assessment due to its ability to capture uncertainty in structural response.


Damage State Definition
-----------------------

Four damage states (DS) are considered for structural fragility:

.. list-table:: Structural Damage States
   :header-rows: 1
   :widths: 20 30 50

   * - Damage State
     - Label
     - Description
   * - DS1
     - Slight
     - Minor cracking, onset of yielding
   * - DS2
     - Moderate
     - Significant cracking, some spalling
   * - DS3
     - Extensive
     - Major structural damage
   * - DS4
     - Complete
     - Building at or near collapse

The onset of these damage states is inferred from the maximum interstorey drift ratio 
(:math:`\theta_{max}`) attaining pre-defined thresholds based on the capacity curve.


Damage State Thresholds
~~~~~~~~~~~~~~~~~~~~~~~

DS thresholds for MDOF systems are expressed in terms of maximum interstorey drift ratio:

.. list-table:: DS Thresholds
   :header-rows: 1
   :widths: 20 80

   * - Damage State
     - Maximum Interstorey Drift Ratio Threshold
   * - Slight (DS1)
     - :math:`\theta_{max,DS1} = \max_{i=1,...,n_s}[\Gamma_1(\phi_{1,i} - \phi_{1,i-1}) SD_y / h_i]`
   * - Moderate (DS2)
     - :math:`\theta_{max,DS2} = \max_{i=1,...,n_s}[\Gamma_1(\phi_{1,i} - \phi_{1,i-1})(0.67 SD_y + 0.33 SD_u) / h_i]`
   * - Extensive (DS3)
     - :math:`\theta_{max,DS3} = \max_{i=1,...,n_s}[\Gamma_1(\phi_{1,i} - \phi_{1,i-1})(0.33 SD_y + 0.67 SD_u) / h_i]`
   * - Complete (DS4)
     - :math:`\theta_{max,DS4} = \max_{i=1,...,n_s}[\Gamma_1(\phi_{1,i} - \phi_{1,i-1}) SD_u / h_i]`

where :math:`SD_y` and :math:`SD_u` are yield and ultimate spectral displacements, 
:math:`\Gamma_1` is the first-mode participation factor, :math:`\phi_{1,i}` is the 
first-mode shape ordinate, and :math:`h_i` is the storey height.


Fragility Function Derivation
-----------------------------

Lognormal Fragility Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Let :math:`P(DS \ge ds_i | IM)` denote the probability that damage state :math:`ds_i` is exceeded 
at a given intensity measure level IM. Under the lognormal assumption:

.. math::

   P(DS \ge ds_i | IM) = \Phi\left(\frac{\ln(IM) - \ln(\mu_{DS_i})}{\beta_{DS_i}}\right)

where:

* :math:`\mu_{DS_i}` is the **median** intensity measure corresponding to damage state :math:`ds_i`
* :math:`\beta_{DS_i}` is the **total logarithmic standard deviation** (dispersion)
* :math:`\Phi(\cdot)` denotes the standard normal cumulative distribution function


Total Dispersion
~~~~~~~~~~~~~~~~

The total dispersion accounts for multiple sources of uncertainty:

.. math::

   \beta_{DS_i} = \sqrt{\beta_{r2r}^2 + \beta_{b2b}^2 + \beta_{ds}^2}

where:

* :math:`\beta_{r2r}` (record-to-record or :math:`\beta_{EDP|IM}`) represents variability due to 
  ground motion record-to-record uncertainty
* :math:`\beta_{b2b}` (building-to-building or :math:`\beta_{MDL}`) captures variability in 
  structural properties across nominally similar buildings
* :math:`\beta_{ds}` represents uncertainty associated with damage state threshold definition

A building-to-building dispersion of 0.30 is adopted following FEMA P-58 recommendations.


Collapse Fragility
------------------

In addition to the four damage states, a separate **collapse fragility** function is derived 
using logistic regression on collapse/non-collapse outcomes from the cloud analysis:

.. math::

   P(C | IM) = \frac{1}{1 + \exp[-(\alpha_0 + \alpha_1 \ln(IM))]}

The collapse cases are identified when:

* Numerical non-convergence occurs during NLTHA
* The EDP exceeds a collapse threshold :math:`EDP_C = 1.5 \times \theta_{max,DS4}`


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

Use the interactive viewer below to explore fragility functions for different building classes.

.. raw:: html

   <div class="viewer-container" id="fragility-viewer">
       <div class="viewer-controls">
           <div class="control-row">
               <div class="control-group">
                   <label for="fragility-model-select">Model:</label>
                   <select id="fragility-model-select" class="viewer-select model-select" onchange="switchModel(this.value).then(() => { fragilitySelections = []; updateFragilitySelections(); initFragilityViewer(); })">
                       <option value="GEM">GEM</option>
                   </select>
               </div>
           </div>
       </div>
       <div class="viewer-controls">
           <div class="control-row">
               <div class="control-group">
                   <label for="fragility-building-select">Building Class:</label>
                   <select id="fragility-building-select" class="viewer-select">
                       <option value="">-- Select Building Class --</option>
                   </select>
               </div>
               <div class="control-group">
                   <label for="fragility-region-select">Region:</label>
                   <select id="fragility-region-select" class="viewer-select">
                       <option value="">-- Select Region --</option>
                   </select>
               </div>
           </div>
           <div class="control-row">
               <div class="control-group">
                   <label for="fragility-imt-select">IMT:</label>
                   <select id="fragility-imt-select" class="viewer-select">
                       <option value="">-- Select IMT --</option>
                       <option value="PGA">PGA</option>
                       <option value="SA(0.3)">SA(0.3)</option>
                       <option value="SA(0.6)">SA(0.6)</option>
                       <option value="SA(1.0)">SA(1.0)</option>
                   </select>
               </div>
               <div class="control-group">
                   <label for="fragility-occupancy-select">Occupancy:</label>
                   <select id="fragility-occupancy-select" class="viewer-select">
                       <option value="">-- Select Occupancy --</option>
                       <option value="RES">Residential (RES)</option>
                       <option value="COM">Commercial (COM)</option>
                       <option value="IND">Industrial (IND)</option>
                   </select>
               </div>
           </div>
           <div class="control-group">
               <button id="fragility-add-btn" class="viewer-btn btn-primary">Add to Plot</button>
               <button id="fragility-clear-btn" class="viewer-btn btn-danger">Clear All</button>
           </div>
       </div>
       <div class="viewer-selections" id="fragility-selections"></div>
       <div class="viewer-plot" id="fragility-plot"></div>
       <div class="viewer-controls slider-controls">
           <div class="control-group">
               <label for="fragility-xmax-slider">X-Axis Max (g):</label>
               <input type="range" id="fragility-xmax-slider" min="1" max="10" value="5" step="0.5">
               <span id="fragility-xmax-value">5.0</span>
           </div>
       </div>
   </div>

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


Fragility Parameters Summary
----------------------------

The table below shows the fragility function parameters for all building classes using the most 
efficient intensity measure (IM). Parameters include median values (θ) for each damage state 
and the total dispersion (β).

The complete fragility parameters are available in the summary file:
``{model_version}/summaries/structural_fragility_params_efficient_imt.csv``

.. raw:: html

   <div id="fragility-params-table-container">
       <div class="viewer-controls" style="margin-bottom: 15px;">
           <input type="text" id="fragility-table-search" placeholder="Search building class..." 
                  style="padding: 8px 12px; border: 1px solid #ddd; border-radius: 4px; width: 300px;">
       </div>
       <div id="fragility-params-table" style="max-height: 600px; overflow-y: auto; border: 1px solid #e9ecef; border-radius: 6px;">
           <p style="padding: 20px; color: #666;">Loading fragility parameters table...</p>
       </div>
   </div>

   <script>
       document.addEventListener('DOMContentLoaded', async function() {
           const tableContainer = document.getElementById('fragility-params-table');
           const searchInput = document.getElementById('fragility-table-search');

           try {
               await _loadDocsConfig();
               const summariesBase = DOCS_CONFIG.summaries_base || '_static/data/out/out_v2/GEM/summaries';
               const response = await fetch(`${summariesBase}/structural_fragility_params_efficient_imt.csv`);
               if (!response.ok) throw new Error('Summary file not found');
               
               const text = await response.text();
               const lines = text.trim().split('\n');
               const headers = lines[0].split(',').map(h => h.trim());
               
               // Parse data
               const data = [];
               for (let i = 1; i < lines.length; i++) {
                   const values = lines[i].split(',');
                   const row = {};
                   headers.forEach((h, idx) => {
                       row[h] = values[idx]?.trim() || '';
                   });
                   data.push(row);
               }
               
               // Build table with Greek letter headers
               function renderTable(filteredData) {
                   let html = `<table style="width: 100%; border-collapse: collapse; font-size: 12px;">
                       <thead style="position: sticky; top: 0; background: #f8f9fa;">
                           <tr style="border-bottom: 2px solid #dee2e6;">`;
                   
                   // Header row with Greek letters
                   headers.forEach(h => {
                       let displayName = h;
                       // Replace Median_DS with μ_DS
                       if (h.startsWith('Median_DS')) displayName = 'μ<sub>' + h.replace('Median_', '') + '</sub>';
                       else if (h.startsWith('Median_')) displayName = 'μ<sub>' + h.replace('Median_', '') + '</sub>';
                       // Replace Beta_DS with β_DS
                       if (h.startsWith('Beta_DS')) displayName = 'β<sub>' + h.replace('Beta_', '') + '</sub>';
                       else if (h.startsWith('Beta_')) displayName = 'β<sub>' + h.replace('Beta_', '') + '</sub>';
                       // Handle theta and other variants
                       if (h.startsWith('theta_')) displayName = 'θ<sub>' + h.replace('theta_', '') + '</sub>';
                       if (h.startsWith('beta_')) displayName = 'β<sub>' + h.replace('beta_', '') + '</sub>';
                       html += `<th style="padding: 10px 8px; text-align: left; font-weight: 600; white-space: nowrap;">${displayName}</th>`;
                   });
                   html += '</tr></thead><tbody>';
                   
                   // Data rows
                   filteredData.forEach((row, idx) => {
                       const bgColor = idx % 2 === 0 ? 'white' : '#f8f9fa';
                       html += `<tr style="border-bottom: 1px solid #e9ecef; background: ${bgColor};">`;
                       headers.forEach(h => {
                           let val = row[h];
                           // Format numbers
                           if (!isNaN(parseFloat(val)) && h !== headers[0]) {
                               val = parseFloat(val).toFixed(4);
                           }
                           html += `<td style="padding: 8px; white-space: nowrap;">${val}</td>`;
                       });
                       html += '</tr>';
                   });
                   
                   html += '</tbody></table>';
                   tableContainer.innerHTML = html;
               }
               
               renderTable(data);
               
               // Search functionality
               searchInput.addEventListener('input', () => {
                   const query = searchInput.value.toLowerCase();
                   const filtered = data.filter(row => 
                       Object.values(row).some(v => v.toLowerCase().includes(query))
                   );
                   renderTable(filtered);
               });
               
           } catch (error) {
               tableContainer.innerHTML = `
                   <div style="padding: 20px; color: #856404; background: #fff3cd; border-radius: 4px;">
                       <strong>Note:</strong> Fragility parameters summary not available. 
                       Run <code>prepare_data.py</code> to generate the data files, or view the 
                       <a href="https://github.com/gem/global_vulnerability_model" target="_blank">GitHub repository</a> 
                       for the complete dataset.
                   </div>
               `;
           }
       });
   </script>


Column Descriptions
~~~~~~~~~~~~~~~~~~~

.. list-table:: Fragility Parameters Table Columns
   :header-rows: 1
   :widths: 25 75

   * - Column
     - Description
   * - Building Class
     - GEM taxonomy string identifying the building class
   * - Efficient IM
     - Most efficient intensity measure for this building class
   * - θ_DS1 to θ_DS4
     - Median IM values [g] for damage states DS1 through DS4
   * - β_DS1 to β_DS4
     - Total logarithmic standard deviation for each damage state


References
----------

* Porter K. et al. (2007). Creating fragility functions for performance-based earthquake 
  engineering. Earthquake Spectra.
  
* Eads L. et al. (2013). An efficient method for estimating the collapse risk of structures 
  in seismic regions. Earthquake Engineering & Structural Dynamics.
  
* FEMA (2012). Next-Generation Methodology for Seismic Performance Assessment of Buildings 
  (FEMA P-58). Washington, D.C.