DataFrame

class 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 method.

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

inline explicit DataFrame(std::size_t numberOfIndexColumns)

Create a new DataFrame with the specified number of indices.

inline ~DataFrame()

Destructor.

inline 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

Throws:

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

inline explicit 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

Throws:

std::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

inline DataFrame(const DataFrame &other)

Copy constructor (deep copy)

inline DataFrame &operator=(const DataFrame &df)

Assignment operator (deep copies all the data)

inline bool operator==(const DataFrame &other) const

Equality check.

inline bool operator!=(const DataFrame &other) const

Inequality check.

inline std::size_t getNumCols() const

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

Returns:

The number of columns.

inline std::size_t getNumRows() const

Get the number of data rows in this dataframe.

Returns:

The number of rows.

inline std::size_t getNumIndices() const

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

Returns:

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

inline 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.

inline void addRow(VariantRef a1)

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

Parameters:

a1 – The value to be added.

inline 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.

inline 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.

inline 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.

inline 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.

inline std::string toString() const

Give a tabular string representation of the dataframe object.

Returns:

A std::string that represents this object

inline void addColumn(fmt::CStringRef header)

Add a new empty column with the corresponding header.

Parameters:

header – The header.

inline 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

inline Column getColumn(fmt::CStringRef header) const

Get the specified column as a view object.

Parameters:

header – The header of the column.

inline void setValue(TupleRef rowIndex, fmt::CStringRef colHeader, ampl::VariantRef value)

Set the value at the specified row and columnn.

Parameters:

• rowIndex – A tuple identiying the row to modify

• colHeader – The header of the column to modify

• value – The value to assign

inline void setValue(std::size_t rowIndex, size_t colIndex, ampl::VariantRef value)

Set the value at the specified row and columnn.

Parameters:

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

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

• value – The value to assign

inline 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.

inline Row getRowByIndex(std::size_t index) const

Get row by numeric index.

Parameters:

index – Zero-based index of the row to get

Returns:

The corresponding row.

inline Row getRow(VariantRef a1)

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

Parameters:

a1 – Index of the desired row

Returns:

The correponding row.

inline Row getRow(TupleRef index = TupleRef()) 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.

Parameters:

index – Tuple representing the index of the desired row

Returns:

The row.

inline iterator begin() const

Get the iterator to the first row in this DataFrame.

inline iterator end() const

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

inline iterator find(TupleRef index) const

Get the iterator to the specified row in this DataFrame.

Parameters:

index – The index of the Row to be found

Returns:

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

inline StringArray getHeaders() const

Get the headers of this DataFrame.

Returns:

The headers of this DataFrame

template<std::size_t NR>
inline 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>
inline 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

inline 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

inline void setArray(std::size_t size, internal::Args indices, const char *const *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>
inline 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>
inline 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

inline 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

inline void setMatrix(std::size_t num_rows, internal::Args row_indices, std::size_t num_cols, internal::Args indices_cols, const char *const *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

inline 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 Types

using iterator_category = std::forward_iterator_tag

using value_type = Row

using difference_type = std::ptrdiff_t

using pointer = value_type*

using reference = value_type&

Public Functions

inline value_type operator*() const

Dereferences the iterator, gets a DataFrame::Row.

inline iterator &operator++()

Go to the next row.

inline iterator operator++(int)

Go to the next row.

inline bool operator==(iterator other) const

Equality check.

inline bool operator!=(iterator other) const

Inequality check.