# Risk metric functions

## `losses_by_period`

Arguments: `[losses: List[Floating], return-periods: List[Floating], investigation-time: Integer, options: {mode=>WithinSet(type=Text, allowed=[percentile, ranked_closest])}]`

Returns: `List[Floating]`

Calculates loss metrics, such as Probable Maximum Loss, Occurrence Exceedance Probability, or Aggregate Exceedance Probability for specific return periods. (beta)
 
The default mode is `percentile`. In this mode losses are interpolated using a percentile based approach where the percentile is `(1 - 1/RP) * 100`.
 
With the `ranked_closest` mode each loss is assigned an RP. Then the loss closest to the desired RP is returned. If there are not enough event losses for the requested return period, then zero is returned for the event loss.
 
The `investigation-time` argument specifies the effective time period that the losses cover. E.g. `losses_by_period(losses, [1000, 250, 100, 50], investigation-time: 10000) as PML` calculates metrics for a 10,000 year period. The first requested return-period (1000) corresponds to the 10th largest loss (i.e. a 10 in 10000-year event)