Portability | portable |
---|---|

Stability | experimental |

Maintainer | bos@serpentine.com |

Safe Haskell | None |

Table-driven generation of random variates. This approach can
generate random variates in *O(1)* time for the supported
distributions, at a modest cost in initialization time.

- data CondensedTable v a
- type CondensedTableV = CondensedTable Vector
- type CondensedTableU = CondensedTable Vector
- genFromTable :: (PrimMonad m, Vector v a) => CondensedTable v a -> Gen (PrimState m) -> m a
- tableFromProbabilities :: (Vector v (a, Word32), Vector v (a, Double), Vector v a, Vector v Word32) => v (a, Double) -> CondensedTable v a
- tableFromWeights :: (Vector v (a, Word32), Vector v (a, Double), Vector v a, Vector v Word32) => v (a, Double) -> CondensedTable v a
- tableFromIntWeights :: (Vector v (a, Word32), Vector v a, Vector v Word32) => v (a, Word32) -> CondensedTable v a
- tablePoisson :: Double -> CondensedTableU Int
- tableBinomial :: Int -> Double -> CondensedTableU Int

# Condensed tables

data CondensedTable v a Source

A lookup table for arbitrary discrete distributions. It allows
the generation of random variates in *O(1)*. Note that probability
is quantized in units of `1/2^32`

, and all distributions with
infinite support (e.g. Poisson) should be truncated.

type CondensedTableV = CondensedTable VectorSource

A `CondensedTable`

that uses boxed vectors, and is able to hold
any type of element.

type CondensedTableU = CondensedTable VectorSource

A `CondensedTable`

that uses unboxed vectors.

genFromTable :: (PrimMonad m, Vector v a) => CondensedTable v a -> Gen (PrimState m) -> m aSource

Generate a random value using a condensed table.

# Constructors for tables

tableFromProbabilities :: (Vector v (a, Word32), Vector v (a, Double), Vector v a, Vector v Word32) => v (a, Double) -> CondensedTable v aSource

Generate a condensed lookup table from a list of outcomes with given probabilities. The vector should be non-empty and the probabilites should be non-negative and sum to 1. If this is not the case, this algorithm will construct a table for some distribution that may bear no resemblance to what you intended.

tableFromWeights :: (Vector v (a, Word32), Vector v (a, Double), Vector v a, Vector v Word32) => v (a, Double) -> CondensedTable v aSource

Same as `tableFromProbabilities`

but treats number as weights not
probilities. Non-positive weights are discarded, and those
remaining are normalized to 1.

tableFromIntWeights :: (Vector v (a, Word32), Vector v a, Vector v Word32) => v (a, Word32) -> CondensedTable v aSource

Generate a condensed lookup table from integer weights. Weights
should sum to `2^32`

. If they don't, the algorithm will alter the
weights so that they do. This approach should work reasonably well
for rounding errors.

## Disrete distributions

tablePoisson :: Double -> CondensedTableU IntSource

Create a lookup table for the Poisson distibution. Note that table construction may have significant cost. For λ < 100 it takes as much time to build table as generation of 1000-30000 variates.

:: Int | Number of tries |

-> Double | Probability of success |

-> CondensedTableU Int |

Create a lookup table for the binomial distribution.

# References

- Wang, J.; Tsang, W. W.; G. Marsaglia (2004), Fast Generation of Discrete Random Variables, /Journal of Statistical Software, American Statistical Association/, vol. 11(i03). http://ideas.repec.org/a/jss/jstsof/11i03.html