edu.northwestern.at.utils

## Class CountMapUtils

- java.lang.Object
- - edu.northwestern.at.utils.CountMapUtils

-     public class CountMapUtils
      extends java.lang.Object

  Count map utilities.

  Count maps have a key representing items to count and java.lang.Number values as the counts. In many cases, the Number values are of type java.lang.Integer, but this is not necessarily the case. For example, a count map may have strings as keys and java.lang.Double scaled word frequencies as values.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CountMapUtils()` Don't allow instantiation but do allow overrides.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <K> void` | `addCountMap(java.util.Map<K,java.lang.Number> destinationMap, java.util.Map<K,java.lang.Number> sourceMap)` Add words/counts from one map to another.
    `static <K> java.util.Map<K,java.lang.Number>` | `booleanizeCountMap(java.util.Map<K,? extends java.lang.Number> map)` Convert map values to integer 1 or 0.
    `static <V extends java.lang.Number> java.util.Map<java.lang.String,java.lang.Number>` | `convertKeysToStrings(java.util.Map<? extends java.lang.Object,V> countMap)` Convert keys in count map to plain strings.
    `static <K> int` | `getCountOfWordsInCommon(java.util.Map<K,? extends java.lang.Number> countMap1, java.util.Map<K,? extends java.lang.Number> countMap2)` Get count of words which two count maps share.
    `static double[]` | `getSummaryCountsFromCountMap(java.util.Map<? extends java.lang.Object,? extends java.lang.Number> map)` Get summary counts from a count map.
    `static double` | `getSumOfCrossProducts(java.util.Map<? extends java.lang.Object,? extends java.lang.Number> countMap1, java.util.Map<? extends java.lang.Object,? extends java.lang.Number> countMap2)` Get sum of cross products for counts in two maps.
    `static int` | `getTotalWordCount(java.util.Map<? extends java.lang.Object,? extends java.lang.Number> map)` Get total count of words in map.
    `static <K> int` | `getWordCount(java.util.Map<K,? extends java.lang.Number> countMap, K word)` Get count for a specific word form from a count map.
    `static <K> java.util.Set<K>` | `getWordsFromMap(java.util.Map<K,?> map)` Get words from a map.
    `static <K> java.util.List` | `getWordsInCommon(java.util.Map<K,? extends java.lang.Number> countMap1, java.util.Map<K,? extends java.lang.Number> countMap2)` Get list of words which two count maps share.
    `static <K> void` | `incrementCountMap(java.util.Map<K,java.lang.Number> destinationMap, java.util.Map<K,java.lang.Number> sourceMap)` Increment words/counts in one map from another.
    `static java.util.Map<java.lang.String,java.lang.Number>` | `loadCountMapFromFile(java.io.File file)` Load strings and counts into count map from a file.
    `static java.util.Map<java.lang.String,java.lang.Number>` | `loadCountMapFromFile(java.io.File file, java.lang.String encoding)` Load strings and counts into count map from a file.
    `static java.util.Map<java.lang.String,java.lang.Number>` | `loadCountMapFromReader(java.io.Reader reader)` Load strings and counts into count map from a reader.
    `static <K> java.util.Map<K,java.lang.Number>` | `scaleCountMap(java.util.Map<K,? extends java.lang.Number> map, double scaleFactor)` Scale count entries in count map.
    `static <K,V extends java.lang.Number> java.util.Map<java.lang.String,java.lang.Number>` | `semiDeepClone(java.util.Map<K,V> countMap)` Get semi-deep clone of a count map.
    `static java.lang.String[]` | `splitKeyedCountString(java.lang.String s)` Split string at tab character.
    `static <K> void` | `subtractCountMap(java.util.Map<K,java.lang.Number> destinationMap, java.util.Map<K,java.lang.Number> sourceMap)` Subtract words/counts in one map from another.
    `static <K> void` | `updateWordCountMap(K word, int count, java.util.Map<K,java.lang.Number> countMap)` Updates counts for a word in a map.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CountMapUtils

          protected CountMapUtils()

      Don't allow instantiation but do allow overrides.

  - ### Method Detail

    - #### getSummaryCountsFromCountMap

          public static double[] getSummaryCountsFromCountMap(java.util.Map<? extends java.lang.Object,? extends java.lang.Number> map)

      Get summary counts from a count map.
      Parameters:
        `map` - The map with string keys and Number counts as values.
      Returns:
        Three entry double array. result[ 0 ] = sum of counts result[ 1 ] = sum of squared counts result[ 2 ] = unique count (size of map)

    - #### getTotalWordCount

          public static int getTotalWordCount(java.util.Map<? extends java.lang.Object,? extends java.lang.Number> map)

      Get total count of words in map.
      Parameters:
        `map` - The map with string keys and Number counts as values.
      Returns:
        Sum of counts as an integer.

    - #### getSumOfCrossProducts

          public static double getSumOfCrossProducts(java.util.Map<? extends java.lang.Object,? extends java.lang.Number> countMap1,
                                     java.util.Map<? extends java.lang.Object,? extends java.lang.Number> countMap2)

      Get sum of cross products for counts in two maps.
      Parameters:
        `countMap1` - First count map.
        `countMap2` - Second count map.
      Returns:
        sum of cross products as a double.

    - #### booleanizeCountMap

          public static <K> java.util.Map<K,java.lang.Number> booleanizeCountMap(java.util.Map<K,? extends java.lang.Number> map)

      Convert map values to integer 1 or 0.
      Parameters:
        `map` - Count map to booleanize.
      Returns:
        New map containing booleanized count values.

        Non-zero counts are converted to integer 1, 0 counts are converted to integer 0.

    - #### scaleCountMap

          public static <K> java.util.Map<K,java.lang.Number> scaleCountMap(java.util.Map<K,? extends java.lang.Number> map,
                                                            double scaleFactor)

      Scale count entries in count map.
      Parameters:
        `map` - The count map.
        `scaleFactor` - The double value by which to multiply each count value in the count map.
      Returns:
        Map with same keys as input map and counts scaled using scaleFactor.

    - #### getWordsFromMap

          public static <K> java.util.Set<K> getWordsFromMap(java.util.Map<K,?> map)

      Get words from a map.
      Parameters:
        `map` - The map with arbitrary objects as keys and Number counts as values.
      Returns:
        Keys as a set.

    - #### splitKeyedCountString

          public static java.lang.String[] splitKeyedCountString(java.lang.String s)

      Split string at tab character.
      Parameters:
        `s` - The string to split into a key and a count.
      Returns:
        Two element string array with the key and count.

    - #### addCountMap

          public static <K> void addCountMap(java.util.Map<K,java.lang.Number> destinationMap,
                             java.util.Map<K,java.lang.Number> sourceMap)

      Add words/counts from one map to another.
      Parameters:
        `destinationMap` - Destination map.
        `sourceMap` - Source map.

        On output, the destination map is updated with words and counts from the source map. The key type for both input maps must be the same for this to make sense.

    - #### incrementCountMap

          public static <K> void incrementCountMap(java.util.Map<K,java.lang.Number> destinationMap,
                                   java.util.Map<K,java.lang.Number> sourceMap)

      Increment words/counts in one map from another.
      Parameters:
        `destinationMap` - Destination map.
        `sourceMap` - Source map.

        The key types for the two input maps must be the same.

        On output, the destination map counts are incremented by one for each word appearing in the source map. If a source word does not already appear in the destination, it is added with a count of one.

    - #### subtractCountMap

          public static <K> void subtractCountMap(java.util.Map<K,java.lang.Number> destinationMap,
                                  java.util.Map<K,java.lang.Number> sourceMap)

      Subtract words/counts in one map from another.
      Parameters:
        `destinationMap` - Destination map.
        `sourceMap` - Source map.

        The key types for the two input maps must be the same.

        On output, the destination map counts are updated by removing the counts for matching words from the source map. If the count goes to zero for any word in the destination, that word is removed from from the destination map.

    - #### getWordsInCommon

          public static <K> java.util.List getWordsInCommon(java.util.Map<K,? extends java.lang.Number> countMap1,
                                            java.util.Map<K,? extends java.lang.Number> countMap2)

      Get list of words which two count maps share.
      Parameters:
        `countMap1` - First count map.
        `countMap2` - Second count map.
      Returns:
        List of words appearing in both maps.

    - #### getCountOfWordsInCommon

          public static <K> int getCountOfWordsInCommon(java.util.Map<K,? extends java.lang.Number> countMap1,
                                        java.util.Map<K,? extends java.lang.Number> countMap2)

      Get count of words which two count maps share.
      Parameters:
        `countMap1` - First count map.
        `countMap2` - Second count map.
      Returns:
        Count of words appearing in both maps. The key type for the two maps should be the same for this to make sense.

    - #### getWordCount

          public static <K> int getWordCount(java.util.Map<K,? extends java.lang.Number> countMap,
                             K word)

      Get count for a specific word form from a count map.
      Parameters:
        `countMap` - The word count map.
        `word` - The word text.
      Returns:
        The count for the specified word as an integer, 0 if the word does not occur.

    - #### updateWordCountMap

          public static <K> void updateWordCountMap(K word,
                                    int count,
                                    java.util.Map<K,java.lang.Number> countMap)

      Updates counts for a word in a map.
      Parameters:
        `word` - The word.
        `count` - The word count.
        `countMap` - The word count map.

    - #### convertKeysToStrings

          public static <V extends java.lang.Number> java.util.Map<java.lang.String,java.lang.Number> convertKeysToStrings(java.util.Map<? extends java.lang.Object,V> countMap)

      Convert keys in count map to plain strings.
      Parameters:
        `countMap` - The count map whose keys should be converted to strings.
      Returns:
        The count map with keys converted to plain strings.

        Each key element's toString() method is called to convert the key object to a plain text string. Key elements without a toString() method will not be added to the result map. The object values (counts) are left untouched. Note that no key should be null. Null keys will be ignored.

    - #### loadCountMapFromReader

          public static java.util.Map<java.lang.String,java.lang.Number> loadCountMapFromReader(java.io.Reader reader)
                                                                                         throws java.io.IOException,
                                                                                                InvalidDataException

      Load strings and counts into count map from a reader.
      Parameters:
        `reader` - The reader.
      Returns:
        Count map.
      Throws:
        `java.io.IOException` - when an I/O error occurs while reading the input.
        `InvalidDataException` - when an input line is badly structured (too many or too few tokens) or the count token cannot be converted to an integer.

        Each line of the input file has one string, followed by an Ascii tab character, followed by an integer count.

    - #### loadCountMapFromFile

          public static java.util.Map<java.lang.String,java.lang.Number> loadCountMapFromFile(java.io.File file,
                                                                              java.lang.String encoding)
                                                                                       throws java.io.IOException,
                                                                                              InvalidDataException

      Load strings and counts into count map from a file.
      Parameters:
        `file` - The file.
        `encoding` - Character encoding for file.
      Returns:
        Count map.
      Throws:
        `java.io.IOException` - when an I/O error occurs while reading the input.
        `InvalidDataException` - when an input line is badly structured (too many or too few tokens) or the count token cannot be converted to an integer.

        Each line of the input file has one string, followed by an Ascii tab character, followed by a count. The counts may be integers or floating point values.

    - #### loadCountMapFromFile

          public static java.util.Map<java.lang.String,java.lang.Number> loadCountMapFromFile(java.io.File file)
                                                                                       throws java.io.IOException,
                                                                                              InvalidDataException

      Load strings and counts into count map from a file.
      Parameters:
        `file` - The file.
      Returns:
        Count map.
      Throws:
        `java.io.IOException` - when an I/O error occurs while reading the input.
        `InvalidDataException` - when an input line is badly structured (too many or too few tokens) or the count token cannot be converted to an integer.

        Each line of the input file has one string, followed by an Ascii tab character, followed by a count. The counts may be integers or floating point values. The input file is assumed to be in utf-8 format.

    - #### semiDeepClone

          public static <K,V extends java.lang.Number> java.util.Map<java.lang.String,java.lang.Number> semiDeepClone(java.util.Map<K,V> countMap)

      Get semi-deep clone of a count map.
      Parameters:
        `countMap` - The count map to clone.
      Returns:
        Semi-deep clone of the count map.

        A semi-deep clone creates a new count map by duplicating each count value and creating new string keys using "toString()" on the original map's key values. For a count map with string keys, this produces a deep clone. For a count map with non-string keys, this produces what might be called a semi-deep clone, since only the string values of the original keys are duplicated.