org.strbio.math
Class DMatrix

java.lang.Object
  org.strbio.math.DMatrix

public class DMatrix
extends java.lang.Object

a class to encapsulate a 2-D matrix of doubles. Can do a bunch of math/statistics functions, and save/load from a file. The binary loading methods are usually 3-4 times faster than ascii; saves go at about the same speed (sometimes ascii is faster than binary due to superior buffering).

 Version 1.33, 7/7/99 - added equals
 Version 1.32, 4/16/99 - some error conditions (i.e. min() when there's
   no data) return Double.NaN, instead of (incorrect) 0.0.
 Version 1.31, 1/25/99 - made save/load methods non-final, changed
   most instances of PrintfStream to generic Printf
 Version 1.3, 10/29/98 - added makeInverseTransform()
 Version 1.2, 5/18/98 - added saveBinary, more load() methods.
   load(filename) now autodetects binary/ascii files.
 Version 1.13, 5/11/98 - added constructors from IMatrix, int[][].
 Version 1.12, 4/29/98 - added saveDplot
 Version 1.11, 4/28/98 - fixed a couple of saving bugs, normalize(),
   removed norm().
 Version 1.1, 4/9/98 - added add(double), makeTransform(), and print()
 Version 1.0, 3/30/98 - original version
 

Version:

1.33, 7/7/99

Author:

JMC

See Also:

IMatrix, DVector, DHalfMatrix

Field Summary

double[][]

data data contains the actual matrix itself; it's public so that it can be manipulated directly (for speed, such as that is in java) and so that you can do something like 'dm.data[0][0] = tmp' as well as 'tmp = dm.data[0][0]' without needing 2 different functions.

Constructor Summary

DMatrix()
makes a blank 0x0 matrix; you can assign a double[][] to the data directly, or load data in from a file

DMatrix(DMatrix x)
copies another DMatrix.

DMatrix(double[][] x)
makes a new DMatrix object out of a double[][] array.

DMatrix(IMatrix x)
copies an IMatrix, making a copy of the data, and casting to doubles.

DMatrix(int[][] x)
makes a new DMatrix object out of an int[][] array, copying the data and casting to doubles.

DMatrix(int c, int r)
makes an emptry DMatrix object with a specified number of columns and rows.

Method Summary

void	add(DMatrix x) Adds another DMatrix to this one.
static DMatrix	add(DMatrix a, DMatrix b) Adds two DMatrix's and returns a new DMatrix containing the sum.
void	add(double x) Adds a double to every value in this DMatrix.
double	average() Returns the average value in the matrix.
int	cols() returns the number of columns in the encapsulated array.
double	covar(DMatrix y) Returns the covariance of values in this matrix with those in another matrix.
void	diffuse() This does a single round of 'diffusive smoothing' on the matrix.
static DMatrix	divide(DMatrix a, int b) Divides a DMatrix by a double, and returns a new DMatrix containing the result.
void	divide(double x) Divides this DMatrix by a specified double.
boolean	equals(java.lang.Object x) mathematical objects are equal if their contents are.
DMatrix	inverse() Returns the inverse of this matrix.
boolean	isEmpty() Does the matrix contain all zeroes?
void	load(java.io.BufferedReader infile) Load Ascii from an open BufferedReader.
void	load(java.io.DataInputStream infile) Load binary matrix from an open DataInputStream.
void	load(java.lang.String filename) Loads matrix from a file; file type (text/binary) is autodetected.
static DMatrix	makeInverseTransform(double x, double y, double z, double phi, double theta, double psi) Return an inverse transformation matrix given 3 transformation coordinates and 3 Euler rotation angles.
static DMatrix	makeTransform(double x, double y, double z, double phi, double theta, double psi) Return a transformation matrix given 3 transformation coordinates and 3 Euler rotation angles.
double	max() What's the maximum value in the matrix?
double	mean() Returns the mean value in the matrix.
double	min() What's the minimum value in the matrix?
DMatrix	multiply(DMatrix x) Multiples this DMatrix by another DMatrix, and returns another DMatrix containing the result.
static DMatrix	multiply(DMatrix a, DMatrix b) Multiplies two DMatrix's, and returns another DMatrix containing the result.
static DMatrix	multiply(DMatrix a, double b) Multiplies a DMatrix by a double and returns a new DMatrix containing the result.
void	multiply(double x) Multiplies all values in this DMatrix by a specified double.
static DMatrix	multiply(double b, DMatrix a) Multiplies a DMatrix by a double and returns a new DMatrix containing the result.
void	normalize() Rescale matrix so the average is one.
double	pearson(DMatrix y) Returns the Pearson correlation coefficient R of values in this matrix with values in another matrix.
void	print(Printf outfile) prints in ascii to an open Printf, with a nicer format than 'save'.
void	print(java.lang.String filename) prints in ascii to a new file, with a nicer format than 'save'.
void	rescale(double offset, double scale) Rescales every value in this DMatrix: data[i][j] -> (data[i][j] + offset) * scale
void	rescaleTo(double newMean, double newSD) Rescales to a given mean and standard deviation.
int	rows() returns the number of rows in the encapsulated array.
void	save(Printf outfile) Save to an open Printf.
void	save(java.lang.String filename) Saves to a new text file.
void	saveBinary(java.io.DataOutputStream outfile) Save in binary format to an open DataOutputStream.
void	saveBinary(java.lang.String filename) Saves to a new binary file.
void	saveDplot(java.lang.String filename) Saves in Dplot (ASGL) format to a new text file.
void	setValue(double x) Sets every value in the matrix to a specified double.
void	setValueAt(int c, int r, double d) Sets the data at a given column/row.
void	smooth(double minValid, int maxTolerance) This function smooths the matrix by averaging over adjacent blocks.
void	smoothPeriodic(double minValid, int maxTolerance) This function smooths the matrix by averaging over adjacent blocks.
double	stdev() Returns the standard deviation of a distribution containing all values in the matrix.
double	stdevp() Returns the standard deviation of a distribution containing all values in the matrix.
void	subtract(DMatrix x) Subtracts another DMatrix from this one.
static DMatrix	subtract(DMatrix a, DMatrix b) Subtracts one DMatrix's from another returns a new DMatrix containing the difference.
void	subtract(double x) Subtracts a double to every value in this DMatrix.
DMatrix	transpose() Returns the transpose of this DMatrix.
double	valueAt(int c, int r) Returns the data at a given column/row.
double	zScore(double x) Shows how many standard deviations (of this matrix) a given double is below the average (of this matrix)

Methods inherited from class java.lang.Object

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

Field Detail

data

public double[][] data

data contains the actual matrix itself; it's public so that it can be manipulated directly (for speed, such as that is in java) and so that you can do something like 'dm.data[0][0] = tmp' as well as 'tmp = dm.data[0][0]' without needing 2 different functions. In C++ this could all be hidden by operator overloading, but that would be too elegant for some people.

Constructor Detail

DMatrix

public DMatrix(int c,
               int r)

makes an emptry DMatrix object with a specified number of columns and rows. All data should be zeroed out... this is not done explicitly, but relies on Java's default values.

Parameters:

c - columns

r - rows

DMatrix

public DMatrix()

makes a blank 0x0 matrix; you can assign a double[][] to the data directly, or load data in from a file

DMatrix

public DMatrix(double[][] x)

makes a new DMatrix object out of a double[][] array. It copies the data rather than creating a reference to it, so if you manipulate data in your original array after calling this constructor, it will NOT affect the new object. If you want to do the latter, try dm = new DMatrix(), then dm.data = my_array.

DMatrix

public DMatrix(DMatrix x)

copies another DMatrix. A new copy of the array is made.

DMatrix

public DMatrix(int[][] x)

makes a new DMatrix object out of an int[][] array, copying the data and casting to doubles.

DMatrix

public DMatrix(IMatrix x)

copies an IMatrix, making a copy of the data, and casting to doubles.

Method Detail

equals

public boolean equals(java.lang.Object x)

mathematical objects are equal if their contents are.

Overrides:

equals in class java.lang.Object

cols

public final int cols()

returns the number of columns in the encapsulated array.

rows

public final int rows()

returns the number of rows in the encapsulated array.

valueAt

public final double valueAt(int c,
                            int r)

Returns the data at a given column/row. It's easier to manipulate the data directly, but this method is there if you don't feel like doing that.

Parameters:

c - column

r - row

setValueAt

public final void setValueAt(int c,
                             int r,
                             double d)

Sets the data at a given column/row. It's easier to manipulate the data directly, but this method is there if you don't feel like doing that.

Parameters:

c - column

r - row

d - value to set the data to

setValue

public final void setValue(double x)

Sets every value in the matrix to a specified double.

inverse

public final DMatrix inverse()

Returns the inverse of this matrix.

add

public final void add(DMatrix x)

Adds another DMatrix to this one. If the sizes aren't the same, you will probably get an ArrayOutOfBounds exception.

add

public final void add(double x)

Adds a double to every value in this DMatrix. Don't tell the Math Police.

add

public static final DMatrix add(DMatrix a,
                                DMatrix b)

Adds two DMatrix's and returns a new DMatrix containing the sum. If the sizes aren't the same, you will probably get an ArrayOutOfBounds exception.

subtract

public final void subtract(DMatrix x)

Subtracts another DMatrix from this one. If the sizes aren't the same, you will probably get an ArrayOutOfBounds exception.

subtract

public final void subtract(double x)

Subtracts a double to every value in this DMatrix. Call add instead.

subtract

public static final DMatrix subtract(DMatrix a,
                                     DMatrix b)

Subtracts one DMatrix's from another returns a new DMatrix containing the difference. If the sizes aren't the same, you will probably get an ArrayOutOfBounds exception. To do 'c = a - b', use c = subtract(a,b). Too bad operator overloading is so complicated and confusing...

multiply

public final void multiply(double x)

Multiplies all values in this DMatrix by a specified double.

multiply

public static final DMatrix multiply(DMatrix a,
                                     double b)

Multiplies a DMatrix by a double and returns a new DMatrix containing the result.

multiply

public static final DMatrix multiply(double b,
                                     DMatrix a)

Multiplies a DMatrix by a double and returns a new DMatrix containing the result.

multiply

public final DMatrix multiply(DMatrix x)

Multiples this DMatrix by another DMatrix, and returns another DMatrix containing the result. 'c = a * b' could be expressed as c = a.multiply(b), or c = multiply(a,b). Note that multiply(a,b) is not the same as multiply(b,a).

Throws:

java.lang.IllegalArgumentException - if the number of rows/columns in the two matrices don't match up (the number of rows and columns in B must match the number of columns and rows in A).

multiply

public static final DMatrix multiply(DMatrix a,
                                     DMatrix b)

Multiplies two DMatrix's, and returns another DMatrix containing the result. 'c = a * b' could be expressed as c = a.multiply(b), or c = multiply(a,b). Note that multiply(a,b) is not the same as multiply(b,a).

Throws:

java.lang.IllegalArgumentException - if the number of rows/columns in the two matrices don't match up (the number of rows and columns in B must match the number of columns and rows in A).

divide

public final void divide(double x)

Divides this DMatrix by a specified double.

divide

public static final DMatrix divide(DMatrix a,
                                   int b)

Divides a DMatrix by a double, and returns a new DMatrix containing the result.

rescale

public final void rescale(double offset,
                          double scale)

Rescales every value in this DMatrix: data[i][j] -> (data[i][j] + offset) * scale

Parameters:

offset - value added to data

scale - data is multiplied by this after offset is added

rescaleTo

public final void rescaleTo(double newMean,
                            double newSD)

Rescales to a given mean and standard deviation. This uses the sample 'standard' deviation. If the current stdev is zero, it will change the mean but be unable to change the stdev.

See Also:

average(), stdev()

transpose

public final DMatrix transpose()

Returns the transpose of this DMatrix.

isEmpty

public final boolean isEmpty()

Does the matrix contain all zeroes?

max

public final double max()

What's the maximum value in the matrix?

min

public final double min()

What's the minimum value in the matrix?

normalize

public final void normalize()

Rescale matrix so the average is one. If the average is zero, this can't be done, so it does nothing. Note that this is not the same thing as normalizing a vector.

See Also:

DVector.normalize()

average

public final double average()

Returns the average value in the matrix.

mean

public final double mean()

Returns the mean value in the matrix. This is usually really close to the average.

stdev

public final double stdev()

Returns the standard deviation of a distribution containing all values in the matrix. This is the 'sample' standard deviation.

stdevp

public final double stdevp()

Returns the standard deviation of a distribution containing all values in the matrix. This is the 'population' standard deviation.

covar

public final double covar(DMatrix y)

Returns the covariance of values in this matrix with those in another matrix.

Throws:

java.lang.IllegalArgumentException - if the matrices are not the same size.

pearson

public final double pearson(DMatrix y)

Returns the Pearson correlation coefficient R of values in this matrix with values in another matrix.

Throws:

java.lang.IllegalArgumentException - if the matrices are not the same size.

zScore

public final double zScore(double x)

Shows how many standard deviations (of this matrix) a given double is below the average (of this matrix)

smooth

public final void smooth(double minValid,
                         int maxTolerance)

This function smooths the matrix by averaging over adjacent blocks. The minimum size of the block is 1x1, but this is expanded in larger and larger rectangles until at least N statistics are included in the averaging.

Parameters:

minValid - N, include at least this many samples before averaging.

maxTolerance - don't expand the rectangle more than this many units. 0 = 1x1 maximum, 1 = 3x3 maximum, etc.

smoothPeriodic

public final void smoothPeriodic(double minValid,
                                 int maxTolerance)

This function smooths the matrix by averaging over adjacent blocks. The minimum size of the block is 1x1, but this is expanded in larger and larger circles until at least N statistics are included in the averaging. This assumes the matrix represents a periodic function, so averages off one edge of the matrix continue to the opposite edge.

Parameters:

minValid - N, include at least this many samples before averaging.

maxTolerance - don't expand the circle more than this many units. 0 = 0 units away, 1 = 1 units away, etc.

diffuse

public final void diffuse()

This does a single round of 'diffusive smoothing' on the matrix. The value at each point is weighted by 4.0, and averaged with the 4 adjacent points.

makeTransform

public static final DMatrix makeTransform(double x,
                                          double y,
                                          double z,
                                          double phi,
                                          double theta,
                                          double psi)

Return a transformation matrix given 3 transformation coordinates and 3 Euler rotation angles. Rotation by rotation matrix R (phi,Z then theta,X then psi,Z) followd by transformation T (x,y,z). This is a 4x4 matrix, with the last column always being (0,0,0,1). It should therefore only be used to transform DVectors with length 3.

See Also:

DVector.transform(org.strbio.math.DMatrix)

makeInverseTransform

public static final DMatrix makeInverseTransform(double x,
                                                 double y,
                                                 double z,
                                                 double phi,
                                                 double theta,
                                                 double psi)

Return an inverse transformation matrix given 3 transformation coordinates and 3 Euler rotation angles. This means, transform by T', where T' is -R'T, and rotation by R, where R is (-psi,Z then -theta,X then -phi,Z) This is a 4x4 matrix, with the last column always being (0,0,0,1). It should therefore only be used to transform DVectors with length 3.

See Also:

DVector.transform(org.strbio.math.DMatrix)

print

public void print(Printf outfile)
           throws java.io.IOException

prints in ascii to an open Printf, with a nicer format than 'save'.

Throws:

java.io.IOException

See Also:

save(org.strbio.io.Printf)

print

public void print(java.lang.String filename)
           throws java.io.IOException

prints in ascii to a new file, with a nicer format than 'save'. Will overwrite any existing file with the same name.

Throws:

java.io.IOException

See Also:

save(org.strbio.io.Printf)

save

public void save(Printf outfile)
          throws java.io.IOException

Save to an open Printf. You can comment the file with lines beginning with a semicolon.

Throws:

java.io.IOException

See Also:

Printf

saveBinary

public void saveBinary(java.io.DataOutputStream outfile)
                throws java.io.IOException

Save in binary format to an open DataOutputStream.

Throws:

java.io.IOException

saveDplot

public final void saveDplot(java.lang.String filename)
                     throws java.io.IOException

Saves in Dplot (ASGL) format to a new text file. Overwrites any existing file.

Parameters:

filename - the file name.

Throws:

java.io.IOException

load

public void load(java.io.BufferedReader infile)
          throws java.io.IOException

Load Ascii from an open BufferedReader. You can comment the matrix with lines beginning with a semicolon.

Throws:

java.io.IOException

load

public void load(java.io.DataInputStream infile)
          throws java.io.IOException

Load binary matrix from an open DataInputStream.

Throws:

java.io.IOException

save

public void save(java.lang.String filename)
          throws java.io.IOException

Saves to a new text file. Overwrites any existing file. You can comment the file with lines beginning with a semicolon.

Parameters:

filename - the file name.

Throws:

java.io.IOException

saveBinary

public void saveBinary(java.lang.String filename)
                throws java.io.IOException

Saves to a new binary file. Overwrites any existing file.

Parameters:

filename - the file name.

Throws:

java.io.IOException

load

public void load(java.lang.String filename)
          throws java.io.IOException

Loads matrix from a file; file type (text/binary) is autodetected.

Parameters:

filename - the file name.

Throws:

java.io.IOException