SparseVector (LensKit 2.2.1)

java.lang.Object
- org.grouplens.lenskit.vectors.SparseVector

All Implemented Interfaces:

Serializable, Iterable<VectorEntry>

Direct Known Subclasses:

ImmutableSparseVector, MutableSparseVector
```
public abstract class SparseVector
extends Object
implements Iterable<VectorEntry>, Serializable
```
Read-only interface to sparse vectors.
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.

See Also:

Sparse Vector tutorial, Serialized Form

Compatibility

Public

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated 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()
```
    Deprecated. Fast iteration is going away.
    
    Fast iterator over all set entries (it can reuse entry objects).
    
    Returns:
    
    a fast iterator over all key/value pairs
    
    See Also:
    
    fastIterator(VectorEntry.State), Long2DoubleMap.FastEntrySet.fastIterator()
  - 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
    
    See Also:
    
    Long2DoubleMap.FastEntrySet.fastIterator()
  - fast
```
@Deprecated
public Iterable<VectorEntry> fast()
```
    Deprecated. Fast iteration is going away.
    
    Return an iterable view of this vector using a fast iterator. This method delegates to fast(VectorEntry.State) with state VectorEntry.State.SET.
    
    Returns:
    
    This object wrapped in an iterable that returns a fast iterator.
    
    See Also:
    
    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
    
    See Also:
    
    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.
    
    See Also:
    
    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.

Class SparseVector

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Method Detail

containsKey

get

get

get

isSet

fastIterator

fastIterator

fast

fast

iterator

iterator

view

keyDomain

keySet

unsetKeySet

keysByValue

values

keysByValue

size

isEmpty

norm

sum

sumAbs

mean

dot

countCommonKeys

combineWith

toString

equals

hashCode

immutable

mutableCopy

hasChannelVector

hasChannel

getChannelVector

getChannel

getChannelVectorSymbols

getChannelSymbols

empty