com.jstatcom.model
Class JSCNArray

java.lang.Object
  com.jstatcom.model.AbstractJSCData
      com.jstatcom.model.JSCNArray

All Implemented Interfaces:

JSCData

public final class JSCNArray
extends AbstractJSCData

A wrapper for 2-dimensional number arrays that conforms to the JSCData interface. Number arrays are stored as double[][]. It provides some convenience methods for matrix transformation, but it is not intended to serve as a general purpose matrix class. Instead it provides an adapter to set and get instances of the Jama.Matrix class, which is probably the de facto standard matrix class for JAVA .

A JSCNArray is empty, if the stored array is null or has either zero rows or columns. All rows of array values must have the same length.

All array arguments are copied before they are set as values. The original arrays are untouched. In a similar way all get methods return either a copy of a mutable object (like double[][]) or a reference to an immutable object.

Whenever the value of this data object changes, registered JSCDataListeners are notified via a JSCDataEvent. If not otherwise stated, the event objects always contain the values before the change and after the change.

This class is thread-safe. All access to mutable data is synchronized. All events are fired outside the synchronized blocks.

Author:

Markus Kraetzig

Field Summary

static javolution.xml.XmlFormat<JSCNArray>

JSCNArray_XML XML format field for (de)serialization.

Constructor Summary

JSCNArray(JSCNArray narray)
Copy-Constructor.

JSCNArray(java.lang.String name)
Creates an empty JSCNArray.

JSCNArray(java.lang.String name, double... value)
Creates a JSCNArray from value.

JSCNArray(java.lang.String name, double[][] value)
Creates a JSCNArray from value.

JSCNArray(java.lang.String name, int[] value)
Creates a JSCNArray from value.

JSCNArray(java.lang.String name, int[][] value)
Creates a JSCNArray from value.

Method Summary

void	appendCols(JSCNArray newCols) Appends newCols to the right end of the value array.
void	appendRows(JSCNArray newRows) Appends newRows to the bottom the value array.
void	clear() Clears this data object.
int	cols() Gets the number of columns in the stored array.
JSCNArray	copy() Gets a copy of the current object.
void	delCol(int i) Deletes column i from the value array.
void	delColsIf(int... index) Deletes all columns of this that have a corresponding nonzero element in index.
void	delRow(int i) Deletes row i from the value array.
void	delRowsIf(int... index) Deletes all rows of this that have a corresponding nonzero element in index.
java.lang.String	display() Gets a string representing the double[][] stored.
double[][]	doubleArray() Gets a copy of the underlying value as a double[][].
double	doubleAt(int i, int j) Gets the double element stored at index i, j.
java.lang.Double	doubleValAt(int i, int j) Gets the Double element stored at index i, j.
double[]	getCol(int colIndex) Gets the column of the underlying double array specified with colIndex.
double[][]	getCols(int startCol, int endCol) Gets all columns of the underlying double array defined by startCol:endCol.
double[][]	getPow(double pow) Gets a new double array with the elements raised to the power of pow.
double[]	getRow(int rowIndex) Gets the row of the underlying double array specified with rowIndex.
double[][]	getRows(int startRow, int endRow) Gets all rows of the underlying double array defined by startRow:endRow.
double[][]	getTransposed() Gets a new double array with elements transposed.
int[][]	intArray() Gets a copy of the underlying value as a int[][].
int	intAt(int i, int j) Gets the int element stored at index i, j.
boolean	isEmpty() Gets whether this is empty.
boolean	isEqual(JSCData o) Gets whether the values of this data object and other are logically equal.
boolean	isNaN(int i, int j) Gets whether the element stored at index i, j is of type Double.NaN.
Jama.Matrix	jamaMatrix() Gets the values stored in this JSCNArray as an instance of Jama.Matrix.
java.lang.String	name() Gets the name of the data object.
int	nanCount() Gets the number of double elements that are equal to Double.NaN.
int	rank() Gets the rank of the stored value.
int	rows() Gets the number of rows in the stored array.
double[][]	selColsIf(int... colIndex) Gets all columns of the underlying double array that have a nonzero corresponding element in colIndex.
double[][]	selRowsIf(int... rowIndex) Gets all rows of the underlying double array that have a nonzero corresponding element in rowIndex.
void	setFormatString(java.lang.String newFormatString) Sets a new format string.
void	setVal(double[] newValue) Sets the value of this to newValue, see setVal(double[][] newValue).
void	setVal(double[][] newValue) Sets the value of this to newValue.
void	setVal(int[] newValue) Sets the value of this to newValue, see setVal(double[][] newValue).
void	setVal(int[][] newValue) Sets the value of this to newValue, see setVal(double[][] newValue).
void	setVal(JSCNArray val) Sets the values stored in val to this JSCNArray.
void	setVal(Jama.Matrix mat) Sets the values stored in mat to this JSCNArray.
void	setValAt(double val, int i, int j) Sets the double element stored at index i, j.
java.lang.String	toString() Gets a string representation of this JSCNArray instance.
void	transpose() Transposes the underlying array.
JSCTypes	type() Gets the type of this JSCData object.
java.lang.Object	value() Gets a copy of the underlying value, which is stored as a double[][].
static JSCNArray	valueOf(java.io.File file, java.lang.String name) Creates an instance of this class from a data file.
double[]	vec() Gets a vector stacked with the columns of the underlying data array.
int	zeroCount() Gets the number of double elements that are equal to zero.

Methods inherited from class com.jstatcom.model.AbstractJSCData

addJSCDataListener, getJSCProperty, removeJSCDataListener, removeJSCProperty, setJSCProperty

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

JSCNArray_XML

public static final javolution.xml.XmlFormat<JSCNArray> JSCNArray_XML

XML format field for (de)serialization.

Constructor Detail

JSCNArray

public JSCNArray(java.lang.String name)

Creates an empty JSCNArray.

Parameters:

name - the identifier of that object

Throws:

java.lang.IllegalArgumentException - if name is not valid or if (name == null)

See Also:

JSCConstants.isValidName(java.lang.String)

JSCNArray

public JSCNArray(java.lang.String name,
                 double[][] value)

Creates a JSCNArray from value. The elements of value are copied before.

Parameters:

name - the identifier of that object

value - the double[][] to be copied and used as value

Throws:

java.lang.IllegalArgumentException - if name is not valid
or if rows of value have different lengths or if (name == null)

See Also:

JSCConstants.isValidName(java.lang.String)

JSCNArray

public JSCNArray(JSCNArray narray)

Copy-Constructor.

Parameters:

narray - the number array to copy

Throws:

java.lang.IllegalArgumentException - if (narray == null)

See Also:

JSCConstants.isValidName(java.lang.String)

JSCNArray

public JSCNArray(java.lang.String name,
                 double... value)

Creates a JSCNArray from value. The elements of value are copied before.

Parameters:

name - the identifier of that object

value - the double[] to be copied and used as value

Throws:

java.lang.IllegalArgumentException - if name is not valid or if (name == null)

See Also:

JSCConstants.isValidName(java.lang.String)

JSCNArray

public JSCNArray(java.lang.String name,
                 int[] value)

Creates a JSCNArray from value. The elements of value are copied before.

Parameters:

name - the identifier of that object

value - the int[] to be copied and used as value

Throws:

java.lang.IllegalArgumentException - if name is not valid or if (name == null)

See Also:

JSCConstants.isValidName(java.lang.String)

JSCNArray

public JSCNArray(java.lang.String name,
                 int[][] value)

Creates a JSCNArray from value. The elements of value are copied before.

Parameters:

name - the identifier of that object

value - the int[][] to be copied and used as value

Throws:

java.lang.IllegalArgumentException - if name is not valid
or if rows of value have different lengths or if (name == null)

See Also:

JSCConstants.isValidName(java.lang.String)

Method Detail

appendCols

public void appendCols(JSCNArray newCols)

Appends newCols to the right end of the value array. Fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED if newCols is not empty
• JSCDataEventTypes.EMPTY_STATE if newCols is not empty and this was empty before

It is possible to append columns to an empty data object. This would be similar to setting new values. If newCols is empty, nothing happens.

Parameters:

newCols - the JSCNArray to be appended

Throws:

java.lang.IllegalArgumentException - if (newCols == null) or if (rows() > 0 && newCols.rows() > 0 && rows() != newCols.rows())

appendRows

public void appendRows(JSCNArray newRows)

Appends newRows to the bottom the value array. Fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED if newRows is not empty
• JSCDataEventTypes.EMPTY_STATE if newRows is not empty and this was empty before

It is possible to append rows to an empty data object. This would be similar to setting new values. If newRows is empty, nothing happens.

Parameters:

newRows - the JSCNArray to be appended

Throws:

java.lang.IllegalArgumentException - if (newRows == null) or if (cols() > 0 && newRows.cols() > 0 && cols() != newRows.cols())

clear

public void clear()

Clears this data object. Fires:

• JSCDataEventTypes.EMPTY_STATE event
• JSCDataEventTypes.VALUE_CHANGED event

if it was not empty before. After calling this method isEmpty returns true.

cols

public int cols()

Gets the number of columns in the stored array.

Returns:

the number of columns or 0 if (isEmpty())

copy

public JSCNArray copy()

Description copied from interface: JSCData

Gets a copy of the current object. Implementations of this method must fulfil the two conditions:

• a.isEqual(a.copy())- compares values
• a.getName().equals(a.copy().getName())- compares name

JSCDataListeners attached to the original object should not be copied.

Returns:

a clonelike copy of the original object

See Also:

JSCData

delCol

public void delCol(int i)

Deletes column i from the value array. Fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED in any case
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

Parameters:

i - the index of the column to remove

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - if column index is invalid

delColsIf

public void delColsIf(int... index)

Deletes all columns of this that have a corresponding nonzero element in index. If index contains only zeros, nothing happens. If index selects all columns, this is cleared.

This method fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED if some column was deleted
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

Parameters:

index - the cols() x 1 int array, nonzero entries select columns

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - if (index.length != cols()) if (index == null)

delRow

public void delRow(int i)

Deletes row i from the value array. Fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED in any case
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

Parameters:

i - the index of the row to remove

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - if row index is invalid

delRowsIf

public void delRowsIf(int... index)

Deletes all rows of this that have a corresponding nonzero element in index. If index contains only zeros, nothing happens. If index selects all rows, this is cleared.

This method fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED if some row was deleted
• JSCDataEventTypes.EMPTY_STATE if this is emtpy afterwards

Parameters:

index - the rows() x 1 int array, nonzero entries select rows

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - if (index.length != rows() or if (index == null)

display

public java.lang.String display()

Gets a string representing the double[][] stored.

Specified by:

display in interface JSCData

Overrides:

display in class AbstractJSCData

Returns:

"{}" if isEmpty == true, otherwise a formatted string with all elements in table form, the format parameters can be changed via setFormatString

doubleArray

public double[][] doubleArray()

Gets a copy of the underlying value as a double[][].

Returns:

the double array
if this is empty new double[0][0] is returned

doubleAt

public double doubleAt(int i,
                       int j)

Gets the double element stored at index i, j.

Parameters:

i - the row index, zero based

j - the column index, zero based

Returns:

the double stored at this array position

Throws:

java.lang.IllegalArgumentException - if indices out of range

doubleValAt

public java.lang.Double doubleValAt(int i,
                                    int j)

Gets the Double element stored at index i, j.

Parameters:

i - the row index, zero based

j - the column index, zero based

Returns:

the Double stored at this array position

Throws:

java.lang.IllegalArgumentException - if indices out of range

intArray

public int[][] intArray()

Gets a copy of the underlying value as a int[][]. The following special int values for element i, j are returned:

• 0 if value[i][j] == Double.NaN
• Integer.MAX_VALUE if value[i][j] == Double.POSITIVE_INFINITY
• Integer.MIN_VALUE if value[i][j] == Double.NEGATIVE_INFINITY

Note that during this operation information is potentially lost. Only the integer part is preserved, which is different from rounding.

Returns:

the double array
if this is empty, then either null or new int[0][0] is returned, depending on what has been set before

intAt

public int intAt(int i,
                 int j)

Gets the int element stored at index i, j. Note that during this operation information is potentially lost. Only the integer part is preserved, which is different from rounding. The following special int values are returned:

• 0 if value == Double.NaN
• Integer.MAX_VALUE if value == Double.POSITIVE_INFINITY
• Integer.MIN_VALUE if value == Double.NEGATIVE_INFINITY

Parameters:

i - the row index, zero based

j - the column index, zero based

Returns:

the int stored at this array position

Throws:

java.lang.IllegalArgumentException - if indices out of range

isEmpty

public boolean isEmpty()

Gets whether this is empty. This method returns true if one of the following conditions is met:

• value() == null
• rows() == 0
• cols() == 0

Returns:

true if empty

isEqual

public boolean isEqual(JSCData o)

Description copied from interface: JSCData

Gets whether the values of this data object and other are logically equal.

Returns:

true if considered equal according to the logic of the representation

See Also:

JSCData

isNaN

public boolean isNaN(int i,
                     int j)

Gets whether the element stored at index i, j is of type Double.NaN.

Parameters:

i - the row index

j - the column index

Returns:

true if the array element is a missing value

Throws:

java.lang.IllegalArgumentException - if indices out of range

jamaMatrix

public Jama.Matrix jamaMatrix()

Gets the values stored in this JSCNArray as an instance of Jama.Matrix. The underlying array is copied before.

Returns:

instance of Jama.Matrix initialized with the stored values

Throws:

java.lang.IllegalStateException - if this is empty

See Also:

Matrix

name

public java.lang.String name()

Description copied from interface: JSCData

Gets the name of the data object. It must fulfil the requirements for variable names defined in JSCConstants.

Returns:

the name

See Also:

JSCData

nanCount

public int nanCount()

Gets the number of double elements that are equal to Double.NaN.

Returns:

the number of missing values

rank

public int rank()

Gets the rank of the stored value. The computation is delegated to a Jama.Matrix instance.

Returns:

the rank of the double[][] value

Throws:

java.lang.IllegalStateException - if this is empty

rows

public int rows()

Gets the number of rows in the stored array.

Returns:

the number of rows or 0 if (isEmpty())

setFormatString

public void setFormatString(java.lang.String newFormatString)

Sets a new format string. This string is used by the display method to format the double array. The default format string is

"%- 8.4f ".

For a complete description of all legal arguments, see the PrintfFormat documentation. The string must contain exactly one conversion character.

Parameters:

newFormatString - the format string to be used for display

Throws:

java.lang.IllegalArgumentException - if newFormatString is not valid

See Also:

PrintfFormat

setVal

public void setVal(double[][] newValue)

Sets the value of this to newValue. Fires a JSCDataEvent of type:

• JSCDataEventTypes.VALUE_CHANGED if newValue is different from current value
• JSCDataEventTypes.EMPTY_STATE if newValue is not empty and this was empty before
• JSCDataEventTypes.EMPTY_STATE if newValue is empty and this was not empty before

A value is empty if it is either null or at least one dimension is zero. The newValue is only compared to the existing value if a listener to JSCDataEventTypes.VALUE_CHANGED is registered.

Parameters:

newValue - the new value

Throws:

java.lang.IllegalArgumentException - if rows of newValue have different lengths

setVal

public void setVal(int[][] newValue)

Sets the value of this to newValue, see setVal(double[][] newValue).

Parameters:

newValue - the new value

Throws:

java.lang.IllegalArgumentException - if rows of newValue have different lengths

setVal

public void setVal(double[] newValue)

Sets the value of this to newValue, see setVal(double[][] newValue).

Parameters:

newValue - the new value

setVal

public void setVal(int[] newValue)

Sets the value of this to newValue, see setVal(double[][] newValue).

Parameters:

newValue - the new value

setVal

public void setVal(JSCNArray val)

Sets the values stored in val to this JSCNArray. Future changes in val have no effect on this.

Parameters:

val - instance of JSCNArray

Throws:

java.lang.IllegalArgumentException - if (val == null)

setVal

public void setVal(Jama.Matrix mat)

Sets the values stored in mat to this JSCNArray. The underlying array is copied before.

Parameters:

mat - instance of Jama.Matrix

See Also:

Matrix

setValAt

public void setValAt(double val,
                     int i,
                     int j)

Sets the double element stored at index i, j. Fires a JSCDataEvent of type JSCDataEventTypes.VALUE_CHANGED if the new value is different from the one currently stored at that position. The event object contains the following values:

• oldValue- new double[] { oldNumber, i, j }
• newValue- new double[] { newNumber, i, j }

Thus listeners can exactly pin down, where the change in the array happened.

Parameters:

val - the double to store at the given position

i - the row index, zero based

j - the column index, zero based

Throws:

java.lang.IllegalArgumentException - if indices out of range

toString

public java.lang.String toString()

Gets a string representation of this JSCNArray instance. The value is only represented with a summary string, because the underlying array might be large. To print the complete value, use display instead.

Overrides:

toString in class AbstractJSCData

Returns:

string with name, type and value information

transpose

public void transpose()

Transposes the underlying array. Nothing happens if this is empty. Fires a JSCDataEvent of type JSCDataEventTypes.VALUE_CHANGED if the stored array is not symmetric.

type

public JSCTypes type()

Gets the type of this JSCData object.

Returns:

JSCTypes.NARRAY

See Also:

JSCTypes

value

public java.lang.Object value()

Gets a copy of the underlying value, which is stored as a double[][].

Returns:

the value object
if this is empty new double[0][0] is returned

zeroCount

public int zeroCount()

Gets the number of double elements that are equal to zero.

Returns:

the number of zero elements

valueOf

public static JSCNArray valueOf(java.io.File file,
                                java.lang.String name)

Creates an instance of this class from a data file. The method parses the elements file into a double array according to the following conventions:

• the number of rows of the array is the number of nonempty rows in file
• the number of cols of the array is the number of tokens of the row with the most tokens
• entries are parsed to numbers, exponential notation is allowed, all entries that cannot be parsed to a number are set to Double.NaN

This means that if file is empty, an empty JSCNArray will be returned.

Parameters:

file - the file to parse the double array from

name - the name of the new JSCNArray to create

Returns:

an instance of JSCNArray

Throws:

java.lang.IllegalArgumentException - if (file == null || name == null), or if name is not legal or if (!file.isFile())

getCol

public double[] getCol(int colIndex)

Gets the column of the underlying double array specified with colIndex. The index starts with 0 as usual.

Parameters:

colIndex - the index of the column to extract (starting from 0)

Returns:

a one dimensional double array with the column data

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - colIndex is outside of valid array bounds

vec

public double[] vec()

Gets a vector stacked with the columns of the underlying data array.

Returns:

a one dimensional double array with all values starting with the first column

getRow

public double[] getRow(int rowIndex)

Gets the row of the underlying double array specified with rowIndex. The index starts with 0 as usual.

Parameters:

rowIndex - the index of the row to extract (starting from 0)

Returns:

a one dimensional double array with the row data

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - rowIndex is outside of valid array bounds

getCols

public double[][] getCols(int startCol,
                          int endCol)

Gets all columns of the underlying double array defined by startCol:endCol. The indices start with 0 as usual.

Parameters:

startCol - the index of the first column to extract (starting from 0)

endCol - the index of the last column to extract (starting from 0)

Returns:

a two dimensional double array with the column data

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - if (startCol > endCol) or if the indices are outside the valid array bounds

getRows

public double[][] getRows(int startRow,
                          int endRow)

Gets all rows of the underlying double array defined by startRow:endRow. The indices start with 0 as usual.

Parameters:

startRow - the index of the first row to extract (starting from 0)

endRow - the index of the last row to extract (starting from 0)

Returns:

a two dimensional double array with the row data

Throws:

java.lang.IllegalStateException - if this is empty

java.lang.IllegalArgumentException - if (startRow > endRow) or if the indices are outside the valid array bounds

selColsIf

public double[][] selColsIf(int... colIndex)

Gets all columns of the underlying double array that have a nonzero corresponding element in colIndex.

Parameters:

colIndex - this.cols() x 1 vector selecting columns

Returns:

new array with the extracted columns, new double[0][0] if index contains only 0's, a copy of the underlying values if colIndex contains only nonzero elements

Throws:

java.lang.IllegalArgumentException - if (colIndex == null) or if (this.isEmpty() && colIndex > 0) or if (this.cols() != colIndex)

selRowsIf

public double[][] selRowsIf(int... rowIndex)

Gets all rows of the underlying double array that have a nonzero corresponding element in rowIndex.

Parameters:

rowIndex - this.rows() x 1 vector selecting rows

Returns:

new array with the extracted rows, new double[0][0] if index contains only 0's, a copy of the underlying values if rowIndex contains only nonzero elements

Throws:

java.lang.IllegalArgumentException - if (rowIndex == null) or if (this.isEmpty() && rowIndex > 0) or if (this.rows() != rowIndex)

getTransposed

public double[][] getTransposed()

Gets a new double array with elements transposed.

Returns:

transposed data

getPow

public double[][] getPow(double pow)

Gets a new double array with the elements raised to the power of pow.

Parameters:

pow - the power to raise each element of the data array to

Returns:

double array with changed elements