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_i
   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, bin_scaling)

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

   :param bin_from: bin minimum damage.
   :type bin_from: oasis_float
   :param bin_to: bin maximum damage.
   :type bin_to: oasis_float
   :param bin_mean: bin mean damage (`interpolation` column in damagebins file).
   :type bin_mean: oasis_float
   :param prob_from: bin minimum probability
   :type prob_from: oasis_float
   :param prob_to: bin maximum probability
   :type prob_to: oasis_float
   :param rval: the random cdf value.
   :type rval: float64
   :param bin_scaling: scaling on the bins.
   :type bin_scaling: oasis_float

   :returns: the computed ground-up loss
   :rtype: float64


.. py:function:: setmaxloss_i(losses, sidx)

.. 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`.

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

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


.. 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.

   :param gulitems: array containing losses of all items.
   :type gulitems: numpy.array[oasis_float]
   :param tiv: total insured value.
   :type tiv: oasis_float


.. 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.

   :param gulitems: array containing losses of all items.
   :type gulitems: numpy.array[oasis_float]
   :param tiv: total insured value.
   :type tiv: oasis_float


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

   Compute the mean ground-up loss and some properties.

   :param bin_scaling: scaling on damage bin values.
   :type bin_scaling: oasis_float
   :param prob_to: bin maximum probability
   :type prob_to: numpy.array[oasis_float]
   :param bin_mean: bin mean damage (`interpolation` column in damagebins file).
   :type bin_mean: numpy.array[oasis_float]
   :param bin_count: number of bins.
   :type bin_count: int
   :param max_damage_bin_to: maximum damage value (i.e., `bin_to` of the last damage bin).
   :type max_damage_bin_to: oasis_float

   :returns:

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