.. index:: Multi Year, Financial Structures; Multi Year Multi Year ========== .. contents:: Table of Contents :depth: 3 :local: :backlinks: none Description ----------- Graphene provides a built-in template for modelling multi-year or mid-year inception contracts. The Multi Year template allows users to model contracts whose inception and expiry span periods that are larger than the periods of their subject losses by automatically repeating occurrences to cover the extended period. A couple of common scenarios are supported by this layer: - Applying single year trials to contracts that span the length of multiple years, by repeating the occurrences of each trial to encompass the dates from inception until the expiration date. - Applying single year trials to contracts that incept mid-year and expire in the second year, by repeating the occurrences of the trial when wrapping into the second year. This ensures seasonality of events is maintained. Additionally, there are some features that make this template applicable to a wide variety of use cases: - The ability to be used with any underlying :ref:`schema ` that contains the ``inception_date`` and ``expiration_date`` parameters. - A configurable trial length that allows for differences in accounting methods for the ``Time`` value. - A configurable trial begin setting, to adapt for differences in accounting methods for the ``Time`` value. Structure --------- This is an example of a contract using the built-in Multi Year template. .. code-block:: json { "_schema": "MultiYear_1.0", "layer_schema": "QuotaShare_1.0", "inception_date": 120, "expiration_date": 485, "trial_length": 365, "premium_value": 100000, "brokerage": 0.1, "limit_value": 1000000, "share": 0.5 } .. note:: Any parameters that follow the ``trial_length`` parameter in this example are inherited from the referenced layer template. In this case, the :doc:`quotashare` template. Parameters ---------- The parameters are defined as follows: +--------------------------+----------+------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Parameter Name | Required | Type | Default | Description | +==========================+==========+============+=========+==============================================================================================================================================================================================================================================================================================================================================+ | ``layer_schema`` | Yes | ``string`` | | The name of the underlying wrapped layer. **Note:** *The template assumes and forwards any parameters of this schema, including its required parameters.* | +--------------------------+----------+------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``inception_date`` | No | ``double`` | ``0`` | Time value on which the contract incepts. This is used to calculate the number of trial repetitions necessary for the coverage period. See :ref:`timestamps` for more details on time. | +--------------------------+----------+------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``expiration_date`` | No | ``double`` | ``365`` | Time value on which the contract expires. This is used to calculate the number of trial repetitions necessary for the coverage period. See :ref:`timestamps` for more details on time. | +--------------------------+----------+------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``trial_length`` | No | ``double`` | ``365`` | The length of time that trials span, in the same units as other time values. This will determine how many times the trial is repeated to cover the ``inception_date`` through to the ``expiration_date``, and how much each time value should be offset to cover an additional trial period. See :ref:`timestamps` for more details on time. | +--------------------------+----------+------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ``trial_begin`` | No | ``double`` | ``0`` | Time value at which the trial begins in accordance with the time units are being used. For example, if using POSIX timestamps, ``1577836800`` would indicate that the trials begin on January 1st, 2020. See :ref:`timestamps` for more details on time. | +--------------------------+----------+------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. note:: In addition to the above parameters, this template forwards parameters to the template referenced by ``layer_schema``. Implementation details ---------------------- The Multi Year template allows multi-year, or mid-year inception contracts by looping a trial repeatedly. For example, imagine a contract begins on day 120 of a trial and expires on day 485 (i.e. one year later). If the simulation available only contains trials that span from day 0 to day 365, the Multi Year template can be used to wrap that contract to retain seasonality. The template will loop the trial into multiple "years" by repeating all the occurrences with an additional value of 365 added to their ``Time`` value. The Multi Year template will decide how many times the trial needs to be repeated by looking at the ``inception_date``, ``expiration_date``, ``trial_length``, and ``trial_begin`` parameters. Limitations ----------- The Multi Year template acts only on the input parameters and does not assess or validate the inputs specified versus the time values present in the ledger input. It is the user's responsibility to ensure consistency between both. The Multi Year template provides a maximum of 100 trial repetitions. If the inputs are specified such that the ledger data needs to be repeated a large number of times, this will result in the system doing no operation where this template is used. As an example: .. code-block:: json { "_schema": "MultiYear_1.0", "layer_schema": "QuotaShare_1.0", "inception_date": 0, "expiration_date": 365, "premium_value": 100000, "brokerage": 0.1, "limit_value": 1000000, "share": 0.5, "trial_length": 1 } In this case, the node will end up behaving equivalently to ``{}``, because the ledger input would have been repeated over 100 times, thanks to a ``trial_length`` of ``1`` and total time span of ``365``. Output Records -------------- The Multi Year financial structure does not output any additional output record types on its own. The output records will depend on the template referenced by ``layer_schema``. Advanced Usage ---------------------- Leap Years ^^^^^^^^^^^^^^^^^^^^^^^ No native support for handling leap years is provided by the Multi Year template. However, a common way to support modelling of leap years is to assume all years are 365.25 days in length. If your input trials are modelled this way, and you need support for modeling multiple years or mid-year inception contracts, specify the ``trial_length`` parameter so that it agrees with the modelled events. For example: .. code-block:: json { "_schema": "MultiYear_1.0", "layer_schema": "QuotaShare_1.0", "inception_date": 120.0, "expiration_date": 485.25, "trial_length": 365.25, "premium_value": 100000, "brokerage": 0.1, "limit_value": 1000000, "share": 0.5, } Using this scheme, ``Time=365.25`` corresponds to 01 January, 00:00:00 on the second year of the simulated events. This will affect exported ledger data, and needs to be considered when specifying the inception and expiry dates, especially for any downstream structures. Since the Multi Year template provides only basic convenience for dealing with contracts that have varying inception and expiry dates, it is not immune to error; no validation is performed. When using input data that models leap years with 0.25 extra days, overlapping events may result. If the ``trial_length`` parameter remains set to the default of 365 days, the resulting output will have extra loss on the first day of the second simulated year. The first and second years will overlap each other by 0.25 days (or 6 hours). :: +------------------------------------------+ | Year 1 modelled input (365.25 days) | | +------------------------------------------+ +-------------------------------------------+ | | Year 2 modelled input (repeated Year 1) | +-------------------------------------------+ ^ ^ Overlap Year 2, January 01 | | 00:00:00 - 06:00:00 (365.0 - 365.25) .. note:: To avoid unintentional repetition or overlap of events, ensure the ``trial_length`` matches the range of potential time values that are present in the modelled output. Variable Length Years ^^^^^^^^^^^^^^^^^^^^^^^ No support is provided for extending a fixed-year-length data set to a different length on a per-year basis. If the input data contains modelled events for years with different time spans, this template may still be used, although there may be no convenience gained. The transformation applied will not be able to selectively extend some years to a wider time range without also potentially causing unintended repetition of events. .. note:: If the input data contains events for multiple years of varying length, the Multi Year template may not be suitable. Custom Time Offsets ^^^^^^^^^^^^^^^^^^^^^^^ The ``trial_length`` and ``trial_begin`` parameters are useful when your time values are not consistent with the defaults assumed by this template (``365`` and ``0``, respectively). For example, if you are using POSIX timestamps, and your ledger data begins at timestamp ``1577836800`` (January 1st, 2020), covering a one-year time span: .. code-block:: json { "_schema": "MultiYear_1.0", "layer_schema": "QuotaShare_1.0", "inception_date": 1577836800, "expiration_date": 1640995200, "trial_length": 31622400, "trial_begin": 1577836800, "premium_value": 100000, "brokerage": 0.1, "limit_value": 1000000, "share": 0.5 } The contract modelled here covers two years (``expiration_date`` is equivalent to January 01, 2022). The ``trial_length`` in this case is equal to the number of seconds in ``366`` days, because 2020 is a leap year, and that is the year for which the modelled losses are available. Handling trials with inconsistent year lengths is not the intended use of the Multi Year template, but this helps illustrate how the repetition will function in unusual cases. :: +------------------------------------+ | Year 1 modelled input (366 days) | unused extra day | | +------------------------------------+ v v +------------------------------------------+-+ | Year 2 (covered by 366 days from Year 1) | | +------------------------------------------+-+ ^ ^ January 01, 2021 | | January 01, 2022 contract expiration | Using the Multi Year template to repeat a leap year may not be ideal, due to the arbitrary exclusion of the 366th day of modelled losses. Model output that matches the year(s) being modelled should be used when possible. .. note:: Use the ``trial_length`` and ``trial_begin`` parameters when your trials cover a time range other than ``[0, 365)``.