.. index:: Core Operations; Trigger
.. _core-operation-trigger:

Trigger
==================================
Emits subject loss records based on control losses that satisfies a trigger condition.
This can be used to implement a variety of different triggers such as:

- Industry Loss Triggers
- Company Loss Triggers
- Exclusive Triggers (Step Layers)
- Aggregate Triggers


Structure
---------

.. code-block:: json

    {
        "_schema": "Trigger_1.0",
        "threshold": 100.0,
        "op": "LESS_THAN",
        "control_record_type": "Control",
        "accumulation_class_columns": ["Trial"]
        "accumulation_prefix_class_columns": ["Trial", "Time", "Occurrencekey"]
        "exclusive": false,
        "currency": "GBP"
    }

Parameters
----------

+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Parameter Name                        | Required | Type                  | Description                                                                                                                                                                     |
+=======================================+==========+=======================+=================================================================================================================================================================================+
| ``threshold``                         | Yes      | ``double``            | The trigger ``threshold``. Cannot be negative.                                                                                                                                  |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``op``                                | Yes      | ``Trigger.Operation`` | Operator to be used in comparing threshold. Allowed values are ``LESS_THAN``, ``LESS_THAN_EQUAL``, ``GREATER_THAN`` and ``GREATER_THAN_EQUAL``.                                 |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``control_record_type``               | Yes      | ``string``            | The record type string used to identify the control loss records.                                                                                                               |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``accumulation_class_columns``        | No       | ``string list``       | List of column names. Defines the accumulation equivalance class. This will always include the ``Trial`` column.  Supported columns: ``Trial``, ``OccurrenceKey``, ``Time``.    |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``accumulation_prefix_class_columns`` | No       | ``string list``       | List of column names. Defines the accumulation prefix class. This will always include the ``Trial`` column. Supported columns: ``Trial``, ``OccurrenceKey``, ``Time``.          |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``exclusive``                         | No       | ``bool``              | Specifies if the current prefix increment should be excluded from the threshold.                                                                                                |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``currency``                          | No       | ``string``            | The currency in which the ``threshold`` is defined.                                                                                                                             |
+---------------------------------------+----------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Behaviour
----------

Control losses are accumulated within accumulation equivalance classes, which are
defned by the column values specified by ``accumulation_class_columns``. Records
sharing identical values specified by the ``accumulation_class_columns``
constitute an equivalance class.  The aggregation of control losses occures
through accumulation prefix increments, which are equivalence classes congruent
to or subclasses of the accumulation equivalance classes. The set of columns
whose values defined by ``accumulation_prefix_class_columns`` must be identical
or a super set of the columns specified by ``accumulation_class_columns``. A
running total of the accumulation prefix is maintained as a prefix sum. This
prefix sum undergoes evaluation against the trigger condition. For exclusive
triggers, the trigger condition evaluation is conducted before incorporating the
current prefix increment. For each prefix sum meeting the trigger condition test,
subject losses falling with the same equivalence classes at the current prefix
increment are emitted. Subject losses are those records where its value of the
column name ``Type`` is not equal to the control record type specified by
``control_record_type``.


Example
--------

For example, an occurrence industry loss trigger with a trigger value of $100
will only pass those subject losses if the industry losses for the same
occurrence that are less than or equal to $100 in losses. This example is
illustrated in the input ledger below:

+---------+------+------------+-------+---------+-----+
| Trial   | Time | Type       | Value | EventId | LOB |
+=========+======+============+=======+=========+=====+
| 1       | 1    | Control    | -50   | 1       | A   |
+---------+------+------------+-------+---------+-----+
| 1       | 1    | Loss       | -500  | 1       | A   |
+---------+------+------------+-------+---------+-----+
| 1       | 1    | Control    | -100  | 2       | B   |
+---------+------+------------+-------+---------+-----+
| 1       | 1    | Loss       | -1000 | 2       | B   |
+---------+------+------------+-------+---------+-----+

If we use Trigger primitive with the following attributes:

.. code-block:: json

    {
        "_schema": "Trigger_1.0",
        "threshold": 100.0,
        "op":"LESS_THAN_EQUAL",
        "control_record_type":"Control",
        "accumulation_class_columns":["Trial", "Time", "OccurrenceKey"]
        "accumulation_prefix_class_columns":["Trial", "Time", "Occurrencekey"]
        "exclusive": false
    }

We will get the following output:

+---------+------+------------+-------+---------+-----+
| Trial   | Time | Type       | Value | EventId | LOB |
+=========+======+============+=======+=========+=====+
| 1       | 1    | Loss       | -1000 | 2       | B   |
+---------+------+------------+-------+---------+-----+