org.grouplens.lenskit.vectors

## Class SparseVector

• All Implemented Interfaces:
Serializable, Iterable<VectorEntry>
Direct Known Subclasses:
ImmutableSparseVector, MutableSparseVector

public abstract class SparseVector
extends Object
implements Iterable<VectorEntry>, Serializable

This vector class works a lot like a map, but it also caches some commonly-used statistics. The values are stored in parallel arrays sorted by key. This allows fast lookup and sorted iteration. All iterators access the items in key order.

Vectors have a key domain, which is a set containing all valid keys in the vector. This key domain is fixed at construction; mutable vectors cannot set values for keys not in this domain. Thinking of the vector as a function from longs to doubles, the key domain would actually be the codomain, and the key set the algebraic domain, but that gets cumbersome to write in code. So think of the key domain as the domain from which valid keys are drawn.

This class provides a read-only interface to sparse vectors. It may actually be a MutableSparseVector, so the data may be modified by code elsewhere that has access to the mutable representation. For sparse vectors that are guaranteed to be unchanging, see ImmutableSparseVector.

Sparse Vector tutorial, Serialized Form
Compatibility
Public
• ### Method Summary

All Methods
Modifier and Type Method and Description
abstract SparseVector combineWith(SparseVector o)
Combine this vector with another vector by taking the union of the key domains of two vectors.
boolean containsKey(long key)
Query whether the vector contains an entry for the key in question.
int countCommonKeys(SparseVector o)
Count the common keys between two vectors.
double dot(SparseVector o)
Compute the dot product between two vectors.
static ImmutableSparseVector empty()
Get an empty sparse vector.
boolean equals(Object o)
Iterable<VectorEntry> fast()
Deprecated.
Fast iteration is going away.
Iterable<VectorEntry> fast(VectorEntry.State state)
Deprecated.
Fast iteration is going away.
Iterator<VectorEntry> fastIterator()
Deprecated.
Fast iteration is going away.
Iterator<VectorEntry> fastIterator(VectorEntry.State state)
Deprecated.
Fast iteration is going away.
double get(long key)
Get the value for key.
double get(long key, double dft)
Get the value for key.
double get(VectorEntry entry)
Get the value for the entry's key.
abstract <K> Long2ObjectMap<K> getChannel(TypedSymbol<K> channelSymbol)
Fetch the channel stored under a particular typed symbol.
abstract Set<TypedSymbol<?>> getChannelSymbols()
Retrieve all symbols that map to typed side channels for this vector.
abstract SparseVector getChannelVector(Symbol channelSymbol)
Get the vector associated with a particular unboxed channel.
abstract Set<Symbol> getChannelVectorSymbols()
Retrieve all symbols that map to side channels for this vector.
abstract boolean hasChannel(TypedSymbol<?> channelSymbol)
Return whether this sparse vector has a channel stored under a particular typed symbol.
abstract boolean hasChannelVector(Symbol channelSymbol)
Return whether this sparse vector has a channel vector stored under a particular symbol.
int hashCode()
abstract ImmutableSparseVector immutable()
Return an immutable snapshot of this sparse vector.
boolean isEmpty()
Query whether this vector is empty.
boolean isSet(VectorEntry entry)
Check whether an entry is set.
Iterator<VectorEntry> iterator()
Iterator<VectorEntry> iterator(VectorEntry.State state)
LongSortedSet keyDomain()
Get the key domain for this vector.
LongArrayList keysByValue()
Return the keys of this vector sorted by value.
LongArrayList keysByValue(boolean decreasing)
Get the keys of this vector sorted by the value of the items stored for each key.
LongSortedSet keySet()
Get the set of keys of this vector.
double mean()
Compute and return the mean of the vector's values.
abstract MutableSparseVector mutableCopy()
Return a mutable copy of this sparse vector.
double norm()
Compute and return the L2 norm (Euclidian length) of the vector.
int size()
Get the size of this vector (the number of keys).
double sum()
Compute and return the L1 norm (sum) of the vector.
double sumAbs()
Compute and return the sum of the absolute values of the vector.
String toString()
LongSortedSet unsetKeySet()
Get the set of unset keys.
DoubleCollection values()
Get the collection of values of this vector.
Collection<VectorEntry> view(VectorEntry.State state)
Get a collection view of a vector entry.
• ### Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
• ### Methods inherited from interface java.lang.Iterable

forEach, spliterator
• ### Method Detail

• #### containsKey

public boolean containsKey(long key)
Query whether the vector contains an entry for the key in question.
Parameters:
key - The key to search for.
Returns:
true if the key exists.
• #### get

public double get(long key)
Get the value for key.
Parameters:
key - the key to look up; the key must be in the key set.
Returns:
the key's value
Throws:
IllegalArgumentException - if key is not in the key set.
• #### get

public double get(long key,
double dft)
Get the value for key.
Parameters:
key - the key to look up
dft - The value to return if the key is not in the vector
Returns:
the value (or dft if the key is not set to a value)
• #### get

public double get(VectorEntry entry)
Get the value for the entry's key.
Parameters:
entry - A VectorEntry with the key to look up
Returns:
the key's value
Throws:
IllegalArgumentException - if the entry is unset, or if it is not from this vector or another vector sharing the same key domain. Only vectors and their side channels share key domains for the purposes of this check.
• #### isSet

public boolean isSet(VectorEntry entry)
Check whether an entry is set.
Parameters:
entry - The entry.
Returns:
true if the entry is set in this vector.
Throws:
IllegalArgumentException - if the entry is not from this vector or another vector sharing the same key domain. Only vectors and their side channels share key domains for the purposes of this check.
• #### fastIterator

@Deprecated
public Iterator<VectorEntry> fastIterator(VectorEntry.State state)
Deprecated. Fast iteration is going away.
Fast iterator over entries (it can reuse entry objects).
Parameters:
state - The state of entries to iterate.
Returns:
a fast iterator over all key/value pairs
Since:
0.11
Long2DoubleMap.FastEntrySet.fastIterator()
• #### fast

@Deprecated
public Iterable<VectorEntry> fast(VectorEntry.State state)
Deprecated. Fast iteration is going away.
Return an iterable view of this vector using a fast iterator.
Parameters:
state - The entries the resulting iterable should return.
Returns:
This object wrapped in an iterable that returns a fast iterator.
Since:
0.11
fastIterator(VectorEntry.State)
• #### iterator

public Iterator<VectorEntry> iterator()
Specified by:
iterator in interface Iterable<VectorEntry>
• #### iterator

public Iterator<VectorEntry> iterator(VectorEntry.State state)
• #### view

public Collection<VectorEntry> view(VectorEntry.State state)
Get a collection view of a vector entry.
Parameters:
state - The state of entries to view.
Returns:
A collection of vector entries.
• #### keyDomain

public LongSortedSet keyDomain()
Get the key domain for this vector. All keys used are in this set. The keys will be in sorted order.
Returns:
The key domain for this vector.
• #### keySet

public LongSortedSet keySet()
Get the set of keys of this vector. It is a subset of the key domain. The keys will be in sorted order.
Returns:
The set of keys used in this vector.
• #### unsetKeySet

public LongSortedSet unsetKeySet()
Get the set of unset keys. This is $$D \\ S$$, where $$D$$ is the key domain and $$S$$ the key set.
• #### keysByValue

public LongArrayList keysByValue()
Return the keys of this vector sorted by value.
Returns:
A list of keys in nondecreasing order of value.
keysByValue(boolean)
• #### values

public DoubleCollection values()
Get the collection of values of this vector.
Returns:
The collection of all values in this vector.
• #### keysByValue

public LongArrayList keysByValue(boolean decreasing)
Get the keys of this vector sorted by the value of the items stored for each key.
Parameters:
decreasing - If true, sort in decreasing order.
Returns:
The sorted list of keys of this vector.
• #### size

public int size()
Get the size of this vector (the number of keys).
Returns:
The number of keys in the vector. This is at most the size of the key domain.
• #### isEmpty

public boolean isEmpty()
Query whether this vector is empty.
Returns:
true if the vector is empty.
• #### norm

public double norm()
Compute and return the L2 norm (Euclidian length) of the vector.
Returns:
The L2 norm of the vector
• #### sum

public double sum()
Compute and return the L1 norm (sum) of the vector.
Returns:
the sum of the vector's values
• #### sumAbs

public double sumAbs()
Compute and return the sum of the absolute values of the vector.
Returns:
the sum of the vector's absolute values
• #### mean

public double mean()
Compute and return the mean of the vector's values.
Returns:
the mean of the vector
• #### dot

public double dot(SparseVector o)
Compute the dot product between two vectors.
Parameters:
o - The other vector.
Returns:
The dot (inner) product between this vector and o.
• #### countCommonKeys

public int countCommonKeys(SparseVector o)
Count the common keys between two vectors.
Parameters:
o - The other vector.
Returns:
The number of keys appearing in both this and the other vector.
• #### combineWith

public abstract SparseVector combineWith(SparseVector o)
Combine this vector with another vector by taking the union of the key domains of two vectors. If both vectors have values the same key, the values in o override those from the current vector.
Parameters:
o - The other vector
Returns:
A vector whose key domain is the union of the key domains of this vector and the other.
• #### toString

public String toString()
Overrides:
toString in class Object
• #### equals

public boolean equals(Object o)
Overrides:
equals in class Object
• #### hashCode

public int hashCode()
Overrides:
hashCode in class Object
• #### immutable

public abstract ImmutableSparseVector immutable()
Return an immutable snapshot of this sparse vector. The new vector's key domain may be shrunk to remove storage of unused keys; no keys in the key set will be removed.
Returns:
An immutable sparse vector whose contents are the same as this vector. If the vector is already immutable, the returned object may be identical.
• #### mutableCopy

public abstract MutableSparseVector mutableCopy()
Return a mutable copy of this sparse vector. The key domain of the mutable vector will be the same as this vector's key domain.
Returns:
A mutable sparse vector which can be modified without modifying this vector.
• #### hasChannelVector

public abstract boolean hasChannelVector(Symbol channelSymbol)
Return whether this sparse vector has a channel vector stored under a particular symbol.
Parameters:
channelSymbol - the symbol under which the channel was stored in the vector.
Returns:
whether this vector has such a channel right now.
• #### hasChannel

public abstract boolean hasChannel(TypedSymbol<?> channelSymbol)
Return whether this sparse vector has a channel stored under a particular typed symbol.
Parameters:
channelSymbol - the typed symbol under which the channel was stored in the vector.
Returns:
whether this vector has such a channel right now.
• #### getChannelVector

public abstract SparseVector getChannelVector(Symbol channelSymbol)
Get the vector associated with a particular unboxed channel.
Parameters:
channelSymbol - the symbol under which the channel was/is stored in the vector.
Returns:
The vector corresponding to the specified unboxed channel, or null if there is no such channel.
• #### getChannel

public abstract <K> Long2ObjectMap<K> getChannel(TypedSymbol<K> channelSymbol)
Fetch the channel stored under a particular typed symbol.
Parameters:
channelSymbol - the typed symbol under which the channel was/is stored in the vector.
Returns:
the channel, which is itself a map from the key domain to objects of the channel's type, or null if there is no such channel.
• #### getChannelVectorSymbols

public abstract Set<Symbol> getChannelVectorSymbols()
Retrieve all symbols that map to side channels for this vector.
Returns:
A set of symbols, each of which identifies a side channel of the vector.
• #### getChannelSymbols

public abstract Set<TypedSymbol<?>> getChannelSymbols()
Retrieve all symbols that map to typed side channels for this vector.
Returns:
A set of symbols, each of which identifies a side channel of the vector.
• #### empty

public static ImmutableSparseVector empty()
Get an empty sparse vector.
Returns:
An empty sparse vector. The vector is immutable, because mutating an empty vector is impossible.