DataFrame

public class DataFrame implements Iterable<Object[]>

A DataFrame object, used to communicate data to and from the AMPL entities. An object of this class can be used to do the following tasks:

• Assign values to AMPL entities (once the DataFrame is populated, use the AMPL.setData to assign its values to the modelling entities in its columns)

• Get values from AMPL, decoupling the values from the AMPL entities they originate from (via Entity.getValues)

A DataFrame object can be created in various ways.

• Create a skeleton via DataFrame.DataFrame(int numberOfIndexColumns, String... headers), specifiying manually the number of indexing columns and the column headers.

• Get column names (and number of indexing columns) from entities of the API, using the constructor DataFrame.DataFrame(Entity... headers).

• Get values from AMPL, decoupling the values from the AMPL entities they originate from (via Entity.getValues)

Populating a DataFrame object can be done adding row by row to a pre-existing skeleton via DataFrame.addRow, setting whole columns of a pre-existing skeleton via DataFrame.setColumn or adding columns (including indexing columns) via DataFrame.addColumn.

Modifying a DataFrame object can be done via DataFrame.setColumn or, item by item, via DataFrame.setValue.

Accessing data in a DataFrame can be done row by row using DataFrame.getRow or by column via DataFrame.getColumn. Automated casting of columns is provided via DataFrame.getColumnAsDoubles and DataFrame.getColumnAsStrings.

Fields

_impl

DataFrameBase _impl

Constructors

DataFrame

DataFrame(DataFrameBase impl)

DataFrame

DataFrame(int numberOfIndexColumns)

Create a new DataFrame with the specified number of indices.

Throws:

• IllegalArgumentException – If a negative number of column is specified

DataFrame

public DataFrame(Entity... headers)

Create a new DataFrame with the specified entities as column headers.

Parameters:

• headers – The columns headers to be used; since they are AMPL entities, sets are automatically considered indices and have to be placed first in the constructor

Throws:

• IllegalArgumentException – if sets are not put first while using this constructor

DataFrame

public DataFrame(int numberOfIndexColumns, String... headers)

Create a new DataFrame where the specified number of columns are an index and with the specified strings as column headers.

Parameters:

• numberOfIndexColumns – Number of columns to be considered as index for this table (>=0)

• headers – The columns headers to be used.

Throws:

• IllegalArgumentException – If a non-valid number of keys is specified

Methods

addColumn

public void addColumn(Object header)

Add a new (empty) column to the DataFrame. Data can then be reassigned with DataFrame.setColumn

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – If a column with the same name exists already or if a set column is added after a data column has been added already.

addColumn

public void addColumn(Object header, Collection<?> values)

Add a new column to the dataframe, with the corresponding data. *

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – if the size of values is not the same as the number of indices in the DataFrame, if a column with the same name exists already or if a set column is added after a data column has been added already.

addColumn

public <T> void addColumn(Object header, T[] values)

Add a new column to the dataframe, with the corresponding data.

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame, if a column with the same name exists already or if a set column is added after a data column has been added already.

addColumn

public void addColumn(Object header, int[] values)

Add a new column to the dataframe, with the corresponding data.

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame, if a column with the same name exists already or if a set column is added after a data column has been added already.

addColumn

public void addColumn(Object header, double[] values)

Add a new column to the dataframe, with the corresponding data.

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – if the cardinality of values is incompatible with the dataframe structure or if a column with the same name exists already

addColumn

public void addColumn(Object header, long[] values)

Add a new column to the dataframe, with the corresponding data.

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame, if a column with the same name exists already or if a set column is added after a data column has been added already.

addColumn

public void addColumn(Object header, float[] values)

Add a new column to the dataframe, with the corresponding data.

Parameters:

• header – The header for the new column to be added

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame, if a column with the same name exists already or if a set column is added after a data column has been added already.

addRow

public void addRow(Object... items)

Add a row to the current table. The first numberOfIndexColumns columns (decided at object creation time) are treated as indices

Parameters:

• items – Items of the row to be added

Throws:

• IllegalArgumentException – if the number of items in the row is not equal to the number of columns, if a row is added to a DataFrame with no indices or if a row with the same indices exists already.

equals

public boolean equals(Object obj)

getColumn

public Object[] getColumn(Object header)

Get the data corresponding to the specified column

Parameters:

• header – Column to be returned

Returns:

Data corresponding to the column, null if the specified column does not exist.

getColumnAsDoubles

public double[] getColumnAsDoubles(Object header)

Get the data corresponding to the specified column as an array of double numbers

Parameters:

• header – Column to be returned

Returns:

Data corresponding to the column, null if the specified column does not exist.

getColumnAsStrings

public String[] getColumnAsStrings(Object header)

Get the data corresponding to the specified column as an array of strings

Parameters:

• header – Column to be returned

Throws:

• IllegalArgumentException – If the header specified does not correspond to any column

Returns:

Data corresponding to the column, null if the specified column does not exist.

getHeaders

public String[] getHeaders()

Get the column headers of this DataFrame

Returns:

Header names

getNumCols

public int getNumCols()

Get the number of columns in the table

Returns:

Number of columns

getNumIndices

public int getNumIndices()

Get the number of indices in the table

Returns:

Number of indices

getNumRows

public int getNumRows()

Get the number of rows in the table

Returns:

Number of rows

getRow

public Object[] getRow(Object... index)

Get the specified row (by values of the indexing columns)

Parameters:

• index – Indices for the row

Throws:

• IllegalArgumentException – If the number of indices specified is wrong for the DataFrame

Returns:

The specified row, or ‘null’ if the row was not found

getRowByIndex

public Object[] getRowByIndex(int index)

Get the specified row

Parameters:

• index – 0-based numeric index

Throws:

• IndexOutOfBoundsException – If the index is < 0 or greater than the number of rows in the DataFrame.

hashCode

public int hashCode()

iterator

public Iterator<Object[]> iterator()

setColumn

public void setColumn(Object header, int[] values)

Set (all) the values for a specific column.

Parameters:

• column – Column identifier

• values – Values to be assigned

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame or if a column with the same name exists already.

setColumn

public void setColumn(Object header, float[] values)

Set (all) the values for a specific column.

Parameters:

• header – Column identifier

• values – Values to be assigned

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame or if a column with the same name exists already.

setColumn

public void setColumn(Object header, double[] values)

Set (all) the values for a specific column.

Parameters:

• header – Column identifier

• values – Values to be assigned

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame or if a column with the same name exists already.

setColumn

public void setColumn(Object header, long[] values)

Set (all) the values for a specific column.

Parameters:

• header – Column identifier

• values – Values to be assigned

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame or if a column with the same name exists already.

setColumn

public <T> void setColumn(Object header, T[] values)

Set (all) the values for a specific column.

Parameters:

• header – Column identifier

• values – Values to be assigned

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame or if a column with the same name exists already.

setColumn

public void setColumn(Object header, Collection<?> values)

Set (all) the values for a specific column.

Parameters:

• column – Column identifier

• header – Values to be assigned

Throws:

• IllegalArgumentException – if the cardinality of values is not the same as the number of indices in the DataFrame or if a column with the same name exists already.

setMatrix

public void setMatrix(Object values, Object[]... indices)

Set the multidimensional array values as data column for this DataFrame, and all the vectors in indices as indices values.

For example, the code snippet (which does not include the arrays initialization):

double[][][][] fourdimensions = new double[][][][] {...};
String[] firstIndex = new String[]{...};
String[] secondIndex = new String[]{...};
String[] thirdIndex = new String[]{...};
String[] fourthIndex = new String[]{...};
setMatrix(fourdimensions, firstIndex, secondIndex, thirdIndex, fourthIndex);

is valid.

Parameters:

• values – A multidimensional array, can be either double[]..[], String[]..[] or Object[]..[]. The arrays can be anything from 1 to 6 dimensional. Items in Object arrays are converted to AMPL datatypes, so any numeric type is converted to double, anything else to String.

• indices – Vectors containing the indices values for each dimension of the values array.

Throws:

• IllegalArgumentException – If the number of indices is not equal to the arity of the values array, or if the arity is not supported.

setMatrix

public void setMatrix(double[] values, double[] rowindices, double[] colindices)

setMatrix

public void setMatrix(double[] values, String[] rowindices, double[] colindices)

setMatrix

public void setMatrix(double[] values, double[] rowindices, String[] colindices)

setMatrix

public void setMatrix(double[] values, String[] rowindices, String[] colindices)

setMatrix

public void setMatrix(String[] values, double[] rowindices, double[] colindices)

setMatrix

public void setMatrix(String[] values, String[] rowindices, double[] colindices)

setMatrix

public void setMatrix(String[] values, double[] rowindices, String[] colindices)

setMatrix

public void setMatrix(String[] values, String[] rowindices, String[] colindices)

setMatrixPacked

public void setMatrixPacked(Object values, Object indices)

Set the multidimensional array values as data column for this DataFrame, and all the vectors in indices as indices values. Packed version, usable to pass an Object representing all the arrays of indices.

setValue

public void setValue(Object... values)

Set a single value in the DataFrame object.

Parameters:

• values – The first objects are the row indices, followed by the column index, and finally by the value to be assigned

Throws:

• IllegalArgumentException – if the specified column or row is not in the dataframe or if the number of arguments is wrong

setValue

public void setValue(int rowIndex, int colIndex, double value)

setValue

public void setValue(int rowIndex, int colIndex, String value)

setValue

public void setValue(Tuple rowIndex, String colHeader, double value)

setValue

public void setValue(Tuple rowIndex, String colHeader, String value)

toString

public String toString()

Gives a tabular string representation of the dataframe object