Facemorph.tensor
Class Tensor

java.lang.Object
  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[]	buildWithAverage(double[][] weights, int dataDim, int subDim, 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

buildWithAverage

public BigMat[] buildWithAverage(double[][] weights,
                                 int dataDim,
                                 int subDim,
                                 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

subDim - the dimension that has already had the average calculated and subtracted

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.