edu.ucla.sspace.matrix

Class MatrixIO

java.lang.Object

edu.ucla.sspace.matrix.MatrixIO

public class MatrixIO
extends Object

A shared utility for printing matrices to files in a uniform manner and converting between different formats.

Author:

David Jurgens

See Also:

MatrixIO.Format, Matrix, Matrix.Type

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MatrixIO.Format An enum that specifies the formatting used for the matrix that is serialized in a file.

Method Summary

Methods

Modifier and Type	Method and Description
static File	convertFormat(File matrix, MatrixIO.Format current, MatrixIO.Format desired) Converts the format of the input matrix, returning a temporary file containing the matrix's data in the desired format.
static File	convertFormat(File matrix, MatrixIO.Format current, MatrixIO.Format desired, boolean transpose) Converts the format of the input matrix, returning a temporary file containing the matrix's data in the desired format.
static FileTransformer	fileTransformer(MatrixIO.Format format) Returns a FileTransformer for an Matrix file encodeded in the provided MatrixIO.Format.
static Iterator<MatrixEntry>	getMatrixFileIterator(File matrixFile, MatrixIO.Format fileFormat) Returns an iterator over the matrix entries in the data file.
static Matrix	readMatrix(File matrix, MatrixIO.Format format) Converts the contents of a matrix file as a Matrix object, using the provided format as a hint for what kind to create.
static Matrix	readMatrix(File matrix, MatrixIO.Format format, Matrix.Type matrixType) Converts the contents of a matrix file as a Matrix object, using the provided type description as a hint for what kind to create.
static Matrix	readMatrix(File matrix, MatrixIO.Format format, Matrix.Type matrixType, boolean transposeOnRead) Converts the contents of a matrix file as a Matrix object, using the provided type description as a hint for what kind to create.
static double[][]	readMatrixArray(File input, MatrixIO.Format format) Deprecated.
static void	writeMatrix(Matrix matrix, File output, MatrixIO.Format format) Writes the matrix to the specified output file in the provided format
static void	writeMatrixArray(double[][] matrix, File output) Deprecated.

Methods inherited from class java.lang.Object

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

Method Detail

convertFormat

public static File convertFormat(File matrix,
                 MatrixIO.Format current,
                 MatrixIO.Format desired)
                          throws IOException

Converts the format of the input matrix, returning a temporary file containing the matrix's data in the desired format.

Parameters:

matrix - a file containing a matrix to convert

current - the format of the matrix file

desired - the format of the returned matrix file

Returns:

a matrix file with the same data in the desired format

Throws:

IOException - if any error occurs while reading the input matrix or wring the output matrix

convertFormat

public static File convertFormat(File matrix,
                 MatrixIO.Format current,
                 MatrixIO.Format desired,
                 boolean transpose)
                          throws IOException

Converts the format of the input matrix, returning a temporary file containing the matrix's data in the desired format.

Parameters:

matrix - a file containing a matrix to convert

current - the format of the matrix file

desired - the format of the returned matrix file

transpose - true if data in the input matrix should be transposed while converting formats to the output matrix.

Returns:

a matrix file with the same data in the desired format

Throws:

IOException - if any error occurs while reading the input matrix or wring the output matrix

getMatrixFileIterator

public static Iterator<MatrixEntry> getMatrixFileIterator(File matrixFile,
                                          MatrixIO.Format fileFormat)
                                                   throws IOException

Returns an iterator over the matrix entries in the data file. For sparse formats that specify only non-zero, no zero valued entries will be returened. Conversely, for dense matrix formats, all of the entries, including zero entries will be returned.

Parameters:

matrixFile - the file containing matrix data in the specified format

fileFormat - the format of the matrix file

Returns:

an interator over the entries in the matrix file

Throws:

IOException

fileTransformer

public static FileTransformer fileTransformer(MatrixIO.Format format)

Returns a FileTransformer for an Matrix file encodeded in the provided MatrixIO.Format.

Parameters:

format - the format of a Matrix that will be transformed

Returns:

A FileTransformer for the given format

readMatrixArray

@Deprecated
public static double[][] readMatrixArray(File input,
                                    MatrixIO.Format format)
                                  throws IOException

Deprecated.

Reads in the content of the file as a two dimensional Java array matrix. This method has been deprecated in favor of using purely Matrix objects for all operations. If a Java array is needed, the Matrix#toArray() method may be used to generate one.

Returns:

a two-dimensional array of the matrix contained in provided file

Throws:

IOException

readMatrix

public static Matrix readMatrix(File matrix,
                MatrixIO.Format format)
                         throws IOException

Converts the contents of a matrix file as a Matrix object, using the provided format as a hint for what kind to create. The type of Matrix object created will assuming that the entire matrix can fit in memory based on the format of the file speicfied Note that the returned Matrix instance is not backed by the data on file; changes to the Matrix will not be reflected in the original file's data.

Parameters:

matrix - a file contain matrix data

format - the format of the file

Returns:

the Matrix instance that contains the data in the provided file

Throws:

IOException

readMatrix

public static Matrix readMatrix(File matrix,
                MatrixIO.Format format,
                Matrix.Type matrixType)
                         throws IOException

Converts the contents of a matrix file as a Matrix object, using the provided type description as a hint for what kind to create. The type of Matrix object created will be based on an estimate of whether the data will fit into the available memory. Note that the returned Matrix instance is not backed by the data on file; changes to the Matrix will not be reflected in the original file's data.

Parameters:

matrix - a file contain matrix data

format - the format of the file

matrixType - the expected type and behavior of the matrix in relation to memory. This value will be used as a hint for what kind of Matrix instance to create

Returns:

the Matrix instance that contains the data in the provided file

Throws:

IOException

readMatrix

public static Matrix readMatrix(File matrix,
                MatrixIO.Format format,
                Matrix.Type matrixType,
                boolean transposeOnRead)
                         throws IOException

Converts the contents of a matrix file as a Matrix object, using the provided type description as a hint for what kind to create. The type of Matrix object created will be based on an estimate of whether the data will fit into the available memory. Note that the returned Matrix instance is not backed by the data on file; changes to the Matrix will not be reflected in the original file's data.

Parameters:

matrix - a file contain matrix data

format - the format of the file

matrixType - the expected type and behavior of the matrix in relation to memory. This value will be used as a hint for what kind of Matrix instance to create

transposeOnRead - true if the matrix should be transposed as its data is read in. For certain formats, this is more efficient than reading the data in and then transposing it directly.

Returns:

the Matrix instance that contains the data in the provided file, optionally transposed from its original format

Throws:

IOException - if any error occurs while reading in the matrix data

writeMatrix

public static void writeMatrix(Matrix matrix,
               File output,
               MatrixIO.Format format)
                        throws IOException

Writes the matrix to the specified output file in the provided format

Parameters:

matrix - the matrix to be written

output - the file in which the matrix should be written

format - the data format in which the matrix's data should be written

Throws:

IllegalArgumentException - if the input matrix is 0-dimensional

IOException - if an error occurs while writing to the output file

writeMatrixArray

@Deprecated
public static void writeMatrixArray(double[][] matrix,
                               File output)
                             throws IOException

Deprecated.

Throws:

IOException