Package processing.data

Class Table

java.lang.Object
processing.data.Table
public class Table extends Object
Table objects store data with multiple rows and columns, much like in a traditional spreadsheet. Tables can be generated from scratch, dynamically, or using data from an existing file. Tables can also be output and saved to disk, as in the example above.

Additional Table methods are documented in the Processing Table Javadoc.

Advanced

Generic class for handling tabular data, typically from a CSV, TSV, or other sort of spreadsheet file.

CSV files are comma separated values, often with the data in quotes. TSV files use tabs as separators, and usually don't bother with the quotes.

File names should end with .csv if they're comma separated.

A rough "spec" for CSV can be found here.

See Also:

  • Field Details

  • Constructor Details

    • Table

      public Table()
      Creates a new, empty table. Use addRow() to add additional rows.

    • Table

      public Table(File file) throws IOException
      Throws:
      IOException

    • Table

      public Table(File file, String options) throws IOException
      version that uses a File object; future releases (or data types) may include additional optimizations here
      Throws:
      IOException

    • Table

      public Table(InputStream input) throws IOException
      Throws:
      IOException

    • Table

      public Table(InputStream input, String options) throws IOException
      Read the table from a stream. Possible options include:
      • csv - parse the table as comma-separated values
      • tsv - parse the table as tab-separated values
      • newlines - this CSV file contains newlines inside individual cells
      • header - this table has a header (title) row
      Parameters:
      input -
      options -
      Throws:
      IOException

    • Table

      public Table(Iterable<TableRow> rows)

    • Table

      public Table(ResultSet rs)

  • Method Details

    • typedParse

      public Table typedParse(InputStream input, String options) throws IOException
      Throws:
      IOException

    • extensionOptions

      public static String extensionOptions(boolean loading, String filename, String options)

    • parseInto

      public void parseInto(Object enclosingObject, String fieldName)
      incomplete, do not use

    • save

      public boolean save(File file, String options) throws IOException
      Throws:
      IOException

    • save

      public boolean save(OutputStream output, String options)

    • addColumn

      public void addColumn()
      Use addColumn() to add a new column to a Table object. Typically, you will want to specify a title, so the column may be easily referenced later by name. (If no title is specified, the new column's title will be null.) A column type may also be specified, in which case all values stored in this column must be of the same type (e.g., Table.INT or Table.FLOAT). If no type is specified, the default type of STRING is used.
      See Also:

    • addColumn

      public void addColumn(String title)
      Parameters:
      title - the title to be used for the new column

    • addColumn

      public void addColumn(String title, int type)
      Parameters:
      type - the type to be used for the new column: INT, LONG, FLOAT, DOUBLE, or STRING

    • insertColumn

      public void insertColumn(int index)

    • insertColumn

      public void insertColumn(int index, String title)

    • insertColumn

      public void insertColumn(int index, String title, int type)

    • removeColumn

      public void removeColumn(String columnName)
      Use removeColumn() to remove an existing column from a Table object. The column to be removed may be identified by either its title (a String) or its index value (an int). removeColumn(0) would remove the first column, removeColumn(1) would remove the second column, and so on.
      Parameters:
      columnName - the title of the column to be removed
      See Also:

    • removeColumn

      public void removeColumn(int column)
      Parameters:
      column - the index number of the column to be removed

    • getColumnCount

      public int getColumnCount()
      Returns the total number of columns in a table.
      See Also:

    • setColumnCount

      public void setColumnCount(int newCount)
      Change the number of columns in this table. Resizes all rows to ensure the same number of columns in each row. Entries in the additional (empty) columns will be set to null.
      Parameters:
      newCount -

    • setColumnType

      public void setColumnType(String columnName, String columnType)

    • setColumnType

      public void setColumnType(int column, String columnType)
      Set the data type for a column so that using it is more efficient.
      Parameters:
      column - the column to change
      columnType - One of int, long, float, double, string, or category.

    • setColumnType

      public void setColumnType(String columnName, int newType)

    • setColumnType

      public void setColumnType(int column, int newType)
      Sets the column type. If data already exists, then it'll be converted to the new type.
      Parameters:
      column - the column whose type should be changed
      newType - something fresh, maybe try an int or a float for size?

    • setTableType

      public void setTableType(String type)
      Set the entire table to a specific data type.

    • setColumnTypes

      public void setColumnTypes(int[] types)

    • setColumnTypes

      public void setColumnTypes(Table dictionary)
      Set the titles (and if a second column is present) the data types for this table based on a file loaded separately. This will look for the title in column 0, and the type in column 1. Better yet, specify a column named "title" and another named "type" in the dictionary table to future-proof the code.
      Parameters:
      dictionary -

    • getColumnType

      public int getColumnType(String columnName)

    • getColumnType

      public int getColumnType(int column)
      Returns one of Table.STRING, Table.INT, etc...

    • getColumnTypes

      public int[] getColumnTypes()

    • removeTitleRow

      @Deprecated public String[] removeTitleRow()
      Deprecated.
      Remove the first row from the data set, and use it as the column titles. Use loadTable("table.csv", "header") instead.

    • setColumnTitles

      public void setColumnTitles(String[] titles)

    • setColumnTitle

      public void setColumnTitle(int column, String title)

    • hasColumnTitles

      public boolean hasColumnTitles()

    • getColumnTitles

      public String[] getColumnTitles()

    • getColumnTitle

      public String getColumnTitle(int col)

    • getColumnIndex

      public int getColumnIndex(String columnName)

    • checkColumnIndex

      public int checkColumnIndex(String title)
      Same as getColumnIndex(), but creates the column if it doesn't exist. Named this way to not conflict with checkColumn(), an internal function used to ensure that a columns exists, and also to denote that it returns an int for the column index.
      Parameters:
      title - column title
      Returns:
      index of a new or previously existing column

    • getRowCount

      public int getRowCount()
      Returns the total number of rows in a Table.
      See Also:

    • lastRowIndex

      public int lastRowIndex()

    • clearRows

      public void clearRows()
      Removes all rows from a Table. While all rows are removed, columns and column titles are maintained.
      See Also:

    • setRowCount

      public void setRowCount(int newCount)

    • addRow

      public TableRow addRow()
      Use addRow() to add a new row of data to a Table object. By default, an empty row is created. Typically, you would store a reference to the new row in a TableRow object (see newRow in the example above), and then set individual values using setInt(), setFloat(), or setString(). If a TableRow object is included as a parameter, then that row is duplicated and added to the table.
      See Also:

    • addRow

      public TableRow addRow(TableRow source)
      Parameters:
      source - a reference to the original row to be duplicated

    • setRow

      public TableRow setRow(int row, TableRow source)

    • addRow

      public TableRow addRow(Object[] columnData)

    • addRows

      public void addRows(Table source)

    • insertRow

      public void insertRow(int insert, Object[] columnData)

    • removeRow

      public void removeRow(int row)
      Removes a row from a Table object
      Parameters:
      row - ID number of the row to remove
      See Also:

    • setRow

      public void setRow(int row, Object[] pieces)

    • getRow

      public TableRow getRow(int row)
      Returns a reference to the specified TableRow. The reference can then be used to get and set values of the selected row, as illustrated in the example above.
      Parameters:
      row - ID number of the row to get
      See Also:

    • rows

      public Iterable<TableRow> rows()
      Gets all rows from the table. Returns an iterator, so for must be used to iterate through all the rows, as shown in the example above.
      See Also:

    • rows

      public Iterable<TableRow> rows(int[] indices)

    • getInt

      public int getInt(int row, int column)
      Retrieves an integer value from the Table's specified row and column. The row is specified by its ID, while the column may be specified by either its ID or title.
      Parameters:
      row - ID number of the row to reference
      column - ID number of the column to reference
      See Also:

    • getInt

      public int getInt(int row, String columnName)
      Parameters:
      columnName - title of the column to reference

    • setMissingInt

      public void setMissingInt(int value)

    • setInt

      public void setInt(int row, int column, int value)
      Stores an integer value in the Table's specified row and column. The row is specified by its ID, while the column may be specified by either its ID or title.
      Parameters:
      row - ID number of the target row
      column - ID number of the target column
      value - value to assign
      See Also:

    • setInt

      public void setInt(int row, String columnName, int value)
      Parameters:
      columnName - title of the target column

    • getIntColumn

      public int[] getIntColumn(String name)

    • getIntColumn

      public int[] getIntColumn(int col)

    • getIntRow

      public int[] getIntRow(int row)

    • getLong

      public long getLong(int row, int column)

    • getLong

      public long getLong(int row, String columnName)

    • setMissingLong

      public void setMissingLong(long value)

    • setLong

      public void setLong(int row, int column, long value)

    • setLong

      public void setLong(int row, String columnName, long value)

    • getLongColumn

      public long[] getLongColumn(String name)

    • getLongColumn

      public long[] getLongColumn(int col)

    • getLongRow

      public long[] getLongRow(int row)

    • getFloat

      public float getFloat(int row, int column)
      Retrieves a float value from the Table's specified row and column. The row is specified by its ID, while the column may be specified by either its ID or title.
      Parameters:
      row - ID number of the row to reference
      column - ID number of the column to reference
      See Also:

    • getFloat

      public float getFloat(int row, String columnName)
      Parameters:
      columnName - title of the column to reference

    • setMissingFloat

      public void setMissingFloat(float value)

    • setFloat

      public void setFloat(int row, int column, float value)
      Stores a float value in the Table's specified row and column. The row is specified by its ID, while the column may be specified by either its ID or title.
      Parameters:
      row - ID number of the target row
      column - ID number of the target column
      value - value to assign
      See Also:

    • setFloat

      public void setFloat(int row, String columnName, float value)
      Parameters:
      columnName - title of the target column

    • getFloatColumn

      public float[] getFloatColumn(String name)

    • getFloatColumn

      public float[] getFloatColumn(int col)

    • getFloatRow

      public float[] getFloatRow(int row)

    • getDouble

      public double getDouble(int row, int column)

    • getDouble

      public double getDouble(int row, String columnName)

    • setMissingDouble

      public void setMissingDouble(double value)

    • setDouble

      public void setDouble(int row, int column, double value)

    • setDouble

      public void setDouble(int row, String columnName, double value)

    • getDoubleColumn

      public double[] getDoubleColumn(String name)

    • getDoubleColumn

      public double[] getDoubleColumn(int col)

    • getDoubleRow

      public double[] getDoubleRow(int row)

    • getString

      public String getString(int row, int column)
      Retrieves a String value from the Table's specified row and column. The row is specified by its ID, while the column may be specified by either its ID or title.
      Parameters:
      row - ID number of the row to reference
      column - ID number of the column to reference
      See Also:

    • getString

      public String getString(int row, String columnName)
      Parameters:
      columnName - title of the column to reference

    • setMissingString

      public void setMissingString(String value)
      Treat entries with this string as "missing". Also used for categorial.

    • setString

      public void setString(int row, int column, String value)
      Stores a String value in the Table's specified row and column. The row is specified by its ID, while the column may be specified by either its ID or title.
      Parameters:
      row - ID number of the target row
      column - ID number of the target column
      value - value to assign
      See Also:

    • setString

      public void setString(int row, String columnName, String value)
      Parameters:
      columnName - title of the target column

    • getStringColumn

      public String[] getStringColumn(String columnName)
      Retrieves all values in the specified column, and returns them as a String array. The column may be specified by either its ID or title.
      Parameters:
      columnName - title of the column to search
      See Also:

    • getStringColumn

      public String[] getStringColumn(int column)
      Parameters:
      column - ID number of the column to search

    • getStringRow

      public String[] getStringRow(int row)

    • findRowIndex

      public int findRowIndex(String value, int column)
      Return the row that contains the first String that matches.
      Parameters:
      value - the String to match
      column - ID number of the column to search

    • findRowIndex

      public int findRowIndex(String value, String columnName)
      Return the row that contains the first String that matches.
      Parameters:
      value - the String to match
      columnName - title of the column to search

    • findRowIndices

      public int[] findRowIndices(String value, int column)
      Return a list of rows that contain the String passed in. If there are no matches, a zero length array will be returned (not a null array).
      Parameters:
      value - the String to match
      column - ID number of the column to search

    • findRowIndices

      public int[] findRowIndices(String value, String columnName)
      Return a list of rows that contain the String passed in. If there are no matches, a zero length array will be returned (not a null array).
      Parameters:
      value - the String to match
      columnName - title of the column to search

    • findRow

      public TableRow findRow(String value, int column)
      Finds the first row in the Table that contains the value provided, and returns a reference to that row. Even if multiple rows are possible matches, only the first matching row is returned. The column to search may be specified by either its ID or title.
      Parameters:
      value - the value to match
      column - ID number of the column to search
      See Also:

    • findRow

      public TableRow findRow(String value, String columnName)
      Parameters:
      columnName - title of the column to search

    • findRows

      public Iterable<TableRow> findRows(String value, int column)
      Finds the rows in the Table that contain the value provided, and returns references to those rows. Returns an iterator, so for must be used to iterate through all the rows, as shown in the example above. The column to search may be specified by either its ID or title.
      Parameters:
      value - the value to match
      column - ID number of the column to search
      See Also:

    • findRows

      public Iterable<TableRow> findRows(String value, String columnName)
      Parameters:
      columnName - title of the column to search

    • findRowIterator

      public Iterator<TableRow> findRowIterator(String value, int column)
      Parameters:
      value - the value to match
      column - ID number of the column to search

    • findRowIterator

      public Iterator<TableRow> findRowIterator(String value, String columnName)
      Parameters:
      columnName - title of the column to search

    • matchRowIndex

      public int matchRowIndex(String regexp, int column)
      Return the row that contains the first String that matches.
      Parameters:
      regexp - the String to match
      column - ID number of the column to search

    • matchRowIndex

      public int matchRowIndex(String what, String columnName)
      Return the row that contains the first String that matches.
      Parameters:
      what - the String to match
      columnName - title of the column to search

    • matchRowIndices

      public int[] matchRowIndices(String regexp, int column)
      Return a list of rows that contain the String passed in. If there are no matches, a zero length array will be returned (not a null array).
      Parameters:
      regexp - the String to match
      column - ID number of the column to search

    • matchRowIndices

      public int[] matchRowIndices(String what, String columnName)
      Return a list of rows that match the regex passed in. If there are no matches, a zero length array will be returned (not a null array).
      Parameters:
      what - the String to match
      columnName - title of the column to search

    • matchRow

      public TableRow matchRow(String regexp, int column)
      Finds the first row in the Table that matches the regular expression provided, and returns a reference to that row. Even if multiple rows are possible matches, only the first matching row is returned. The column to search may be specified by either its ID or title.
      Parameters:
      regexp - the regular expression to match
      column - ID number of the column to search
      See Also:

    • matchRow

      public TableRow matchRow(String regexp, String columnName)
      Parameters:
      columnName - title of the column to search

    • matchRows

      public Iterable<TableRow> matchRows(String regexp, int column)
      Finds the rows in the Table that match the regular expression provided, and returns references to those rows. Returns an iterator, so for must be used to iterate through all the rows, as shown in the example above. The column to search may be specified by either its ID or title.
      Parameters:
      regexp - the regular expression to match
      column - ID number of the column to search
      See Also:

    • matchRows

      public Iterable<TableRow> matchRows(String regexp, String columnName)
      Parameters:
      columnName - title of the column to search

    • matchRowIterator

      public Iterator<TableRow> matchRowIterator(String value, int column)
      Finds multiple rows that match the given expression
      Parameters:
      value - the regular expression to match
      column - ID number of the column to search

    • matchRowIterator

      public Iterator<TableRow> matchRowIterator(String value, String columnName)
      Parameters:
      columnName - title of the column to search

    • replace

      public void replace(String orig, String replacement)
      Replace a String with another. Set empty entries null by using replace("", null) or use replace(null, "") to go the other direction. If this is a typed table, only String columns will be modified.
      Parameters:
      orig -
      replacement -

    • replace

      public void replace(String orig, String replacement, int col)

    • replace

      public void replace(String orig, String replacement, String colName)

    • replaceAll

      public void replaceAll(String regex, String replacement)

    • replaceAll

      public void replaceAll(String regex, String replacement, int column)

    • replaceAll

      public void replaceAll(String regex, String replacement, String columnName)
      Run String.replaceAll() on all entries in a column. Only works with columns that are already String values.
      Parameters:
      regex - the String to match
      columnName - title of the column to search

    • removeTokens

      public void removeTokens(String tokens)
      Removes any of the specified characters (or "tokens"). The example above removes all commas, dollar signs, and spaces from the table.

      If no column is specified, then the values in all columns and rows are processed. A specific column may be referenced by either its ID or title.
      Parameters:
      tokens - a list of individual characters to be removed
      See Also:

    • removeTokens

      public void removeTokens(String tokens, int column)
      Removed any of the specified characters from a column. For instance, the following code removes dollar signs and commas from column 2: 
       table.removeTokens(",$", 2);
      Parameters:
      column - ID number of the column to process

    • removeTokens

      public void removeTokens(String tokens, String columnName)
      Parameters:
      columnName - title of the column to process

    • trim

      public void trim()
      Trims leading and trailing whitespace, such as spaces and tabs, from String table values. If no column is specified, then the values in all columns and rows are trimmed. A specific column may be referenced by either its ID or title.
      See Also:

    • trim

      public void trim(int column)
      Parameters:
      column - ID number of the column to trim

    • trim

      public void trim(String columnName)
      Parameters:
      columnName - title of the column to trim

    • sort

      public void sort(String columnName)
      Sorts (orders) a table based on the values in a column.
      Parameters:
      columnName - the name of the column to sort
      See Also:

    • sort

      public void sort(int column)
      Parameters:
      column - the column ID, e.g. 0, 1, 2

    • sortReverse

      public void sortReverse(String columnName)

    • sortReverse

      public void sortReverse(int column)

    • getUnique

      public String[] getUnique(String columnName)

    • getUnique

      public String[] getUnique(int column)

    • getTally

      public IntDict getTally(String columnName)

    • getTally

      public IntDict getTally(int column)

    • getOrder

      public IntDict getOrder(String columnName)

    • getOrder

      public IntDict getOrder(int column)

    • getIntList

      public IntList getIntList(String columnName)

    • getIntList

      public IntList getIntList(int column)

    • getFloatList

      public FloatList getFloatList(String columnName)

    • getFloatList

      public FloatList getFloatList(int column)

    • getStringList

      public StringList getStringList(String columnName)

    • getStringList

      public StringList getStringList(int column)

    • getIntDict

      public IntDict getIntDict(String keyColumnName, String valueColumnName)

    • getIntDict

      public IntDict getIntDict(int keyColumn, int valueColumn)

    • getFloatDict

      public FloatDict getFloatDict(String keyColumnName, String valueColumnName)

    • getFloatDict

      public FloatDict getFloatDict(int keyColumn, int valueColumn)

    • getStringDict

      public StringDict getStringDict(String keyColumnName, String valueColumnName)

    • getStringDict

      public StringDict getStringDict(int keyColumn, int valueColumn)

    • getRowMap

      public Map<String,TableRow> getRowMap(String columnName)

    • getRowMap

      public Map<String,TableRow> getRowMap(int column)
      Return a mapping that connects the entry from a column back to the row from which it came. For instance: 
       Table t = loadTable("country-data.tsv", "header");
 // use the contents of the 'country' column to index the table
 Map<String, TableRow> lookup = t.getRowMap("country");
 // get the row that has "us" in the "country" column:
 TableRow usRow = lookup.get("us");
 // get an entry from the 'population' column
 int population = usRow.getInt("population");

    • copy

      public Table copy()
      Make a copy of the current table

    • write

      public void write(PrintWriter writer)

    • print

      public void print()