AMPL_DATAFRAME

group AMPL_DATAFRAME

An AMPL_DATAFRAME struct is used to communicate data to and from the AMPL entities.

A struct of AMPL_DATAFRAME can be used to do the following tasks:

• Assign values to AMPL entities (once the AMPL_DATAFRAME is populated, use 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 via AMPL_EntityGetValues()

An AMPL_DATAFRAME struct can be created in various ways.

• Create a skeleton via AMPL_DataFrameCreate(AMPL_DATAFRAME **dataframe,size_t numberOfIndexColumns, size_t numberOfDataColumns,const char *const *headers), specifiying manually the number of indexing columns, the number of data columns and the column headers.

• Get column names (and number of indexing columns) from entities of the API, using the constructor DataFrame(const EntityArgs

  &headers).

• Get values from AMPL, decoupling the values from the AMPL entities they originate from (via AMPL_EntityGetValues())

Populating a DataFrame object can be done adding row by row to a pre-existing skeleton via AMPL_DataFrameAddRow(), setting whole columns of a pre-existing skeleton via AMPL_DataFrameSetColumnArg(), AMPL_DataFrameSetColumnArgDouble() and AMPL_DataFrameSetColumnArgString() or adding columns (including indexing columns) via AMPL_DataFrameAddColumn().

Modifying a DataFrame object can be done via DataFrame.setColumn method.

Accessing data in a DataFrame can be done row by row using DataFrame.getRow() or by column via DataFrame.getColumn().

Typedefs

typedef struct AMPL_DataFrame AMPL_DATAFRAME

An AMPL Dataframe.

Functions

AMPL_ERRORINFO *AMPL_DataFrameCreate(AMPL_DATAFRAME **dataframe, size_t numberOfIndexColumns, size_t numberOfDataColumns, const char *const *headers)

Allocates the AMPL_DATAFRAME struct.

Parameters:

• dataframe – Pointer to the pointer of the AMPL_DATAFRAME struct.

• numberOfIndexColumns – Number of index columns.

• numberOfDataColumns – Number of data columns.

• headers – Column headers.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameCreate2(AMPL_DATAFRAME **dataframe, size_t numberOfIndexColumns)

Allocates the AMPL_DATAFRAME struct.

Parameters:

• dataframe – Pointer to the pointer of the AMPL_DATAFRAME struct.

• numberOfIndexColumns – Number of index columns.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameCopy(AMPL_DATAFRAME **dataframe, AMPL_DATAFRAME *copy)

Allocates a copy of an AMPL_DATAFRAME struct.

Parameters:

• dataframe – Pointer to the pointer of the AMPL_DATAFRAME struct.

• copy – Pointer to the AMPL_DATAFRAME struct to copy.

Returns:

Pointer to the AMPL_ERRORINFO struct.

void AMPL_DataFrameFree(AMPL_DATAFRAME **dataframe)

Frees the AMPL_DATAFRAME struct.

Parameters:

• dataframe – Pointer to the pointer of the AMPL_DATAFRAME struct.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetHeaders(AMPL_DATAFRAME *dataframe, size_t *size, char ***headers)

Get the headers of this DataFrame.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• size – Pointer to the size of the headers.

• headers – Pointer to array of headers.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameEquals(AMPL_DATAFRAME *df1, AMPL_DATAFRAME *df2, int *equals)

Equality check of DataFrames.

Parameters:

• df1 – Pointer to the first AMPL_DATAFRAME struct.

• df2 – Pointer to the second AMPL_DATAFRAME struct.

• equals – Pointer to the result of the equality check.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameToString(AMPL_DATAFRAME *dataframe, char **output)

Get a tabular string representation of the DataFrame.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• output – Pointer to the tabular string representation.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameReserve(AMPL_DATAFRAME *dataframe, size_t numRows)

Reserve space for the given number of rows.

NOTE that the rows cannot be accessed, they still have to be added via AMPL_DataFrameAddRow.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• numRows – Number of rows to be allocated.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameAddRow(AMPL_DATAFRAME *dataframe, AMPL_TUPLE *value)

Add a row to the DataFrame.

The size of the tuple must be equal to the total number of columns in the dataframe.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• value – A tuple containing all the values for the row to be added.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetColumnArg(AMPL_DATAFRAME *dataframe, const char *header, AMPL_ARGS *column, size_t n)

Set the values of a column using AMPL_ARGS.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The header of the column to be set.

• column – The values to set.

• n – The number of items in the column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetColumnArgDouble(AMPL_DATAFRAME *dataframe, const char *header, const double *column, size_t n)

Set the values of a double column using doubles.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The header of the column to be set.

• column – The values to set.

• n – The number of items in the column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetColumnArgString(AMPL_DATAFRAME *dataframe, const char *header, const char *const *column, size_t n)

Set the values of a string column using strings.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The header of the column to be set.

• column – The values to set.

• n – The number of items in the column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetValue(AMPL_DATAFRAME *dataframe, AMPL_TUPLE *rowIndex, const char *header, AMPL_VARIANT *value)

Set the value at the specified row and columnn.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• rowIndex – A tuple identiying the row to modify.

• header – The header of the column to modify.

• value – The value to assign.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetValueByIndex(AMPL_DATAFRAME *dataframe, size_t rowNumber, size_t colNumber, AMPL_VARIANT *value)

Set the value at the specified row and columnn.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• rowNumber – The 0-based index of the row to modify.

• colNumber – The 0-based index of the column to modify (including indices).

• value – The value to assign.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameAddColumn(AMPL_DATAFRAME *dataframe, const char *header, AMPL_ARGS *values)

Add a new column with the corresponding header and values to the dataframe.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The name of the new column header.

• values – Pointer to the new column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameAddColumnDouble(AMPL_DATAFRAME *dataframe, const char *header, const double *values)

Add a new column with the corresponding header and double values to the dataframe.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The name of the new column header.

• values – Array of doubles representing the new column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameAddColumnString(AMPL_DATAFRAME *dataframe, const char *header, const char **values)

Add a new column with the corresponding header and string values to the dataframe.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The name of the new column header.

• values – Array of strings representing the new column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameAddEmptyColumn(AMPL_DATAFRAME *dataframe, const char *header)

Add a new empty column with the corresponding header.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• header – The name of the new columnheader.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetNumCols(AMPL_DATAFRAME *dataframe, size_t *num)

Get the total number of columns in this dataframe (indexarity + number of values).

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• num – Pointer to the number of columns.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetNumRows(AMPL_DATAFRAME *dataframe, size_t *num)

Get the number of data rows in this dataframe.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• num – Pointer to the number of data rows.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetNumIndices(AMPL_DATAFRAME *dataframe, size_t *num)

Get the number of indices (the indexarity) of this dataframe.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• num – Pointer to the number of indices needed to access one row of this dataframe.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetArray(AMPL_DATAFRAME *dataframe, const double *values, size_t l0, AMPL_ARGS *indices0)

Set the values of a DataFrame from an array of doubles.

The DataFrame must have one index and one data column.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• values – An array containing the values to be set.

• l0 – The size of the two arrays passed.

• indices0 – The indices of the values to set as AMPL_ARGS.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetArrayString(AMPL_DATAFRAME *dataframe, const char *const *values, size_t l0, AMPL_ARGS *indices0)

Set the values of a DataFrame from an array of string literals.

The DataFrame must have one index and one data column.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• values – An array containing the values to be set

• l0 – The size of the two arrays passed.

• indices0 – The indices of the values to set

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetMatrix(AMPL_DATAFRAME *dataframe, const double *values, size_t l0, AMPL_ARGS *indices0, size_t l1, AMPL_ARGS *indices1)

Set a matrix of doubles to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• values – A flattend 2d-array of doubles.

• l0 – The size of the first indexing column.

• indices0 – The values of the first indexing column.

• l1 – The size of the second indexing column.

• indices1 – The values of the second indexing column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetMatrixStringString(AMPL_DATAFRAME *dataframe, const double *values, size_t l0, const char *const *indices0, size_t l1, const char *const *indices1)

Set a matrix of strings to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• values – A flattend 2d-array of doubles.

• l0 – The size of the first indexing column.

• indices0 – The values of the first indexing column.

• l1 – The size of the second indexing column.

• indices1 – The values of the second indexing column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameSetMatrixString(AMPL_DATAFRAME *dataframe, const char *const *values, size_t l0, AMPL_ARGS *indices0, size_t l1, AMPL_ARGS *indices1)

Set a matrix of strings to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• values – A flattend 2d-array of strings.

• l0 – The size of the first indexing column.

• indices0 – The values of the first indexing column.

• l1 – The size of the second indexing column.

• indices1 – The values of the second indexing column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetColumnIndex(AMPL_DATAFRAME *dataframe, const char *name, size_t *columnindex)

Get the column index of a column by its header.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• name – The header of the column.

• columnindex – Pointer to the index of the column.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetIndexingTuple(AMPL_DATAFRAME *dataframe, size_t rowindex, AMPL_TUPLE **index)

Get the tuple representation of a row index.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• rowindex – The index of the row.

• index – Pointer to the tuple representing the index of the row.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameGetRowIndex(AMPL_DATAFRAME *dataframe, AMPL_TUPLE *index, size_t *rowindex)

Get a row index by its tuple representation.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• index – Tuple representing the index of the desired row.

• rowindex – Pointer to the index of the row.

Returns:

Pointer to the AMPL_ERRORINFO struct.

AMPL_ERRORINFO *AMPL_DataFrameElement(AMPL_DATAFRAME *dataframe, size_t rowindex, size_t colindex, AMPL_VARIANT **v)

Get the values of a row by its index.

Parameters:

• dataframe – Pointer to the AMPL_DATAFRAME struct.

• rowindex – The index of the row.

• colindex – The index of the column.

• v – Pointer to element.

Returns:

Pointer to the AMPL_ERRORINFO struct.