## distributions.PredictiveDistribution


The joint result every model returns: draws for each simulation (row)


Usage


``` python
distributions.PredictiveDistribution()
```


and component (column), keyed by dimension values.

The [mean](risk.Gpd.md#prospicio.risk.Gpd.mean), [quantile](risk.Gpd.md#prospicio.risk.Gpd.quantile), [var](risk.PotTail.md#prospicio.risk.PotTail.var) and [tvar](risk.PotTail.md#prospicio.risk.PotTail.tvar) methods describe the total over all components, computed from row sums.


## Parameters


`dims: list of str`  
Dimension names, e.g. `["lob", "origin"]`.

`components: list of tuple`  
One key per component, with one `int` or `str` per dimension.

`draws: list of list of float`  
One row per simulation, one value per component.


## Raises


`ValueError`  
If the keys or the draws do not fit together.


## Examples

``` python
>>> from prospicio.distributions import PredictiveDistribution
>>> pd = PredictiveDistribution(["line"], [("A",), ("B",)],
...                             [[0.0, 0.0], [0.0, 0.0], [0.0, 100.0], [100.0, 0.0]])
>>> pd.var(0.75)
```

100.0

``` python
>>> pd.marginal(("A",)).var(0.75)
```

0.0


## Attributes

| Name | Description |
|----|----|
| [dims](#dims) | Dimension names. |
| [n_components](#n_components) | Number of components (columns). |
| [n_sims](#n_sims) | Number of simulations (rows). |

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


#### dims


Dimension names.


`dims: list[str]`


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


#### n_components


Number of components (columns).


`n_components: int`


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


#### n_sims


Number of simulations (rows).


`n_sims: int`


## Methods

| Name | Description |
|----|----|
| [aggregate()](#aggregate) | Sums the components within each simulation over every dimension not |
| [blend()](#blend) | Blends several models' predictive distributions: simulation `i` is |
| [blend_by_component()](#blend_by_component) | Blends models with weights that differ by component, as |
| [components()](#components) | Component keys, one tuple per column. |
| [draw_matrix()](#draw_matrix) | All draws, one row per simulation. |
| [join()](#join) | Joins distributions of different models into one portfolio, with a |
| [marginal()](#marginal) | One component's draws, or `None` if no component has this key. |
| [mean()](#mean) | Mean of the total. |
| [provenance()](#provenance) | Where this result came from: model, parameters, seed, stream scheme, |
| [quantile()](#quantile) | Quantile of the total. |
| [reorder_groups()](#reorder_groups) | Sets the dependence between the groups of dimension [dim](risk.GaussianCopula.md#prospicio.risk.GaussianCopula.dim) by |
| [total()](#total) | The total over all components, one value per simulation. |
| [tvar()](#tvar) | Tail value at risk of the total at level [p](models.Elpd.md#prospicio.models.Elpd.p). |
| [var()](#var) | Value at risk of the total at level [p](models.Elpd.md#prospicio.models.Elpd.p). |
| [variance()](#variance) | Variance of the total. |

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


#### aggregate()


Sums the components within each simulation over every dimension not


Usage


``` python
aggregate(keep)
```


in `keep`, keeping the joint structure.


##### Parameters


`keep: list of str`  


##### Returns


`PredictiveDistribution`  


##### Raises


`ValueError`  
If `keep` names an unknown dimension or repeats one.


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


#### blend()


Blends several models' predictive distributions: simulation `i` is


Usage


``` python
blend(models, weights, seed)
```


simulation `i` of model `k`, with `k` drawn with probability `weights[k]` from stream `i` of [seed](aggregate.EventSet.md#prospicio.aggregate.EventSet.seed). Rows stay whole, so sums across components remain coherent. Use weights from [stacking_weights](models.stacking_weights.md#prospicio.models.stacking_weights) or [pseudo_bma_weights](models.pseudo_bma_weights.md#prospicio.models.pseudo_bma_weights).


##### Parameters


`models: list of PredictiveDistribution`  
Same dimensions, components and number of simulations.

`weights: list of float`  
Non-negative, not all zero; normalized.

`seed: int`  


##### Returns


`PredictiveDistribution`  


##### Examples

``` python
>>> from prospicio.distributions import PredictiveDistribution
>>> a = PredictiveDistribution(["lob"], [("x",)], [[0.0]] * 1000)
>>> b = PredictiveDistribution(["lob"], [("x",)], [[1.0]] * 1000)
>>> mix = PredictiveDistribution.blend([a, b], [0.25, 0.75], seed=7)
>>> abs(mix.mean() - 0.75) < 0.05
```

True

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


#### blend_by_component()


Blends models with weights that differ by component, as


Usage


``` python
blend_by_component(models, weights, seed)
```


[HierarchicalStacking](models.HierarchicalStacking.md#prospicio.models.HierarchicalStacking) gives them: in simulation `i` every component draws its model from the same uniform against its own cumulative weights, so components with equal weights take the same model and dependence is kept as far as the weights allow.


##### Parameters


`models: list of PredictiveDistribution`  

`weights: list of list of float`  
One weight vector per component (in [components()](pricing.PortfolioPrice.md#prospicio.pricing.PortfolioPrice.components) order), one weight per model.

`seed: int`  


##### Returns


`PredictiveDistribution`  


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


#### components()


Component keys, one tuple per column.


Usage


``` python
components()
```


##### Returns


`list of tuple`  


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


#### draw_matrix()


All draws, one row per simulation.


Usage


``` python
draw_matrix()
```


##### Returns


`list of list of float`  


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


#### join()


Joins distributions of different models into one portfolio, with a


Usage


``` python
join(parts, dim, same_simulations=False)
```


leading dimension [dim](risk.GaussianCopula.md#prospicio.risk.GaussianCopula.dim) holding each part's label, followed by the union of the parts' dimensions (`""` where a part lacks one). Simulation `i` of the result is simulation `i` of every part.


##### Parameters


`parts: list of (str, PredictiveDistribution)`  

`dim: str`  

`same_simulations: bool = ``False`  
`False`: the parts were simulated separately, and two with the same seed and stream scheme (which would share random numbers) are refused. `True`: the parts come from the same scenarios (a cover applied to a reserve) and keep their pairing.


##### Returns


`PredictiveDistribution`  


##### Examples

``` python
>>> from prospicio.distributions import PredictiveDistribution
>>> a = PredictiveDistribution(["origin"], [(2023,), (2024,)], [[10.0, 20.0], [12.0, 25.0]])
>>> b = PredictiveDistribution(["lob"], [("motor",)], [[50.0], [40.0]])
>>> p = PredictiveDistribution.join([("reserve", a), ("premium", b)], "risk")
>>> p.dims, p.total().draws
```

(\['risk', 'origin', 'lob'\], \[80.0, 77.0\])

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


#### marginal()


One component's draws, or `None` if no component has this key.


Usage


``` python
marginal(key)
```


An origin period is named by its label, as a string or an integer: `("2021",)` or `(2021,)` for a year, `("2021Q3",)` for a quarter.


##### Parameters


`key: tuple`  


##### Returns


`Sampled or None`  


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


#### mean()


Mean of the total.


Usage


``` python
mean()
```


##### Returns


`float`  


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


#### provenance()


Where this result came from: model, parameters, seed, stream scheme,


Usage


``` python
provenance()
```


crate versions and input hash.


##### Returns


`dict`  


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


#### quantile()


Quantile of the total.


Usage


``` python
quantile(p)
```


##### Parameters


`p: float`  


##### Returns


`float`  


##### Raises


`ValueError`  
If [p](models.Elpd.md#prospicio.models.Elpd.p) is outside `[0, 1]`.


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


#### reorder_groups()


Sets the dependence between the groups of dimension [dim](risk.GaussianCopula.md#prospicio.risk.GaussianCopula.dim) by


Usage


``` python
reorder_groups(dim, correlation, seed)
```


Iman-Conover on the groups' totals, moving each group's simulations as whole rows: every group keeps its distribution and internal joint structure, and the group totals take a rank correlation close to `correlation`.


##### Parameters


`dim: str`  

`correlation: list of list of float`  
One row and column per group, in order of first appearance.

`seed: int`  


##### Returns


`PredictiveDistribution`  


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


#### total()


The total over all components, one value per simulation.


Usage


``` python
total()
```


##### Returns


`Sampled`  


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


#### tvar()


Tail value at risk of the total at level [p](models.Elpd.md#prospicio.models.Elpd.p).


Usage


``` python
tvar(p)
```


##### Parameters


`p: float`  


##### Returns


`float`  


##### Raises


`ValueError`  
If [p](models.Elpd.md#prospicio.models.Elpd.p) is outside `[0, 1]`.


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


#### var()


Value at risk of the total at level [p](models.Elpd.md#prospicio.models.Elpd.p).


Usage


``` python
var(p)
```


##### Parameters


`p: float`  


##### Returns


`float`  


##### Raises


`ValueError`  
If [p](models.Elpd.md#prospicio.models.Elpd.p) is outside `[0, 1]`.


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


#### variance()


Variance of the total.


Usage


``` python
variance()
```


##### Returns


`float`