de.javagl.nd.tuples.d

Class DoubleTupleCollections

java.lang.Object

de.javagl.nd.tuples.d.DoubleTupleCollections

public class DoubleTupleCollections
extends Object

Utility methods related to collections of DoubleTuple instances.

For the methods that receive a collection of input tuples and a result tuple, unless otherwise noted, the behavior is as follows:

• If the input collection is empty, then null will be returned
• If the input collection is not empty:
  • If the result tuple is null, then a new tuple will be created and returned.
  • If the result tuple is not null, then it will be verified that the result tuple has an appropriate size for the respective operation, and an IllegalArgumentException will be thrown if this is not the case.

All these methods assume that the collections do not contain null elements, and that the size of all tuples is the same. If this is not the case, the behavior is unspecified (although in most cases, a NullPointerException or an IllegalArgumentException will be thrown, respectively)

Method Summary

Modifier and Type	Method and Description
static MutableDoubleTuple	add(Collection<? extends DoubleTuple> tuples, MutableDoubleTuple result) Computes the component-wise sum of the given collection of tuples.
static MutableDoubleTuple	arithmeticMean(Collection<? extends DoubleTuple> tuples, MutableDoubleTuple result) Computes the component-wise arithmetic mean of the given collection of DoubleTuple objects.
static List<MutableDoubleTuple>	create(int dimensions, int numElements) Create the specified number of tuples with the given dimensions (size), all initialized to zero, and return them as a list
static void	create(int dimensions, int numElements, Collection<? super MutableDoubleTuple> target) Create the specified number of tuples with the given dimensions (size), all initialized to zero, and place them into the given target collection
static List<MutableDoubleTuple>	deepCopy(Collection<? extends DoubleTuple> tuples) Returns a deep copy of the given collection of tuples.
static MutableDoubleTuple	max(Collection<? extends DoubleTuple> tuples, MutableDoubleTuple result) Computes the component-wise maximum of the given collection of tuples.
static MutableDoubleTuple	min(Collection<? extends DoubleTuple> tuples, MutableDoubleTuple result) Computes the component-wise minimum of the given collection of tuples.
static List<MutableDoubleTuple>	normalize(Collection<? extends DoubleTuple> inputs, List<MutableDoubleTuple> results) Normalize the given collection of MutableDoubleTuples.
static MutableDoubleTuple	standardDeviation(Collection<? extends DoubleTuple> tuples, MutableDoubleTuple result) Returns the component-wise standard deviation of the given collection of DoubleTuple objects.
static MutableDoubleTuple	standardDeviationFromMean(Collection<? extends DoubleTuple> tuples, DoubleTuple mean, MutableDoubleTuple result) Returns the component-wise standard deviation of the given collection of DoubleTuple objects.
static List<MutableDoubleTuple>	standardize(Collection<? extends DoubleTuple> inputs, List<MutableDoubleTuple> results) Standardize the given input tuples.
static MutableDoubleTuple	variance(Collection<? extends DoubleTuple> tuples, DoubleTuple mean, MutableDoubleTuple result) Computes the component-wise variance of the given collection of DoubleTuple objects.
static MutableDoubleTuple	variance(Collection<? extends DoubleTuple> tuples, MutableDoubleTuple result) Computes the component-wise variance of the given collection of DoubleTuple objects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static void create(int dimensions,
                          int numElements,
                          Collection<? super MutableDoubleTuple> target)

Create the specified number of tuples with the given dimensions (size), all initialized to zero, and place them into the given target collection

Parameters:

dimensions - The dimensions (size) of the tuples to create

numElements - The number of tuples to create

target - The target collection

Throws:

IllegalArgumentException - If the given dimensions are negative

create

public static List<MutableDoubleTuple> create(int dimensions,
                                              int numElements)

Create the specified number of tuples with the given dimensions (size), all initialized to zero, and return them as a list

Parameters:

dimensions - The dimensions (size) of the tuples to create

numElements - The number of tuples to create

Returns:

The list

Throws:

IllegalArgumentException - If the given dimensions are negative

deepCopy

public static List<MutableDoubleTuple> deepCopy(Collection<? extends DoubleTuple> tuples)

Returns a deep copy of the given collection of tuples. If any element of the given collection is null, then null will also be added to the target collection.

Parameters:

tuples - The input tuples

Returns:

The deep copy

min

public static MutableDoubleTuple min(Collection<? extends DoubleTuple> tuples,
                                     MutableDoubleTuple result)

Computes the component-wise minimum of the given collection of tuples.

If the given collection is not empty, and the given result is null, then a new tuple with the same size as the first tuple of the collection will be created internally. All elements of this tuple will be initialized with Double.POSITIVE_INFINITY.

Parameters:

tuples - The input tuples

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

max

public static MutableDoubleTuple max(Collection<? extends DoubleTuple> tuples,
                                     MutableDoubleTuple result)

Computes the component-wise maximum of the given collection of tuples.

If the given collection is not empty, and the given result is null, then a new tuple with the same size as the first tuple of the collection will be created internally. All elements of this tuple will be initialized with Double.NEGATIVE_INFINITY.

Parameters:

tuples - The input tuples

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

add

public static MutableDoubleTuple add(Collection<? extends DoubleTuple> tuples,
                                     MutableDoubleTuple result)

Computes the component-wise sum of the given collection of tuples.

If the given collection is not empty, and the given result is null, then a new tuple with the same size as the first tuple of the collection will be created internally.

Parameters:

tuples - The input tuples

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

standardize

public static List<MutableDoubleTuple> standardize(Collection<? extends DoubleTuple> inputs,
                                                   List<MutableDoubleTuple> results)

Standardize the given input tuples. This means that the mean of the given tuples is subtracted from them, and they are divided by the standard deviation.

The results will be written into the given result tuples. If the given results list is null, then a new list will be created and returned.

If the result list is not null, then it must have the same size as the input collection, otherwise an IllegalArgumentException will be thrown.

If the input collection contains null elements, then a NullPointerException will be thrown.

If the result list contains null elements, then a NullPointerException will be thrown.

The input collection and the results list may contain pairwise identical elements.

The input collection and the results list may be identical.

Parameters:

inputs - The input tuples

results - The result tuples

Returns:

The result tuples

Throws:

IllegalArgumentException - If the result list is not null and has a size that is different from the size of the input collection

NullPointerException - If the inputs list is null or contains null elements, or if the output list is non-null and contains null elements

normalize

public static List<MutableDoubleTuple> normalize(Collection<? extends DoubleTuple> inputs,
                                                 List<MutableDoubleTuple> results)

Normalize the given collection of MutableDoubleTuples.

The results will be written into the given result tuples. If the given results list is null, then a new list will be created and returned.

If the result list is not null, then it must have the same size as the input collection, otherwise an IllegalArgumentException will be thrown.

If the input collection contains null elements, then a NullPointerException will be thrown.

If the result list contains null elements, then a NullPointerException will be thrown.

The input collection and the results list may contain pairwise identical elements.

The input collection and the results list may be identical.

Parameters:

inputs - The tuples to normalize

results - The result tuples

Returns:

The result tuples

Throws:

IllegalArgumentException - If the result list is not null and has a size that is different from the size of the input collection

NullPointerException - If the inputs list is null or contains null elements, or if the output list is non-null and contains null elements

See Also:

DoubleTuples.normalize(DoubleTuple, MutableDoubleTuple)

arithmeticMean

public static MutableDoubleTuple arithmeticMean(Collection<? extends DoubleTuple> tuples,
                                                MutableDoubleTuple result)

Computes the component-wise arithmetic mean of the given collection of DoubleTuple objects.

Parameters:

tuples - The input tuples

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

variance

public static MutableDoubleTuple variance(Collection<? extends DoubleTuple> tuples,
                                          MutableDoubleTuple result)

Computes the component-wise variance of the given collection of DoubleTuple objects. The method will compute the arithmetic mean, and then compute the actual result with the variance(Collection, DoubleTuple, MutableDoubleTuple) method.

Parameters:

tuples - The input tuples

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

variance

public static MutableDoubleTuple variance(Collection<? extends DoubleTuple> tuples,
                                          DoubleTuple mean,
                                          MutableDoubleTuple result)

Computes the component-wise variance of the given collection of DoubleTuple objects.

Parameters:

tuples - The input tuples

mean - The mean, which may have been computed before with arithmeticMean(java.util.Collection<? extends de.javagl.nd.tuples.d.DoubleTuple>, de.javagl.nd.tuples.d.MutableDoubleTuple)

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

standardDeviation

public static MutableDoubleTuple standardDeviation(Collection<? extends DoubleTuple> tuples,
                                                   MutableDoubleTuple result)

Returns the component-wise standard deviation of the given collection of DoubleTuple objects. The method will compute the arithmetic mean, and then compute the actual result with the standardDeviationFromMean(java.util.Collection<? extends de.javagl.nd.tuples.d.DoubleTuple>, de.javagl.nd.tuples.d.DoubleTuple, de.javagl.nd.tuples.d.MutableDoubleTuple) method.

Parameters:

tuples - The input tuples

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.

standardDeviationFromMean

public static MutableDoubleTuple standardDeviationFromMean(Collection<? extends DoubleTuple> tuples,
                                                           DoubleTuple mean,
                                                           MutableDoubleTuple result)

Returns the component-wise standard deviation of the given collection of DoubleTuple objects. The method will compute variance(java.util.Collection<? extends de.javagl.nd.tuples.d.DoubleTuple>, de.javagl.nd.tuples.d.MutableDoubleTuple), and then compute the actual result with the DoubleTuples.standardDeviationFromVariance(de.javagl.nd.tuples.d.DoubleTuple, de.javagl.nd.tuples.d.MutableDoubleTuple) method.

Parameters:

tuples - The input tuples

mean - The mean, which may have been computed before with arithmeticMean(java.util.Collection<? extends de.javagl.nd.tuples.d.DoubleTuple>, de.javagl.nd.tuples.d.MutableDoubleTuple)

result - The result tuple

Returns:

The result, or null if the given collection is empty

Throws:

IllegalArgumentException - If the given result is not null, and has a size that is different from that of the input tuples.