.. index:: AggXL, Financial Structures; AggXL, Aggregate Excess Of Loss

Aggregate Excess of Loss (AggXL)
==================================

Graphene provides a default built-in template for modelling conventional
Aggregate Excess Of Loss (AggXL) contracts. The default template for
AggXL supports the following financial features:

- occurrence attachment and limit
- aggregate attachment and limit
- franchise deductible
- upfront premium income and brokerage expense
- contract inception / expiration dates
- participation
- currency exchange

.. note:: Even though the financial terms are specified as positive values, losses are assumed to be negative in
   Graphene, so they will be applied as if they are negative.  Flowing only positive loss values into the structure
   will result in zero loss output.

Structure
---------

The general structure of a default AggXL using the built-in template in
Graphene is:

.. code-block:: json

    {
        "_schema": "AggXL_1.0",
        "inception_date": 1546300800,
        "expiration_date": 1577836800,
        "occurrence_attachment_value": 10000,
        "occurrence_limit_value": 30000,
        "aggregate_attachment_value": 20000,
        "aggregate_limit_value": 50000,
        "franchise_deductible_value": 15000,
        "premium_value": 3000,
        "brokerage": 0.1,
        "share": 0.2,
        "currency": "GBP"
    }

Parameters
----------

The parameters are defined as follows:

+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter Name                  | Required | Type       | Description                                                                                                                                                                                                                                                                                                   |
+=================================+==========+============+===============================================================================================================================================================================================================================================================================================================+
| ``inception_date``              | Yes      | ``double`` | Timestamp on which the contract incepts. The coverage period is **inclusive** of this time.                                                                                                                                                                                                                   |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``expiration_date``             | Yes      | ``double`` | Timestamp on which the contract expires. The coverage period is **exclusive** of this time.                                                                                                                                                                                                                   |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``occurrence_attachment_value`` | Yes      | ``double`` | The occurrence attachment or retention of the contract in currency units.                                                                                                                                                                                                                                     |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``occurrence_limit_value``      | Yes      | ``double`` | The occurrence limit of the contract in currency units.                                                                                                                                                                                                                                                       |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``aggregate_attachment_value``  | Yes      | ``double`` | The aggregate attachment or retention of the contract in currency units.                                                                                                                                                                                                                                      |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``aggregate_limit_value``       | Yes      | ``double`` | The aggregate limit of the contract in currency units.                                                                                                                                                                                                                                                        |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``franchise_deductible_value``  | No       | ``double`` | The occurrence franchise deductible of the contract in currency units.                                                                                                                                                                                                                                        |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``premium_value``               | Yes      | ``double`` | The amount of premium paid upfront in currency units. Premium is paid at time of inception.                                                                                                                                                                                                                   |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``brokerage``                   | Yes      | ``double`` | The percentage of brokerage paid on the upfront premium. Brokerage is paid at time of inception.                                                                                                                                                                                                              |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``share``                       | Yes      | ``double`` | The share or participation assumed for this contract.                                                                                                                                                                                                                                                         |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``currency``                    | No       | ``string`` | The currency in which the input currency values (``occurrence_attachment_value``, ``occurrence_limit_value``, ``aggregate_attachment_value``, ``aggregate_limit_value``, ``franchise_deductible_value``, and ``premium_value``) are defined. Defaults to the :ref:`base currency <base-currency>` if not set. |
+---------------------------------+----------+------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Output Records
--------------

The AggXL financial structure can produce 3 different types of records:

- ``Loss``: Layered losses, that is losses that are covered by the contract.
  Losses generally have a negative value.
- ``Premium``: Upfront premium paid at
  the time of inception. Premium is accounted for as a positive credit.
- ``BrokerageFee``: Upfront premium brokerage paid at the time of inception.
  Brokerage is accounted as an expense debit with a negative value.

References
----------

A detailed description of the financial modelling internals of the AggXL
structure can be found in :doc:`aggxl_step_by_step`.