com.aliasi.matrix
Class SparseFloatVector

java.lang.Object
  extended by com.aliasi.matrix.AbstractVector
      extended by com.aliasi.matrix.SparseFloatVector
All Implemented Interfaces:
Vector, Serializable

public class SparseFloatVector
extends AbstractVector
implements Serializable

A SparseFloatVector implements an immutable sparse vector with values represented as single-precision floating point numbers. Sparse vectors are specified in terms of mappings from integer dimensions to single-precision floating-point values. The constructor allows the number of dimensions to be set, or to be inferred as the largest dimension with a value in the mapping. Dimensions for which no value is specified in the map provided to the constructor will have values of 0.0.

A deep copy is made of the map provided to the constructor, so that changes to the specified map do not affect this vector and changes to this vector do not affect the map.

Implementation Note: The underlying data is stored in a pair of parallel arrays, one containing integer indexes and the other values of type float. The constructor computes and stores the fixed number of dimensions. The constructor also stores the length of the vector by walking over the values. Dot products between sparse vectors are computed at double-precision by walking over the indices and doing a merge, which is the most efficient approach if the vectors are roughly the same size. Dot products with other vector implementations are computed by iterating over the indexes in the sparse vector and looking up the corresponding values in the argument vector. Cosines are computed by dividing dot products by lengths.

Equality versus other sparse float vectors only considers indexes with values. Hash codes also only consider indexes with values, computing a shift and mask as well as an integer multiply and add for each dimension.

Since:
LingPipe3.1
Version:
3.8
Author:
Bob Carpenter
See Also:
Serialized Form

Constructor Summary
SparseFloatVector(int[] keys, float[] values, int numDimensions)
          Construct a sparse floating point vector with the specified keys defined at the specified values with the specified number of dimensions.
SparseFloatVector(Map<Integer,? extends Number> map)
          Construct a sparse vector from the specified map.
SparseFloatVector(Map<Integer,? extends Number> map, int numDimensions)
          Constructs a sparse vector from the specified map with the specified number of dimensions.
 
Method Summary
 Vector add(Vector v)
          Returns the result of adding the specified vector to this vector.
 double cosine(Vector v)
          Returns the cosine of this vector and the specified vector.
 double dotProduct(Vector v)
          Returns the dot product (inner product) of this vector with the specified vector.
 boolean equals(Object that)
          Returns true if the specified object is a vector with the same dimensionality and values as this vector.
 int hashCode()
          Returns the hash code for this sparse float vector.
 void increment(double scale, Vector v)
          This operation is not supported for sparse vectors.
 double length()
          Returns the length of this vector.
 int[] nonZeroDimensions()
          Returns the array of dimensions that have non-zero values.
 int numDimensions()
          Returns the number of dimensions of this vector.
 String toString()
           
 double value(int dimension)
          The value of this vector for the specified dimension.
 
Methods inherited from class com.aliasi.matrix.AbstractVector
setValue
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SparseFloatVector

public SparseFloatVector(Map<Integer,? extends Number> map)
Construct a sparse vector from the specified map. The dimensionality will be fixed to the largest integer with a value specified in the map. See the class documentation for information details.

Parameters:
map - Mapping from dimensions to values.
Throws:
IllegalArgumentException - If there are negative keys.

SparseFloatVector

public SparseFloatVector(Map<Integer,? extends Number> map,
                         int numDimensions)
Constructs a sparse vector from the specified map with the specified number of dimensions. See the class documentation for further implementation details.

Parameters:
map - Mapping from dimensions to values.
numDimensions - Number of dimensions for the constructed vector.
Throws:
IllegalArgumentException - If there are negative keys, or if the specified number of dimensions is negative, or if the specified number of dimensions is not greater than or equal to the largest integer key.

SparseFloatVector

public SparseFloatVector(int[] keys,
                         float[] values,
                         int numDimensions)
Construct a sparse floating point vector with the specified keys defined at the specified values with the specified number of dimensions. The keys must be non-negative and sorted in ascending order, no two keys may be equal, and no key may be equal to or greater than the number of dimensions.

Parameters:
keys - Array of keys indicating the defined dimensions.
values - Array of values for specified dimensions.
numDimensions - The dimensionality of the constructed vector.
Throws:
IllegalArgumentException - If the keys are not in ascending order, if a key is negative, if two keys are the same, or if a key is greater than or equal to the number of dimensions.
Method Detail

numDimensions

public int numDimensions()
Description copied from class: AbstractVector
Returns the number of dimensions of this vector. Concrete subclasses must implement at least this method and AbstractVector.value(int).

Specified by:
numDimensions in interface Vector
Specified by:
numDimensions in class AbstractVector
Returns:
The number of dimensions of this vector.

nonZeroDimensions

public int[] nonZeroDimensions()
Returns the array of dimensions that have non-zero values. This method may return dimensions with zero values if this vector was initialized with zero values.

Warning:The ret8urned array is the actual set of dimensions used for this vector implementation, so should not be modified. Modifications result in a vector in an illegal states if the dimensions don't remain sorted and within the range of the dimensionality of this vector.

Specified by:
nonZeroDimensions in interface Vector
Overrides:
nonZeroDimensions in class AbstractVector
Returns:
The dimensions with non-zero values.

increment

public void increment(double scale,
                      Vector v)
This operation is not supported for sparse vectors.

Specified by:
increment in interface Vector
Overrides:
increment in class AbstractVector
Parameters:
scale - Ignored.
v - Ignored.
Throws:
UnsupportedOperationException - Always.

toString

public String toString()
Overrides:
toString in class Object

value

public double value(int dimension)
Description copied from class: AbstractVector
The value of this vector for the specified dimension. Concrete subclasses must implement at least this method and AbstractVector.numDimensions().

Specified by:
value in interface Vector
Specified by:
value in class AbstractVector
Parameters:
dimension - Dimension whose value is returned.
Returns:
Value of this vector for the specified dimension.

length

public double length()
Description copied from class: AbstractVector
Returns the length of this vector.

the implementation iterates over the dimensions once accessing each value.

Specified by:
length in interface Vector
Overrides:
length in class AbstractVector
Returns:
The length of this vector.

add

public Vector add(Vector v)
Description copied from class: AbstractVector
Returns the result of adding the specified vector to this vector.

Implementation Note: The result is a dense vector and this method iterates over the dimensions adding. Subclasses may override this with a more specific implementation and then fall back on this implementation for the general case.

Specified by:
add in interface Vector
Overrides:
add in class AbstractVector
Parameters:
v - Vector to add to this vector.
Returns:
The result of adding the specified vector to this vector.

dotProduct

public double dotProduct(Vector v)
Description copied from class: AbstractVector
Returns the dot product (inner product) of this vector with the specified vector.

Implementation Note: This method iterates over the dimensions, accessing values for this vector and the specified vector for each dimension.

Specified by:
dotProduct in interface Vector
Overrides:
dotProduct in class AbstractVector
Parameters:
v - The specified vector.
Returns:
The dot product of this vector with the specified vector.

equals

public boolean equals(Object that)
Returns true if the specified object is a vector with the same dimensionality and values as this vector.

Implementation Note: This method requires a get and comparison for each dimension with a non-zero value in this vector.

Specified by:
equals in interface Vector
Overrides:
equals in class AbstractVector
Parameters:
that - Specified object.
Returns:
true if the specified object is a vector with the same dimensionality and values as this vector.

hashCode

public int hashCode()
Returns the hash code for this sparse float vector. The hash code is the same as it would be for the equivalent dense vector.

Implementation Note: hashing requires a long integer shift and mask, as well as a normal integer multiply and add for each dimension with a value.

Specified by:
hashCode in interface Vector
Overrides:
hashCode in class AbstractVector
Returns:
The hash code for this sparse float vector.

cosine

public double cosine(Vector v)
Description copied from class: AbstractVector
Returns the cosine of this vector and the specified vector.

Implementation Note: This method iterates over the dimensions once and accesses the value of each vector once per dimension.

Specified by:
cosine in interface Vector
Overrides:
cosine in class AbstractVector
Parameters:
v - The specified vector.
Returns:
The cosine of this vector with the specified vector.