# NAME

Statistics::Sampler::Multinomial::Indexed - Generate multinomial samples using the conditional binomial method, using a hierarchical index to speed up the draw method.

# SYNOPSIS

``````    use Statistics::Sampler::Multinomial::Indexed;

my \$object = Statistics::Sampler::Multinomial->new(
data => [0.1, 0.3, 0.2, 0.4],
);
\$object->draw;
#  returns a number between 0..3

my \$samples = \$object->draw_n_samples(5)
#  returns an array ref that might look something like
#  [3,3,0,2,0]

#  locally set data at positions 1 and 2 to zero
#  so they will have zero probability of being returned

# to specify your own PRNG object, in this case the Mersenne Twister
my \$mrma = Math::Random::MT::Auto->new;
my \$object = Statistics::Sampler::Multinomial->new(
prng => \$mrma,
data => [1,2,3,5,10],
);``````

# DESCRIPTION

This is a subclass of Statistics::Sampler::Multinomial. All methods are inherited from there.

The difference is that this uses an index to speed up the calls to the draw method. Note that this can be expensive to calculate, so is only of benefit for repeated calls.

# METHODS

\$object->new (data => [2,7,9,12])

Generates a new object. For full arguments, see the new method in Statistics::Sampler::Multinomial.

\$object->draw

Draw one sample from the distribution. Returns the sampled class number (array index).

The internal index means calls will be O(log n) instead of O(n/2) on average for the non-indexed variant.

Setting up the index costs O(n log n), so best used when the setup costs can be amortised across many calls.

\$object->update_values (1 => 10, 4 => 0.2)

Updates the data values at the specified positions. Argument list must be a set of numeric key/value pairs. The keys and values are not otherwise checked, but the system will follow perl's rules regarding non-numeric values under the warnings pragma. The same applies for floating point array indices.

Due to the index, this will run at O(log n).

If the updates would increase the size of the data array beyond the next power of two then the index is completely rebuilt.

\$object->build_index

Build the index. This is called automatically in new(), so is probably only useful if one reblesses a Statistics::Sampler::Multinomial object into this class.

# BUGS AND LIMITATIONS

Please report any bugs or feature requests to https://github.com/shawnlaffan/perl-statistics-sampler-multinomial/issues.

Most tests are skipped on x86 as Math::Random::MT::Auto seeds differently and thus the PRNG sequences differ between x86 and x64.

These packages also have multinomial samplers and are (much) faster than this package, but you cannot supply your own PRNG. If you do not care that all your random samples come from the same PRNG stream then you should use them.

# AUTHOR

Shawn Laffan `<shawnlaffan@gmail.com>`

Copyright (c) 2016, Shawn Laffan `<shawnlaffan@gmail.com>`. All rights reserved.