Struct Grid 

pub struct Grid { /* private fields */ }

A distribution on the points 0, h, 2h, …, (n - 1)h.

Grids are what FFT and Panjer aggregation work on. They are exact for sums, layers and stop-loss on the grid, but a grid made from a continuous distribution is an approximation: see Grid::local_moment, Grid::rounding and Grid::lower, which return a DiscretizationReport with the error introduced.

The probabilities always sum to 1. Discretization lumps whatever lies beyond the last point onto it and reports that mass.

Example

use prospicio_prob::{Distribution, Grid, Lognormal, Severity};

let sev = Lognormal::new(7.0, 0.5).unwrap();
let (grid, report) = Grid::local_moment(&sev, 100.0, 200).unwrap();
// Local moment matching preserves the limited mean up to the last point.
assert!((grid.mean() - sev.lev(199.0 * 100.0)).abs() < 1e-9);
// About 3e-9 of the mass lies beyond the last point (19,900).
assert!(report.tail_mass < 1e-8);

Implementations

impl Grid

pub fn new(step: f64, probs: Vec<f64>) -> Result<Self>

A grid with step step and probabilities probs at 0, step, ….

Fails if step is not finite and positive, probs is empty or holds a negative or non-finite value, or the probabilities do not sum to 1 within 1e-9.

pub fn local_moment<D: Severity>( source: &D, step: f64, points: usize, ) -> Result<(Self, DiscretizationReport)>

Discretizes source by local moment matching on the mean, using its limited expected values:

f_0 = 1 - LEV(h) / h
f_j = (2 LEV(jh) - LEV((j-1)h) - LEV((j+1)h)) / h,  0 < j < n - 1
f_{n-1} = (LEV((n-1)h) - LEV((n-2)h)) / h            (the rest)

The grid’s mean is exactly LEV((n - 1)h).

pub fn rounding<D: Distribution>( source: &D, step: f64, points: usize, ) -> Result<(Self, DiscretizationReport)>

Discretizes source by rounding each loss to the nearest point: f_0 = F(h/2), f_j = F((j + 1/2)h) - F((j - 1/2)h), and the last point takes everything above (n - 3/2)h.

pub fn lower<D: Distribution>( source: &D, step: f64, points: usize, ) -> Result<(Self, DiscretizationReport)>

Discretizes source by moving each cell’s mass to its left end: f_j = F((j + 1)h) - F(jh), with the last point taking everything above (n - 1)h. The result is a stochastic lower bound of source.

pub fn step(&self) -> f64

Grid step h.

pub fn probs(&self) -> &[f64]

Probabilities at 0, h, 2h, ….

pub fn len(&self) -> usize

Number of grid points.

pub fn is_empty(&self) -> bool

Always false: a grid has at least one point.

pub fn x(&self, j: usize) -> f64

Loss at point j, j * h.

pub fn distortion(&self, d: &Distortion) -> f64

Distortion risk measure of the grid, exact for the grid; see Distortion::apply_discrete.

use prospicio_prob::{Distortion, Grid};

let g = Grid::new(1.0, vec![0.5, 0.25, 0.25]).unwrap();
// TVaR at 50%: the top half of the mass, at 1 and 2.
assert_eq!(g.distortion(&Distortion::tvar(0.5).unwrap()), 1.5);

pub fn map(&self, f: impl FnMut(f64) -> f64) -> Result<(Self, bool)>

The distribution of f(X) on the same step, and whether it is exact.

Each point’s mass moves to f(x_j). A value on a grid point (within 1e-9 of a step) keeps its mass there; one between points k and k + 1 is split between them so its mean is kept, as local moment matching does. The mean is therefore always exact, and the whole distribution is exact when the flag is true. The result is as long as the largest value needs.

For a layer with boundaries on grid points the map is exact:

use prospicio_prob::{Distribution, Grid};

let x = Grid::new(1.0, vec![0.2, 0.3, 0.3, 0.2]).unwrap();
// 1 xs 1: values 0, 0, 1, 1.
let (layer, exact) = x.map(|v| (v - 1.0).clamp(0.0, 1.0)).unwrap();
assert!(exact);
assert_eq!(layer.probs(), [0.5, 0.5]);
// 1.5 xs 0.5 puts 0.5 and 1.5 between points: the mean is kept.
let (layer, exact) = x.map(|v| (v - 0.5).clamp(0.0, 1.5)).unwrap();
assert!(!exact);
assert!((layer.mean() - (0.3 * 0.5 + 0.5 * 1.5)).abs() < 1e-15);

Fails if f returns a negative or non-finite value at a point with mass.

Trait Implementations

impl Clone for Grid

fn clone(&self) -> Grid

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Grid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Distribution for Grid

fn survival(&self, x: f64) -> f64

Summed from the top, so small tail probabilities keep their precision.

fn mean(&self) -> f64

Expected value.

fn variance(&self) -> f64

Variance.

fn cdf(&self, x: f64) -> f64

P(X <= x).

fn quantile(&self, p: f64) -> Result<f64>

Smallest x with cdf(x) >= p.

fn std_dev(&self) -> f64

Standard deviation.

fn sample(&self, rng: &mut StreamRng, n: usize) -> Vec<f64>

n draws from stream rng, by inverse transform unless the family overrides it (crate::Gamma draws by Marsaglia and Tsang).

fn is_parallel_safe(&self) -> bool

Whether the distribution may be evaluated on several threads at once. True for every native family; false for a crate::Custom whose callbacks must stay on the calling thread (an R function), so the parallel simulations run single-threaded when they meet one.

impl From<Grid> for Dist

fn from(d: Grid) -> Self

Converts to this type from the input type.

impl PartialEq for Grid

fn eq(&self, other: &Grid) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Severity for Grid

fn lev(&self, limit: f64) -> f64

Limited expected value E[min(X, limit)].

fn stop_loss(&self, retention: f64) -> f64

Expected excess over a retention, E[max(X - retention, 0)].

fn layer_second_moment(&self, limit: f64, attachment: f64) -> f64

Second moment of the loss to the layer limit xs attachment, E[min(max(X - attachment, 0), limit)^2]. limit = +inf gives the unlimited layer (infinite if the second moment is).

fn layer(&self, limit: f64, attachment: f64) -> f64

Expected loss to the layer limit xs attachment, E[min(max(X - attachment, 0), limit)].

fn layer_variance(&self, limit: f64, attachment: f64) -> f64

Variance of the loss to the layer limit xs attachment.

impl StructuralPartialEq for Grid