edu.ucla.sspace.matrix

Interface MatrixBuilder

All Known Implementing Classes:

ClutoDenseMatrixBuilder, ClutoSparseMatrixBuilder, MatlabSparseMatrixBuilder, SvdlibcSparseBinaryMatrixBuilder

public interface MatrixBuilder

An interface for utilities that support incrementally building matrices on disk, one column at a time. Instances of these class are designed to abstract away the format-specific details of writing the matrix to disk.

Columns may be added via the addColumn method until the matrix has the desired data. The underlying matrix structure will expand to match the dimensions of the input data. Great care should be taken when using SparseArray and DoubleVector instances to ensure that the values returned by their respective length methods are fixed to the actual data structure size, rather than the a possible maximum size of the struture. This is necessary to determine this matrix's dimension; passing in an array or vector with a maximum size bound will greatly distort the matrix's size.

After all the data has been added, the finish method should be invoked. Instances should use this as a signal to finish any last remaining writes or perform any necessary post processing for the matrix. Once this method returns the getMatrixFile method will allow access to the finished data in its correct format.

Implementations may cache all, part, or none of the data prior to finishing the matrix data. However, all implementations are expected to be have a low memory overhead, especially when building large matrices.

All implementations are expected to be thread-safe.

Author:

David Jurgens

Method Summary

Methods

Modifier and Type	Method and Description
int	addColumn(double[] column) Adds the column values to the underlying matrix, updating the dimensions as necessary and returning the index at which the column was added.
int	addColumn(SparseArray<? extends Number> column) Adds the double values in the array to the underlying matrix, updating the dimensions as necessary and returning the index at which the column was added.
int	addColumn(Vector column) Adds the vector values to the underlying matrix, updating the dimensions as necessary and returning the index at which the column was added.
void	finish() Indicates that no further data will be added to the matrix and any remaining matrix meta-data should be written and flushed to disk.
File	getFile() Returns the file containing the matrix data after all data has finished being written.
MatrixFile	getMatrixFile()
MatrixIO.Format	getMatrixFormat() Returns the data format for the matrix file.
boolean	isFinished() Returns true if no further data should be added to the matrix and the file containing the data is available for us.

Method Detail

addColumn

int addColumn(double[] column)

Adds the column values to the underlying matrix, updating the dimensions as necessary and returning the index at which the column was added.

Parameters:

column - the values of the column in the matrix.

Returns:

the index at which the column is present.

Throws:

IllegalStateException - if finish has been called, thereby signaling that no further data will be added to the matrix

addColumn

int addColumn(SparseArray<? extends Number> column)

Adds the double values in the array to the underlying matrix, updating the dimensions as necessary and returning the index at which the column was added.

Parameters:

column - the values of the column in the matrix.

Returns:

the index at which the column is present.

Throws:

IllegalStateException - if finish has been called, thereby signaling that no further data will be added to the matrix

addColumn

int addColumn(Vector column)

Adds the vector values to the underlying matrix, updating the dimensions as necessary and returning the index at which the column was added.

Parameters:

column - the values of the column in the matrix.

Returns:

the index at which the column is present.

Throws:

IllegalStateException - if finish has been called, thereby signaling that no further data will be added to the matrix

finish

void finish()

Indicates that no further data will be added to the matrix and any remaining matrix meta-data should be written and flushed to disk. Once this method has been called addColumn will thcolumn a IllegalStateException if called.

getFile

File getFile()

Returns the file containing the matrix data after all data has finished being written. The finish method must be called prior to accessing the underlying file to ensure that all necessary matrix meta-data has been written to disk.

Returns:

the file containing the matrix data

Throws:

IllegalStateException - if finish has not yet been called, which indicates that the file would be in an inconsistent state

getMatrixFormat

MatrixIO.Format getMatrixFormat()

Returns the data format for the matrix file.

Returns:

the format of the matrix's data

getMatrixFile

MatrixFile getMatrixFile()

isFinished

boolean isFinished()

Returns true if no further data should be added to the matrix and the file containing the data is available for us. This will only return true if finish has been called first.

Returns:

true if no further data should be added to the matrix