## reinsurance.Tower


A reinsurance programme: layers in inuring stages.


Usage


``` python
reinsurance.Tower()
```


`Tower(layers)` is one stage: every layer sees the gross losses. `Tower.inuring(stages)` applies stages in order, each seeing the losses net of all earlier stages, event by event.


## Parameters


`layers: list of Layer`  
At least one; names must be unique.


## Raises


`ValueError`  
If there are no layers or two share a name.


## Examples

``` python
>>> from prospicio.aggregate import simulate_events
>>> from prospicio.reinsurance import Layer, Tower
>>> from prospicio.distributions import Lognormal, Poisson
>>> events = simulate_events(Poisson(2.0), Lognormal.from_mean_cv(3e6, 1.5), 1_000, 7)
>>> tower = Tower([Layer("5x5", 5e6, 5e6), Layer("15x10", 15e6, 10e6)])
>>> result = tower.apply(events)
>>> [k[0] for k in result.aggregate(["kind"]).components()]
```

\['gross', 'ceded', 'net'\]


## Attributes

| Name | Description |
|----|----|
| [layer_names](#layer_names) | Layer names, in order. |
| [stages](#stages) | Stage of each layer, in order, starting at 0. |

------------------------------------------------------------------------


#### layer_names


Layer names, in order.


`layer_names: list[str]`


------------------------------------------------------------------------


#### stages


Stage of each layer, in order, starting at 0.


`stages: list[int]`


## Methods

| Name | Description |
|----|----|
| [apply()](#apply) | Applies the tower to every simulated year. |
| [apply_aggregate()](#apply_aggregate) | Applies the tower to any predictive distribution, each simulation's |
| [ceded()](#ceded) | Ceded loss of each layer, in order, for one year's losses. |
| [from_json()](#from_json) | A tower whose stages inure in order. |
| [inuring()](#inuring) | A tower whose stages inure in order. |
| [on_grid()](#on_grid) | Gross, ceded and net annual distributions on the grid, by FFT. |
| [to_json()](#to_json) | The programme as a versioned JSON document: every stage and layer |

------------------------------------------------------------------------


#### apply()


Applies the tower to every simulated year.


Usage


``` python
apply(events)
```


The result has dimensions `["kind", "layer"]`: `("gross", "ground_up")`, `("ceded", name)` per layer, `("net", "retained")`, then `("reinstatement_premium", name)` per layer with paid reinstatements. `aggregate(["kind"])` gives gross, total ceded and net; net is a loss, before premiums.


##### Parameters


`events: EventSet`  


##### Returns


`PredictiveDistribution`  


------------------------------------------------------------------------


#### apply_aggregate()


Applies the tower to any predictive distribution, each simulation's


Usage


``` python
apply_aggregate(losses)
```


total taken as one aggregate loss: an adverse development cover on a reserve bootstrap, a stop-loss or quota share on modelled premium risk. An occurrence layer sees the total as one occurrence, so it acts as an aggregate excess of loss. Components as [apply](reinsurance.Tower.md#prospicio.reinsurance.Tower.apply).


##### Parameters


`losses: PredictiveDistribution`  


##### Returns


`PredictiveDistribution`  


------------------------------------------------------------------------


#### ceded()


Ceded loss of each layer, in order, for one year's losses.


Usage


``` python
ceded(losses)
```


##### Parameters


`losses: list of float`  


##### Returns


`list of float`  


------------------------------------------------------------------------


#### from_json()


A tower whose stages inure in order.


Usage


``` python
from_json(text)
```


Each stage's layers see the losses net of all earlier stages, event by event, with annual terms used up in event order.


##### Parameters


`stages: list of list of Layer`  
No stage may be empty; names must be unique across stages.


##### Returns


`Tower`  


##### Examples

``` python
>>> from prospicio.reinsurance import Layer, Tower
>>> tower = Tower.inuring([[Layer.quota_share("QS", 0.5)], [Layer("5x5", 5.0, 5.0)]])
>>> tower.ceded([30.0])
```

\[15.0, 5.0\] Reads a document written by [Tower.to_json](reinsurance.Tower.md#prospicio.reinsurance.Tower.to_json).


##### Parameters


`text: str`  


##### Returns


`Tower`  


##### Raises


`ValueError`  
On malformed JSON, another format, a newer format version, or a term a layer refuses.


------------------------------------------------------------------------


#### inuring()


A tower whose stages inure in order.


Usage


``` python
inuring(stages)
```


Each stage's layers see the losses net of all earlier stages, event by event, with annual terms used up in event order.


##### Parameters


`stages: list of list of Layer`  
No stage may be empty; names must be unique across stages.


##### Returns


`Tower`  


##### Examples

``` python
>>> from prospicio.reinsurance import Layer, Tower
>>> tower = Tower.inuring([[Layer.quota_share("QS", 0.5)], [Layer("5x5", 5.0, 5.0)]])
>>> tower.ceded([30.0])
```

\[15.0, 5.0\]

------------------------------------------------------------------------


#### on_grid()


Gross, ceded and net annual distributions on the grid, by FFT.


Usage


``` python
on_grid(frequency, severity, points)
```


Each layer's per-occurrence recoveries form a severity grid, which is compounded with the same claim count; annual terms and the share then apply to the total. With boundaries on multiples of the step the grids are exact for the discretized problem, with no sampling error. Grids are marginal (use [apply](reinsurance.Tower.md#prospicio.reinsurance.Tower.apply) on simulated events for joint results). [net](reinsurance.TowerGrids.md#prospicio.reinsurance.TowerGrids.net) is given when no layer has annual terms, or when the last stage is a single aggregate cover such as a stop-loss; otherwise it is `None`.


##### Parameters


`frequency: (Poisson, NegativeBinomial or Binomial)`  

`severity: Grid`  

`points: int`  
Points in every aggregate grid.


##### Returns


`TowerGrids`  


##### Raises


`ValueError`  
If a layer with annual terms inures to a later stage, or [points](aggregate.CompoundReport.md#prospicio.aggregate.CompoundReport.points) is 0.


##### Examples

``` python
>>> from prospicio.reinsurance import Layer, Tower
>>> from prospicio.distributions import Grid, Poisson
>>> sev = Grid(1.0, [0.0, 0.4, 0.3, 0.2, 0.1])
>>> r = Tower([Layer("2x2", 2.0, 2.0)]).on_grid(Poisson(3.0), sev, 200)
>>> round(r.ceded[0].mean(), 12), r.on_points
```

(1.2, True)

------------------------------------------------------------------------


#### to_json()


The programme as a versioned JSON document: every stage and layer


Usage


``` python
to_json()
```


with all its terms, numbers bit for bit. [Tower.from_json](reinsurance.Tower.md#prospicio.reinsurance.Tower.from_json) reads it back to an equal tower, rebuilding each layer through the same checks; towers also pickle this way.


##### Returns


`str`  


##### Examples

``` python
>>> from prospicio.reinsurance import Layer, Tower
>>> tower = Tower.inuring([[Layer.surplus("S", 1e6, 4.0)], [Layer("xl", 2e6, 1e6)]])
>>> back = Tower.from_json(tower.to_json())
>>> back.to_json() == tower.to_json()
```

True