org.grouplens.lenskit.vectors

## Class MutableSparseVector

• All Implemented Interfaces:
Serializable, Iterable<VectorEntry>

public final class MutableSparseVector
extends SparseVector
implements Serializable
Mutable version of sparse vector.

This class extends the sparse vector with support for imperative mutation operations on their values.

Once created the domain of potential keys remains immutable. Since the vector is sparse, keys can be added, but only within the domain the vector was constructed with. These vectors separate the concepts of the key set, which is the current set of active keys from the key domain, which is the set of potential keys. Of course, the key domain must always include the key set.

Addition and subtraction are supported, though they are modified from the mathematical operations because they never change the set of keys. Mutation operations also operate in-place to reduce the reallocation and copying required. Therefore, a common pattern is:

 MutableSparseVector normalized = vector.mutableCopy();
normalized.subtract(normFactor);


Create mutable sparse vectors using the various create static methods provided (create(java.util.Collection), create(java.util.Collection, double), create(long...), create(java.util.Map)).

Serialized Form
Compatibility
Public
• ### Method Summary

All Methods
Modifier and Type Method and Description
void add(double value)
Add a value to all set keys in this array.
double add(long key, double value)
Add a value to the specified entry.
void add(SparseVector other)
Add another rating vector to this one.
<K> Long2ObjectMap<K> addChannel(TypedSymbol<K> channelSymbol)
Add a typed channel to this vector.
MutableSparseVector addChannelVector(Symbol channelSymbol)
Add a channel to this vector.
void addScaled(SparseVector v, double scale)
Add a vector to this vector with a scaling factor.
void clear()
Clear all values from the set.
MutableSparseVector combineWith(SparseVector o)
Combine this vector with another vector by taking the union of the key domains of two vectors.
MutableSparseVector copy()
Copy the rating vector.
static MutableSparseVector create(Collection<Long> domain)
Create a new empty mutable sparse vector with the specified key domain.
static MutableSparseVector create(Collection<Long> domain, double value)
Create a new mutable sparse vector with the specified key domain and filled with a value.
static MutableSparseVector create(long... keys)
Create a mutable sparse vector with a fixed set of keys.
static MutableSparseVector create(Map<Long,Double> content)
Create a new mutable sparse vector with the specified content.
void fill(double value)
Set the values for all items in the key domain to value.
ImmutableSparseVector freeze()
Construct an immutable sparse vector from this vector's data (if possible), invalidating this vector in the process.
<K> Long2ObjectMap<K> getChannel(TypedSymbol<K> channelSymbol)
Fetch the channel stored under a particular typed symbol.
Set<TypedSymbol<?>> getChannelSymbols()
Retrieve all symbols that map to typed side channels for this vector.
MutableSparseVector getChannelVector(Symbol channelSymbol)
Get the vector associated with a particular unboxed channel.
Set<Symbol> getChannelVectorSymbols()
Retrieve all symbols that map to side channels for this vector.
<K> Long2ObjectMap<K> getOrAddChannel(TypedSymbol<K> channelSymbol)
Add a typed channel to the vector, even if there is already a channel with the same symbol.
MutableSparseVector getOrAddChannelVector(Symbol channelSymbol)
Add a channel to the vector, even if there is already a channel with the same symbol.
boolean hasChannel(TypedSymbol<?> channelSymbol)
Return whether this sparse vector has a channel stored under a particular typed symbol.
boolean hasChannelVector(Symbol channelSymbol)
Return whether this sparse vector has a channel vector stored under a particular symbol.
ImmutableSparseVector immutable()
Return an immutable snapshot of this sparse vector.
LongSortedSet keySet()
Get the set of keys of this vector.
void multiply(double s)
Multiply the vector by a scalar.
void multiply(SparseVector other)
Multiply each element in the vector by the corresponding element in another vector.
MutableSparseVector mutableCopy()
Return a mutable copy of this sparse vector.
void removeAllChannels()
Remove all channels stored in this vector.
<K> Long2ObjectMap<K> removeChannel(TypedSymbol<K> channelSymbol)
Remove the typed channel stored under a particular symbol.
SparseVector removeChannelVector(Symbol channelSymbol)
Remove the channel stored under a particular symbol.
double set(long key, double value)
Set a value in the vector.
void set(SparseVector other)
Set the values in this SparseVector to equal the values in other for each key that is present in both vectors.
double set(VectorEntry entry, double value)
Set the value in the vector corresponding to a vector entry.
MutableSparseVector shrinkDomain()
Create a new version of this MutableSparseVector that has keyDomain equal to this vector's key set.
void subtract(SparseVector other)
Subtract another rating vector from this one.
void unset(long key)
Unset the value for a key.
void unset(VectorEntry entry)
Unset the value for a vector entry.
void unsetLessThan(double thresh)
Unset all values less than a threshold.
MutableSparseVector withDomain(LongSet keyDomain)
Create a new version of this MutableSparseVector that has a different domain from the current version of the vector.
static MutableSparseVector wrap(long[] keys, double[] values)
Wrap key and value arrays in a sparse vector.
static MutableSparseVector wrap(long[] keys, double[] values, int size)
Wrap key and value arrays in a sparse vector.
static MutableSparseVector wrap(LongArrayList keyList, DoubleArrayList valueList)
Wrap key and value array lists in a mutable sparse vector.
static MutableSparseVector wrapUnsorted(long[] keys, double[] values)
Create a new MutableSparseVector from unsorted key and value arrays.
• ### Methods inherited from class org.grouplens.lenskit.vectors.SparseVector

containsKey, countCommonKeys, dot, empty, equals, fast, fast, fastIterator, fastIterator, get, get, get, hashCode, isEmpty, isSet, iterator, iterator, keyDomain, keysByValue, keysByValue, mean, norm, size, sum, sumAbs, toString, unsetKeySet, values, view
• ### 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

• #### create

public static MutableSparseVector create(Collection<Long> domain)
Create a new empty mutable sparse vector with the specified key domain.
Parameters:
domain - The key domain. This method is more efficient if you pass some form of LongCollection, particularly a LongSortedSet.
Returns:
A mutable sparse vector with the specified domain and no active keys.
• #### create

public static MutableSparseVector create(Collection<Long> domain,
double value)
Create a new mutable sparse vector with the specified key domain and filled with a value.
Parameters:
domain - The key domain. This method is more efficient if you pass some form of LongCollection, particularly a LongSortedSet.
value - The value to fill the vector with.
Returns:
A mutable sparse vector with the specified domain and no active keys.
• #### create

public static MutableSparseVector create(Map<Long,Double> content)
Create a new mutable sparse vector with the specified content.
Parameters:
content - The content of the vector. Pass a Long2DoubleMap for more efficiency. It may not contain any null values.
Returns:
The content.
• #### keySet

public LongSortedSet keySet()
Description copied from class: SparseVector
Get the set of keys of this vector. It is a subset of the key domain. The keys will be in sorted order.
Overrides:
keySet in class SparseVector
Returns:
The set of keys used in this vector.
• #### withDomain

public MutableSparseVector withDomain(LongSet keyDomain)
Create a new version of this MutableSparseVector that has a different domain from the current version of the vector. All elements in the current vector that are also in the new keyDomain are copied over into the new vector.

Channels from the current vector are copied over to the new vector, all with the changed keyDomain.

Parameters:
keyDomain - the set of keys to use for the domain of the new vector.
Returns:
the new copy of the vector.
• #### shrinkDomain

public MutableSparseVector shrinkDomain()
Create a new version of this MutableSparseVector that has keyDomain equal to this vector's key set. All elements in the current vector that are also in the new keyDomain are copied over into the new vector. Channels from the current vector are copied over to the new vector, all with the changed keyDomain.

Note: the domain of this vector is not changed.

Returns:
the new vector with a contracted domain.
• #### set

public double set(long key,
double value)
Set a value in the vector.
Parameters:
key - The key of the value to set.
value - The value to set.
Returns:
The original value, or Double.NaN if the key had no value (or if the original value was Double.NaN).
Throws:
IllegalArgumentException - if the key is not in the domain for this sparse vector.
• #### set

public double set(@Nonnull
VectorEntry entry,
double value)
Set the value in the vector corresponding to a vector entry. This is used in lieu of providing a setValue method on VectorEntry, and changes the value in constant time. The value on the entry is also changed to reflect the new value. Is guaranteed to work on any vector that has an identical set of keys as the vector from which the VectorEntry was created (such as the channels of that vector), but may throw an IllegalArgumentException if the keys are not an identical object even if they are the same value, to permit more efficient implementations.
Parameters:
entry - The entry to update.
value - The new value.
Returns:
The old value.
Throws:
IllegalArgumentException - if entry does not come from this vector, or if the index in the entry is corrupt.
• #### fill

public void fill(double value)
Set the values for all items in the key domain to value.
Parameters:
value - The value to set.
• #### unset

public void unset(long key)
Unset the value for a key. The key remains in the key domain, but is removed from the key set.
Parameters:
key - The key to unset.
Throws:
IllegalArgumentException - if the key is not in the key domain.
• #### unset

public void unset(@Nonnull
VectorEntry entry)
Unset the value for a vector entry. The key remains in the domain, but is removed from the key set.
Parameters:
entry - The entry to unset.
• #### unsetLessThan

public void unsetLessThan(double thresh)
Unset all values less than a threshold.
Parameters:
thresh - The threshold.
• #### clear

public void clear()
Clear all values from the set.

public double add(long key,
double value)
Add a value to the specified entry. The key must be in the key set.
Parameters:
key - The key whose value should be added.
value - The value to increase it by.
Returns:
The new value.
Throws:
IllegalArgumentException - if the key is not in the key set.

public void add(double value)
Add a value to all set keys in this array.
Parameters:
value - The value to add.
• #### subtract

public void subtract(SparseVector other)
Subtract another rating vector from this one.

After calling this method, every element of this vector has been decreased by the corresponding element in other. Elements with no corresponding element are unchanged.

Parameters:
other - The vector to subtract.

public void add(SparseVector other)
Add another rating vector to this one.

After calling this method, every element of this vector has been increased by the corresponding element in other. Elements with no corresponding element are unchanged.

Parameters:
other - The vector to add.

public void addScaled(SparseVector v,
double scale)
Add a vector to this vector with a scaling factor. It multiplies v by the scaling factor scale and adds it to this vector. Only keys set in both v and this are modified. The scaling is done on-the-fly; v is unmodified.
Parameters:
v - The vector to add to this vector.
scale - The scaling factor to be applied to the vector.
• #### set

public void set(SparseVector other)
Set the values in this SparseVector to equal the values in other for each key that is present in both vectors.

After calling this method, every element in this vector that has a key in other has its value set to the corresponding value in other. Elements with no corresponding key are unchanged, and elements in other that are not in this vector are not inserted.

Parameters:
other - The vector to blit its values into this vector
• #### multiply

public void multiply(double s)
Multiply the vector by a scalar. This multiples every element in the vector by s.
Parameters:
s - The scalar to rescale the vector by.
• #### multiply

public void multiply(SparseVector other)
Multiply each element in the vector by the corresponding element in another vector. Elements not in the other vector are left unchanged.
Parameters:
other - The vector to pairwise-multiply with this one.
• #### copy

public MutableSparseVector copy()
Copy the rating vector.
Returns:
A new rating vector which is a copy of this one.
• #### mutableCopy

public MutableSparseVector mutableCopy()
Description copied from class: SparseVector
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.
Specified by:
mutableCopy in class SparseVector
Returns:
A mutable sparse vector which can be modified without modifying this vector.
• #### immutable

public ImmutableSparseVector immutable()
Description copied from class: SparseVector
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.
Specified by:
immutable in class SparseVector
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.
• #### freeze

public ImmutableSparseVector freeze()
Construct an immutable sparse vector from this vector's data (if possible), invalidating this vector in the process. Any subsequent use of this vector is invalid; all access must be through the returned immutable vector. The frozen vector's key domain is equal to this vector's key set.
Returns:
An immutable vector built from this vector's data.
immutable()
• #### wrap

public static MutableSparseVector wrap(long[] keys,
double[] values)
Wrap key and value arrays in a sparse vector.

This method allows a new vector to be constructed from pre-created arrays. After wrapping arrays in a sparse vector, client code should not modify them (particularly the keys array). The key domain of the newly created vector will be the same as the keys.

Parameters:
keys - Array of entry keys. This array must be in sorted order and be duplicate-free.
values - The values for the vector, in key order.
Returns:
A sparse vector backed by the provided arrays.
Throws:
IllegalArgumentException - if there is a problem with the provided arrays (length mismatch, keys not sorted, etc.).
• #### wrap

public static MutableSparseVector wrap(long[] keys,
double[] values,
int size)
Wrap key and value arrays in a sparse vector.

This method allows a new vector to be constructed from pre-created arrays. After wrapping arrays in a sparse vector, client code should not modify them (particularly the keys array). The key domain of the newly created vector will be the same as the keys.

Parameters:
keys - Array of entry keys. This array must be in sorted order and be duplicate-free.
values - The values for the vector.
size - The size of the vector; only the first size entries from each array are actually used.
Returns:
A sparse vector backed by the provided arrays.
Throws:
IllegalArgumentException - if there is a problem with the provided arrays (length mismatch, keys not sorted, etc.).
• #### wrap

public static MutableSparseVector wrap(LongArrayList keyList,
DoubleArrayList valueList)
Wrap key and value array lists in a mutable sparse vector. Don't modify the original lists once this has been called! There must be at least as many values as keys. The value list will be truncated to the length of the key list.
Parameters:
keyList - The list of keys
valueList - The list of values
Returns:
A backed by the backing stores of the provided lists.
• #### create

public static MutableSparseVector create(long... keys)
Create a mutable sparse vector with a fixed set of keys. This is mostly useful for tests.
Parameters:
keys - The key domain.
Returns:
A mutable sparse vector with the specified keys in its domain, all unset.
• #### wrapUnsorted

public static MutableSparseVector wrapUnsorted(long[] keys,
double[] values)
Create a new MutableSparseVector from unsorted key and value arrays. The provided arrays will be modified and should not be used by the client after this operation has completed. The key domain of the new MutableSparseVector will be the same as keys.
Parameters:
keys - Array of entry keys. This should be duplicate-free.
values - The values of the vector, in key order.
Returns:
A sparse vector backed by the provided arrays.
Throws:
IllegalArgumentException - if there is a problem with the provided arrays (length mismatch, etc.).
• #### removeChannelVector

public SparseVector removeChannelVector(Symbol channelSymbol)
Remove the channel stored under a particular symbol.
Parameters:
channelSymbol - the symbol under which the channel was stored in the vector.
Returns:
the channel, which is itself a sparse vector.
Throws:
IllegalArgumentException - if this vector does not have such a channel at this time.
• #### removeChannel

public <K> Long2ObjectMap<K> removeChannel(TypedSymbol<K> channelSymbol)
Remove the typed channel stored under a particular symbol.
Parameters:
channelSymbol - the symbol under which the channel was stored in the vector.
Returns:
the channel
Throws:
IllegalArgumentException - if this vector does not have such a channel at this time.
• #### removeAllChannels

public void removeAllChannels()
Remove all channels stored in this vector.

public MutableSparseVector addChannelVector(Symbol channelSymbol)
Add a channel to this vector. The new channel will be empty, and will have the same key domain as this vector.
Parameters:
channelSymbol - the symbol under which this new channel should be created.
Returns:
the newly created channel
Throws:
IllegalArgumentException - if there is already a channel with that symbol

public <K> Long2ObjectMap<K> addChannel(TypedSymbol<K> channelSymbol)
Add a typed channel to this vector. The new channel will be empty, and will have the same key domain as this vector.
Parameters:
channelSymbol - the symbol under which this new channel should be created.
Returns:
the newly created channel
Throws:
IllegalArgumentException - if there is already a channel with that symbol

public MutableSparseVector getOrAddChannelVector(Symbol channelSymbol)
Add a channel to the vector, even if there is already a channel with the same symbol. If there already was such a channel it will be unchanged; otherwise a new empty channel will be created with the same key domain as this vector.
Parameters:
channelSymbol - the symbol under which this new channel should be created.
Returns:
the newly created channel

public <K> Long2ObjectMap<K> getOrAddChannel(TypedSymbol<K> channelSymbol)
Add a typed channel to the vector, even if there is already a channel with the same symbol. The new channel will be empty, and will have the same key domain as this vector.
Parameters:
channelSymbol - the symbol under which this new channel should be created.
Returns:
the newly created channel
• #### hasChannelVector

public boolean hasChannelVector(Symbol channelSymbol)
Description copied from class: SparseVector
Return whether this sparse vector has a channel vector stored under a particular symbol.
Specified by:
hasChannelVector in class SparseVector
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 boolean hasChannel(TypedSymbol<?> channelSymbol)
Description copied from class: SparseVector
Return whether this sparse vector has a channel stored under a particular typed symbol.
Specified by:
hasChannel in class SparseVector
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 MutableSparseVector getChannelVector(Symbol channelSymbol)
Description copied from class: SparseVector
Get the vector associated with a particular unboxed channel.
Specified by:
getChannelVector in class SparseVector
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 <K> Long2ObjectMap<K> getChannel(TypedSymbol<K> channelSymbol)
Description copied from class: SparseVector
Fetch the channel stored under a particular typed symbol.
Specified by:
getChannel in class SparseVector
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 Set<Symbol> getChannelVectorSymbols()
Description copied from class: SparseVector
Retrieve all symbols that map to side channels for this vector.
Specified by:
getChannelVectorSymbols in class SparseVector
Returns:
A set of symbols, each of which identifies a side channel of the vector.
• #### getChannelSymbols

public Set<TypedSymbol<?>> getChannelSymbols()
Description copied from class: SparseVector
Retrieve all symbols that map to typed side channels for this vector.
Specified by:
getChannelSymbols in class SparseVector
Returns:
A set of symbols, each of which identifies a side channel of the vector.
• #### combineWith

public MutableSparseVector combineWith(SparseVector o)
Description copied from class: SparseVector
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.
Specified by:
combineWith in class SparseVector
Parameters:
o - The other vector
Returns:
A vector whose key domain is the union of the key domains of this vector and the other.