edu.stanford.nlp.stats
Class Counter<E>

java.lang.Object
  extended by edu.stanford.nlp.stats.Counter<E>
All Implemented Interfaces:
GenericCounter<E>, Serializable

public class Counter<E>
extends Object
implements Serializable, GenericCounter<E>

A specialized kind of hash table (or map) for storing numeric counts for objects. It works like a Map, but with different methods for easily getting/setting/incrementing counts for objects and computing various functions with the counts. The Counter constructor and addAll method can be used to copy another Counter's contents over. This class also provides access to Comparators that can be used to sort the keys or entries of this Counter by the counts, in either ascending or descending order.

Implementation note: Note that this class stores a totalCount field as well as the map. This makes certain operations much more efficient, but means that any methods that change the map must also update totalCount appropriately. If you use the setCount method, then you cannot go wrong.

Author:
Dan Klein (klein@cs.stanford.edu), Joseph Smarr (jsmarr@stanford.edu), Teg Grenager, Galen Andrew, Christopher Manning, Kayur Patel (kdpatel@cs)
See Also:
Serialized Form

Constructor Summary
Counter()
          Constructs a new (empty) Counter.
Counter(Collection<E> collection)
          Constructs a new Counter by counting the elements in the given Collection.
Counter(GenericCounter<E> c)
          Constructs a new Counter with the contents of the given Counter.
Counter(MapFactory mapFactory)
          Pass in a MapFactory and the map it vends will back your counter.
 
Method Summary
 void addAll(Collection<E> collection)
          Calls incrementCount(key) on each key in the given collection.
 void addAll(GenericCounter<E> counter)
          Adds the counts in the given Counter to the counts in this Counter.
 E argmax()
          Finds and returns the key in this Counter with the largest count.
 E argmax(Comparator<E> tieBreaker)
          Finds and returns the key in this Counter with the largest count.
 E argmin()
          Finds and returns the key in this Counter with the smallest count.
 E argmin(Comparator<E> tieBreaker)
          Finds and returns the key in this Counter with the smallest count.
 BinaryHeapPriorityQueue<E> asBinaryHeapPriorityQueue()
          Builds a priority queue whose elements are the counter's elements, and whose priorities are those elements' counts in the counter.
 PriorityQueue<E> asPriorityQueue()
          Builds a priority queue whose elements are the counter's elements, and whose priorities are those elements' counts in the counter.
 double averageCount()
          Returns the mean of all the counts (totalCount/size).
 void clear()
          Removes all counts from this Counter.
 Object clone()
           
 Comparator comparator()
          Comparator that sorts objects by (increasing) count.
 Comparator comparator(boolean ascending)
          Returns a comparator suitable for sorting this Counter's keys or entries by their respective counts.
 Comparator comparator(boolean ascending, boolean useMagnitude)
          Returns a comparator suitable for sorting this Counter's keys or entries by their respective value or magnitude (unsigned value).
 boolean containsKey(E key)
           
 void decrementCount(E key)
          Subtracts 1.0 from the count for the given key.
 void decrementCount(E key, double count)
          Subtracts the given count from the current count for the given key.
 void decrementCounts(Collection<E> keys)
          Subtracts 1.0 from the counts of each of the given keys.
 void decrementCounts(Collection<E> keys, double count)
          Subtracts the given count from the current counts for each of the given keys.
 void divideBy(Counter<E> counter)
          Divides every non-zero count by the count for the corresponding key in the argument Counter.
 void divideBy(double divisor)
          Divides every count by the given divisor.
 double doubleMax()
          Returns the value of the maximum entry in this counter, as a double.
 Set<Map.Entry<E,MutableDouble>> entrySet()
           
 boolean equals(Object o)
           
 double getCount(E key)
          Returns the current count for the given key, which is 0 if it hasn't been seen before.
 String getCountAsString(E key)
          Returns the count for this key as a String.
 MapFactory getMapFactory()
          Returns the MapFactory used by this counter.
 double getNormalizedCount(E key)
          Return the proportion of the Counter mass under this key.
 int hashCode()
           
 void incrementAll(double count)
          Adds the same amount to every count, that is to every key currently stored in the counter (with no lookups).
 void incrementCount(E key)
          Adds 1.0 to the count for the given key.
 void incrementCount(E key, double count)
          Adds the given count to the current count for the given key.
 void incrementCounts(Collection<E> keys)
          Adds 1.0 to the counts for each of the given keys.
 void incrementCounts(Collection<E> keys, double count)
          Adds the given count to the current counts for each of the given keys.
 boolean isEmpty()
           
 Set<E> keysAbove(double countThreshold)
          Returns the set of keys whose counts are at or above the given threshold.
 Set<E> keysAt(double count)
          Returns the set of keys that have exactly the given count.
 Set<E> keysBelow(double countThreshold)
          Returns the set of keys whose counts are at or below the given threshold.
 Set<E> keySet()
          Returns the Set of keys in this counter.
 void logIncrementCount(E key, double count)
          If the current count for the object is c1, and you call logIncrementCount with a value of c2, then the new value will be log(e^c1 + e^c2).
 void logNormalize()
           
 double logSum()
           
static void main(String[] args)
          For internal debugging purposes only.
 double max()
          Finds and returns the largest count in this Counter.
 double min()
          Finds and returns the smallest count in this Counter.
 void multiplyBy(double multiplier)
          Multiplies every count by the given multiplier.
 void normalize()
          This has been de-deprecated in order to reduce compilation warnings, but really you should create a Distribution instead.
 MutableDouble remove(E key)
          Removes the given key from this Counter.
 void removeAll(Collection<E> keys)
          Removes all the given keys from this Counter.
 void removeZeroCounts()
          Removes all keys whose count is 0.
 void retainTop(int num)
           
 void setCount(E key, double count)
          Sets the current count for the given key.
 void setCount(E key, String s)
          Sets the count for this key to be the number encoded in the given String.
 void setCounts(Collection<E> keys, double count)
          Sets the current count for each of the given keys.
 int size()
          Returns the number of keys stored in the counter.
 void subtractAll(GenericCounter<E> counter, boolean removeZeroKeys)
          Subtracts the counts in the given Counter from the counts in this Counter.
 String toString()
           
 String toString(int maxKeysToPrint)
          Returns a string representation which includes no more than the maxKeysToPrint elements with largest counts.
 String toString(NumberFormat nf)
          Pretty print a Counter.
 String toString(NumberFormat nf, String preAppend, String postAppend, String keyValSeparator, String itemSeparator)
          Pretty print a Counter.
 double totalCount()
          Returns the current total count for all objects in this Counter.
 double totalCount(Filter<E> filter)
          Returns the total count for all objects in this Counter that pass the given Filter.
 double totalDoubleCount()
          Returns the current total count for all objects in this Counter.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Counter

public Counter()
Constructs a new (empty) Counter.


Counter

public Counter(MapFactory mapFactory)
Pass in a MapFactory and the map it vends will back your counter.


Counter

public Counter(GenericCounter<E> c)
Constructs a new Counter with the contents of the given Counter.


Counter

public Counter(Collection<E> collection)
Constructs a new Counter by counting the elements in the given Collection.

Method Detail

getMapFactory

public MapFactory getMapFactory()
Description copied from interface: GenericCounter
Returns the MapFactory used by this counter.

Specified by:
getMapFactory in interface GenericCounter<E>

totalCount

public double totalCount()
Returns the current total count for all objects in this Counter.


totalDoubleCount

public double totalDoubleCount()
Returns the current total count for all objects in this Counter.

Specified by:
totalDoubleCount in interface GenericCounter<E>

totalCount

public double totalCount(Filter<E> filter)
Returns the total count for all objects in this Counter that pass the given Filter. Passing in a filter that always returns true is equivalent to calling totalCount().


logSum

public double logSum()

logNormalize

public void logNormalize()

averageCount

public double averageCount()
Returns the mean of all the counts (totalCount/size).


getCount

public double getCount(E key)
Returns the current count for the given key, which is 0 if it hasn't been seen before. This is a convenient version of get that casts and extracts the primitive value.

Specified by:
getCount in interface GenericCounter<E>

getCountAsString

public String getCountAsString(E key)
Description copied from interface: GenericCounter
Returns the count for this key as a String.

Specified by:
getCountAsString in interface GenericCounter<E>

getNormalizedCount

public double getNormalizedCount(E key)
Return the proportion of the Counter mass under this key. This has been de-deprecated in order to reduce compilation warnings, but really you should create a Distribution instead of using this method.


setCount

public void setCount(E key,
                     double count)
Sets the current count for the given key. This will wipe out any existing count for that key.

To add to a count instead of replacing it, use incrementCount(Object,double).


setCount

public void setCount(E key,
                     String s)
Description copied from interface: GenericCounter
Sets the count for this key to be the number encoded in the given String.

Specified by:
setCount in interface GenericCounter<E>

setCounts

public void setCounts(Collection<E> keys,
                      double count)
Sets the current count for each of the given keys. This will wipe out any existing counts for these keys.

To add to the counts of a collection of objects instead of replacing them, use incrementCounts(Collection, double).


incrementCount

public void incrementCount(E key,
                           double count)
Adds the given count to the current count for the given key. If the key hasn't been seen before, it is assumed to have count 0, and thus this method will set its count to the given amount. Negative increments are equivalent to calling decrementCount.

To more conveniently increment the count by 1.0, use incrementCount(Object).

To set a count to a specifc value instead of incrementing it, use setCount(Object,double).


logIncrementCount

public void logIncrementCount(E key,
                              double count)
If the current count for the object is c1, and you call logIncrementCount with a value of c2, then the new value will be log(e^c1 + e^c2). If the key hasn't been seen before, it is assumed to have count Double.NEGATIVE_INFINITY, and thus this method will set its count to the given amount. To set a count to a specifc value instead of incrementing it, use setCount(Object,double).


incrementCount

public void incrementCount(E key)
Adds 1.0 to the count for the given key. If the key hasn't been seen before, it is assumed to have count 0, and thus this method will set its count to 1.0.

To increment the count by a value other than 1.0, use incrementCount(Object,double).

To set a count to a specifc value instead of incrementing it, use setCount(Object,double).


incrementCounts

public void incrementCounts(Collection<E> keys,
                            double count)
Adds the given count to the current counts for each of the given keys. If any of the keys haven't been seen before, they are assumed to have count 0, and thus this method will set their counts to the given amount. Negative increments are equivalent to calling decrementCounts.

To more conviniently increment the counts of a collection of objects by 1.0, use incrementCounts(Collection).

To set the counts of a collection of objects to a specific value instead of incrementing them, use setCounts(Collection,double).


incrementCounts

public void incrementCounts(Collection<E> keys)
Adds 1.0 to the counts for each of the given keys. If any of the keys haven't been seen before, they are assumed to have count 0, and thus this method will set their counts to 1.0.

To increment the counts of a collection of object by a value other than 1.0, use incrementCounts(Collection,double).

To set the counts of a collection of objects to a specifc value instead of incrementing them, use setCounts(Collection,double).


incrementAll

public void incrementAll(double count)
Adds the same amount to every count, that is to every key currently stored in the counter (with no lookups).

Parameters:
count - The amount to be added

decrementCount

public void decrementCount(E key,
                           double count)
Subtracts the given count from the current count for the given key. If the key hasn't been seen before, it is assumed to have count 0, and thus this method will set its count to the negative of the given amount. Negative increments are equivalent to calling incrementCount.

To more conviently decrement the count by 1.0, use decrementCount(Object).

To set a count to a specifc value instead of decrementing it, use setCount(Object,double).


decrementCount

public void decrementCount(E key)
Subtracts 1.0 from the count for the given key. If the key hasn't been seen before, it is assumed to have count 0, and thus this method will set its count to -1.0.

To decrement the count by a value other than 1.0, use decrementCount(Object,double).

To set a count to a specifc value instead of decrementing it, use setCount(Object,double).


decrementCounts

public void decrementCounts(Collection<E> keys,
                            double count)
Subtracts the given count from the current counts for each of the given keys. If any of the keys haven't been seen before, they are assumed to have count 0, and thus this method will set their counts to the negative of the given amount. Negative increments are equivalent to calling incrementCount.

To more conviniently decrement the counts of a collection of objects by 1.0, use decrementCounts(Collection).

To set the counts of a collection of objects to a specific value instead of decrementing them, use setCounts(Collection,double).


decrementCounts

public void decrementCounts(Collection<E> keys)
Subtracts 1.0 from the counts of each of the given keys. If any of the keys haven't been seen before, they are assumed to have count 0, and thus this method will set their counts to -1.0.

To decrement the counts of a collection of object by a value other than 1.0, use decrementCounts(Collection,double).

To set the counts of a collection of objects to a specifc value instead of decrementing them, use setCounts(Collection,double).


addAll

public void addAll(GenericCounter<E> counter)
Adds the counts in the given Counter to the counts in this Counter.

To copy the values from another Counter rather than adding them, use


addAll

public void addAll(Collection<E> collection)
Calls incrementCount(key) on each key in the given collection.


multiplyBy

public void multiplyBy(double multiplier)
Multiplies every count by the given multiplier.


divideBy

public void divideBy(double divisor)
Divides every count by the given divisor.


divideBy

public void divideBy(Counter<E> counter)
Divides every non-zero count by the count for the corresponding key in the argument Counter. Beware that this can give NaN values for zero counts in the argument counter!

Parameters:
counter - Entries in argument scale individual keys in this counter

subtractAll

public void subtractAll(GenericCounter<E> counter,
                        boolean removeZeroKeys)
Subtracts the counts in the given Counter from the counts in this Counter.

To copy the values from another Counter rather than subtracting them, use


containsKey

public boolean containsKey(E key)
Specified by:
containsKey in interface GenericCounter<E>
Returns:
true iff key is a key in this GenericCounter.

remove

public MutableDouble remove(E key)
Removes the given key from this Counter. Its count will now be 0 and it will no longer be considered previously seen.


removeAll

public void removeAll(Collection<E> keys)
Removes all the given keys from this Counter.


clear

public void clear()
Removes all counts from this Counter.


size

public int size()
Returns the number of keys stored in the counter.

Specified by:
size in interface GenericCounter<E>
Returns:
The number of keys

isEmpty

public boolean isEmpty()

keySet

public Set<E> keySet()
Description copied from interface: GenericCounter
Returns the Set of keys in this counter.

Specified by:
keySet in interface GenericCounter<E>

entrySet

public Set<Map.Entry<E,MutableDouble>> entrySet()

equals

public boolean equals(Object o)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object

toString

public String toString(int maxKeysToPrint)
Returns a string representation which includes no more than the maxKeysToPrint elements with largest counts.

Parameters:
maxKeysToPrint -
Returns:
partial string representation

toString

public String toString(NumberFormat nf,
                       String preAppend,
                       String postAppend,
                       String keyValSeparator,
                       String itemSeparator)
Pretty print a Counter. This one has more flexibility in formatting, and doesn't sort the keys.


toString

public String toString(NumberFormat nf)
Pretty print a Counter. This version tries to sort the keys.


clone

public Object clone()
Overrides:
clone in class Object

normalize

public void normalize()
This has been de-deprecated in order to reduce compilation warnings, but really you should create a Distribution instead.


removeZeroCounts

public void removeZeroCounts()
Removes all keys whose count is 0. After incrementing and decrementing counts or adding and subtracting Counters, there may be keys left whose count is 0, though normally this is undesirable. This method cleans up the map.

Maybe in the future we should try to do this more on-the-fly, though it's not clear whether a distinction should be made between "never seen" (i.e. null count) and "seen with 0 count". Certainly there's no distinction in getCount() but there is in containsKey().


asPriorityQueue

public PriorityQueue<E> asPriorityQueue()
Builds a priority queue whose elements are the counter's elements, and whose priorities are those elements' counts in the counter.


asBinaryHeapPriorityQueue

public BinaryHeapPriorityQueue<E> asBinaryHeapPriorityQueue()
Builds a priority queue whose elements are the counter's elements, and whose priorities are those elements' counts in the counter.


max

public double max()
Finds and returns the largest count in this Counter.


doubleMax

public double doubleMax()
Description copied from interface: GenericCounter
Returns the value of the maximum entry in this counter, as a double.

Specified by:
doubleMax in interface GenericCounter<E>

min

public double min()
Finds and returns the smallest count in this Counter.


argmax

public E argmax(Comparator<E> tieBreaker)
Finds and returns the key in this Counter with the largest count. Ties are broken by comparing the objects using the given tie breaking Comparator, favoring Objects that are sorted to the front. This is useful if the keys are numeric and there is a bias to prefer smaller or larger values, and can be useful in other circumstances where random tie-breaking is not desirable. Returns null if this Counter is empty.


retainTop

public void retainTop(int num)

argmax

public E argmax()
Finds and returns the key in this Counter with the largest count. Ties are broken according to the natural ordering of the objects. This will prefer smaller numeric keys and lexicographically earlier String keys. To use a different tie-breaking Comparator, use argmax(Comparator). Returns null if this Counter is empty.


argmin

public E argmin(Comparator<E> tieBreaker)
Finds and returns the key in this Counter with the smallest count. Ties are broken by comparing the objects using the given tie breaking Comparator, favoring Objects that are sorted to the front. This is useful if the keys are numeric and there is a bias to prefer smaller or larger values, and can be useful in other circumstances where random tie-breaking is not desirable. Returns null if this Counter is empty.


argmin

public E argmin()
Finds and returns the key in this Counter with the smallest count. Ties are broken according to the natural ordering of the objects. This will prefer smaller numeric keys and lexicographically earlier String keys. To use a different tie-breaking Comparator, use argmin(Comparator). Returns null if this Counter is empty.


keysAbove

public Set<E> keysAbove(double countThreshold)
Returns the set of keys whose counts are at or above the given threshold. This set may have 0 elements but will not be null.


keysBelow

public Set<E> keysBelow(double countThreshold)
Returns the set of keys whose counts are at or below the given threshold. This set may have 0 elements but will not be null.


keysAt

public Set<E> keysAt(double count)
Returns the set of keys that have exactly the given count. This set may have 0 elements but will not be null.


comparator

public Comparator comparator(boolean ascending)
Returns a comparator suitable for sorting this Counter's keys or entries by their respective counts. If ascending is true, lower counts will be returned first, otherwise higher counts will be returned first.

Sample usage:

 Counter c = new Counter();
 // add to the counter...
 List biggestKeys = new ArrayList(c.keySet());
 Collections.sort(biggestKeys, c.comparator(false));
 List smallestEntries = new ArrayList(c.entrySet());
 Collections.sort(smallestEntries, c.comparator(true))
 


comparator

public Comparator comparator(boolean ascending,
                             boolean useMagnitude)
Returns a comparator suitable for sorting this Counter's keys or entries by their respective value or magnitude (unsigned value). If ascending is true, smaller magnitudes will be returned first, otherwise higher magnitudes will be returned first.

Sample usage:

 Counter c = new Counter();
 // add to the counter...
 List biggestKeys = new ArrayList(c.keySet());
 Collections.sort(biggestKeys, c.comparator(false, true));
 List smallestEntries = new ArrayList(c.entrySet());
 Collections.sort(smallestEntries, c.comparator(true))
 


comparator

public Comparator comparator()
Comparator that sorts objects by (increasing) count. Shortcut for calling comparator(true).

Specified by:
comparator in interface GenericCounter<E>

main

public static void main(String[] args)
                 throws Exception
For internal debugging purposes only.

Throws:
Exception


Stanford NLP Group