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