IncrementalSemanticAnalysis (S-Space Package 2.0.1 API)

java.lang.Object
- edu.ucla.sspace.isa.IncrementalSemanticAnalysis

All Implemented Interfaces:

SemanticSpace
```
public class IncrementalSemanticAnalysis
extends Object
implements SemanticSpace
```
An implementation of Incremental Semantic Analysis (ISA). This implementation is based on the following paper.
- M. Baroni, A. Lenci and L. Onnis. 2007. ISA meets Lara: An incremental word space model for cognitively plausible simulations of semantic learning. Proceedings of the ACL 2007 Workshop on Cognitive Aspects of Computational Language Acquisition, East Stroudsburg PA: ACL. 49-56. Available here
ISA is notable in that it builds semantics incrementally using both information from the co-occurrence of a word and the semantics of the co-occurring word. Similar to Random Indexing (RI), ISA uses index vectors to reduce the number of dimensions needed to represent the full co-occurrence matrix. In contrast, other semantic space algorithms such as RI, HAL and BEAGLE, ISA uses the semantics of the co-occurring words to update the semantics of their neighbors. Formally, the semantics of a word w_i are updated for the co-occurrence of another word w_j as:
sem(w_i) += i · (m_c · sem(w_j) + (1 - m_c) · IV(w_j))

where sem is the semantics for a word, and IV is the index vector for a word. i defines the impact rate, which is how much the co-occurrence affects the semantics. m_c defines the degree to which the semantics affect the co-occurring word's semantics. This weighting factor is based on the frequency of occurrence; the semantics of frequently occurring words cause less impact. m_c is formally defined as 1 ÷ e^{freq(word) ÷ k_m}, where k_m is a weighting factor for determing how quickly the semantic of a a word diminish in their affect on co-occurring words.
This class defines the following configurable properties that may be set using either the System properties or using the IncrementalSemanticAnalysis(Properties) constructor. The two most important properties for configuring ISA are "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.impactRate" and "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.historyDecayRate". The values that these properties set have been initialized to the values specified in Baroni et al.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.impactRate"
Default: 0.003
This property specifies the impact rate of co-occurrence, which specifies to what degree does the co-occurrence of one word affect the semantics of the other. This rate affects both the impact of the index vector for a co-occurring word as well as the impact of the semantics.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.historyDecayRate"
Default: 100.0
This property specifies the decay rate at which the semantics of co-occurring words lessen their impact. A word's frequency of occurrence is combined with the history decay rate to indicate the degree to which the word's semantics will influence (i.e. be added to) the semantics of a co-occurring word. High values will cause the semantics of frequently occurring words to have minimal impact on other words' semantics.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.windowSize"
Default: 5
This property sets the number of words before and after that are counted as co-occurring. With the default value, 5 words are counted before and 5 words are counter after. This class always uses a symmetric window.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.vectorLength"
Default: 1800
This property sets the number of dimensions to be used for the index and semantic vectors.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.usePermutations"
Default: false
This property specifies whether to enable permuting the index vectors of co-occurring words. Enabling this option will cause the word semantics to include word-ordering information. However this option is best used with a larger corpus.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.permutationFunction"
Default: DefaultPermutationFunction
This property specifies the fully qualified class name of a PermutationFunction instance that will be used to permute index vectors. If the "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.usePermutations" is set to false, the value of this property has no effect.

Property: "edu.ucla.sspace.isa.IncrementalSemanticAnalysis.sparseSemantics"
Default: false
This property specifies whether to use a sparse encoding for each word's semantics. Using a sparse encoding can result in a large saving in memory, while requiring more time to process each document.

Due to the incremental nature of ISA, instance of this class are not designed to be multi-threaded. Documents must be processed sequentially to properly model how the semantics of co-occurring words affect each other. Multi-threading would induce an ambiguous ordering to co-occurrence.
Author:

David Jurgens

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`DEFAULT_HISTORY_DECAY_RATE` The default rate at which the history (semantics) decays when affecting other co-occurring word's semantics.
`static double`	`DEFAULT_IMPACT_RATE` The default rate at which the co-occurrence of a word affects the semantics.
`static int`	`DEFAULT_VECTOR_LENGTH` The default number of dimensions to be used by the index and semantic vectors.
`static int`	`DEFAULT_WINDOW_SIZE` The default number of words to view before and after each word in focus.
`static String`	`HISTORY_DECAY_RATE_PROPERTY` The property to specify the decay rate for determing how much the history (semantics) of a word will affect the semantics of co-occurring words.
`static String`	`IMPACT_RATE_PROPERTY` The property to specify the impact rate of word co-occurrence.
`static String`	`PERMUTATION_FUNCTION_PROPERTY` The property to specify the fully qualified named of a `PermutationFunction` if using permutations is enabled.
`static String`	`USE_PERMUTATIONS_PROPERTY` The property to specify whether the index vectors for co-occurrent words should be permuted based on their relative position.
`static String`	`USE_SPARSE_SEMANTICS_PROPERTY` Specifies whether to use a sparse encoding for each word's semantics, which saves space when words do not co-occur with many unique tokens, but requires more computation.
`static String`	`VECTOR_LENGTH_PROPERTY` The property to specify the number of dimensions to be used by the index and semantic vectors.
`static String`	`WINDOW_SIZE_PROPERTY` The property to specify the number of words to view before and after each word in focus.

Constructor Summary

Constructors
Constructor and Description
`IncrementalSemanticAnalysis()` Creates a new `IncrementalSemanticAnalysis` instance using the current `System` properties for configuration.
`IncrementalSemanticAnalysis(Properties properties)` Creates a new `IncrementalSemanticAnalysis` instance using the provided properties for configuration.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearSemantics()` Removes all associations between word and semantics while still retaining the word to index vector mapping.
`String`	`getSpaceName()` Returns a unique string describing the name and configuration of this algorithm.
`Vector`	`getVector(String word)` Returns the semantic vector for the provided word.
`int`	`getVectorLength()` Returns the length of vectors in this semantic space.
`Set<String>`	`getWords()` Returns the set of words that are represented in this semantic space.
`Map<String,TernaryVector>`	`getWordToIndexVector()` Returns an unmodifiable view on the token to `IntegerVector` mapping used by this instance.
`void`	`processDocument(BufferedReader document)` Processes the contents of the provided file as a document.
`void`	`processSpace(Properties properties)` Does nothing, as ISA in an incremental algorithm and no final processing needs to be performed on the space.
`void`	`setWordToIndexVector(Map<String,TernaryVector> m)` Assigns the token to `IntegerVector` mapping to be used by this instance.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - HISTORY_DECAY_RATE_PROPERTY
```
public static final String HISTORY_DECAY_RATE_PROPERTY
```
    The property to specify the decay rate for determing how much the history (semantics) of a word will affect the semantics of co-occurring words.
    
    See Also:
    Constant Field Values
  - IMPACT_RATE_PROPERTY
```
public static final String IMPACT_RATE_PROPERTY
```
    The property to specify the impact rate of word co-occurrence.
    
    See Also:
    Constant Field Values
  - PERMUTATION_FUNCTION_PROPERTY
```
public static final String PERMUTATION_FUNCTION_PROPERTY
```
    The property to specify the fully qualified named of a PermutationFunction if using permutations is enabled.
    
    See Also:
    Constant Field Values
  - USE_PERMUTATIONS_PROPERTY
```
public static final String USE_PERMUTATIONS_PROPERTY
```
    The property to specify whether the index vectors for co-occurrent words should be permuted based on their relative position.
    
    See Also:
    Constant Field Values
  - VECTOR_LENGTH_PROPERTY
```
public static final String VECTOR_LENGTH_PROPERTY
```
    The property to specify the number of dimensions to be used by the index and semantic vectors.
    
    See Also:
    Constant Field Values
  - WINDOW_SIZE_PROPERTY
```
public static final String WINDOW_SIZE_PROPERTY
```
    The property to specify the number of words to view before and after each word in focus.
    
    See Also:
    Constant Field Values
  - USE_SPARSE_SEMANTICS_PROPERTY
```
public static final String USE_SPARSE_SEMANTICS_PROPERTY
```
    Specifies whether to use a sparse encoding for each word's semantics, which saves space when words do not co-occur with many unique tokens, but requires more computation.
    
    See Also:
    Constant Field Values
  - DEFAULT_HISTORY_DECAY_RATE
```
public static final double DEFAULT_HISTORY_DECAY_RATE
```
    The default rate at which the history (semantics) decays when affecting other co-occurring word's semantics.
    
    See Also:
    Constant Field Values
  - DEFAULT_IMPACT_RATE
```
public static final double DEFAULT_IMPACT_RATE
```
    The default rate at which the co-occurrence of a word affects the semantics.
    
    See Also:
    Constant Field Values
  - DEFAULT_VECTOR_LENGTH
```
public static final int DEFAULT_VECTOR_LENGTH
```
    The default number of dimensions to be used by the index and semantic vectors.
    
    See Also:
    Constant Field Values
  - DEFAULT_WINDOW_SIZE
```
public static final int DEFAULT_WINDOW_SIZE
```
    The default number of words to view before and after each word in focus.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - IncrementalSemanticAnalysis
```
public IncrementalSemanticAnalysis()
```
    Creates a new IncrementalSemanticAnalysis instance using the current System properties for configuration.
  - IncrementalSemanticAnalysis
```
public IncrementalSemanticAnalysis(Properties properties)
```
    Creates a new IncrementalSemanticAnalysis instance using the provided properties for configuration.
    
    Parameters:
    properties - the properties that specify the configuration for this instance
- Method Detail
  - clearSemantics
```
public void clearSemantics()
```
    Removes all associations between word and semantics while still retaining the word to index vector mapping. This method can be used to re-use the same mapping on multiple corpora while keeping the same semantic space.
  - getSpaceName
```
public String getSpaceName()
```
    Returns a unique string describing the name and configuration of this algorithm. Any configurable parameters that would affect the resulting semantic space should be expressed as a part of this name.
    
    Specified by:
    
    getSpaceName in interface SemanticSpace
  - getVector
```
public Vector getVector(String word)
```
    Returns the semantic vector for the provided word.
    
    Specified by:
    
    getVector in interface SemanticSpace
    
    Parameters:
    word - a word that may be in the semantic space
    
    Returns:
    The Vector for the provided word or null if the word was not in the space.
  - getVectorLength
```
public int getVectorLength()
```
    Returns the length of vectors in this semantic space. Implementations are left free to define whether the returned value is valid before processSpace is called.
    
    Specified by:
    
    getVectorLength in interface SemanticSpace
  - getWordToIndexVector
```
public Map<String,TernaryVector> getWordToIndexVector()
```
    Returns an unmodifiable view on the token to IntegerVector mapping used by this instance. Any further changes made by this instance to its token to IntegerVector mapping will be reflected in the return map.
    
    Returns:
    a mapping from the current set of tokens to the index vector used to represent them
  - getWords
```
public Set<String> getWords()
```
    Returns the set of words that are represented in this semantic space.
    
    Specified by:
    
    getWords in interface SemanticSpace
    
    Returns:
    the set of words that are represented in this semantic space.
  - processDocument
```
public void processDocument(BufferedReader document)
                     throws IOException
```
    Processes the contents of the provided file as a document. Note that this method is not thread safe.
    
    Specified by:
    
    processDocument in interface SemanticSpace
    
    Parameters:
    document - a reader that allows access to the text of the document
    
    Throws:
    
    IOException - if any error occurs while reading the document
  - processSpace
```
public void processSpace(Properties properties)
```
    Does nothing, as ISA in an incremental algorithm and no final processing needs to be performed on the space.
    
    Specified by:
    
    processSpace in interface SemanticSpace
    
    Parameters:
    properties - a set of properties and values that may be used to configure any exposed parameters of the algorithm.
  - setWordToIndexVector
```
public void setWordToIndexVector(Map<String,TernaryVector> m)
```
    Assigns the token to IntegerVector mapping to be used by this instance. The contents of the map are copied, so any additions of new index words by this instance will not be reflected in the parameter's mapping.
    
    Parameters:
    m - a mapping from token to the IntegerVector that should be used represent it when calculating other word's semantics

Class IncrementalSemanticAnalysis

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

HISTORY_DECAY_RATE_PROPERTY

IMPACT_RATE_PROPERTY

PERMUTATION_FUNCTION_PROPERTY

USE_PERMUTATIONS_PROPERTY

VECTOR_LENGTH_PROPERTY

WINDOW_SIZE_PROPERTY

USE_SPARSE_SEMANTICS_PROPERTY

DEFAULT_HISTORY_DECAY_RATE

DEFAULT_IMPACT_RATE

DEFAULT_VECTOR_LENGTH

DEFAULT_WINDOW_SIZE

Constructor Detail

IncrementalSemanticAnalysis

IncrementalSemanticAnalysis

Method Detail

clearSemantics

getSpaceName

getVector

getVectorLength

getWordToIndexVector

getWords

processDocument

processSpace

setWordToIndexVector