org.apache.mahout.math
Interface Vector

All Superinterfaces:
java.lang.Cloneable
All Known Implementing Classes:
AbstractMatrix.TransposeViewVector, AbstractVector, DenseVector, RandomAccessSparseVector, SequentialAccessSparseVector, VectorView

public interface Vector
extends java.lang.Cloneable

The basic interface including numerous convenience functions

NOTE: All implementing classes must have a constructor that takes an int for cardinality and a no-arg constructor that can be used for marshalling the Writable instance

NOTE: Implementations may choose to reuse the Vector.Element in the Iterable methods


Nested Class Summary
static interface Vector.Element
          A holder for information about a specific item in the Vector.
 
Method Summary
 void addTo(Vector v)
          Add the elements to the other vector and results are stored in that vector.
 double aggregate(BinaryFunction aggregator, UnaryFunction map)
          Examples speak louder than words: aggregate(plus, pow(2)) is another way to say getLengthSquared(), aggregate(max, abs) is norm(Double.POSITIVE_INFINITY).
 double aggregate(Vector other, BinaryFunction aggregator, BinaryFunction combiner)
          Generalized inner product - take two vectors, iterate over them both, using the combiner to combine together (and possibly map in some way) each pair of values, which are then aggregated with the previous accumulated value in the combiner.
 java.lang.String asFormatString()
           
 Vector assign(BinaryFunction f, double y)
          Apply the function to each element of the receiver, using the y value as the second argument of the BinaryFunction
 Vector assign(double value)
          Assign the value to all elements of the receiver
 Vector assign(double[] values)
          Assign the values to the receiver
 Vector assign(UnaryFunction function)
          Apply the function to each element of the receiver
 Vector assign(Vector other)
          Assign the other matrix values to the receiver
 Vector assign(Vector other, BinaryFunction function)
          Apply the function to each element of the receiver and the corresponding element of the other argument
 Vector clone()
          Return a copy of the recipient
 Matrix cross(Vector other)
          Return the cross product of the receiver and the other vector
 Vector divide(double x)
          Return a new matrix containing the values of the recipient divided by the argument
 double dot(Vector x)
          Return the dot product of the recipient and the argument
 double get(int index)
          Return the value at the given index
 double get(java.lang.String label)
          Return the value at the index defined by the label
 double getDistanceSquared(Vector v)
          Get the square of the distance between this vector and the other vector.
 Vector.Element getElement(int index)
          Return an object of Vector.Element representing an element of this Vector.
 java.util.Map<java.lang.String,java.lang.Integer> getLabelBindings()
          Return a map of the current label bindings of the receiver
 double getLengthSquared()
          Return the sum of squares of all elements in the vector.
 java.lang.String getName()
          Vectors may have a name associated with them, which makes them easy to identify
 int getNumNondefaultElements()
          Return the number of values in the recipient
 double getQuick(int index)
          Return the value at the given index, without checking bounds
 java.util.Iterator<Vector.Element> iterateAll()
          Iterates over all elements

* NOTE: Implementations may choose to reuse the Element returned for performance reasons, so if you need a copy of it, you should call getElement(int) for the given index

 java.util.Iterator<Vector.Element> iterateNonZero()
          Iterates over all non-zero elements.
 Vector like()
          Return an empty matrix of the same underlying class as the receiver
 Vector like(int cardinality)
          Return an empty matrix of the same underlying class as the receiver and of the given cardinality
 double maxValue()
           
 int maxValueIndex()
           
 Vector minus(Vector x)
          Return a new matrix containing the element by element difference of the recipient and the argument
 double norm(double power)
          Return the k-norm of the vector.
 Vector normalize()
          Return a new matrix containing the normalized (L_2 norm) values of the recipient
 Vector normalize(double power)
          Return a new Vector containing the normalized (L_power norm) values of the recipient.
 Vector plus(double x)
          Return a new matrix containing the sum of each value of the recipient and the argument
 Vector plus(Vector x)
          Return a new matrix containing the element by element sum of the recipient and the argument
 void set(int index, double value)
          Set the value at the given index
 void set(java.lang.String label, double value)
          Set the value at the index that is mapped to the label
 void set(java.lang.String label, int index, double value)
          Set the value at the index and add the label to the bindings
 void setLabelBindings(java.util.Map<java.lang.String,java.lang.Integer> bindings)
          Sets a map of label bindings in the receiver
 void setName(java.lang.String name)
          Set a name for this vector.
 void setQuick(int index, double value)
          Set the value at the given index, without checking bounds
 int size()
          Return the cardinality of the recipient (the maximum number of values)
 Vector times(double x)
          Return a new matrix containing the product of each value of the recipient and the argument
 Vector times(Vector x)
          Return a new matrix containing the element-wise product of the recipient and the argument
 Vector viewPart(int offset, int length)
          Return a new matrix containing the subset of the recipient
 double zSum()
          Return the sum of all the elements of the receiver
 

Method Detail

getName

java.lang.String getName()
Vectors may have a name associated with them, which makes them easy to identify

Returns:
The name, or null if one has not been set

setName

void setName(java.lang.String name)
Set a name for this vector. Need not be unique in a set of Vectors, but probably is more useful if it is. In other words, Mahout does not check for uniqueness.

Parameters:
name - The name

asFormatString

java.lang.String asFormatString()
Returns:
a formatted String suitable for output

assign

Vector assign(double value)
Assign the value to all elements of the receiver

Parameters:
value - a double value
Returns:
the modified receiver

assign

Vector assign(double[] values)
Assign the values to the receiver

Parameters:
values - a double[] of values
Returns:
the modified receiver
Throws:
CardinalityException - if the cardinalities differ

assign

Vector assign(Vector other)
Assign the other matrix values to the receiver

Parameters:
other - a Vector
Returns:
the modified receiver
Throws:
CardinalityException - if the cardinalities differ

assign

Vector assign(UnaryFunction function)
Apply the function to each element of the receiver

Parameters:
function - a UnaryFunction to apply
Returns:
the modified receiver

assign

Vector assign(Vector other,
              BinaryFunction function)
Apply the function to each element of the receiver and the corresponding element of the other argument

Parameters:
other - a Vector containing the second arguments to the function
function - a BinaryFunction to apply
Returns:
the modified receiver
Throws:
CardinalityException - if the cardinalities differ

assign

Vector assign(BinaryFunction f,
              double y)
Apply the function to each element of the receiver, using the y value as the second argument of the BinaryFunction

Parameters:
f - a BinaryFunction to be applied
y - a double value to be argument to the function
Returns:
the modified receiver

size

int size()
Return the cardinality of the recipient (the maximum number of values)

Returns:
an int

clone

Vector clone()
Return a copy of the recipient

Returns:
a new Vector

iterateAll

java.util.Iterator<Vector.Element> iterateAll()
Iterates over all elements

* NOTE: Implementations may choose to reuse the Element returned for performance reasons, so if you need a copy of it, you should call getElement(int) for the given index

Returns:
An Iterator over all elements

iterateNonZero

java.util.Iterator<Vector.Element> iterateNonZero()
Iterates over all non-zero elements.

NOTE: Implementations may choose to reuse the Element returned for performance reasons, so if you need a copy of it, you should call getElement(int) for the given index

Returns:
An Iterator over all non-zero elements

get

double get(java.lang.String label)
           throws IndexException,
                  UnboundLabelException
Return the value at the index defined by the label

Parameters:
label - a String label that maps to an index
Returns:
the double at the index
Throws:
IndexException - if the index is out of bounds
UnboundLabelException - if the label is unbound

getLabelBindings

java.util.Map<java.lang.String,java.lang.Integer> getLabelBindings()
Return a map of the current label bindings of the receiver

Returns:
a Map

getElement

Vector.Element getElement(int index)
Return an object of Vector.Element representing an element of this Vector. Useful when designing new iterator types.

Parameters:
index - Index of the Vector.Element required
Returns:
The Vector.Element Object

divide

Vector divide(double x)
Return a new matrix containing the values of the recipient divided by the argument

Parameters:
x - a double value
Returns:
a new Vector

dot

double dot(Vector x)
Return the dot product of the recipient and the argument

Parameters:
x - a Vector
Returns:
a new Vector
Throws:
CardinalityException - if the cardinalities differ

get

double get(int index)
Return the value at the given index

Parameters:
index - an int index
Returns:
the double at the index
Throws:
IndexException - if the index is out of bounds

getQuick

double getQuick(int index)
Return the value at the given index, without checking bounds

Parameters:
index - an int index
Returns:
the double at the index

like

Vector like()
Return an empty matrix of the same underlying class as the receiver

Returns:
a Vector

like

Vector like(int cardinality)
Return an empty matrix of the same underlying class as the receiver and of the given cardinality

Parameters:
cardinality - an int specifying the desired cardinality
Returns:
a Vector

minus

Vector minus(Vector x)
Return a new matrix containing the element by element difference of the recipient and the argument

Parameters:
x - a Vector
Returns:
a new Vector
Throws:
CardinalityException - if the cardinalities differ

normalize

Vector normalize()
Return a new matrix containing the normalized (L_2 norm) values of the recipient

Returns:
a new Vector

normalize

Vector normalize(double power)
Return a new Vector containing the normalized (L_power norm) values of the recipient.

See http://en.wikipedia.org/wiki/Lp_space

Technically, when 0 < power < 1, we don't have a norm, just a metric, but we'll overload this here.

Also supports power == 0 (number of non-zero elements) and power = Double.POSITIVE_INFINITY (max element). Again, see the Wikipedia page for more info

Parameters:
power - The power to use. Must be >= 0. May also be Double.POSITIVE_INFINITY. See the Wikipedia link for more on this.
Returns:
a new Vector

norm

double norm(double power)
Return the k-norm of the vector.

See http://en.wikipedia.org/wiki/Lp_space

Technically, when 0 > power < 1, we don't have a norm, just a metric, but we'll overload this here. Also supports power == 0 (number of non-zero elements) and power = Double.POSITIVE_INFINITY (max element). Again, see the Wikipedia page for more info.

Parameters:
power - The power to use.
See Also:
normalize(double)

maxValue

double maxValue()
Returns:
The maximum value in the Vector

maxValueIndex

int maxValueIndex()
Returns:
The index of the maximum value

plus

Vector plus(double x)
Return a new matrix containing the sum of each value of the recipient and the argument

Parameters:
x - a double
Returns:
a new Vector

plus

Vector plus(Vector x)
Return a new matrix containing the element by element sum of the recipient and the argument

Parameters:
x - a Vector
Returns:
a new Vector
Throws:
CardinalityException - if the cardinalities differ

set

void set(java.lang.String label,
         double value)
         throws IndexException,
                UnboundLabelException
Set the value at the index that is mapped to the label

Parameters:
label - a String label that maps to an index
value - the double value at the index
Throws:
IndexException
UnboundLabelException

set

void set(java.lang.String label,
         int index,
         double value)
         throws IndexException
Set the value at the index and add the label to the bindings

Parameters:
label - a String label that maps to an index
index - an int index
value - a double value
Throws:
IndexException

setLabelBindings

void setLabelBindings(java.util.Map<java.lang.String,java.lang.Integer> bindings)
Sets a map of label bindings in the receiver

Parameters:
bindings - a Map of label bindings

set

void set(int index,
         double value)
Set the value at the given index

Parameters:
index - an int index into the receiver
value - a double value to set
Throws:
IndexException - if the index is out of bounds

setQuick

void setQuick(int index,
              double value)
Set the value at the given index, without checking bounds

Parameters:
index - an int index into the receiver
value - a double value to set

getNumNondefaultElements

int getNumNondefaultElements()
Return the number of values in the recipient

Returns:
an int

times

Vector times(double x)
Return a new matrix containing the product of each value of the recipient and the argument

Parameters:
x - a double argument
Returns:
a new Vector

times

Vector times(Vector x)
Return a new matrix containing the element-wise product of the recipient and the argument

Parameters:
x - a Vector argument
Returns:
a new Vector
Throws:
CardinalityException - if the cardinalities differ

viewPart

Vector viewPart(int offset,
                int length)
Return a new matrix containing the subset of the recipient

Parameters:
offset - an int offset into the receiver
length - the cardinality of the desired result
Returns:
a new Vector
Throws:
CardinalityException - if the length is greater than the cardinality of the receiver
IndexException - if the offset is negative or the offset+length is outside of the receiver

zSum

double zSum()
Return the sum of all the elements of the receiver

Returns:
a double

cross

Matrix cross(Vector other)
Return the cross product of the receiver and the other vector

Parameters:
other - another Vector
Returns:
a Matrix

aggregate

double aggregate(BinaryFunction aggregator,
                 UnaryFunction map)
Examples speak louder than words: aggregate(plus, pow(2)) is another way to say getLengthSquared(), aggregate(max, abs) is norm(Double.POSITIVE_INFINITY). To sum all of the postive values, aggregate(plus, max(0)).

Parameters:
aggregator - used to combine the current value of the aggregation with the result of map.apply(nextValue)
map - a function to apply to each element of the vector in turn before passing to the aggregator
Returns:
the final aggregation

aggregate

double aggregate(Vector other,
                 BinaryFunction aggregator,
                 BinaryFunction combiner)

Generalized inner product - take two vectors, iterate over them both, using the combiner to combine together (and possibly map in some way) each pair of values, which are then aggregated with the previous accumulated value in the combiner.

Example: dot(other) could be expressed as aggregate(other, Plus, Times), and kernelized inner products (which are symmetric on the indices) work similarly.

Parameters:
other - a vector to aggregate in combination with
aggregator -
combiner -
Returns:
the final aggregation

getLengthSquared

double getLengthSquared()
Return the sum of squares of all elements in the vector. Square root of this value is the length of the vector.


getDistanceSquared

double getDistanceSquared(Vector v)
Get the square of the distance between this vector and the other vector.


addTo

void addTo(Vector v)
Add the elements to the other vector and results are stored in that vector.



Copyright © 2008-2010 The Apache Software Foundation. All Rights Reserved.