Documentation of 'com.jstatcom.model.JSCNArray' Java class
JSCNArray
com.jstatcom.model

Class 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.

    • Constructor Summary

      Constructors 
      Constructor and Description
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      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.
      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(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 java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • JSCNArray_XML

        public static final 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(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 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(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

DMelt 3.0 © DataMelt by jWork.ORG

You see the box below because you did not login.