org.strbio.math
Class FMatrix

java.lang.Object
  org.strbio.math.FMatrix

public class FMatrix
extends java.lang.Object

a class to encapsulate a 2-D matrix of floats. 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 Float.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(float), makeTransform(), and print()
 Version 1.0, 3/30/98 - original version
 

Version:

1.33, 7/7/99

Author:

JMC

See Also:

IMatrix, FVector, FHalfMatrix

Field Summary

float[][]

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

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

FMatrix(float[][] x)
makes a new FMatrix object out of a float[][] array.

FMatrix(FMatrix x)
copies another FMatrix.

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

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

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

Method Summary

void	add(float x) Adds a float to every value in this FMatrix.
void	add(FMatrix x) Adds another FMatrix to this one.
static FMatrix	add(FMatrix a, FMatrix b) Adds two FMatrix's and returns a new FMatrix containing the sum.
float	average() Returns the average value in the matrix.
int	cols() returns the number of columns in the encapsulated array.
float	covar(FMatrix 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.
void	divide(float x) Divides this FMatrix by a specified float.
static FMatrix	divide(FMatrix a, int b) Divides a FMatrix by a float, and returns a new FMatrix containing the result.
boolean	equals(java.lang.Object x) mathematical objects are equal if their contents are.
FMatrix	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 FMatrix	makeInverseTransform(float x, float y, float z, float phi, float theta, float psi) Return an inverse transformation matrix given 3 transformation coordinates and 3 Euler rotation angles.
static FMatrix	makeTransform(float x, float y, float z, float phi, float theta, float psi) Return a transformation matrix given 3 transformation coordinates and 3 Euler rotation angles.
float	max() What's the maximum value in the matrix?
float	mean() Returns the mean value in the matrix.
float	min() What's the minimum value in the matrix?
void	multiply(float x) Multiplies all values in this FMatrix by a specified float.
static FMatrix	multiply(float b, FMatrix a) Multiplies a FMatrix by a float and returns a new FMatrix containing the result.
FMatrix	multiply(FMatrix x) Multiples this FMatrix by another FMatrix, and returns another FMatrix containing the result.
static FMatrix	multiply(FMatrix a, float b) Multiplies a FMatrix by a float and returns a new FMatrix containing the result.
static FMatrix	multiply(FMatrix a, FMatrix b) Multiplies two FMatrix's, and returns another FMatrix containing the result.
void	normalize() Rescale matrix so the average is one.
float	pearson(FMatrix 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(float offset, float scale) Rescales every value in this FMatrix: data[i][j] -> (data[i][j] + offset) * scale
void	rescaleTo(float newMean, float 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(float x) Sets every value in the matrix to a specified float.
void	setValueAt(int c, int r, float d) Sets the data at a given column/row.
void	smooth(float minValid, int maxTolerance) This function smooths the matrix by averaging over adjacent blocks.
void	smoothPeriodic(float minValid, int maxTolerance) This function smooths the matrix by averaging over adjacent blocks.
float	stdev() Returns the standard deviation of a distribution containing all values in the matrix.
float	stdevp() Returns the standard deviation of a distribution containing all values in the matrix.
void	subtract(float x) Subtracts a float to every value in this FMatrix.
void	subtract(FMatrix x) Subtracts another FMatrix from this one.
static FMatrix	subtract(FMatrix a, FMatrix b) Subtracts one FMatrix's from another returns a new FMatrix containing the difference.
FMatrix	transpose() Returns the transpose of this FMatrix.
float	valueAt(int c, int r) Returns the data at a given column/row.
float	zScore(float x) Shows how many standard deviations (of this matrix) a given float 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 float[][] 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

FMatrix

public FMatrix(int c,
               int r)

makes an emptry FMatrix 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

FMatrix

public FMatrix()

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

FMatrix

public FMatrix(float[][] x)

makes a new FMatrix object out of a float[][] 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 FMatrix(), then dm.data = my_array.

FMatrix

public FMatrix(FMatrix x)

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

FMatrix

public FMatrix(int[][] x)

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

FMatrix

public FMatrix(IMatrix x)

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

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 float 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,
                             float 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(float x)

Sets every value in the matrix to a specified float.

inverse

public final FMatrix inverse()

Returns the inverse of this matrix.

add

public final void add(FMatrix x)

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

add

public final void add(float x)

Adds a float to every value in this FMatrix. Don't tell the Math Police.

add

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

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

subtract

public final void subtract(FMatrix x)

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

subtract

public final void subtract(float x)

Subtracts a float to every value in this FMatrix. Call add instead.

subtract

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

Subtracts one FMatrix's from another returns a new FMatrix 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(float x)

Multiplies all values in this FMatrix by a specified float.

multiply

public static final FMatrix multiply(FMatrix a,
                                     float b)

Multiplies a FMatrix by a float and returns a new FMatrix containing the result.

multiply

public static final FMatrix multiply(float b,
                                     FMatrix a)

Multiplies a FMatrix by a float and returns a new FMatrix containing the result.

multiply

public final FMatrix multiply(FMatrix x)

Multiples this FMatrix by another FMatrix, and returns another FMatrix 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 FMatrix multiply(FMatrix a,
                                     FMatrix b)

Multiplies two FMatrix's, and returns another FMatrix 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(float x)

Divides this FMatrix by a specified float.

divide

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

Divides a FMatrix by a float, and returns a new FMatrix containing the result.

rescale

public final void rescale(float offset,
                          float scale)

Rescales every value in this FMatrix: 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(float newMean,
                            float 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 FMatrix transpose()

Returns the transpose of this FMatrix.

isEmpty

public final boolean isEmpty()

Does the matrix contain all zeroes?

max

public final float max()

What's the maximum value in the matrix?

min

public final float 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:

FVector.normalize()

average

public final float average()

Returns the average value in the matrix.

mean

public final float mean()

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

stdev

public final float stdev()

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

stdevp

public final float stdevp()

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

covar

public final float covar(FMatrix 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 float pearson(FMatrix 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 float zScore(float x)

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

smooth

public final void smooth(float 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(float 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 FMatrix makeTransform(float x,
                                          float y,
                                          float z,
                                          float phi,
                                          float theta,
                                          float 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 FVectors with length 3.

See Also:

FVector.transform(org.strbio.math.FMatrix)

makeInverseTransform

public static final FMatrix makeInverseTransform(float x,
                                                 float y,
                                                 float z,
                                                 float phi,
                                                 float theta,
                                                 float 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 FVectors with length 3.

See Also:

FVector.transform(org.strbio.math.FMatrix)

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