Added correlation features for 2.3

src/sections/correlation.rst

@@ -10,6 +10,7 @@ On this page
 * :ref:`available_1.15_correlation`
 * :ref:`available_1.27_correlation`
 * :ref:`available_1.28_correlation`
+* :ref:`available_2.3_correlation`
 
 |
 .. _intro_correlation:
@@ -536,11 +537,112 @@ With these settings, damage and hazard groups are the same, representing each ex
 
 OasisLMF 1.28 supports disaggregation of exposure locations when the **NumberOfBuildings** value is greater than 1. This means that one exposure location is split into multiple locations for the purposes of ground up loss sampling and financial module calculations.
 
-The **IsAggregate** field is used to determine how damage group_ids are assigned if there are no damage group settings specified.
+The default behaviour is that disaggregated risks will be fully correlated if not otherwise specified in model settings, ie correlation groups are defined as each original location.
 
-* When IsAggregate = 1, meaning the exposure location represents aggregate risks, different damage group_ids are assigned to disaggregated risks of the exposure location.
-* When IsAggregate = 0, meaning the exposure location represents a multi-building single site, the same damage group_id is assigned to dissaggregated risks of the exposure location.
+|
+
+.. _available_2.3_correlation:
+
+Available in OasisLMF 2.3
+##########################
+
+----
+
+**Correlation groups for disaggregated risks**
+
+OasisLMF 2.3 adds support for additional internal fields, **building_id** and **risk_id**, to be used in data_settings to control how disaggregated risks are correlated.
+
+The default behaviour is that disaggregated risks will be fully correlated if not otherwise specified in model settings, ie correlation groups are defined as each original location.
+
+|
+
+**Default correlation group settings**
+
+``Model_settings.json``
+
+.. code-block:: JSON
+
+    {
+        "data_settings": {
+        "damage_group_fields": ["PortNumber", "AccNumber", "LocNumber"],
+        "hazard_group_fields": ["PortNumber", "AccNumber", "LocNumber"]
+        },
+
+The fields building_id or risk_id, in addition to 'PortNumber, AccNumber, LocNumber' may be used to make disaggregated risks uncorrelated for either damage, or hazard, or both.
+
+* building_id is a index counter of disaggregated risks for each original location, regardless if the original location represents aggregate data (IsAggregate=1) or a multi-building single location (IsAggregate=0).  Adding building_id to data settings will result in uncorrelated disaggregated risks in both cases.
+
+* risk_id takes the same value as building_id for aggregate risks (IsAggregate=1) but is different for multi-building single locations (IsAggregate=0) where it takes the value of 1. Adding risk_id to data settings will result in uncorrelated disaggregated risks for the IsAggregate=1 case, but fully correlated disaggregated risks for the IsAggregate=0 case.
+
+Some usage examples in model_settings are given below;
+
+|
+
+**Example 1**
+
+Uncorrelated damage for disaggregated risks in all cases:
+
+``Model_settings.json``
+
+.. code-block:: JSON
+
+    {
+        "data_settings": {
+        "damage_group_fields": ["PortNumber", "AccNumber", "LocNumber","building_id"]
+        },
+
+|
+
+**Example 2**
+
+Uncorrelated damage for aggregate risks, fully correlated damage for multi-building single locations:
+
+``Model_settings.json``
+
+.. code-block:: JSON
+
+    {
+        "data_settings": {
+        "damage_group_fields": ["PortNumber", "AccNumber", "LocNumber","risk_id"]
+        },
+
+|
+
+**Example 3**
+
+Correlation in hazard intensity is not applicable for many models and in these cases does not need to be specified. When it is modelled, however, it may be specified differently to damage. 
+
+Uncorrelated hazard in all cases, fully correlated damage for multi-building single locations:
+
+``Model_settings.json``
+
+.. code-block:: JSON
 
-Hazard groups are not required to be assigned in general, therefore these should be controlled by the data settings in the model settings json if required. 
+    {
+        "data_settings": {
+        "damage_group_fields": ["PortNumber", "AccNumber", "LocNumber","risk_id"],
+        "hazard_group_fields": ["PortNumber", "AccNumber", "LocNumber","building_id"]
+        },
+
+|
+
+**Example 4**
+
+If correlation factors are also specified in correlation_settings, then partial correlation is applied to the uncorrelated disaggregated risks in the same way as it does between locations.
+
+20% partially correlated damage for disaggregated risks in all cases:
+
+``Model_settings.json``
+
+.. code-block:: JSON
+
+    {
+        "data_settings": {
+        "damage_group_fields": ["PortNumber", "AccNumber", "LocNumber","building_id"]
+        },
+
+        "correlation_settings": [
+              {"peril_correlation_group":  1, "damage_correlation_value": 0.2, "hazard_correlation_value": 0}
+            ]
 
 For more information about disaggregation functionality, please see :doc:`Disaggregation <disaggregation>`.