org.dishevelled.weighted
Interface WeightedMap<E>

Type Parameters:

E - the type of elements maintained by this weighted map

All Superinterfaces:

Map<E,Double>

All Known Implementing Classes:

HashWeightedMap

public interface WeightedMap<E>
extends Map<E,Double>

A map of elements to weights with sampling and ranking functionality.

 WeightedMap<String> m = new HashWeightedMap<String>();
 m.put("foo", 100.0d);
 m.put("bar", 500.0d);
 m.put("baz", 1000.0d);

 assert(m.get("foo") == 100.0d);
 assert(m.weight("foo") == 100.0d);
 assert(m.totalWeight() == 1600.0d);
 assert(m.normalizedWeight("foo") == 0.0625d);
 assert(m.rank("baz") == 1);
 assert(m.rank("bar") == 2);
 assert(m.rank("foo") == 3);

 List<String> list = new ArrayList<String>(100);
 for (int i = 0; i < 100; i++) {
     list.add(m.sample());
 }

 assert(cardinality in list of "foo" approximately equal to 6.25)
 assert(cardinality in list of "bar" approximately equal to 31.25)
 assert(cardinality in list of "baz" approximately equal to 62.5)
 

Version:

$Revision: 1059 $ $Date: 2012-01-03 14:03:02 -0600 (Tue, 03 Jan 2012) $

Author:

Michael Heuer, Mark Schreiber

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

int	maximumRank() Return the maximum rank in this weighted map.
Double	normalizedWeight(E e) Return the normalized weight for the specified element in this weighted map.
int	rank(E e) Return an integer rank for the specified element in this weighted map based on its weight.
E	sample() Randomly sample an element from this weighted map according to its normalized weight.
Double	totalWeight() Return the sum of the weights in this weighted map.
Double	weight(E e) Return the weight for the specified element in this weighted map.

Methods inherited from interface java.util.Map

clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, values

Method Detail

sample

E sample()

Randomly sample an element from this weighted map according to its normalized weight.

Returns:

a random element from this weighted map according to its normalized weight, or null if this weighted map is empty or if the total weight is zero

See Also:

totalWeight(), normalizedWeight(E)

weight

Double weight(E e)

Return the weight for the specified element in this weighted map. Returns the same value as get(E e).

Parameters:

e - element

Returns:

the weight for the specified element in this weighted map, or null if this weighted map is empty

normalizedWeight

Double normalizedWeight(E e)

Return the normalized weight for the specified element in this weighted map.

Parameters:

e - element

Returns:

the normalized weight for the specified element in this weighted map, or null if this weighted map is empty

totalWeight

Double totalWeight()

Return the sum of the weights in this weighted map.

Returns:

the sum of the weights in this weighted map

rank

int rank(E e)

Return an integer rank for the specified element in this weighted map based on its weight.

Parameters:

e - element

Returns:

an integer rank for the specified element in this weighted map based on its weight, or -1 if this weighted map is empty or if e is not an element in this weighted map

maximumRank

int maximumRank()

Return the maximum rank in this weighted map.

Returns:

the maximum integer rank in this weighted map or -1 if this weighted map is empty