Facemorph.tensor
Class Tensor

java.lang.Object
  extended by Facemorph.tensor.Tensor
All Implemented Interfaces:
java.io.Serializable, java.lang.Iterable

public class Tensor
extends java.lang.Object
implements java.io.Serializable, java.lang.Iterable

Tensor model implementation

See Also:
Serialized Form

Constructor Summary
Tensor()
          Creates a new instance of Tensor
Tensor(int[] dims)
          constructor
Tensor(int[] dims, double[] data)
          Constructor with some data
 
Method Summary
 void addRowAverages(Tensor rowAvs, int dim, int dataDim)
          Add row average
 void addRowAveragesInPlace(Tensor average, int row)
          Add the row average for each row to each element along that row
static void adjust(double[] params, double[] mean, double[] sd)
          Subtracts the mean and multiplies by the standard deviation
static void adjust(double[] params, int start, int end, double amount)
          multiplies elements of params from start to end by amount
 BigMat[] build(boolean rotate, double[][] weights)
          build N-way model, replace this with the core tensor and return the rotation components.
 BigMat[] build(boolean rotate, double[][] weights, int dataDim)
          build N-way model, replace this with the core tensor and return the rotation components.
static java.awt.Image buildAverageFromWarped(java.util.Vector<java.awt.Image> images)
          Build an average from a set of warped images
 BigMat[] buildWithAverage(double[][] weights, int dataDim, double maxvar)
          build N-way model, replace this with the core tensor and return the rotation components
 BigMat[] buildWithAverageInPlace(double[][] weights, int dataDim, double maxvar)
          build N-way model, replace this with the core tensor and return the rotation components
 double[][] convertParams(double[] params, int dataDim)
          Convert a single set of linear parameters into a set of parameters alon each direction
 void copy(Tensor rhs)
          Copy another Tensor
static BigMat createAverageAndSubtractMatrix(int width)
          Creates the matrix that can be used to calculate and subtract the average from rows of length width
static void createExampleData(java.lang.String[] args)
          Create some example data, reconstructs some example images
static void deAdjust(double[] params, double[] mean, double[] sd)
          Reverse the whitening
 void fold(int i, BigMat M)
          Fold the matrix into this Tensor along the axis given
 double get(int[] in)
          Sample from the Tensor
static double[] getALSWeights(BigMat coeffs, double[] testData)
          Get the paramter weights for test data using linear matrix coeffs
 double[][] getALSWeights(double[] testData, double[][] params, int dataDim, int maxIts)
          Get the alternating least squares estimate of the weights
 double[][] getBestRankTensor(int rank)
          Gets the best tensor of the given rank
 BigMat getCovar(int i, boolean skipFirst)
          unfold method, unfolds along a dimension i
 BigMat getFullLinearAnalysisMatrix(int dataDim, BigMat average, boolean skipFirst)
          Get the fll tensor as a linear analysis matrix
static Tensor getImageTensor(int[] dims, java.util.Vector<java.awt.Image> images)
          Create a Tensor from a set of images
 BigMat getLinearAnalysisMatrix(int dataDim, BigMat average)
          Gets a linear analysis matrix
static Tensor getOuterProduct(double[][] vecs)
          Gets the outer product tensor from the array of vectors
static Tensor getOuterProductAppend1(double[][] vecs)
          Gets the outer product tensor when each parameter vector has 1 appended/prepended at the start
 double getRankWeight(double[][] vecs)
          Returns data[0]/product(vecs[i][0])
 Tensor getRowAverage(int row)
          Gets the row average
static Tensor getTemplateTensor(int[] dims, java.util.Vector<Template> templates)
          Get A Tensor from a set of Templates
 double[] getVariance(double[] mean, int dim)
          Get the variance along the dimension specified
protected  int index(int[] in)
          return the index into the data at point in[i,j,k...n]
 java.util.Iterator<java.lang.Double> iterator()
          Returns an iterator over a set of elements of type T.
 java.util.Iterator<java.lang.Double> iterator(int dim)
          Returns an iterator over a set of elements of type T.
static double[] linearAnalyse(BigMat linearModel, BigMat average, double[] testData)
          Analyse some test data with a linear model
static void main(java.lang.String[] args)
          Main method for testing
 Tensor multiply(int i, BigMat M)
          multiply method for N-mode product with M along row i
 void multiplyInPlace(int i, BigMat M)
          multiply method for N-mode product with M along row i
static double normalisedScalarProduct(double[] v, double[] u)
          Normalised scalar product
 BigMat planeAverages(int dim, int dataDim)
          Average across all but dim and dataDim
 void read(java.io.InputStream is)
          Read from an InputStream
 boolean read(java.lang.String filename)
          Read from a file
 Tensor reconstruct(BigMat[] U)
          Tensor reconstruction method
 double[] reconstruct(double[][] weights, int dataDim)
          Reconstruct from a set of edge weights
 double[] reconstruct(double[][] weights, int i, BigMat U)
          reconstruct first multiplying by transpose U along i
 double[] reconstruct(double[][] weights, int dataDim, double s)
          Reconstructs and multiplies each element by by s
 BigMat reconstructForALS(double[][] weights, int dataDim, int studyDim)
          Reconstruction for alternating least squares method
 double[] reconvertParams(double[][] params, int dataDim)
          Converts a set of edge parameters into a single vector
 Tensor rowAverages(int dim, int dataDim, boolean subtract)
          Calculates the averages along rows indexed by dim
 BigMat rowPCAMatrix(int dim, int dataDim, double[] w)
          Calculates the PCA rotation matrix along one row
 void set(int[] in, double value)
          Set an element of the Tensor
 int size(int d)
          Get the length of dimension d
 Tensor subtractAverage(int row)
          Subtract the row average from each element in that row
 void subtractAverageInPlace(int row)
          Subtract the average from each row without creating a new Tensor to hold the result
static void testAverage(java.lang.String[] args)
          Test the ALS method for finding parameters
static void testAverageTransforms(java.lang.String[] args)
          Another test method
static void testFitting(java.lang.String[] args)
          Test fitting
static void testHOSVD(java.lang.String[] args)
          Test for high order SVD (HOSVD)
static void testLinear(java.lang.String[] args)
          Test the linear approximate method
 BigMat unfold(int i)
          unfold method, unfolds along a dimension i
 double[] vectorise()
          Vectorise the Tensor
 double[] vectoriseAppended()
          Vectorise
 boolean whiten(int i, double[] mean, double[] sd)
          Whiten the data (i.e.
 void write(java.io.PrintStream ps)
          Write to a PrintStream
 boolean write(java.lang.String filename)
          Write a Tensor model to file
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Tensor

public Tensor()
Creates a new instance of Tensor


Tensor

public Tensor(int[] dims)
constructor

Parameters:
dims - length of dimensions

Tensor

public Tensor(int[] dims,
              double[] data)
Constructor with some data

Parameters:
dims - the length of each dimension
data - the data
Method Detail

index

protected int index(int[] in)
return the index into the data at point in[i,j,k...n]

Parameters:
in - - array containing the n-mode coordinates
Returns:
returns the index referenceed by the array

get

public double get(int[] in)
Sample from the Tensor

Parameters:
in - the array of coordinates
Returns:
returns the data referenceed by the array

set

public void set(int[] in,
                double value)
Set an element of the Tensor

Parameters:
in - the position
value - the value

size

public int size(int d)
Get the length of dimension d

Parameters:
d - the index of the dimension to get
Returns:
return the length of the dimension

copy

public void copy(Tensor rhs)
Copy another Tensor

Parameters:
rhs -

unfold

public BigMat unfold(int i)
unfold method, unfolds along a dimension i

Parameters:
i - the direction to unfold along
Returns:
return the unfolded Tensor as a Matrix

getCovar

public BigMat getCovar(int i,
                       boolean skipFirst)
unfold method, unfolds along a dimension i

Parameters:
i - dimension to unfold along
skipFirst - optionally skip the first
Returns:
retrn the unfolded Tensor as a matrix

vectorise

public double[] vectorise()
Vectorise the Tensor

Returns:
just returns the data vector

vectoriseAppended

public double[] vectoriseAppended()
Vectorise

Returns:
return the Tensor vectorised

getOuterProduct

public static Tensor getOuterProduct(double[][] vecs)
Gets the outer product tensor from the array of vectors

Parameters:
vecs - the array of vectors
Returns:
returns the outer product tensor

getOuterProductAppend1

public static Tensor getOuterProductAppend1(double[][] vecs)
Gets the outer product tensor when each parameter vector has 1 appended/prepended at the start

Parameters:
vecs - the parameter vectors (without the initial 1)
Returns:
the outer product of the vectors with an additional 1 at the start of each

fold

public void fold(int i,
                 BigMat M)
Fold the matrix into this Tensor along the axis given

Parameters:
i - the axis to fold the matrix along
M - the matrix to fold

multiply

public Tensor multiply(int i,
                       BigMat M)
                throws BigMatException
multiply method for N-mode product with M along row i

Parameters:
i - the row, the vectors are extracted along this dimension and multiplied by M, the result is put into the output Tensor
M - the matrix to multiply the vectors with
Returns:
returns the Tensor formed with the N-mode product
Throws:
BigMatException

whiten

public boolean whiten(int i,
                      double[] mean,
                      double[] sd)
Whiten the data (i.e. subtract the mean and divide by the s.d.) along a particular direction

Parameters:
i - the data row to use
mean - the mean vector
sd - the standard deviation vector
Returns:
return true if successful, false if there is a problem, such as incorrect vector lengths

multiplyInPlace

public void multiplyInPlace(int i,
                            BigMat M)
                     throws BigMatException
multiply method for N-mode product with M along row i

Parameters:
i - the direction of the vectors to multiply
M - matrix to multiply with, must be square for the in-place version
Throws:
BigMatException

build

public BigMat[] build(boolean rotate,
                      double[][] weights)
build N-way model, replace this with the core tensor and return the rotation components. We keep the weightings, do we need them?

Parameters:
rotate - if true the PCA rotations are applied to this Tensor
weights - the PCA diagonal vectors are placed here
Returns:
return the rotation components (row Eigenvectors)

build

public BigMat[] build(boolean rotate,
                      double[][] weights,
                      int dataDim)
build N-way model, replace this with the core tensor and return the rotation components. We keep the weightings, do we need them?

Parameters:
rotate - if true rotate this Tensor with the estimated rotation matrices
weights - the weight (row Eigenvalues)
dataDim - the data dimension to leave untouched
Returns:
return the rotation matrices contain the Eigenvectors

getRankWeight

public double getRankWeight(double[][] vecs)
Returns data[0]/product(vecs[i][0])

Parameters:
vecs - the vectors
Returns:
returns data[0]/product(vecs[i][0])

getBestRankTensor

public double[][] getBestRankTensor(int rank)
Gets the best tensor of the given rank

Parameters:
rank - not currently used (Use method with extreme caution!)
Returns:
returns vec[i][j] = U[i](0,j) where U is returned from building the Tensor (i.e. the rotations)

getRowAverage

public Tensor getRowAverage(int row)
Gets the row average

Parameters:
row - the row to averages, average along the row given
Returns:
return the reduced Tensor, flattened along the dimension given by averaging

addRowAveragesInPlace

public void addRowAveragesInPlace(Tensor average,
                                  int row)
Add the row average for each row to each element along that row

Parameters:
average - the Tensor of row averages
row - the dimension to add the averages along

subtractAverage

public Tensor subtractAverage(int row)
Subtract the row average from each element in that row

Parameters:
row - the row to average / subtract along
Returns:
return the Tensor after subtracting the row average from each row

subtractAverageInPlace

public void subtractAverageInPlace(int row)
Subtract the average from each row without creating a new Tensor to hold the result

Parameters:
row - the row to average along

buildWithAverage

public BigMat[] buildWithAverage(double[][] weights,
                                 int dataDim,
                                 double maxvar)
build N-way model, replace this with the core tensor and return the rotation components

Parameters:
weights - stores the output row weightings (row Eigenvalues)
dataDim - the data dimension to leave untouched
maxvar - the maximum variance to explain along each dimension
Returns:
returns the row Eigen vector (rotation) matrices

buildWithAverageInPlace

public BigMat[] buildWithAverageInPlace(double[][] weights,
                                        int dataDim,
                                        double maxvar)
build N-way model, replace this with the core tensor and return the rotation components

Parameters:
weights - stores the output row weightings (row Eigenvalues)
dataDim - the data dimension to leave untouched
maxvar - the maximum variance to explain along each dimension
Returns:
returns the row Eigen vector (rotation) matrices

convertParams

public double[][] convertParams(double[] params,
                                int dataDim)
Convert a single set of linear parameters into a set of parameters alon each direction

Parameters:
params - the linear parameters
dataDim - the data dimension
Returns:
returns the converted parameters

reconvertParams

public double[] reconvertParams(double[][] params,
                                int dataDim)
Converts a set of edge parameters into a single vector

Parameters:
params - the edge parameters
dataDim - the data dimension
Returns:
returns the parameteres as a single vector

getTemplateTensor

public static Tensor getTemplateTensor(int[] dims,
                                       java.util.Vector<Template> templates)
Get A Tensor from a set of Templates

Parameters:
dims - the dimensions (make sure the vector is ordered properly)
templates - the templates to put in the tensor
Returns:
return a tensor containing the template data

getImageTensor

public static Tensor getImageTensor(int[] dims,
                                    java.util.Vector<java.awt.Image> images)
Create a Tensor from a set of images

Parameters:
dims - the data dimensions
images - the images to Tensorise
Returns:
returns a Tensor contain the image data

linearAnalyse

public static double[] linearAnalyse(BigMat linearModel,
                                     BigMat average,
                                     double[] testData)
Analyse some test data with a linear model

Parameters:
linearModel - the linear matrix
average - teh average, should be Mx1, subtracted before the matrix multiplication
testData - the data to analyse
Returns:
returns the linear model parameters

getLinearAnalysisMatrix

public BigMat getLinearAnalysisMatrix(int dataDim,
                                      BigMat average)
Gets a linear analysis matrix

Parameters:
dataDim - the data dimension
average - the average
Returns:
returns the linear analysis matrix

getFullLinearAnalysisMatrix

public BigMat getFullLinearAnalysisMatrix(int dataDim,
                                          BigMat average,
                                          boolean skipFirst)
Get the fll tensor as a linear analysis matrix

Parameters:
dataDim - the data dimension
average - the average
skipFirst - should the first element of each row be treated as 1
Returns:
return the big matrix

reconstruct

public double[] reconstruct(double[][] weights,
                            int dataDim)
Reconstruct from a set of edge weights

Parameters:
weights - the weights
dataDim - the data dimensions
Returns:
the reconstructed vector

reconstruct

public double[] reconstruct(double[][] weights,
                            int dataDim,
                            double s)
Reconstructs and multiplies each element by by s

Parameters:
weights - the parameter weights
dataDim - the data dimension
s - the scale factor
Returns:
returns the reconstructed vector

reconstructForALS

public BigMat reconstructForALS(double[][] weights,
                                int dataDim,
                                int studyDim)
Reconstruction for alternating least squares method

Parameters:
weights - the parameters
dataDim - te data dimension
studyDim - the current fixed dimension in the ASL process
Returns:
returns the reconstruction unfolded along the data dimension

getALSWeights

public static double[] getALSWeights(BigMat coeffs,
                                     double[] testData)
Get the paramter weights for test data using linear matrix coeffs

Parameters:
coeffs - the matrix to use
testData - the test data to analyse
Returns:
return the estimate of the weights using the model coeffs

getALSWeights

public double[][] getALSWeights(double[] testData,
                                double[][] params,
                                int dataDim,
                                int maxIts)
Get the alternating least squares estimate of the weights

Parameters:
testData - the test data to get parameters for
params - the original workspace
dataDim - the data dimension
maxIts - teh maximum iteration to use
Returns:
return the estimated parameter weights for test data

reconstruct

public double[] reconstruct(double[][] weights,
                            int i,
                            BigMat U)
reconstruct first multiplying by transpose U along i

Parameters:
weights - the parameter weights
i - the row to multiply along
U - the matrix to multiply with
Returns:
return the reconstructed vector

reconstruct

public Tensor reconstruct(BigMat[] U)
Tensor reconstruction method

Parameters:
U - the set of rotation / Eigenvector matrices
Returns:
return the reconstructed tensor

rowAverages

public Tensor rowAverages(int dim,
                          int dataDim,
                          boolean subtract)
Calculates the averages along rows indexed by dim

Parameters:
dim - the dimension to average along
dataDim - the dimension containing the data vectors
subtract - flag indicating if the row average should be subtracted from each element in the row
Returns:
a Tensor of degree 1 less than this, containing the row averages

rowPCAMatrix

public BigMat rowPCAMatrix(int dim,
                           int dataDim,
                           double[] w)
Calculates the PCA rotation matrix along one row

Parameters:
dim - the dimension to perform the row PCA along
dataDim - the dimension holding the data vectors
w - an array to store the calulated weight of each component
Returns:
Return a matrix that performs combined averaging and PCA reordering along each row

addRowAverages

public void addRowAverages(Tensor rowAvs,
                           int dim,
                           int dataDim)
Add row average

Parameters:
rowAvs - the tensor of row averages
dim - the dimension to work on
dataDim - the data dimension

createAverageAndSubtractMatrix

public static BigMat createAverageAndSubtractMatrix(int width)
Creates the matrix that can be used to calculate and subtract the average from rows of length width

Parameters:
width - the size of the fibres to multiply
Returns:
return the appropriate matrix

planeAverages

public BigMat planeAverages(int dim,
                            int dataDim)
Average across all but dim and dataDim

Parameters:
dim - the first direction to keep
dataDim - the second direction to keep
Returns:
returns the Tensor squished into a Matrix

write

public boolean write(java.lang.String filename)
Write a Tensor model to file

Parameters:
filename - the file to write to
Returns:
returns true if written OK

write

public void write(java.io.PrintStream ps)
           throws java.io.IOException
Write to a PrintStream

Parameters:
ps - the PrintStream to write to
Throws:
java.io.IOException

read

public boolean read(java.lang.String filename)
Read from a file

Parameters:
filename - the file to read from
Returns:
returns true if read OK

read

public void read(java.io.InputStream is)
          throws java.io.IOException
Read from an InputStream

Parameters:
is - the InputStream to read from
Throws:
java.io.IOException

buildAverageFromWarped

public static java.awt.Image buildAverageFromWarped(java.util.Vector<java.awt.Image> images)
Build an average from a set of warped images

Parameters:
images - the images to average
Returns:
returns the averaged images

getVariance

public double[] getVariance(double[] mean,
                            int dim)
Get the variance along the dimension specified

Parameters:
mean - space to return the mean vector
dim - the dimension
Returns:
returns the variance vector

adjust

public static void adjust(double[] params,
                          int start,
                          int end,
                          double amount)
multiplies elements of params from start to end by amount

Parameters:
params -
start -
end -
amount -

adjust

public static void adjust(double[] params,
                          double[] mean,
                          double[] sd)
Subtracts the mean and multiplies by the standard deviation

Parameters:
params - the vector to whiten
mean - the mean
sd - the standard deviation

deAdjust

public static void deAdjust(double[] params,
                            double[] mean,
                            double[] sd)
Reverse the whitening

Parameters:
params - the vector to re-adjust
mean - the mean
sd - the standard deviation

main

public static void main(java.lang.String[] args)
Main method for testing

Parameters:
args - not currently used

testAverage

public static void testAverage(java.lang.String[] args)
Test the ALS method for finding parameters

Parameters:
args - the test args, reads the Tensor from args[0], reads a BigMat from args[1], writes results to args[2]

testAverageTransforms

public static void testAverageTransforms(java.lang.String[] args)
Another test method

Parameters:
args - args[0] is the training image-template list, args[1] the width, args[2] the height, args[3] the mask, args[4] the test image-template list

normalisedScalarProduct

public static double normalisedScalarProduct(double[] v,
                                             double[] u)
Normalised scalar product

Parameters:
v - the first vector
u - the second vector
Returns:
returns the scalar product of the normalised vectors

testHOSVD

public static void testHOSVD(java.lang.String[] args)
Test for high order SVD (HOSVD)

Parameters:
args - args[0] is the training set, args[1] - width, args[2] - height, args[3] - mask, args[4] test set

testLinear

public static void testLinear(java.lang.String[] args)
Test the linear approximate method

Parameters:
args - args[0] training set, args[1]-width, args[2]-height, args[3]-mask, args[4]-test set

testFitting

public static void testFitting(java.lang.String[] args)
Test fitting

Parameters:
args - args[0] training set, args[1]-width, args[2]-height, args[3]-mask, args[4]-test set

createExampleData

public static void createExampleData(java.lang.String[] args)
Create some example data, reconstructs some example images

Parameters:
args - args[0] training set, args[1]-width, args[2]-height, args[3]-mask

iterator

public java.util.Iterator<java.lang.Double> iterator()
Returns an iterator over a set of elements of type T.

Specified by:
iterator in interface java.lang.Iterable
Returns:
an Iterator.

iterator

public java.util.Iterator<java.lang.Double> iterator(int dim)
Returns an iterator over a set of elements of type T.

Parameters:
dim -
Returns:
an Iterator.