Vulnerability Level Computation
===============================

Definition
----------

Vulnerability Level (VL) is a numeric measure representing the potential impact of an incident in a specific area. VERUS computes this value for each vulnerability zone by analyzing the distribution and influence of PoTIs.

Computation Methods
-------------------

VERUS supports two methods for calculating vulnerability levels:

1. **Gaussian Weighted**: Uses a Gaussian decay function based on distance
2. **Inverse Weighted**: Applies an inverse relationship between distance and influence

The Gaussian method is the default and follows this formula:

.. math::

    VL(z) = \sum_{i \in C_z} VI_i \cdot e^{-\frac{d(z,i)^2}{2\sigma^2}}

Where:

* :math:`VL(z)` is the vulnerability level of zone z
* :math:`C_z` is the set of PoTIs in the same cluster as zone z
* :math:`VI_i` is the vulnerability influence of PoTI i
* :math:`d(z,i)` is the distance between zone z and PoTI i
* :math:`\sigma` is the bandwidth parameter (in meters)

Process Steps
-------------

The vulnerability computation process involves:

1. **Clustering**: Grouping PoTIs into urban clusters
2. **Zone Assignment**: Assigning vulnerability zones to clusters
3. **Raw Calculation**: Computing initial vulnerability levels
4. **Normalization**: Scaling values between 0-1
5. **Smoothing**: Applying spatial smoothing for continuity

Clustering
----------

VERUS uses a two-step clustering approach:

1. **OPTICS** algorithm identifies initial cluster centers
2. **KMeans** with Haversine distance refines the final clusters

This clustering ensures that vulnerability calculations consider the natural grouping of urban features rather than arbitrary boundaries.

Influence of Time Windows
-------------------------

Time windows modify the vulnerability influence (VI) values of PoTIs based on the evaluation time:

1. For a given timestamp, VERUS identifies active time windows
2. VI values are updated according to the time window definitions
3. These updated VI values are used in vulnerability calculations

This enables time-sensitive analysis of urban vulnerability.

Normalization and Smoothing
---------------------------

After raw calculation:

1. **Normalization**: Values are scaled between 0-1 based on the maximum vulnerability in the region
2. **Spatial Smoothing**: A moving window average is applied to create a more continuous vulnerability surface

This makes it easier to visualize and compare vulnerability levels across different areas and scenarios.

Example
-------

.. code-block:: python

    # Configure the vulnerability assessor
    assessor = VERUS(
        place_name="Porto", 
        distance_method="gaussian",  # Use Gaussian weighting
        sigma=1000  # 1000m bandwidth parameter
    )
    
    # Load data
    assessor.load(potis_df=poi_data, zones_gdf=hex_grid)
    
    # Run assessment
    results = assessor.run(evaluation_time=timestamp)

The resulting vulnerability levels can then be visualized as a heatmap, with darker colors indicating higher vulnerability areas.