.. index:: Core Operations; Scoped Limit
.. _core-operation-scoped-limit:

ScopedLimit
==================================

Applies a limit to the sum of a group of records that share equal values
in the columns specified by ``erode_by_columns``. It is applied incrementally
to groups of records that share same values in the columns specified by
``span_columns``. Once the limit is applied, the result is proportionally
allocated to all records in the group.

Structure
---------

.. code-block:: json

    {
        "_schema": "ScopedLimit_1.0",
        "limit": 1000,
        "span_columns": ["Time"],
        "erode_by_columns": ["Time", "OccurrenceKey"],
        "currency":"GBP"
    }

Parameters
----------

+----------------------+----------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|    Parameter Name    | Required |      Type       |                                                                                                       Description                                                                                                       |
+======================+==========+=================+=========================================================================================================================================================================================================================+
| ``limit``            | Yes      | ``double``      | The limit value in currency units. Cannot be negative.                                                                                                                                                                  |
+----------------------+----------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``span_columns``     | No       | ``string list`` | List of column names. Adjacent records with the same values in the provided columns will share the same eroding limit. Supported columns: ``OccurrenceKey``, ``Time``. If left empty, all records share the same limit. |
+----------------------+----------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``erode_by_columns`` | No       | ``string list`` | List of column names. Specifies the grouping of records the limit will apply to. Supported columns: ``OccurrenceKey``, ``Time``. Always implicitly contains the values in ``span_columns``.                             |
+----------------------+----------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``currency``         | No       | ``string``      | The currency in which ``limit`` is defined.                                                                                                                                                                             |
+----------------------+----------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Behaviour
--------------

Records which pass through scoped limit have their limit applied
according to how they are grouped by ``span_columns`` and
``erode_by_columns``.
All adjacent records with matching values in the columns specified by
``span_columns`` are placed within a *span group*.
All adjacent records with matching values in the columns specified by
``erode_by_columns`` within a span group are further placed in an
*erode group*.

Within each erode group, the limit is applied to the sum of the records'
``Value`` fields (``sum``) with the function ``new_sum = max(sum, -limit)``. This
value is then proportionally allocated to the ``Value`` field of each record within
the group with the function ``record.value = new_sum / sum``.
If ``sum`` is 0, then each records' ``Value`` field is instead left unmodified.
In either case, the limit is eroded with the function
``limit = max(limit + min(new_sum, 0), 0)``.

Within each span group, the value of the limit is reset to the original
limit specified in the arguments.