org.knime.core.data.container
Class ColumnRearranger

java.lang.Object
  extended by org.knime.core.data.container.ColumnRearranger

public final class ColumnRearranger
extends Object

Meta object to describe in which way a table shall be modified (column-based) to create a new table.

A ColumnRearranger is used in NodeModel implementations that perform column based operations on columns of the input table, such as a column filter node (that simply hides some columns from the input table) or a node that appends/replaces certain columns.

The following example demonstrates the usage of a ColumnRearranger to append a column to a given table, which contains the sum of the first two columns of the input table (given that these columns are numeric). The node model implementation would contain code as follows.

 public BufferedDataTable[] execute(BufferedDataTable[] in, 
     ExecutionContext exec) throws Exception {
     ColumnRearranger c = createColumnRearranger(in[0].getDataTableSpec());
     BufferedDataTable out = exec.createColumnRearrangeTable(in[0], c, exec);
     return new BufferedDataTable[]{out};
 }
 
 public DataTableSpec[] configure(DataTableSpec[] in)
         throws InvalidSettingsException {
     DataColumnSpec c0 = in[0].getColumnSpec(0);
     DataColumnSpec c1 = in[0].getColumnSpec(1);
     if (!c0.getType().isCompatibleTo(DoubleValue.class)) {
         throw new InvalidSettingsException(
           "Invalid type at first column.");
     }
     if (!c1.getType().isCompatibleTo(DoubleValue.class)) {
         throw new InvalidSettingsException(
           "Invalid type at second column.");
     }
     ColumnRearranger c = createColumnRearranger(in[0]);
     DataTableSpec result = c.createSpec();
     return new DataTableSpec[]{result};
 }
 
The createColumnRearranger method is a local helper method, which is called from both the execute and the configure method:
 private ColumnRearranger createColumnRearranger(DataTableSpec in) {
     ColumnRearranger c = new ColumnRearranger(in);
     // column spec of the appended column
     DataColumnSpec newColSpec = new DataColumnSpecCreator(
     "sum_of_0_and_1", DoubleCell.TYPE).createSpec();
     // utility object that performs the calculation
     CellFactory factory = new SingleCellFactory(newColSpec) {
         public DataCell getCell(DataRow row) {
             DataCell c0 = row.getCellAt(0);
             DataCell c1 = row.getCellAt(1);
             if (c0.isMissing() || c1.isMissing()) {
                 return DataType.getMissingCell();
             } else {
                 // configure method has checked if column 0 and 1 are numeric
                 // safe to type cast
                 double d0 = ((DoubleValue)c0).getDoubleValue();
                 double d1 = ((DoubleValue)c1).getDoubleValue();
                 return new DoubleCell(d0 + d1);
             }
         }
     };
     c.append(factory);
     return c;
 }
 

Author:
Bernd Wiswedel, University of Konstanz
See Also:
CellFactory, ExecutionContext.createColumnRearrangeTable( org.knime.core.node.BufferedDataTable, ColumnRearranger, org.knime.core.node.ExecutionMonitor)

Nested Class Summary
(package private) static class ColumnRearranger.SpecAndFactoryObject
          Utility class that helps us with internal data structures.
 
Constructor Summary
ColumnRearranger(DataTableSpec original)
          Creates new object based on the spec of the table underlying the newly created table.
 
Method Summary
 void append(CellFactory fac)
          Appends the columns provided by fac to the end of the current column set.
 DataTableSpec createSpec()
          Creates the data table spec on the current set of columns.
(package private)  Vector<ColumnRearranger.SpecAndFactoryObject> getIncludes()
          Access method for the internal data structure.
(package private)  DataTableSpec getOriginalSpec()
          Access method for the internal data structure.
 int indexOf(String colName)
          Get the current index of the column with name colName.
 void insertAt(int position, CellFactory fac)
          Inserts the columns provided by fac at a given position.
 void keepOnly(int... colIndices)
          Removes all columns from the current settings, whose index is not contained in the argument colIndices.
 void keepOnly(String... colNames)
          Removes all columns from the current settings, whose column name is not contained in the argument colNames.
 void move(int from, int to)
          Moves the column at index from to the index to.
 void move(String colName, int to)
          Moves the column named colName to the index to.
 void permute(int[] colIndicesInOrder)
          Changes the order of the columns according to the argument array.
 void permute(String[] colNamesInOrder)
          Changes the order of the columns according to the argument array.
 void remove(int... colIndices)
          Removes all columns whose index is contained in the argument array.
 void remove(String... colNames)
          Removes all columns from the current set of columns whose name is contained in the argument array.
 void replace(CellFactory fac, int... colIndex)
          Replaces a set of columns.
 void replace(CellFactory newCol, String colName)
          Replaces a single column.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ColumnRearranger

public ColumnRearranger(DataTableSpec original)
Creates new object based on the spec of the table underlying the newly created table.

Parameters:
original - The table which serves as reference.
Throws:
NullPointerException - If the argument is null.
Method Detail

keepOnly

public void keepOnly(int... colIndices)
Removes all columns from the current settings, whose index is not contained in the argument colIndices. In other words, the number of columns in the spec that would be created after this method has been called, is colIndices.length.

Note: Any subsequent invocation of this method or any other method that refers to column indices is based on the reduced set of columns.

Parameters:
colIndices - The indices of the columns to keep.
Throws:
IndexOutOfBoundsException - If any value in the argument array is out of bounds (smaller 0 or greater/equal to the current number of columns) or the array contains duplicates.
NullPointerException - If the argument is null

keepOnly

public void keepOnly(String... colNames)
Removes all columns from the current settings, whose column name is not contained in the argument colNames. In other words, the number of columns in the spec that would be created after this method has been called, is colNames.length.

Parameters:
colNames - The names of the columns to keep.
Throws:
IllegalArgumentException - If any value in the argument array is invalid, i.e. null or not contained in the current set of columns or if the array contains duplicates.
NullPointerException - If the argument is null

remove

public void remove(int... colIndices)
Removes all columns whose index is contained in the argument array.

Note: Any subsequent invocation of this method or any other method that refers to column indices is based on the reduced set of columns.

Parameters:
colIndices - The indices of the columns to remove.
Throws:
IndexOutOfBoundsException - If any element in the array is out of bounds (i.e. smaller than 0 or greater/equal the current number of columns) or the argument contains duplicates.
NullPointerException - If the argument is null.

remove

public void remove(String... colNames)
Removes all columns from the current set of columns whose name is contained in the argument array.

Parameters:
colNames - The names of the columns to remove.
Throws:
NullPointerException - If any element is null

indexOf

public int indexOf(String colName)
Get the current index of the column with name colName. Note, the index may change if any of the modifier methods is called.

Parameters:
colName - The name of the column to find.
Returns:
The index of the column whose name equals colName or -1 if it is not contained.
Throws:
NullPointerException - If the argument is null.

move

public void move(int from,
                 int to)
Moves the column at index from to the index to. This method can be used to re-sort the set of columns. If from is greater than to, then the column indices will be affected as follows: If the from is smaller than to, the column indices will change as follows:

This method is inherently expensive as it shifts elements back and forth. If you change the order of all columns (and hence would need to call this method often), use the permute method instead.

Parameters:
from - The from index.
to - The destination index.
Throws:
IndexOutOfBoundsException - If any of the values is out of range, i.e. less than 0 or greater or equal to the current set of columns.
See Also:
move(String, int), permute(String[])

move

public void move(String colName,
                 int to)
Moves the column named colName to the index to. This method can be used to re-sort the set of columns. The implementation first determines the index of the argument column and then calls move(int, int) with the correct arguments.

This method is expensive if called multiple times (for instance when re-sorting the entire table). See the move(int, int) method for details.

Parameters:
colName - The name of the column in question.
to - The destination index.
Throws:
IndexOutOfBoundsException - If to is out of range, i.e. less than 0 or greater or equal to the current set of columns.
NullPointerException - If colName is null.
IllegalArgumentException - If there is no column colName.
See Also:
move(int, int), permute(String[])

permute

public void permute(int[] colIndicesInOrder)
Changes the order of the columns according to the argument array. The array must contain the column indices in the desired order. This method is the counterpart to the permute(String[]) method.

Parameters:
colIndicesInOrder - The new column ordering. It may contain fewer names than actually present in this re-arrange object. However, it must not contain unknown columns, nor should it contain duplicates or null elements.
Throws:
NullPointerException - If the argument is null
IllegalArgumentException - If the array contains duplicates-
IndexOutOfBoundsException - If the indices are invalid.

permute

public void permute(String[] colNamesInOrder)
Changes the order of the columns according to the argument array. The array must contain the column names in the desired order. If this rearrange object contains names that are not contained in the argument array, those columns are moved to the end of the new ordering.

This method is efficient compared to the implementation of the move(int, int) method and should be used if the entire table is to be re-sorted.

Parameters:
colNamesInOrder - The new column ordering. It may contain fewer names than actually present in this re-arrange object. However, it must not contain unknown columns, nor should it contain duplicates or null elements.
Throws:
NullPointerException - If the argument is null or contains null elements.
IllegalArgumentException - If the array contains duplicates or unknown columns.

insertAt

public void insertAt(int position,
                     CellFactory fac)
Inserts the columns provided by fac at a given position. Any columns before that position stay where they are, the column at the position and any thereafter are shifted to the right by the number of columns provided by fac.

Parameters:
position - The position (index) where to insert the new columns.
fac - The factory from which we get the new columns.
Throws:
IndexOutOfBoundsException - If position is invalid.
NullPointerException - If fac is null.

append

public void append(CellFactory fac)
Appends the columns provided by fac to the end of the current column set.

Parameters:
fac - The factory from which we get the new columns.
Throws:
NullPointerException - If fac is null.

replace

public void replace(CellFactory newCol,
                    String colName)
Replaces a single column. The target column is specified by the colName argument and the new column is given through the newCol cell factory.

Note:The newCol argument must only specify one single column. If you need to replace one column by many others, use the remove(colName) in conjunction with the insertAt(position, newCol) method.

Parameters:
newCol - The column factory for the single new column.
colName - The name of the column to replace.
Throws:
NullPointerException - If any argument is null.
IndexOutOfBoundsException - If newCol provides not exactly one new column
IllegalArgumentException - If colName is not contained in the current set of columns.

replace

public void replace(CellFactory fac,
                    int... colIndex)
Replaces a set of columns. The columns to be replaced are specified by the colIndex argument and the new columns is given through the newCol cell factory.

Note:The newCol argument must specify exactly as many columns as there are in colIndex. If you want to remove more (or fewer) columns as given by fac, you can always accomplish this using the remove, indexOf, and/or inserAt methods.

Parameters:
fac - The column factory for the new columns.
colIndex - The indices of the columns to be replaced.
Throws:
NullPointerException - If any argument is null.
IndexOutOfBoundsException - If fac provides not exactly as many columns as colIndex.length or the colIndex argument contains invalid entries.

getIncludes

Vector<ColumnRearranger.SpecAndFactoryObject> getIncludes()
Access method for the internal data structure.

Returns:
The current set of columns.

getOriginalSpec

DataTableSpec getOriginalSpec()
Access method for the internal data structure.

Returns:
The original spec as passed in the constructor.

createSpec

public DataTableSpec createSpec()
Creates the data table spec on the current set of columns. Subsequent changes to this object will also change the return value of this method. You may want to call this method during configure in order to create the output spec of your node.

Returns:
The table spec reflecting the current set of columns.


Copyright, 2003 - 2010. All rights reserved.
University of Konstanz, Germany.
Chair for Bioinformatics and Information Mining, Prof. Dr. Michael R. Berthold.
You may not modify, publish, transmit, transfer or sell, reproduce, create derivative works from, distribute, perform, display, or in any way exploit any of the content, in whole or in part, except as otherwise expressly permitted in writing by the copyright owner or as specified in the license file distributed with this product.