Merge pull request #32 from OasisLMF/add/vulnerability_options

vulnerability options docs page

src/index.rst

@@ -122,6 +122,7 @@ It allows regression of the models after updates to the Oasis Platform code, and
     sections/SaaS-providers.rst
     sections/sampling-methodology.rst
     sections/versioning.rst
+    sections/vulnerability-adjustments.rst
 
 .. 
   sections to be populated: sections/pre-analysis-adjustments.rst, sections/errors.rst, sections/complex-model.rst

src/sections/vulnerability-adjustments.rst

@@ -0,0 +1,129 @@
+Vulnerability Adjustments
+==========
+
+On this page
+------------
+
+* :ref:`introduction_vulnerability`
+* :ref:`vulnerability_replacements`
+* :ref:`vulnerability_adjustments`
+
+|
+.. _introduction_vulnerability:
+
+Introduction
+************
+
+----
+
+Vulnerability adjustments allow users to modify or update specific vulnerabilities without needing to replace or edit the entire vulnerability file. Users can apply adjustments in three ways:
+
+1. Replacing vulnerabilities indicating the path to a file.
+2. Replacing specific vulnerabilities via JSON format directly in the ``analysis_settings``.
+3. Applying factor adjustments to modify probabilities.
+
+These methods offer flexibility when customizing the model's vulnerability settings to account for specific risk scenarios or data updates.
+
+|
+
+.. _vulnerability_replacements:
+
+Vulnerability Replacements
+************
+
+----
+
+* 1. Replacing Vulnerabilities via path to a File
+
+This method allows the user to replace specific vulnerabilities by providing an external file containing replacement data.
+
+Example format in ``analysis_settings``:
+
+|
+.. code-block:: JSON
+
+  "vulnerability_adjustments": { "replace_file": {} }
+|
+
+The user can provide the path to a CSV file with the updated vulnerability data:
+
+|
+.. code-block:: JSON
+
+  "vulnerability_adjustments": {"replace_file" : "vulnerability_adjustments.csv"}
+|
+
+The CSV file should contain updated data for the specific vulnerabilities to be replaced. For an example of the expected file contents, refer to the documentation provided in this repository (https://oasislmf.github.io/sections/Oasis-model-data-formats.html).
+
+
+
+
+
+* 2. Replacing Specific Vulnerability Data in JSON format in the ``analysis_settings``
+
+This method allows users to replace data for specific vulnerabilities directly within the ``analysis_settings`` file.
+
+Example format:
+
+|
+.. code-block:: JSON
+
+  "vulnerability_adjustments": { "replace_data": {} }
+|
+
+The data can be replaced for specific ``vulnerability_id``s:
+
+|
+.. code-block:: JSON
+
+  "vulnerability_adjustments": {
+    "replace_data": {
+      "1": [[1,1,0.01],[1,2,0.02],...],
+      "2": [[1,1,0.4],...]
+    }
+  }
+|
+
+This replaces the entire data for the specified vulnerabilities. The format is as follows:
+- `vulnerability_id`
+- `intensity_bin_id`
+- `damage_bin_id`
+- `probability`
+
+
+
+.. _vulnerability_adjustments:
+
+Vulnerability Adjustments
+************
+
+----
+
+* 3. Applying Adjustments Using Factors
+
+This method allows users to apply a factor adjustment to specific vulnerabilities, altering the random number extraction process used to calculate probabilities.
+
+Example format:
+
+|
+.. code-block:: JSON
+
+  "vulnerability_adjustments": { "adjustments": {} }
+|
+
+The user can apply adjustment factors to the ``vulnerability_id`` as shown below:
+
+|
+.. code-block:: JSON
+
+  "vulnerability_adjustments": {
+    "adjustments": {
+      "2": 0.5,
+      "8": 1.5
+    }
+  }
+|
+
+In this example, the factor for ``vulnerability_id`` 2 reduces the extracted random numbers (by multiplying by 0.5), thus lowering the probability of falling into higher damage bins. Conversely, for ``vulnerability_id`` 8, multiplying by 1.5 increases the likelihood of it falling into a higher damage bin.
+
+----