net.returnvoid.analytics

Class ClusteringHelper

java.lang.Object

net.returnvoid.analytics.ClusteringHelper

public class ClusteringHelper
extends java.lang.Object

This class provides basic clustering solutions to learn clusterings and to evaluate these clusterings.

Author:

Diana Lange

Method Summary

Modifier and Type	Method and Description
static ColorCluster[]	addColorsToClusters(ColorCluster[] clusters, RColor[] colors) Assigns each color from given set of colors to one of the cluster of the given set clusters.
static ColorCluster[]	colorsToClusters(RColor[] means, ColorDifferenceMeasure m) Builds new ColorClusters from a given set of colors.
static java.lang.Float	computeLoss(Cluster[] clusters) Computed the mean loss of the given clusters.
static float[]	getLosses(Clustering[] clustering) Calculates the loss for all the clusterings in the given set.
static RColor[]	getTrainingColors(processing.core.PImage img, java.lang.Integer trainingsSize) Picks trainingsSize semi-random colors from the input image.
static RColor[]	getTrainingColors(processing.core.PImage img, java.lang.Integer trainingsSize, ColorDifferenceMeasure m) Picks trainingsSize semi-random colors from the input image.
static RColor[]	getTrainingColors(processing.core.PImage img, java.lang.Integer trainingsSize, ColorDifferenceMeasure m, java.lang.Integer cellSize) Picks trainingsSize semi-random colors from the input image.
static RColor[]	getTrainingColors(processing.core.PImage img, java.lang.Integer trainingsSize, ColorSpace space) Picks trainingsSize semi-random colors from the input image.
static RColor[]	getTrainingColors(processing.core.PImage img, java.lang.Integer trainingsSize, ColorSpace space, int cellSize) Picks trainingsSize semi-random colors from the input image.
static RColor[]	getTrainingColors(processing.core.PImage img, java.lang.Integer trainingsSize, java.lang.Integer cellSize) Picks trainingsSize semi-random colors from the input image.
static RColor[]	getTrainingColors(RColor[] colors, java.lang.Integer trainingsSize) Creates a randomly sampled subset of the give set of colors.
static RColor[]	getTrainingColors(RColor[] colors, java.lang.Integer trainingSize, ColorDifferenceMeasure m) Creates a randomly sampled subset of the give set of colors and converts the returned colors to a color space defined by the given ColorDifferenceMeasure (e.g. m=RGBEuclidean -> returned colors are RGBColors).
static RColor[]	getTrainingColors(RColor[] colors, java.lang.Integer trainingsSize, ColorSpace space) Creates a randomly sampled subset of the give set of colors and converts the returned colors to the given color space.
static java.lang.Object[]	getTrainingData(java.lang.Object[] raw, java.lang.Integer trainingSize) Creates a randomly sampled subset of the give set raw.
static ColorClustering	kmeans(RColor[] colors, java.lang.Integer k, ColorDifferenceMeasure m) Applies the k-means algorithm to colors for a given k.
static ColorClustering	kmeans(RColor[] colors, java.lang.Integer k, ColorDifferenceMeasure m, ColorCluster[] existingClusters) Applies the k-means algorithm to colors for a given k.
static ColorClustering[]	kmeansClusterings(RColor[] colors, java.lang.Integer minK, java.lang.Integer maxK, ColorDifferenceMeasure m) Applies the k-means algorithm to colors for a range of k.

Methods inherited from class java.lang.Object

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

Method Detail

computeLoss

public static java.lang.Float computeLoss(Cluster[] clusters)

Computed the mean loss of the given clusters.

Parameters:

clusters - A set of clusters.

Returns:

The mean loss of all the clusters.

getLosses

public static float[] getLosses(Clustering[] clustering)

Calculates the loss for all the clusterings in the given set.

Parameters:

clustering - A set of clusterings.

Returns:

The set of losses for each given clustering.d

getTrainingData

public static java.lang.Object[] getTrainingData(java.lang.Object[] raw,
                                                 java.lang.Integer trainingSize)

Creates a randomly sampled subset of the give set raw.

Parameters:

raw - The original data.

trainingSize - The number of elements the training data should consist of. If the given set raw is smaller than trainingSize, the returned set is not a subset, but a randomly sorted version of the original set.

Returns:

The shuffled subset of the input data.

colorsToClusters

public static ColorCluster[] colorsToClusters(RColor[] means,
                                              ColorDifferenceMeasure m)

Builds new ColorClusters from a given set of colors.

Parameters:

means - The colors that should be the initial means of the new clusters.

m - A colorDifferenceMeasure.

Returns:

ColorClusters with means (= given means) but without members.

addColorsToClusters

public static ColorCluster[] addColorsToClusters(ColorCluster[] clusters,
                                                 RColor[] colors)

Assigns each color from given set of colors to one of the cluster of the given set clusters. The means of each cluster will be updated after all colors are assigned to their clusters. For any color the most similar cluster is chosen, i.e. the distance to the clusters mean is minimal. The distance is calculated based on the ColorDifferenceMeasure of the first cluster in clusters.

Parameters:

clusters - A set of clusters with already assigned means and ColorDifferenceMeasure. The ColorDifferenceMeasure for all clusters should be equal.

colors - A set of colors. For better performance make sure that the color space of all colors are equal and equal to the cluster means color spaces as well as that the color space correspond to the ColorDifferenceMeasure of the clusters.

Returns:

The updated clusters with new cluster members as well as updated means.

kmeans

public static ColorClustering kmeans(RColor[] colors,
                                     java.lang.Integer k,
                                     ColorDifferenceMeasure m)

Applies the k-means algorithm to colors for a given k. The difference measure which will be applied is set by the given parameter m. The initial clusters are built by looking for the most different k colors in the given set of colors.

Parameters:

colors - The set of colors which will be clustered. To prevent unnecessary color space transformations please make sure that these colors are all members of the same color space and that this color space correlates to the give ColorDifferenceMeasure. You can convert the colors using the ColorHelper.convert(ColorDifferenceMeasure) method.

k - The number of clusters (>= 2).

m - The ColorDifferencemeasure.

Returns:

The clustering of the given input set. The clustering might not consists of k clusters but less (empty clusters are removed).

kmeans

public static ColorClustering kmeans(RColor[] colors,
                                     java.lang.Integer k,
                                     ColorDifferenceMeasure m,
                                     ColorCluster[] existingClusters)

Applies the k-means algorithm to colors for a given k. The difference measure which will be applied is set by the given parameter m. If existingClusters is given the initial cluster will be set by these and one or more new cluster centers will be added to create the first k clusters. If existingClusters is null, the initial clusters are built by looking for the most different k colors in the given set of colors.

Parameters:

colors - The set of colors which will be clustered. To prevent unnecessary color space transformations please make sure that these colors are all members of the same color space and that this color space correlates to the give ColorDifferenceMeasure. You can convert the colors using the ColorHelper.convert(ColorDifferenceMeasure) method.

k - The number of clusters (>= 2).

m - The ColorDifferencemeasure.

existingClusters - null or previously calculated clusters. The means of them will serve as initial cluster centers for the new clustering.

Returns:

The clustering of the given input set. The clustering might not consists of k clusters but less (empty clusters are removed).

kmeansClusterings

public static ColorClustering[] kmeansClusterings(RColor[] colors,
                                                  java.lang.Integer minK,
                                                  java.lang.Integer maxK,
                                                  ColorDifferenceMeasure m)

Applies the k-means algorithm to colors for a range of k. The difference measure which will be applied is set by the given parameter m. For k=minK the initial clusters are built by looking for the most different k colors in the given set of colors. For k>minK, the initial cluster centers are built from the cluster centers of k-1. This means, for k>minK just one new cluster center is added. This new cluster is build again with a color that is the most different to all the existing cluster centers.

Parameters:

colors - The set of colors which will be clustered. To prevent unnecessary color space transformations please make sure that these colors are all members of the same color space and that this color space correlates to the give ColorDifferenceMeasure. You can convert the colors using the ColorHelper.convert(ColorDifferenceMeasure) method.

minK - The number of clusters for the first clustering (minK >= 2, minK < maxK).

maxK - The number of clusters for the last clustering (maxK < colors.length, minK < maxK).

m - The ColorDifferencemeasure.

Returns:

The Clusterings for minK to maxK.

getTrainingColors

public static RColor[] getTrainingColors(processing.core.PImage img,
                                         java.lang.Integer trainingsSize)

Picks trainingsSize semi-random colors from the input image. The image is divided into a regular grid (table grid). Within the cells of the grid one sampler is chosen randomly. The picked colors are converted to a RGBColor

Parameters:

img - A image (Number of pixels should be higher then trainingsSize).

trainingsSize - The number of colors that should be sampled from the image.

Returns:

The sampled colors.

getTrainingColors

public static RColor[] getTrainingColors(processing.core.PImage img,
                                         java.lang.Integer trainingsSize,
                                         java.lang.Integer cellSize)

Picks trainingsSize semi-random colors from the input image. The image is divided into a regular grid (table grid). Within the cells of the grid the samplers are chosen randomly. The picked colors are converted to a RGBColor

Parameters:

img - A image (Number of pixels should be higher then trainingsSize).

trainingsSize - The number of colors that should be sampled from the image.

cellSize - Sets the number of random chosen color samples per cell. If cellSize=1, there are a lot of small cells and in each sell one color is picked. If cellSize=2, there are bigger cells and in each cell two colors are picked. In most cases cellSize=1 is the most convenient value.

Returns:

The sampled colors.

getTrainingColors

public static RColor[] getTrainingColors(processing.core.PImage img,
                                         java.lang.Integer trainingsSize,
                                         ColorDifferenceMeasure m)

Picks trainingsSize semi-random colors from the input image. The image is divided into a regular grid (table grid). Within the cells of the grid one sampler is chosen randomly. The picked colors are converted to a color space defined by the given ColorDifferenceMeasure (e.g. m=RGBEuclidean -> returned colors are RGBColors).

Parameters:

img - A image (Number of pixels should be higher then trainingsSize).

trainingsSize - The number of colors that should be sampled from the image.

m - A ColorDifferenceMeasure (defines in what color space the colors are returned).

Returns:

The sampled colors.

getTrainingColors

public static RColor[] getTrainingColors(processing.core.PImage img,
                                         java.lang.Integer trainingsSize,
                                         ColorSpace space)

Picks trainingsSize semi-random colors from the input image. The image is divided into a regular grid (table grid). Within the cells of the grid one sampler is chosen randomly. The picked colors are converted to the given color space.

Parameters:

img - A image (Number of pixels should be higher then trainingsSize).

space - A color space (defines in what color space the colors are returned).

cellSize - Sets the number of random chosen color samples per cell. If cellSize=1, there are a lot of small cells and in each sell one color is picked. If cellSize=2, there are bigger cells and in each cell two colors are picked. In most cases cellSize=1 is the most convenient value.

Returns:

The sampled colors.

getTrainingColors

public static RColor[] getTrainingColors(processing.core.PImage img,
                                         java.lang.Integer trainingsSize,
                                         ColorSpace space,
                                         int cellSize)

Picks trainingsSize semi-random colors from the input image. The image is divided into a regular grid (table grid). Within the cells of the grid the samplers are chosen randomly. The picked colors are converted to the given color space.

Parameters:

img - A image (Number of pixels should be higher then trainingsSize).

trainingsSize - The number of colors that should be sampled from the image.

space - A color space (defines in what color space the colors are returned).

cellSize - Sets the number of random chosen color samples per cell. If cellSize=1, there are a lot of small cells and in each sell one color is picked. If cellSize=2, there are bigger cells and in each cell two colors are picked. In most cases cellSize=1 is the most convenient value.

Returns:

The sampled colors.

getTrainingColors

public static RColor[] getTrainingColors(processing.core.PImage img,
                                         java.lang.Integer trainingsSize,
                                         ColorDifferenceMeasure m,
                                         java.lang.Integer cellSize)

Picks trainingsSize semi-random colors from the input image. The image is divided into a regular grid (table grid). Within the cells of the grid the samplers are chosen randomly. The picked colors are converted to a color space defined by the given ColorDifferenceMeasure (e.g. m=RGBEuclidean -> returned colors are RGBColors).

Parameters:

img - A image (Number of pixels should be higher then trainingsSize).

trainingsSize - The number of colors that should be sampled from the image.

m - A ColorDifferenceMeasure (defines in what color space the colors are returned).

cellSize - Sets the number of random chosen color samples per cell. If cellSize=1, there are a lot of small cells and in each sell one color is picked. If cellSize=2, there are bigger cells and in each cell two colors are picked. In most cases cellSize=1 is the most convenient value.

Returns:

The sampled colors.

getTrainingColors

public static RColor[] getTrainingColors(RColor[] colors,
                                         java.lang.Integer trainingsSize)

Creates a randomly sampled subset of the give set of colors.

Parameters:

colors - The original data.

trainingsSize - The number of elements the training data should consist of. If the given set colors is smaller than trainingSize, the returned set is not a subset, but a randomly sorted version of the original set.

Returns:

The shuffled subset of the input data.

getTrainingColors

public static RColor[] getTrainingColors(RColor[] colors,
                                         java.lang.Integer trainingsSize,
                                         ColorSpace space)

Creates a randomly sampled subset of the give set of colors and converts the returned colors to the given color space. If space=null the colors will not be converted.

Parameters:

colors - The original data.

trainingsSize - The number of elements the training data should consist of. If the given set colors is smaller than trainingSize, the returned set is not a subset, but a randomly sorted version of the original set.

space - A color space or null. A ColorDifferenceMeasure or null.

Returns:

The shuffled subset of the input data.

getTrainingColors

public static RColor[] getTrainingColors(RColor[] colors,
                                         java.lang.Integer trainingSize,
                                         ColorDifferenceMeasure m)

Creates a randomly sampled subset of the give set of colors and converts the returned colors to a color space defined by the given ColorDifferenceMeasure (e.g. m=RGBEuclidean -> returned colors are RGBColors). If m=null the colors will not be converted.

Parameters:

colors - The original data.

trainingsSize - The number of elements the training data should consist of. If the given set colors is smaller than trainingSize, the returned set is not a subset, but a randomly sorted version of the original set.

m - A ColorDifferenceMeasure or null.

Returns:

The shuffled subset of the input data.