From 3e5a6cbc60c3859aea34b123fc0bdbe49ab3c518 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 14:52:21 +0100 Subject: [PATCH 1/8] vulnerability options docs page --- src/sections/vulnerability-adjustments.rst | 115 +++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 src/sections/vulnerability-adjustments.rst diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst new file mode 100644 index 0000000..7492f04 --- /dev/null +++ b/src/sections/vulnerability-adjustments.rst @@ -0,0 +1,115 @@ +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`: + +```json +vulnerability_adjustments: { "replace_file": {} } +``` + +The user can provide the path to a CSV file with the updated vulnerability data: + +```json +"vulnerability_adjustments": {"replace_file" : "vulnerability_adjustments.csv"} +``` + +The CSV file should contain updated data for specific vulnerabilities. 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). + +| + +.. _vulnerability_adjustments: + +Adjusting the vulnerability file +************ + +---- + +### 2. Replacing Specific Vulnerability Data via JSON format in the `analysis_settings` + +This method allows users to replace data for specific vulnerabilities directly within the `analysis_settings` file. + +Example format: + +```json +vulnerability_adjustments: { "replace_data": {} } +``` + +You can specify the vulnerability data to be replaced for particular `vulnerability_id`s: + +```json +"vulnerability_adjustments": { + "replace_data": { + "1": [[1,1,0.01],[1,2,0.02],...], + "2": [[1,1,0.4],...] + } +} +``` + +This replaces the entire dataset for the specified vulnerabilities. The data format is as follows: +- `vulnerability_id` +- `intensity_bin_id` +- `damage_bin_id` +- `probability` + +| + +### 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: + +```json +vulnerability_adjustments: { "adjustments": {} } +``` + +The user can apply adjustment factors to the `vulnerability_id` as shown below: + +```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. + +---- From f931ad2077518444b8a08c62cca0ec70c8f0b298 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 15:02:03 +0100 Subject: [PATCH 2/8] fix code blocks --- src/index.rst | 1 + src/sections/vulnerability-adjustments.rst | 66 +++++++++++----------- 2 files changed, 34 insertions(+), 33 deletions(-) diff --git a/src/index.rst b/src/index.rst index 11394d1..3febfbf 100644 --- a/src/index.rst +++ b/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 diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index 7492f04..a994913 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -19,7 +19,7 @@ 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`. +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. @@ -37,17 +37,17 @@ Vulnerability Replacements This method allows the user to replace specific vulnerabilities by providing an external file containing replacement data. -Example format in `analysis_settings`: +Example format in ``analysis_settings``: + +.. code-block:: JSON + vulnerability_adjustments: { "replace_file": {} } -```json -vulnerability_adjustments: { "replace_file": {} } -``` The user can provide the path to a CSV file with the updated vulnerability data: -```json -"vulnerability_adjustments": {"replace_file" : "vulnerability_adjustments.csv"} -``` +.. code-block:: JSON + "vulnerability_adjustments": {"replace_file" : "vulnerability_adjustments.csv"} + The CSV file should contain updated data for specific vulnerabilities. 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). @@ -60,26 +60,26 @@ Adjusting the vulnerability file ---- -### 2. Replacing Specific Vulnerability Data via JSON format in the `analysis_settings` +### 2. Replacing Specific Vulnerability Data via JSON format in the ``analysis_settings`` -This method allows users to replace data for specific vulnerabilities directly within the `analysis_settings` file. +This method allows users to replace data for specific vulnerabilities directly within the ``analysis_settings`` file. Example format: -```json -vulnerability_adjustments: { "replace_data": {} } -``` +.. code-block:: JSON + vulnerability_adjustments: { "replace_data": {} } + -You can specify the vulnerability data to be replaced for particular `vulnerability_id`s: +You can specify the vulnerability data to be replaced for particular ``vulnerability_id``s: -```json -"vulnerability_adjustments": { - "replace_data": { - "1": [[1,1,0.01],[1,2,0.02],...], - "2": [[1,1,0.4],...] +.. 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 dataset for the specified vulnerabilities. The data format is as follows: - `vulnerability_id` @@ -95,21 +95,21 @@ This method allows users to apply a factor adjustment to specific vulnerabilitie Example format: -```json -vulnerability_adjustments: { "adjustments": {} } -``` +.. code-block:: JSON + vulnerability_adjustments: { "adjustments": {} } + -The user can apply adjustment factors to the `vulnerability_id` as shown below: +The user can apply adjustment factors to the ``vulnerability_id`` as shown below: -```json -"vulnerability_adjustments": { - "adjustments": { - "2": 0.5, - "8": 1.5 +.. 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. + +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. ---- From 846272a556dba7f3452d553db7fbd6780421bac7 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 15:08:42 +0100 Subject: [PATCH 3/8] fix block --- src/sections/vulnerability-adjustments.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index a994913..609382a 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -40,12 +40,14 @@ This method allows the user to replace specific vulnerabilities by providing an 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"} @@ -67,12 +69,14 @@ This method allows users to replace data for specific vulnerabilities directly w Example format: .. code-block:: JSON + vulnerability_adjustments: { "replace_data": {} } You can specify the vulnerability data to be replaced for particular ``vulnerability_id``s: .. code-block:: JSON + "vulnerability_adjustments": { "replace_data": { "1": [[1,1,0.01],[1,2,0.02],...], @@ -96,12 +100,14 @@ This method allows users to apply a factor adjustment to specific vulnerabilitie 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, From 7281180c741e9f745899b95fd7ec6d5b40bd1661 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 15:16:29 +0100 Subject: [PATCH 4/8] pipes --- src/sections/vulnerability-adjustments.rst | 44 +++++++++++++--------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index 609382a..333d8ae 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -5,8 +5,9 @@ On this page ------------ * :ref:`introduction_vulnerability` -* :ref:`vulnerability_replacements` -* :ref:`vulnerability_adjustments` +* :ref:`vulnerability_replacements_file` +* :ref:`vulnerability_adjustments_json` +* :ref:`vulnerability_adjustments_rng` | .. _introduction_vulnerability: @@ -26,7 +27,7 @@ These methods offer flexibility when customizing the model's vulnerability setti | -.. _vulnerability_replacements: +.. _vulnerability_replacements_file: Vulnerability Replacements ************ @@ -39,42 +40,43 @@ This method allows the user to replace specific vulnerabilities by providing an 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 specific vulnerabilities. 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). +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). | -.. _vulnerability_adjustments: - -Adjusting the vulnerability file -************ +.. _vulnerability_replacements_json: ---- -### 2. Replacing Specific Vulnerability Data via JSON format in the ``analysis_settings`` +### 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: -You can specify the vulnerability data to be replaced for particular ``vulnerability_id``s: - +| .. code-block:: JSON "vulnerability_adjustments": { @@ -83,9 +85,9 @@ You can specify the vulnerability data to be replaced for particular ``vulnerabi "2": [[1,1,0.4],...] } } +| - -This replaces the entire dataset for the specified vulnerabilities. The data format is as follows: +This replaces the entire data for the specified vulnerabilities. The format is as follows: - `vulnerability_id` - `intensity_bin_id` - `damage_bin_id` @@ -93,28 +95,34 @@ This replaces the entire dataset for the specified vulnerabilities. The data for | +.. _vulnerability_replacements_json: + +---- + ### 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. From bc45113ff756f237257ca4ac614f448ef3e68c95 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 15:17:48 +0100 Subject: [PATCH 5/8] typo --- src/sections/vulnerability-adjustments.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index 333d8ae..26d545b 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -43,7 +43,7 @@ Example format in ``analysis_settings``: | .. code-block:: JSON - vulnerability_adjustments: { "replace_file": {} } + "vulnerability_adjustments": { "replace_file": {} } | The user can provide the path to a CSV file with the updated vulnerability data: @@ -71,7 +71,7 @@ Example format: | .. code-block:: JSON - vulnerability_adjustments: { "replace_data": {} } + "vulnerability_adjustments": { "replace_data": {} } | The data can be replaced for specific ``vulnerability_id``s: @@ -108,7 +108,7 @@ Example format: | .. code-block:: JSON - vulnerability_adjustments: { "adjustments": {} } + "vulnerability_adjustments": { "adjustments": {} } | The user can apply adjustment factors to the ``vulnerability_id`` as shown below: From e5de4c496344f5e08d641524a4f9811ff7525e57 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 15:22:29 +0100 Subject: [PATCH 6/8] links --- src/sections/vulnerability-adjustments.rst | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index 26d545b..39690f6 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -5,9 +5,8 @@ On this page ------------ * :ref:`introduction_vulnerability` -* :ref:`vulnerability_replacements_file` -* :ref:`vulnerability_adjustments_json` -* :ref:`vulnerability_adjustments_rng` +* :ref:`vulnerability_replacements` +* :ref:`vulnerability_adjustments` | .. _introduction_vulnerability: @@ -27,7 +26,7 @@ These methods offer flexibility when customizing the model's vulnerability setti | -.. _vulnerability_replacements_file: +.. _vulnerability_replacements: Vulnerability Replacements ************ @@ -56,11 +55,6 @@ The user can provide the path to a CSV file with the updated vulnerability data: 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). -| - -.. _vulnerability_replacements_json: - ----- ### 2. Replacing Specific Vulnerability Data in JSON format in the ``analysis_settings`` @@ -97,6 +91,9 @@ This replaces the entire data for the specified vulnerabilities. The format is a .. _vulnerability_replacements_json: +Vulnerability Adjustments +************ + ---- ### 3. Applying Adjustments Using Factors From 1ee9a06d6c2cb6077629c3cbc0ac3d4887c0aee6 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 15:30:25 +0100 Subject: [PATCH 7/8] links2 --- src/sections/vulnerability-adjustments.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index 39690f6..9ea63a6 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -33,7 +33,7 @@ Vulnerability Replacements ---- -### 1. Replacing Vulnerabilities via path to a File +* 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. @@ -56,7 +56,7 @@ The user can provide the path to a CSV file with the updated vulnerability data: 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`` +* 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. @@ -87,16 +87,16 @@ This replaces the entire data for the specified vulnerabilities. The format is a - `damage_bin_id` - `probability` -| -.. _vulnerability_replacements_json: + +.. _vulnerability_adjustments: Vulnerability Adjustments ************ ---- -### 3. Applying Adjustments Using Factors +* 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. From beb7357b13995204c74b0d0782507767610b3c69 Mon Sep 17 00:00:00 2001 From: ncerutti Date: Mon, 30 Sep 2024 16:16:40 +0100 Subject: [PATCH 8/8] spacing --- src/sections/vulnerability-adjustments.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/sections/vulnerability-adjustments.rst b/src/sections/vulnerability-adjustments.rst index 9ea63a6..28a1933 100644 --- a/src/sections/vulnerability-adjustments.rst +++ b/src/sections/vulnerability-adjustments.rst @@ -56,6 +56,9 @@ The user can provide the path to a CSV file with the updated vulnerability data: 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.