oasislmf.pytools.gul.core
=========================

.. py:module:: oasislmf.pytools.gul.core

.. autoapi-nested-parse::

   This file contains the core mathematical functions used in gulpy.



Functions
---------

.. autoapisummary::

   oasislmf.pytools.gul.core.get_gul
   oasislmf.pytools.gul.core.setmaxloss
   oasislmf.pytools.gul.core.split_tiv_classic
   oasislmf.pytools.gul.core.split_tiv_multiplicative
   oasislmf.pytools.gul.core.compute_mean_loss


Module Contents
---------------

.. py:function:: get_gul(bin_from, bin_to, bin_mean, prob_from, prob_to, rval, tiv)

   Compute the ground-up loss using linear or quadratic interpolaiton if necessary.

   Args:
       bin_from (oasis_float): bin minimum damage.
       bin_to (oasis_float): bin maximum damage.
       bin_mean (oasis_float): bin mean damage (`interpolation` column in damagebins file).
       prob_from (oasis_float): bin minimum probability
       prob_to (oasis_float): bin maximum probability
       rval (float64): the random cdf value.
       tiv (oasis_float): total insured value.

   Returns:
       float64: the computed ground-up loss


.. py:function:: setmaxloss(losses)

   Set maximum losses.
   For each sample idx, find the maximum loss across all items and set to zero
   all the losses smaller than the maximum loss. If the maximum loss occurs in `N` items,
   then set the loss in all these items as the maximum loss divided by `N`.

   Args:
       losses (numpy.array[oasis_float]): losses for all item_ids and sample idx.

   Returns:
       numpy.array[oasis_float]: losses for all item_ids and sample idx.


.. py:function:: split_tiv_classic(gulitems, tiv)

   Split the total insured value (TIV). If the total loss of all the items
   in `gulitems` exceeds the total insured value, re-scale the losses in the
   same proportion to the losses.

   Args:
       gulitems (numpy.array[oasis_float]): array containing losses of all items.
       tiv (oasis_float): total insured value.


.. py:function:: split_tiv_multiplicative(gulitems, tiv)

   Split the total insured value (TIV) using a multiplicative formula for the
   total loss as tiv * (1 - (1-A)*(1-B)*(1-C)...), where A, B, C are damage ratios
   computed as the ratio between a sub-peril loss and the tiv. Sub-peril losses
   in gulitems are always back-allocated proportionally to the losses.

   Args:
       gulitems (numpy.array[oasis_float]): array containing losses of all items.
       tiv (oasis_float): total insured value.


.. py:function:: compute_mean_loss(tiv, prob_to, bin_mean, bin_count, max_damage_bin_to)

   Compute the mean ground-up loss and some properties.

   Args:
       tiv (oasis_float): total insured value.
       prob_to (numpy.array[oasis_float]): bin maximum probability
       bin_mean (numpy.array[oasis_float]): bin mean damage (`interpolation` column in damagebins file).
       bin_count (int): number of bins.
       max_damage_bin_to (oasis_float): maximum damage value (i.e., `bin_to` of the last damage bin).

   Returns:
       float64, float64, float64, float64: mean ground-up loss, standard deviation of the ground-up loss,
         chance of loss, maximum loss