edu.ucla.sspace.lsa

Class LatentSemanticAnalysis

java.lang.Object

edu.ucla.sspace.common.GenericTermDocumentVectorSpace

edu.ucla.sspace.lsa.LatentSemanticAnalysis

All Implemented Interfaces:

SemanticSpace

public class LatentSemanticAnalysis
extends GenericTermDocumentVectorSpace

An implementation of Latent Semantic Analysis (LSA). This implementation is based on two papers.

• Landauer, T. K., Foltz, P. W., and Laham, D. (1998). Introduction to Latent Semantic Analysis. Discourse Processes, 25, 259-284. Available here
• Landauer, T. K., and Dumais, S. T. (1997). A solution to Plato's problem: The Latent Semantic Analysis theory of the acquisition, induction, and representation of knowledge. Psychological Review, 104, 211-240. Available here

See the Wikipedia page on Latent Semantic Analysis for an execuative summary.

LSA first processes documents into a word-document matrix where each unique word is a assigned a row in the matrix, and each column represents a document. The values of ths matrix correspond to the number of times the row's word occurs in the column's document. After the matrix has been built, the Singular Value Decomposition (SVD) is used to reduce the dimensionality of the original word-document matrix, denoted as A. The SVD is a way of factoring any matrix A into three matrices U Σ V^T such that Σ is a diagonal matrix containing the singular values of A. The singular values of Σ are ordered according to which causes the most variance in the values of A. The original matrix may be approximated by recomputing the matrix with only k of these singular values and setting the rest to 0. The approximated matrix  = U_k Σ_k V_k^T is the least squares best-fit rank-k approximation of A. LSA reduces the dimensions by keeping only the first k dimensions from the row vectors of U. These vectors form the semantic space of the words.

This class offers configurable preprocessing and dimensionality reduction. through three parameters. These properties should be specified in the Properties object passed to the processSpace method.

Property: "edu.ucla.sspace.lsa.LatentSemanticAnalysis.transform"
Default: LogEntropyTransform

This variable sets the preprocessing algorithm to use on the term-document matrix prior to computing the SVD. The property value should be the fully qualified named of a class that implements Transform. The class should be public, not abstract, and should provide a public no-arg constructor.

Property: "edu.ucla.sspace.lsa.LatentSemanticAnalysis.dimensions"
Default: 300

The number of dimensions to use for the semantic space. This value is used as input to the SVD.

Property: "edu.ucla.sspace.lsa.LatentSemanticAnalysis.svd.algorithm"
Default: SVD.Algorithm.ANY

This property sets the specific SVD algorithm that LSA will use to reduce the dimensionality of the word-document matrix. In general, users should not need to set this property, as the default behavior will choose the fastest available on the system.

Property: "edu.ucla.sspace.lsa.LatentSemanticAnalysis.retainDocSpace"
Default: false

This property indicate whether the document space should be retained after processSpace. Setting this property to true will enable the getDocumentVector method.

This class is thread-safe for concurrent calls of processDocument. Once processSpace has been called, no further calls to processDocument should be made. This implementation does not support access to the semantic vectors until after processSpace has been called.

Author:

David Jurgens

See Also:

Transform, SVD

Field Summary

Fields

Modifier and Type	Field and Description
static String	LSA_DIMENSIONS_PROPERTY The property to set the number of dimension to which the space should be reduced using the SVD
static String	LSA_SVD_ALGORITHM_PROPERTY The property to set the specific SVD algorithm used by an instance during processSpace.
static String	MATRIX_TRANSFORM_PROPERTY The property to define the Transform class to be used when processing the space after all the documents have been seen.
static String	RETAIN_DOCUMENT_SPACE_PROPERTY The property whose boolean value indicate whether the document space should be retained after processSpace.

Fields inherited from class edu.ucla.sspace.common.GenericTermDocumentVectorSpace

documentCounter, LOG, wordSpace

Constructor Summary

Constructors

Constructor and Description
LatentSemanticAnalysis() Creates a new LatentSemanticAnalysis instance.
LatentSemanticAnalysis(boolean retainDocumentSpace, int dimensions, Transform transform, MatrixFactorization reducer, boolean readHeaderToken, BasisMapping<String,String> termToIndex) Constructs a new LatentSemanticAnalysis using the provided objects for processing.

Method Summary

Methods

Modifier and Type	Method and Description
int	documentSpaceSize() Returns the number of documents processed by LatentSemanticAnalysis if the document space has been retained.
DoubleVector	getDocumentVector(int documentNumber) Returns the semantics of the document as represented by a numeric vector.
String	getSpaceName() Returns a unique string describing the name and configuration of this algorithm.
void	processSpace(Properties properties) Once all the documents have been processed, performs any post-processing steps on the data.

Methods inherited from class edu.ucla.sspace.common.GenericTermDocumentVectorSpace

getVector, getVectorLength, getWords, handleDocumentHeader, processDocument, processSpace

Methods inherited from class java.lang.Object

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

Field Detail

MATRIX_TRANSFORM_PROPERTY

public static final String MATRIX_TRANSFORM_PROPERTY

The property to define the Transform class to be used when processing the space after all the documents have been seen.

See Also:

Constant Field Values

LSA_DIMENSIONS_PROPERTY

public static final String LSA_DIMENSIONS_PROPERTY

The property to set the number of dimension to which the space should be reduced using the SVD

See Also:

Constant Field Values

LSA_SVD_ALGORITHM_PROPERTY

public static final String LSA_SVD_ALGORITHM_PROPERTY

The property to set the specific SVD algorithm used by an instance during processSpace. The value should be the name of a SVD.Algorithm. If this property is unset, any available algorithm will be used according to the ordering defined in SVD.

See Also:

Constant Field Values

RETAIN_DOCUMENT_SPACE_PROPERTY

public static final String RETAIN_DOCUMENT_SPACE_PROPERTY

The property whose boolean value indicate whether the document space should be retained after processSpace. Setting this property to true will enable the getDocumentVector method.

See Also:

Constant Field Values

Constructor Detail

LatentSemanticAnalysis

public LatentSemanticAnalysis()
                       throws IOException

Creates a new LatentSemanticAnalysis instance. This intializes with the default parameters set in the original paper.

Throws:

IOException

LatentSemanticAnalysis

public LatentSemanticAnalysis(boolean retainDocumentSpace,
                      int dimensions,
                      Transform transform,
                      MatrixFactorization reducer,
                      boolean readHeaderToken,
                      BasisMapping<String,String> termToIndex)
                       throws IOException

Constructs a new LatentSemanticAnalysis using the provided objects for processing.

Parameters:

retainDocumentSpace - If true, the document space will be made accessible

dimensions - The number of dimensions to retain in the reduced space

transform - The Transform to apply before reduction

MatrixFactorization - The MatrixFactorization algorithm to apply to reduce the transformed term document matrix

readHeaderToken - If true, the first token of each document will be read and passed to handleDocumentHeader, which discards the header

termToIndex - The ConcurrentMap used to map strings to indices

Throws:

IOException - if this instance encounters any errors when creatng the backing array files required for processing

Method Detail

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.

getDocumentVector

public DoubleVector getDocumentVector(int documentNumber)

Returns the semantics of the document as represented by a numeric vector. Note that document semantics may be represented in an entirely different space, so the corresponding semantic dimensions in the word space will be completely unrelated. However, document vectors may be compared to find those document with similar content.

Similar to getVector, this method is only to be used after processSpace has been called. By default, the document space is not retained unless retainDocumentSpace is set to true.

Implementation note: If a specific document ordering is needed, caution should be used when using this class in a multi-threaded environment. Beacuse the document number is based on what order it was processed, no guarantee is made that this will correspond with the original document ordering as it exists in the corpus files. However, in a single-threaded environment, the ordering will be preserved.

Parameters:

documentNumber - the number of the document according to when it was processed

Returns:

the semantics of the document in the document space.

Throws:

IllegalArgumentException - If the document space was not retained or the document number is out of range.

documentSpaceSize

public int documentSpaceSize()

Returns the number of documents processed by LatentSemanticAnalysis if the document space has been retained.

Throws:

IllegalArgumentException - If the document space has not been retained.

processSpace

public void processSpace(Properties properties)

Once all the documents have been processed, performs any post-processing steps on the data. An algorithm should treat this as a no-op if no post-processing is required. Callers may specify the values for any exposed parameters using the properties argument.

By general contract, once this method has been called, processDocument will not be called again.

Parameters:

properties - a set of properties and values that may be used to configure any exposed parameters of the algorithm. See this class's javadoc for the full list of supported properties.