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

AMPL

Environment