Colt 1.0.1

cern.colt.matrix.doublealgo
Class Sorting

java.lang.Object
  |
  +--cern.colt.matrix.doublealgo.Sorting

public class Sorting
extends Object

Matrix Quicksorts. All sorting algorithms are tuned quicksorts, adapted from Jon L. Bentley and M. Douglas McIlroy's "Engineering a Sort Function", Software-Practice and Experience, Vol. 23(11) P. 1249-1265 (November 1993). This algorithm offers n*log(n) performance on many data sets that cause other quicksorts to degrade to quadratic performance.

See Also:
Sorting, GenericSorting, java.util.Arrays

Method Summary
static void demo1()
          Demonstrates advanced sorting.
static void demo2()
          Demonstrates advanced sorting.
static void demo3()
          Demonstrates advanced sorting.
static void demo5(int rows, int columns, boolean print)
          Demonstrates sorting with precomputation of aggregates (median and sum of logarithms).
static DoubleMatrix1D quickSort(DoubleMatrix1D vector)
          Sorts the vector into ascending order, according to the natural ordering.
static DoubleMatrix1D quickSort(DoubleMatrix1D vector, DoubleComparator c)
          Sorts the vector into ascending order, according to the order induced by the specified comparator.
static DoubleMatrix2D quickSort(DoubleMatrix2D matrix, BinFunction1D aggregate)
          Sorts the matrix rows into ascending order, according to the natural ordering of the values computed by applying the given aggregation function to each row; Particularly efficient when comparing expensive aggregates, because aggregates need not be recomputed time and again, as is the case for comparator based sorts.
static DoubleMatrix2D quickSort(DoubleMatrix2D matrix, double[] aggregates)
          Sorts the matrix rows into ascending order, according to the natural ordering of the matrix values in the virtual column aggregates; Particularly efficient when comparing expensive aggregates, because aggregates need not be recomputed time and again, as is the case for comparator based sorts.
static DoubleMatrix2D quickSort(DoubleMatrix2D matrix, DoubleMatrix1DComparator c)
          Sorts the matrix rows according to the order induced by the specified comparator.
static DoubleMatrix2D quickSort(DoubleMatrix2D matrix, int column)
          Sorts the matrix rows into ascending order, according to the natural ordering of the matrix values in the given column.
static DoubleMatrix3D quickSort(DoubleMatrix3D matrix, DoubleMatrix2DComparator c)
          Sorts the matrix slices according to the order induced by the specified comparator.
static DoubleMatrix3D quickSort(DoubleMatrix3D matrix, int row, int column)
          Sorts the matrix slices into ascending order, according to the natural ordering of the matrix values in the given [row,column] position.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

demo1

public static void demo1()
Demonstrates advanced sorting. Sorts by sum of row.

demo2

public static void demo2()
Demonstrates advanced sorting. Sorts by sum of slice.

demo3

public static void demo3()
Demonstrates advanced sorting. Sorts by sinus of cell values.

demo5

public static void demo5(int rows,
                         int columns,
                         boolean print)
Demonstrates sorting with precomputation of aggregates (median and sum of logarithms).

quickSort

public static DoubleMatrix1D quickSort(DoubleMatrix1D vector)
Sorts the vector into ascending order, according to the natural ordering. The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. To sort ranges use sub-ranging views. To sort descending, use flip views ...

Example:
7, 1, 3, 1

==> 1, 1, 3, 7
The vector IS NOT SORTED.
The new VIEW IS SORTED.

Parameters:
vector - the vector to be sorted.
Returns:
a new sorted vector (matrix) view. Note that the original matrix is left unaffected.

quickSort

public static DoubleMatrix1D quickSort(DoubleMatrix1D vector,
                                       DoubleComparator c)
Sorts the vector into ascending order, according to the order induced by the specified comparator. The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. The algorithm compares two cells at a time, determinining whether one is smaller, equal or larger than the other. To sort ranges use sub-ranging views. To sort descending, use flip views ...

Example:

// sort by sinus of cells
DoubleComparator comp = new DoubleComparator() {
   public int compare(double a, double b) {
      double as = Math.sin(a); double bs = Math.sin(b);
      return as < bs ? -1 : as == bs ? 0 : 1;
   }
};
sorted = quickSort(vector,comp);
Parameters:
vector - the vector to be sorted.
c - the comparator to determine the order.
Returns:
a new matrix view sorted as specified. Note that the original vector (matrix) is left unaffected.

quickSort

public static DoubleMatrix2D quickSort(DoubleMatrix2D matrix,
                                       double[] aggregates)
Sorts the matrix rows into ascending order, according to the natural ordering of the matrix values in the virtual column aggregates; Particularly efficient when comparing expensive aggregates, because aggregates need not be recomputed time and again, as is the case for comparator based sorts. Essentially, this algorithm makes expensive comparisons cheap. Normally each element of aggregates is a summary measure of a row. Speedup over comparator based sorting = 2*log(rows), on average.

The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. To sort ranges use sub-ranging views. To sort columns by rows, use dice views. To sort descending, use flip views ...

Example: Each aggregate is the sum of a row
4 x 2 matrix:
1, 1
5, 4
3, 0
4, 4
aggregates=
2
9
3
8
==>

4 x 2 matrix:
1, 1
3, 0
4, 4
5, 4

The matrix IS NOT SORTED.
The new VIEW IS SORTED.

// sort 10000 x 1000 matrix by sum of logarithms in a row (i.e. by geometric mean)
DoubleMatrix2D matrix = new DenseDoubleMatrix2D(10000,1000);
matrix.assign(new cern.jet.random.engine.MersenneTwister()); // initialized randomly
cern.jet.math.Functions F = cern.jet.math.Functions.functions; // alias for convenience

// THE QUICK VERSION (takes some 3 secs)
// aggregates[i] = Sum(log(row));
double[] aggregates = new double[matrix.rows()];
for (int i = matrix.rows(); --i >= 0; ) aggregates[i] = matrix.viewRow(i).aggregate(F.plus, F.log);
DoubleMatrix2D sorted = quickSort(matrix,aggregates);

// THE SLOW VERSION (takes some 90 secs)
DoubleMatrix1DComparator comparator = new DoubleMatrix1DComparator() {
   public int compare(DoubleMatrix1D x, DoubleMatrix1D y) {
      double a = x.aggregate(F.plus,F.log);
      double b = y.aggregate(F.plus,F.log);
      return a < b ? -1 : a==b ? 0 : 1;
   }
};
DoubleMatrix2D sorted = quickSort(matrix,comparator);

Parameters:
matrix - the matrix to be sorted.
aggregates - the values to sort on. (As a side effect, this array will also get sorted).
Returns:
a new matrix view having rows sorted. Note that the original matrix is left unaffected.
Throws:
IndexOutOfBoundsException - if aggregates.length != matrix.rows().

quickSort

public static DoubleMatrix2D quickSort(DoubleMatrix2D matrix,
                                       int column)
Sorts the matrix rows into ascending order, according to the natural ordering of the matrix values in the given column. The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. To sort ranges use sub-ranging views. To sort columns by rows, use dice views. To sort descending, use flip views ...

Example:
4 x 2 matrix:
7, 6
5, 4
3, 2
1, 0

column = 0;
view = quickSort(matrix,column);
System.out.println(view);

==>

4 x 2 matrix:
1, 0
3, 2
5, 4
7, 6

The matrix IS NOT SORTED.
The new VIEW IS SORTED.

Parameters:
matrix - the matrix to be sorted.
column - the index of the column inducing the order.
Returns:
a new matrix view having rows sorted by the given column. Note that the original matrix is left unaffected.
Throws:
IndexOutOfBoundsException - if column < 0 || column >= matrix.columns().

quickSort

public static DoubleMatrix2D quickSort(DoubleMatrix2D matrix,
                                       DoubleMatrix1DComparator c)
Sorts the matrix rows according to the order induced by the specified comparator. The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. The algorithm compares two rows (1-d matrices) at a time, determinining whether one is smaller, equal or larger than the other. To sort ranges use sub-ranging views. To sort columns by rows, use dice views. To sort descending, use flip views ...

Example:

// sort by sum of values in a row
DoubleMatrix1DComparator comp = new DoubleMatrix1DComparator() {
   public int compare(DoubleMatrix1D a, DoubleMatrix1D b) {
      double as = a.zSum(); double bs = b.zSum();
      return as < bs ? -1 : as == bs ? 0 : 1;
   }
};
sorted = quickSort(matrix,comp);
Parameters:
matrix - the matrix to be sorted.
c - the comparator to determine the order.
Returns:
a new matrix view having rows sorted as specified. Note that the original matrix is left unaffected.

quickSort

public static DoubleMatrix2D quickSort(DoubleMatrix2D matrix,
                                       BinFunction1D aggregate)
Sorts the matrix rows into ascending order, according to the natural ordering of the values computed by applying the given aggregation function to each row; Particularly efficient when comparing expensive aggregates, because aggregates need not be recomputed time and again, as is the case for comparator based sorts. Essentially, this algorithm makes expensive comparisons cheap. Normally aggregates defines a summary measure of a row. Speedup over comparator based sorting = 2*log(rows), on average.

The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. To sort ranges use sub-ranging views. To sort columns by rows, use dice views. To sort descending, use flip views ...

Example: Each aggregate is the sum of a row
4 x 2 matrix:
1, 1
5, 4
3, 0
4, 4
aggregates=
hep.aida.bin.BinFunctions1D.sum
==>

4 x 2 matrix:
1, 1
3, 0
4, 4
5, 4

The matrix IS NOT SORTED.
The new VIEW IS SORTED.

// sort 10000 x 1000 matrix by median or by sum of logarithms in a row (i.e. by geometric mean)
DoubleMatrix2D matrix = new DenseDoubleMatrix2D(10000,1000);
matrix.assign(new cern.jet.random.engine.MersenneTwister()); // initialized randomly
cern.jet.math.Functions F = cern.jet.math.Functions.functions; // alias for convenience

// THE QUICK VERSION (takes some 10 secs)
DoubleMatrix2D sorted = quickSort(matrix,hep.aida.bin.BinFunctions1D.median);
//DoubleMatrix2D sorted = quickSort(matrix,hep.aida.bin.BinFunctions1D.sumOfLogarithms);

// THE SLOW VERSION (takes some 300 secs)
DoubleMatrix1DComparator comparator = new DoubleMatrix1DComparator() {
   public int compare(DoubleMatrix1D x, DoubleMatrix1D y) {
      double a = cern.colt.matrix.doublealgo.Statistic.bin(x).median();
      double b = cern.colt.matrix.doublealgo.Statistic.bin(y).median();
      // double a = x.aggregate(F.plus,F.log);
      // double b = y.aggregate(F.plus,F.log);
      return a < b ? -1 : a==b ? 0 : 1;
   }
};
DoubleMatrix2D sorted = quickSort(matrix,comparator);

Parameters:
matrix - the matrix to be sorted.
aggregate - the function to sort on; aggregates values in a row.
Returns:
a new matrix view having rows sorted. Note that the original matrix is left unaffected.

quickSort

public static DoubleMatrix3D quickSort(DoubleMatrix3D matrix,
                                       int row,
                                       int column)
Sorts the matrix slices into ascending order, according to the natural ordering of the matrix values in the given [row,column] position. The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. To sort ranges use sub-ranging views. To sort by other dimensions, use dice views. To sort descending, use flip views ...

The algorithm compares two 2-d slices at a time, determinining whether one is smaller, equal or larger than the other. Comparison is based on the cell [row,column] within a slice. Let A and B be two 2-d slices. Then we have the following rules

Parameters:
matrix - the matrix to be sorted.
row - the index of the row inducing the order.
column - the index of the column inducing the order.
Returns:
a new matrix view having slices sorted by the values of the slice view matrix.viewRow(row).viewColumn(column). Note that the original matrix is left unaffected.
Throws:
IndexOutOfBoundsException - if row < 0 || row >= matrix.rows() || column < 0 || column >= matrix.columns().

quickSort

public static DoubleMatrix3D quickSort(DoubleMatrix3D matrix,
                                       DoubleMatrix2DComparator c)
Sorts the matrix slices according to the order induced by the specified comparator. The returned view is backed by this matrix, so changes in the returned view are reflected in this matrix, and vice-versa. The algorithm compares two slices (2-d matrices) at a time, determinining whether one is smaller, equal or larger than the other. To sort ranges use sub-ranging views. To sort by other dimensions, use dice views. To sort descending, use flip views ...

Example:

// sort by sum of values in a slice
DoubleMatrix2DComparator comp = new DoubleMatrix2DComparator() {
   public int compare(DoubleMatrix2D a, DoubleMatrix2D b) {
      double as = a.zSum(); double bs = b.zSum();
      return as < bs ? -1 : as == bs ? 0 : 1;
   }
};
sorted = quickSort(matrix,comp);
Parameters:
matrix - the matrix to be sorted.
c - the comparator to determine the order.
Returns:
a new matrix view having slices sorted as specified. Note that the original matrix is left unaffected.

Colt 1.0.1

Submit a bug or feature. Check the Colt home page for the latest news.