MutableSparseVector (LensKit 2.1-SNAPSHOT)

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<VectorEntry>
```
public final class MutableSparseVector
extends SparseVector
implements java.io.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)).
See Also:
Serialized Form
Compatibility: Public

Method Summary

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(java.util.Collection<java.lang.Long> domain)` Create a new empty mutable sparse vector with the specified key domain.
`static MutableSparseVector`	`create(java.util.Collection<java.lang.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(java.util.Map<java.lang.Long,java.lang.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.
`java.util.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.
`java.util.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.
`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, keyDomain, keysByValue, keysByValue, mean, norm, size, sum, toString, unsetKeySet, values

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - create
```
public static MutableSparseVector create(java.util.Collection<java.lang.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(java.util.Collection<java.lang.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(java.util.Map<java.lang.Long,java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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.
  - clear
```
public void clear()
```
    Clear all values from the set.
  - add
```
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:
    
    java.lang.IllegalArgumentException - if the key is not in the key set.
  - add
```
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.
  - add
```
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.
  - addScaled
```
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.
    See Also:
    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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.IllegalArgumentException - if this vector does not have such a channel at this time.
  - removeAllChannels
```
public void removeAllChannels()
```
    Remove all channels stored in this vector.
  - addChannelVector
```
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:
    
    java.lang.IllegalArgumentException - if there is already a channel with that symbol
  - addChannel
```
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:
    
    java.lang.IllegalArgumentException - if there is already a channel with that symbol
  - getOrAddChannelVector
```
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
  - getOrAddChannel
```
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 java.util.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 java.util.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.

Class MutableSparseVector

Method Summary

Methods inherited from class org.grouplens.lenskit.vectors.SparseVector

Methods inherited from class java.lang.Object

Method Detail

create

create

create

keySet

withDomain

shrinkDomain

set

set

fill

unset

unset

clear

add

add

subtract

add

addScaled

set

multiply

multiply

copy

mutableCopy

immutable

freeze

wrap

wrap

wrap

create

wrapUnsorted

removeChannelVector

removeChannel

removeAllChannels

addChannelVector

addChannel

getOrAddChannelVector

getOrAddChannel

hasChannelVector

hasChannel

getChannelVector

getChannel

getChannelVectorSymbols

getChannelSymbols

combineWith