Struct FunctionSampler

pub struct FunctionSampler<T: Fn(f64) -> f64> { /* private fields */ }

Distribution described by a non-negative shape function on an interval

Allows sampling from a generic distribution described by some shape function $f(x)$. The function does not need to be normalised i.e. $ \int f(s) d(s) \ne 1 $ in general

It is intended to be used as a reference distribution for verification of more efficient sampling algorithms.

Sampling procedure

To generate the samples a relatively expensive setup step is required. The user provides an interval $[x_0, x_1]$ which is a support of the shape function $f(x)$. The support is then subdivided into number of bins. In each a local maximum is found by numerical means. This allows to create a histogram approximation of the probability distribution, that ‘tops’ the actual distribution. Hence, we may draw samples from the histogram and use rejection scheme to obtain the distribution described by $f(x)$.

Since the numerical maximisation is associated with some tolerance, a safety factor of 5% is applied on the local maxima to ensure that the supremum criterion required for rejection sampling is met.

Note that for very sharp functions (large $\frac{df}{dx} $) the safety factor may be insufficient. Also a general check if $f(x) \ge 0 \forall x \in [x_0; x_1]$ is met is not feasible. Hence sampling may panic if either of the conditions occurs.

Usage

The distribution is integrated with rand package and can be used to construct a sampling iterator as follows:

use rand::{self, Rng};

let dist = FunctionSampler::new(|x| -x*x + x, 0.0..1.0, 30)?;
let samples = rand::thread_rng().sample_iter(&dist).take(10);

Implementations

impl<T> FunctionSampler<T>

where T: Fn(f64) -> f64,

pub const SAFETY_FACTOR: f64 = 1.05f64

Safety factor to increase bin maxima to protect against error due to tolerance of numerical optimisation

pub fn new( function: T, range: Range<f64>, bins: usize, ) -> Result<Self, SetupError>

New sampler from components

Arguments

• function - A function Fn(f64) -> f64 that is non-negative on range
• range - Support of the probability distribution with the shape of function
• bins - Number of bins to construct topping histogram (at least 1)

Trait Implementations

impl<T: Clone + Fn(f64) -> f64> Clone for FunctionSampler<T>

fn clone(&self) -> FunctionSampler<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Fn(f64) -> f64> Debug for FunctionSampler<T>

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

Formats the value using the given formatter.

impl<T> Distribution<f64> for FunctionSampler<T>

where T: Fn(f64) -> f64,

Draws samples from the FunctionSampler

Panics

Sampling may panic if the shape function has negative values or upper bound is not is not fulfilled. This may happen if gradient of the shape function is strong and the safety factor on the tolerance of optimisation was insufficient

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> f64

Generate a random value of T, using rng as the source of randomness.

fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T>

where R: Rng, Self: Sized,

Create an iterator that generates random values of T, using rng as the source of randomness.

fn map<F, S>(self, func: F) -> DistMap<Self, F, T, S>

where F: Fn(T) -> S, Self: Sized,

Create a distribution of values of ‘S’ by mapping the output of Self through the closure F