org.opensha.commons.calc
Class WeightedSampler<T>

java.lang.Object
  extended by org.opensha.commons.calc.WeightedSampler<T>
Type Parameters:
T -

public class WeightedSampler<T>
extends Object

This class allows you to sample items randomly according to their rates (or any arbitrary positive scalar). It can also generate a random series of items.

Author:
kevin

Constructor Summary
WeightedSampler(List<T> objects, List<Double> rates)
          Creates a PoissonSampler with the given list of objects and rates.
WeightedSampler(List<T> objects, List<Double> rates, Random r)
          Creates a PoissonSampler with the given list of objects and rates.
 
Method Summary
 List<T> generateSeries(int size)
          Generates a series of randomly selected items.
 T getItemForNormCumRate(double rate)
          Returns the item at the given normalized (between 0 and 1) cumulative rate.
 T nextItem()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WeightedSampler

public WeightedSampler(List<T> objects,
                       List<Double> rates)
                throws NullPointerException,
                       IllegalArgumentException
Creates a PoissonSampler with the given list of objects and rates. Rates will be normalized and sorted internally.

Parameters:
objects - list of objects of which to sample
rates - list of rates (or any arbitrary scalar) to be used for sampling. each rate must be >=0, and there must be at least one non zero rate.
Throws:
NullPointerException - if any arguments are null
IllegalArgumentException - if lists of objects and rates are empty, or of different sizes. Will also be thrown if any rates are less than zero, or if all rates are equal to zero.

WeightedSampler

public WeightedSampler(List<T> objects,
                       List<Double> rates,
                       Random r)
                throws NullPointerException,
                       IllegalArgumentException
Creates a PoissonSampler with the given list of objects and rates. Rates will be normalized and sorted internally.

Parameters:
objects - list of objects of which to sample
rates - list of rates (or any arbitrary scalar) to be used for sampling. each rate must be >=0, and there must be at least one non zero rate.
r - random number generator to be used
Throws:
NullPointerException - if any arguments are null
IllegalArgumentException - if lists of objects and rates are empty, or of different sizes. Will also be thrown if any rates are less than zero, or if all rates are equal to zero.
Method Detail

getItemForNormCumRate

public T getItemForNormCumRate(double rate)
Returns the item at the given normalized (between 0 and 1) cumulative rate. Note that all items are sorted, so getItemForNormCumRate(0) would return the first item, and getItemForNormCumRate(1) would return the last item with a non-zero rate

Parameters:
rate -
Returns:

nextItem

public T nextItem()
Returns:
the next randomly selected item

generateSeries

public List<T> generateSeries(int size)
                       throws IllegalArgumentException
Generates a series of randomly selected items.

Parameters:
size - the number of items in the generated series
Returns:
series of randomly selected items
Throws:
IllegalArgumentException - if size is less than or equal to zero