Scenario documentation

ifrs17-template/Report/Reports.ipynb

@@ -84,7 +84,9 @@
                 "\nThe granularity of the reported figures can be modified by changing the Column Slices options.",
                 "\nFor example one can add <code>\"GroupOfContract\"</code> to separate the contributions of the individual Group of Contracts.",
                 "\n",
-                "\nAggregated values are displayed when the data has a finer granularity than the one selected by the report slice options."
+                "\nAggregated values are displayed when the data has a finer granularity than the one selected by the report slice options.",
+                "\n",
+                "\nThe Best Estimate scenario is selected by default. You can select other scenarios through the Scenario field. Possible options includes 'All' and 'Delta'. Select ColumnSlice Scenario if you chose one of these. "
             ],
             "metadata": {},
             "execution_count": 0,
@@ -97,7 +99,8 @@
                 "\npv.ReportingNode = \"CH\";",
                 "\npv.ReportingPeriod = (2021, 3);",
                 "\npv.CurrencyType = CurrencyType.Contractual;",
-                "\npv.ColumnSlices = new string[]{};//\"GroupOfContract\", \"AmountType\"",
+                "\npv.ColumnSlices = new string[]{\"Scenario\"};//\"GroupOfContract\", \"AmountType\", \"Scenario\"",
+                "\npv.Scenario = null; //\"All\";",
                 "\npv.DataFilter = null; //new [] {(\"GroupOfContract\", \"DT1.2\"),(\"LiabilityType\", \"LIC\") };",
                 "\n(await pv.ToReportAsync)"
             ],

ifrs17/DataModel/DataStructure.ipynb

@@ -599,7 +599,9 @@
             "source": [
                 "<a id='scenario'></a>",
                 "\n## Scenario",
-                "\nThe <code>Scenario</code> record holds the various scenarios for which calculations should also be performed."
+                "\nThe <code>Scenario</code> record holds the various Scenarios used for Sensitivity analysis. ",
+                "\n",
+                "\nAny Scenario-case can be defined with this record by providing a SystemName and a DisplayName. During data collection phase the Scenario column of the [main](../Import/Importers#parse-the-main-tab) table of the input can be populated with the SystemName of the desired Scenario. The default Scenario (i.e. the default one, with no-stress situations applied) is referred to as 'Best Estimate' and its identifier is a null string, allowing the input files to not specify any value under the column Scenario or to lack the column itself."
             ],
             "metadata": {},
             "execution_count": 0,
@@ -617,7 +619,24 @@
         {
             "cell_type": "markdown",
             "source": [
-                "The default Scenario (i.e. the default one, with no-stress situations applied) is referred to as 'Best Estimate' and its identifier is a null string, allowing the input files to not specify any value."
+                "### Scenario and inputs",
+                "\n",
+                "\nUnder a particular Scenario, several data types can be imported (e.g. nominal cash flows, parameters, yield-curvers, etc.). However, we suggest arranging a different Scenario for every desired type of stress to facilitate the analysis of the results.",
+                "\n",
+                "\n### Dependecy with Best Estimate scenario: same period",
+                "\n",
+                "\nWhen a file is imported for a specific Scenario, the calculation engine integrates the set of inputs taking the remaining from the best estimate scenario. In this way the user is not required to input again all data for each Scenario calculation but only the file with the stressed input. This is achieved through our system of [Relaxed Queries](../Utils/Queries). The assumption here is that the Best Estimate scenario is the first to be imported, and the stressed scenarios follow. ",
+                "\n",
+                "\nIn the case of re-import, the Engine considers the dependency between each scenario and the Best Estimate scenario. In this case, one import automatically triggers calculation in several partitions allowing all dependant cases to be updated. For more details on how the calculation is performed refer to [Calculate IFRS Variables: for all scenarios](../Import/Importers#calculate-ifrs-variables-for-all-scenarios).",
+                "\n",
+                "\nThe only exception to this is applied to time dependency. When the user imports figures for periods $P$ and $P+1$ are imported for all scenarios and a new input for Best Estimate period $P$ is provided, only the scenarios for period $P$ are automatically updated. A manual update of period $P+1$ is then required to update the figures of $P+1$. We consider the case of restating previous periods particularly sensitive and defer to the user the resposability to ensure that all results are up to date. ",
+                "\n",
+                "\n### Dependecy with Best Estimate scenario: across periods",
+                "\n",
+                "\nWhen a stress scenario is imported for a period $P$ and a previous period $P-1$ is available, the End of Period values ($P-1$) of the Best Estimate scenario is considered as Beginning of Period ($P$) for the stressed and no-stress scenarios. This implies that:",
+                "\n1. scenarios can be occasionally not be calculated without impacting their calculation in future periods,",
+                "\n2. new scenarios can be added at any time in a production environment,",
+                "\n3. in each period the scenario depends only on the perturbation provided in the period and is not applied on top of the previous period perturbation."
             ],
             "metadata": {},
             "execution_count": 0,
@@ -1728,7 +1747,7 @@
                 "\n    [Dimension(typeof(EstimateType))]",
                 "\n    [IdentityProperty]",
                 "\n    public string EstimateType { get; init; }",
-                "\n        ",
+                "\n    ",
                 "\n    [NotVisible]    ",
                 "\n    [Dimension(typeof(AmountType))]",
                 "\n    [IdentityProperty]",

ifrs17/Import/ImportStorage.ipynb

@@ -37,6 +37,11 @@
                 "\n- [EstimateType](../DataModel/DataStructure)",
                 "\n- [DataNodes](../DataModel/DataStructure)",
                 "\n",
+                "\nThe data required for the calculations is retrieved by queries of [parameters](../Utils/Queries#current-and-previous-parameters) and [transactional data](../Utils/Queries#data-variables) and stored in the storage to be available for the Import Scopes.",
+                "\nThe calculation of a Best Estimate scenario is perfomerd using parameters from the data partition with Scenario Best Estimate (for both current and previous period values). For every scenario $S$ every query to parameters prioritize the data belonging to the partition with Scenario $S$ for the current period, if not present the value belonging to the Best Estimate scenario is used. Previous period parameter is always retrieved from the Best Estimate scenario. ",
+                "\n",
+                "\nFor Scenario calculations, the transactional data (RawVariable and IfrsVariable) stored in the ImportStorage is the union of the variables provided for the Scenario and the variables provided for the Best Estimate. In case of intersection betweeen the two sets, priority is given to the values belonging to the scenario. This allows users to input only the variables for scenario that differ from the Best Estimate scenario. For example, if a scenario affects only the Risk Adjustment variables, the nominal cashflow input might contain only the Risk Adjustment. If other variables are provided they are equally considered, stored in the data source and used in calculation. Note that if a scenario requires a variable provided under the Best Estimate scenario to have 0 value, then it must be input in the scenario file with 0 value. Omitting this variable from the input results in the calculation engine picking up the value provided in the Best Estimate scenario. This applies to nominal cash flow, actuals, and opening. ",
+                "\n",
                 "\nSuch storage is then passed to calculations defined in the corresponding Import Scopes:",
                 "\n",
                 "\n- [1ImportScope-Identities](./1ImportScope-Identities)",

ifrs17/Import/Importers.ipynb

@@ -325,9 +325,18 @@
             "source": [
                 "## Parse the Main Tab",
                 "\n",
-                "\nThe main table of our custom import formats contains the information which are required to identify the data partition depending on the ImportFormat. These information are temporarily stored in [Args](../DataModel/DataStructure#args) and used in the next methods.",
+                "\nThe main table of our custom import formats contains the information which are required to identify the data partition depending on the ImportFormat.",
+                "\nThe columns contained in the main table for the different ImportFormats are:",
+                "\n1. Yield Curve : Year, Month, Scenario;",
+                "\n2. Data Node : ReportingNode;",
+                "\n3. Nominal Cashflow, Actual, Opening, Simple Value, Data Node State, Data Node Parameter : ReportingNode, Year, Month, Scenario.",
                 "\n",
-                "\n<code>GetArgsFromMain</code> performes basic valiadations on the existance of the main tab. Then reads the reporting node, year, month, and scenario and return an ImportArgs with the results. If any of these information a default value is returned and will be validated in the following methods. "
+                "\nNote that the Scenario column is not available for Data Node. Data Node can be created regardless of the Scenario and controlling whether they are active or not in a particular scenario can be achieved through the import of Data Node State (which allows the specification of a Scenario).",
+                "\nIn addition, the Scenario column (for the ImportFormats that expect it) is not required, as its value can be left empty in the case of Best Estimate scenario (in this case the entire column can be missing). ",
+                "\n",
+                "\nAfter having parsed the main table, these information are temporarily stored in [Args](../DataModel/DataStructure#args) and used in the next methods.",
+                "\n",
+                "\n<code>GetArgsFromMain</code> performes basic validations on the existance of the main tab. Then reads the reporting node, year, month, and scenario and returns an ImportArgs with the results. If any of these information is missing a default value is returned and will be validated in the following methods. "
             ],
             "metadata": {},
             "execution_count": 0,
@@ -507,13 +516,31 @@
         {
             "cell_type": "markdown",
             "source": [
-                "## Calculate IFRS Variables",
+                "## Calculate IFRS Variables: for all scenarios",
+                "\n",
+                "\nThe following methods are used in all importers that compute [IfrsVariables](../DataModel/DataStructure#ifrs-variable):",
+                "\n- Yield Curve,",
+                "\n- Data Node State,",
+                "\n- Data Node Parameter,",
+                "\n- Nominal Cashflow,",
+                "\n- Actual,",
+                "\n- Opening.",
+                "\n<br><br>",
+                "\n",
+                "\n<code>GetAllArgsAsync</code> retrieves the partitions or Args that require computation. This method is relevant to the re-calculation of Scenarios as it keeps track of the dependencies between Best Estimate scenario and stressed scenarios. The partition to be recomputed are defined as the union of the so called **primary args** which is read from the main table of the imported file, with the **secondary args** corresponding to all scenarios which depend on the imported data.",
                 "\n",
-                "\nThe following methods are used in the different importers to compute the [IfrsVariables](../DataModel/DataStructure#ifrs-variable).",
+                "\nIn the case of Yield Curve the **secondary args** correspond to the partition relative to all Reporting Nodes that use one of the currencies present in the imported file. Only the partitions relative to the specified scenario is recomputed when the input is for a specific scenario. Instead, all existing scenarios expect for those with a perturbed Yield Curve data explictly provided as input are recomputed if the input is for Best Estimate scenario. Year, and Month of the recomputed partitions match the value input in the main table of the imported file. ",
                 "\n",
-                "\n<code>GetAllArgsAsync</code> retrieves the partitions or Args that require computation. They are the union of the primary args (the one read from the main tab of the imported file) with the secondary args (scenarios which depends on the best estimate data).",
+                "\nIn the case of Data Node Parameters and State only the **secondary args** correspond to the partition for the specified scenario if the input is for a specific scenario. When input for Best Estimate scenario is imported all scenarios that do not have perturbed DataNodeParameter or DataNodeState values are recomputed.   ",
+                "\nReportingvNode, Year, and Month of the recomputed partitions correspond to the value input int the file.",
                 "\n",
-                "\n<code>ComputeAsync</code> computes the IfrsVariables for a given partition (identified by its ImportArgs) and stores the results in a disposable workspace. This then serves as DataSource in the calculation of the secondary partitions (identified by the secondary args)."
+                "\nFor all other import formats the **secondary args** correspond to the partition for the specified scenario if the input is for a specific scenario and to all scenarios if the input is for Best Estimate scenario. ",
+                "\nReporting Node, Year, and Month of the recomputed partitions correspond to the value input int the file. ",
+                "\n<br><br>",
+                "\n",
+                "\n<code>ComputeAsync</code> triggers computations of the Ifrs Variables for a given partition (identified by its ImportArgs) and stores the results in a disposable workspace. This then serves as DataSource in the calculation of the secondary partitions (identified by the secondary args). The calculations is performed through ImportScopes (one example is [present value](2ImportScope-PresentValue)) with the use of the [ImportStorage](ImportStorage). ",
+                "\n",
+                "\nIn the case of Scenario calculation the [ImportStorage](ImportStorage) combines the inputs with all information present in the data source for that scenario. In case some information has not been provided for the specified scenario a default fall-back logic retrieves the missing information from the Best Estimate scenario by applying relaxed queries for both [parameters](../Utils/Queries#current-and-previous-parameters) and [transactional data](../Utils/Queries#relaxedqueries). "
             ],
             "metadata": {},
             "execution_count": 0,
@@ -892,12 +919,11 @@
                 "\n            await options.TargetDataSource.Partition.SetAsync<PartitionByReportingNodeAndPeriod>(null);",
                 "\n            if(!(await options.TargetDataSource.Query<RawVariable>().Where(x => x.Partition == targetPartition).Take(1).ToArrayAsync()).Any()) continue;",
                 "\n        }",
-                "\n        ",
-                "\n        // Remove data nodes which are unaffected by the updated yield curves\",",
-                "\n        // TODO : Reintroduce this functionality. Note all UpdateAsync/DeleteAsync performed to the workspaceToCompute are then trasferred to the DataSource.\",",
-                "\n        //        This is way this functionality should be written in a different way. \",",
-                "\n        // await workspaceToCompute.DeleteAsync( await workspaceToCompute.Query<RawVariable>()\",",
-                "\n        //     .Where(x => !(dataNodesToUpdate.Contains(x.DataNode) && (x.Partition == targetPartition || x.Partition == defaultPartition))).ToArrayAsync() );\",",
+                "\n        // Remove data nodes which are unaffected by the updated yield curves",
+                "\n        // TODO : Reintroduce this functionality. Note all UpdateAsync/DeleteAsync performed to the workspaceToCompute are then trasferred to the DataSource.",
+                "\n        //        This is way this functionality should be written in a different way. ",
+                "\n        // await workspaceToCompute.DeleteAsync( await workspaceToCompute.Query<RawVariable>()",
+                "\n        //     .Where(x => !(dataNodesToUpdate.Contains(x.DataNode) && (x.Partition == targetPartition || x.Partition == defaultPartition))).ToArrayAsync() );",
                 "\n",
                 "\n        log = log.Merge(await ComputeAsync(args, workspace, workspaceToCompute, false));",
                 "\n        if(log.Errors.Any()) return Activity.Finish().Merge(log);",
@@ -1526,7 +1552,7 @@
                 "# Simple Value",
                 "\n",
                 "\nSimple Value format imports [IfrsVariables](../DataModel/DataStructure#ifrs-variable) computed by an independent tool.",
-                "\nIn this case our IFRS 17 calculation is not applied and variables are stored in the Database for being consumed in reports with our powerful reporting tooling."
+                "\nIn this case our IFRS 17 calculation is not applied and variables are stored in the Database for being consumed in reports with our powerful reporting tooling. Because there is no computation for this import format, values for scenarios must be imported using the Simple Value format specifing the Scenario in the main table. Analogously to the other import formats, only the variables that change values with respect to the Best Estimate scenario should be input. Note that a variable with a value different form zero in the Best Estimate scenario should be input with value zero for the scenario if it should not be shown in the report."
             ],
             "metadata": {},
             "execution_count": 0,
@@ -1671,15 +1697,6 @@
             "metadata": {},
             "execution_count": 0,
             "outputs": []
-        },
-        {
-            "cell_type": "code",
-            "source": [
-                ""
-            ],
-            "metadata": {},
-            "execution_count": 0,
-            "outputs": []
         }
     ]
 }