public abstract class SparseVector extends java.lang.Object implements java.lang.Iterable<VectorEntry>, java.io.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
.
Compatibility: Public
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(java.lang.Object o) |
java.lang.Iterable<VectorEntry> |
fast()
Return an iterable view of this vector using a fast iterator.
|
java.lang.Iterable<VectorEntry> |
fast(VectorEntry.State state)
Return an iterable view of this vector using a fast iterator.
|
java.util.Iterator<VectorEntry> |
fastIterator()
Fast iterator over all set entries (it can reuse entry objects).
|
java.util.Iterator<VectorEntry> |
fastIterator(VectorEntry.State state)
Fast iterator over entries (it can reuse entry objects).
|
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 java.util.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 java.util.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.
|
java.util.Iterator<VectorEntry> |
iterator() |
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.
|
java.lang.String |
toString() |
LongSortedSet |
unsetKeySet()
Get the set of unset keys.
|
DoubleCollection |
values()
Get the collection of values of this vector.
|
public boolean containsKey(long key)
key
- The key to search for.true
if the key exists.public double get(long key)
key
- the key to look up; the key must be in the key set.java.lang.IllegalArgumentException
- if key is not in the key set.public double get(long key, double dft)
key
- the key to look updft
- The value to return if the key is not in the vectorpublic double get(VectorEntry entry)
entry
- A VectorEntry
with the key to look upjava.lang.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.public boolean isSet(VectorEntry entry)
entry
- The entry.true
if the entry is set in this vector.java.lang.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.public java.util.Iterator<VectorEntry> fastIterator()
fastIterator(VectorEntry.State)
,
Long2DoubleMap.FastEntrySet.fastIterator()
public java.util.Iterator<VectorEntry> fastIterator(VectorEntry.State state)
state
- The state of entries to iterate.Long2DoubleMap.FastEntrySet.fastIterator()
public java.lang.Iterable<VectorEntry> fast()
fast(VectorEntry.State)
with state VectorEntry.State.SET
.fastIterator()
public java.lang.Iterable<VectorEntry> fast(VectorEntry.State state)
state
- The entries the resulting iterable should return.fastIterator(VectorEntry.State)
public java.util.Iterator<VectorEntry> iterator()
iterator
in interface java.lang.Iterable<VectorEntry>
public LongSortedSet keyDomain()
public LongSortedSet keySet()
public LongSortedSet unsetKeySet()
public LongArrayList keysByValue()
keysByValue(boolean)
public DoubleCollection values()
public LongArrayList keysByValue(boolean decreasing)
decreasing
- If true
, sort in decreasing order.public int size()
public boolean isEmpty()
true
if the vector is empty.public double norm()
public double sum()
public double mean()
public double dot(SparseVector o)
o
- The other vector.public int countCommonKeys(SparseVector o)
o
- The other vector.public abstract SparseVector combineWith(SparseVector o)
o
override those from the
current vector.o
- The other vectorpublic java.lang.String toString()
toString
in class java.lang.Object
public boolean equals(java.lang.Object o)
equals
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public abstract ImmutableSparseVector immutable()
public abstract MutableSparseVector mutableCopy()
public abstract boolean hasChannelVector(Symbol channelSymbol)
channelSymbol
- the symbol under which the channel was
stored in the vector.public abstract boolean hasChannel(TypedSymbol<?> channelSymbol)
channelSymbol
- the typed symbol under which the channel was
stored in the vector.public abstract SparseVector getChannelVector(Symbol channelSymbol)
channelSymbol
- the symbol under which the channel was/is
stored in the vector.null
if
there is no such channel.public abstract <K> Long2ObjectMap<K> getChannel(TypedSymbol<K> channelSymbol)
channelSymbol
- the typed symbol under which the channel was/is
stored in the vector.null
if there is no such channel.public abstract java.util.Set<Symbol> getChannelVectorSymbols()
public abstract java.util.Set<TypedSymbol<?>> getChannelSymbols()
public static ImmutableSparseVector empty()