.. _labels:

Labels
======

Labels assigned to nodes can be used to track losses and premiums passing through
financial model graphs.

.. index:: Labels; _NodePath

.. _node_path:

_NodePath
---------

_NodePath is a special column name in YELT that contains a path from the node where
a particular value (e.g. a loss or a premium) was originated to the final node.

For example, we can have a financial model represented by the graph below:

.. graphviz:: node_path.dot

Let's say a loss value was originated in the Loss Set 3 (``LS3``).
In that case, in the YELT table, we may have a number of rows that contain
_NodePath values started with ``LS3``.

.. list-table:: Losses originated in the Loss Set 3
  :widths: 10 10 10 10 10 30
  :header-rows: 1

  * - Trial
    - Time
    - Type
    - Value
    - Event ID
    - _NodePath
  * - 1
    - 3842394.0
    - Loss
    - 5M
    - 32497
    - "LS3,GP,R1,NP"
  * - 1
    - 3842394.0
    - Loss
    - 20M
    - 32497
    - "LS3,GP,R2,NP"
  * - 1
    - 3842801.0
    - Loss
    - 10M
    - 34920
    - "LS3,GP,R3,NP"

All the paths in the table start with ``LS3`` label, but each of the paths
is unique as the losses passed three different Retro Layers (``R1``, ``R2``,
``R3``).

.. index:: Labels; Back-allocation

Back-allocation using _NodePath
-------------------------------

In order to do back-allocation you can sum up all the Values in rows that
passed a node of interest.

For example, to calculate back-allocation of the Loss Set 3 node (``LS3``)
to the Net Portfolio node (``NP``) you would need to sum Value columns
from the table above ("5M" + "20M" + "10M") and divide the result by
the total loss amount.

.. index:: Labels; _NodePath Limitations

Limitations
-----------

_NodePath can not be listed inside of the ``columns`` parameter of
`LedgerExportDescriptor <api_reference.html#are-v1-analysis-LedgerExportDescriptor>`__
and `LedgerSQLQueryDescriptor <api_reference.html#are-v1-analysis-LedgerSQLQueryDescriptor>`__.
If being listed the API will return an error:
`The requested columns are reserved, and cannot be used: _NodePath ...`.

Another limitation is that it is possible to get a Timeout (or Out of Memory) error
while using _NodePath with large graphs. It is due to having a large number of
unique possible paths through the graph.

.. index:: Labels; _NodePath with Projection

Using _NodePath with Projection
-------------------------------

Projections can change _NodePath values in some of the cases.
Please see :ref:`core-operation-projection` for details.