DataFrame

class ampl::DataFrame

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 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 Entity::getValues()

A DataFrame object can be created in various ways.

• Create a skeleton via DataFrame(std::size_t numberOfIndexColumns, StringArgs 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(const EntityArgs &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().

Public Types

typedef internal::Slice<true> Row

Represents a row in a DataFrame.

typedef internal::Slice<false> Column

Represents a column in a DataFrame.

Public Functions

DataFrame(std::size_t numberOfIndexColumns)

Create a new DataFrame with the specified number of indices.

~DataFrame()

Destructor.

DataFrame(std::size_t numberOfIndexColumns, StringArgs 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

Exceptions

• invalid_argument -

  If a non-valid number of indices is specified (e.g. > than the number of headers)

DataFrame(const EntityArgs &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. The

Exceptions

• invalid_argument -

  if sets are not put first while using this constructor or if the indexarity of the data columns does not correspond to the total indexarity of the DataFrame

DataFrame(const DataFrame &other)

Copy constructor (deep copy)

DataFrame &operator=(const DataFrame &df)

Assignment operator (deep copies all the data)

std::size_t getNumCols() const

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

Return

The number of columns.

std::size_t getNumRows() const

Get the number of data rows in this dataframe.

Return

The number of rows.

std::size_t getNumIndices() const

std::size_t DataFrame::getNumIndices() const Get the number of indices (the indexarity) of this dataframe.

Return

The number of indices needed to access one row of this dataframe.

void addRow(TupleRef 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

• value -

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

void addRow(VariantRef a1)

Add a value to a DataFrame composed of only one column.

Parameters

• a1 -

  The value to be added.

void addRow(VariantRef a1, VariantRef a2)

Add a value to a DataFrame composed of two columns.

Parameters

• a1 -

  The value to be added in the first column.

• a2 -

  The value to be added in the second column.

void addRow(VariantRef a1, VariantRef a2, VariantRef a3)

Add a value to a DataFrame composed of three columns.

Parameters

• a1 -

  The value to be added in the first column.

• a2 -

  The value to be added in the second column.

• a3 -

  The value to be added in the third column.

void addRow(VariantRef a1, VariantRef a2, VariantRef a3, VariantRef a4)

Add a value to a DataFrame composed of four columns.

Parameters

• a1 -

  The value to be added in the first column.

• a2 -

  The value to be added in the second column.

• a3 -

  The value to be added in the third column.

• a4 -

  The value to be added in the fourth column.

void reserve(std::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 DataFrame::addRow.

Parameters

• numRows -

  Number of rows to be allocated.

std::string toString() const

Give a tabular string representation of the dataframe object.

Return

A std::string that represents this object

void addColumn(fmt::CStringRef header)

Add a new empty column with the corresponding header.

Parameters

• header -

  The header.

void addColumn(fmt::CStringRef header, internal::Args values)

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

Parameters

• header -

  The name of the new column

• values -

  An array of size getNumRows() with all the values of the new row

Column getColumn(fmt::CStringRef header) const

Get the specified column as a view object.

Parameters

• header -

  The header of the column.

void setColumn(fmt::CStringRef header, internal::Args column, std::size_t n)

Set the values of a column.

Parameters

• header -

  The header of the column to be set

• column -

  The values to set.

• n -

  The number of items in the column.

Row getRowByIndex(std::size_t index) const

Get row by numeric index.

Return

The corresponding row.

Parameters

• index -

  Zero-based index of the row to get

Row getRow(VariantRef a1)

Get a row by value of the indexing column (for DataFrames with one indexing column)

Return

The correponding row.

Parameters

• a1 -

  Index of the desired row

Row getRow(TupleRef index) const

Get a row by value of the indexing columns.

If the index is not specified, gets the only row of a dataframe with no indexing columns.

Return

The row.

Parameters

• index -

  Tuple representing the index of the desired row

iterator begin() const

Get the iterator to the first row in this DataFrame.

iterator end() const

Get the iterator to the last row in this DataFrame (an iterator of numerical index DataFrame::getNumRows).

iterator find(TupleRef index) const

Get the iterator to the specified row in this DataFrame.

Return

An iterator pointing to the found row, or iterator::end if not found.

Parameters

• index -

  The index of the Row to be found

StringRefArray getHeaders() const

Get the headers of this DataFrame.

Return

The headers of this DataFrame

template <std::size_t NR>

void setArray(internal::Args indices, const double (&values)[NR])

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

The DataFrame must have one index and one data column.

Parameters

• indices -

  The indices of the values to set

• values -

  An array containing the values to be set

template <std::size_t NR>

void setArray(internal::Args indices, const char *(&values)[NR])

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

The DataFrame must have one index and one data column.

Parameters

• indices -

  The indices of the values to set

• values -

  An array containing the values to be set

void setArray(std::size_t size, internal::Args indices, const double *values)

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

The DataFrame must have one index and one data column.

Parameters

• size -

  The size of the two arrays passed

• indices -

  The indices of the values to set

• values -

  An array containing the values to be set

void setArray(std::size_t size, internal::Args indices, const char **values)

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

The DataFrame must have one index and one data column.

Parameters

• size -

  The size of the two arrays passed

• indices -

  The indices of the values to set

• values -

  An array containing the values to be set

template <std::size_t NR, std::size_t NC>

void setMatrix(internal::Args indices0, internal::Args indices1, const double (&values)[NR][NC])

Set a matrix of doubles to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters

• indices0 -

  The values of the first indexing column

• indices1 -

  The values of the second indexing column

• values -

  a 2d-array of doubles

template <std::size_t NR, std::size_t NC>

void setMatrix(internal::Args indices0, internal::Args indices1, const char *(&values)[NR][NC])

Set a matrix of strings to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters

• indices0 -

  The values of the first indexing column

• indices1 -

  The values of the second indexing column

• values -

  a 2d-array of string literals

void setMatrix(std::size_t num_rows, internal::Args row_indices, std::size_t num_cols, internal::Args indices_cols, const double *values)

Set a matrix of doubles to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters

• num_rows -

  The size of the first dimension (number of rows)

• row_indices -

  The values of the first indexing column

• num_cols -

  The size of the second dimension (number of columns)

• indices_cols -

  The values of the second indexing column

• values -

  a 2d-array of doubles

void setMatrix(std::size_t num_rows, internal::Args row_indices, std::size_t num_cols, internal::Args indices_cols, const char **values)

Set a matrix of string literals to an empty DataFrame.

The DataFrame must have two indices and one data column.

Parameters

• num_rows -

  The size of the first dimension (number of rows)

• row_indices -

  The values of the first indexing column

• num_cols -

  The size of the second dimension (number of columns)

• indices_cols -

  The values of the second indexing column

• values -

  a 2d-array of strings

internal::DataFrame *impl() const

Infrastructure: returns a pointer to the inner object.

class iterator

Iterates through the DataFrame in a row-by-row fashion.

Public Functions

value_type operator*() const

Dereferences the iterator, gets a DataFrame::Row.

iterator &operator++()

Go to the next row.

iterator operator++(int)

Go to the next row.

bool operator==(iterator other) const

Equality check.

bool operator!=(iterator other) const

Inequality check.

Row

typedef internal::Slice<true> ampl::DataFrame::Row

Represents a row in a DataFrame.

Column

typedef internal::Slice<false> ampl::DataFrame::Column

Represents a column in a DataFrame.